---
id: api/cypress-api/element-selector-api
title: Cypress.ElementSelector | Cypress Documentation
description: >-
  Customize how Cypress chooses selectors in Studio and cy.prompt() by setting
  your preferred selector strategy.
section: api
source_path: docs/api/cypress-api/element-selector-api.mdx
version: 48b03b5502f7aea1d0454750cce208f775403542
updated_at: '2026-05-20T19:00:20.270Z'
---
# Cypress.ElementSelector

The ElementSelector API lets you define how Cypress selects elements in tools like [Cypress Studio](/llm/markdown/app/guides/cypress-studio.md) and [cy.prompt()](/llm/markdown/api/commands/prompt.md).

By setting your own selector strategy, you can control which attributes Cypress prioritizes (like `data-*`, `id`, or `aria-label`) when generating selectors. This helps you enforce consistency, improve test readability, and make generated tests more resilient to changes in your HTML.

Cypress uses a strategy to generate selectors that are not only based on your preferred selectors, but also guaranteed to be **unique** within the document.

This means Cypress will **attempt to follow your configured `selectorPriority`**, but may skip lower-priority options or combine multiple selectors if a single attribute isn't unique enough.

## Syntax

```
Cypress.ElementSelector.defaults(options)
```

### Arguments

**options _(Object)_**

An object containing any or all of the following options:

| Option | Accepts | Description |
| --- | --- | --- |
| `selectorPriority` | `Array of strings` | Determines the order of attributes Cypress uses to generate selectors. |

##### API Stability

The `selectorPriority` API is under active development and may change in future versions as we refine the best way to generate selectors within our products. Stay updated with our [changelog](/llm/markdown/app/references/changelog.md) for any breaking changes.

Accepted values for `selectorPriority` are:

*   `attribute:${string}` - for specific attributes like `attribute:aria-label`, `attribute:lang`, etc.
*   `attributes` - general fallback for any other attributes
*   `class`
*   `data-${string}` - for specific data attributes like `data-cy`, `data-testid`, etc.
*   `id`
*   `name`
*   `nth-child`
*   `tag`

### Default Selector Priority

1.  `data-cy`
2.  `data-test`
3.  `data-testid`
4.  `data-qa`
5.  `name`
6.  `id`
7.  `class`
8.  `tag`
9.  `attributes`
10.  `nth-child`

Consider the following HTML:

```
<button id="submit-btn" class="primary" role="button" aria-label="Submit">  Submit</button>
```

With the default selector priority, Cypress prioritizes `id`, so the selector would be `#submit-btn`.

**$el _(Object)_**

The [jQuery element](http://api.jquery.com/Types/#jQuery) for which you want to retrieve a selector.

## Examples

### Set custom selector priority

You can customize how Cypress generates selectors by defining a priority order for which attributes to prefer. This affects the selectors you see in tools like [Cypress Studio](/llm/markdown/app/guides/cypress-studio.md) and [cy.prompt()](/llm/markdown/api/commands/prompt.md), and is also respected by [Cypress AI Skills](/llm/markdown/app/tooling/ai-skills.md) when your AI coding tool generates selectors.

For example, this config tells Cypress to prefer semantic and accessibility attributes before falling back to styling details like class names.

```
Cypress.ElementSelector.defaults({  selectorPriority: [    'attribute:role',    'attribute:aria-label',    'name',    'class',    'attributes',  ],})
```

### Prioritize accessible attributes

Accessibility-first apps often use ARIA roles and labels. You can configure Cypress to prioritize these when generating selectors:

```
Cypress.ElementSelector.defaults({  selectorPriority: ['attribute:aria-label', 'attribute:role', 'id', 'class'],})
```

This helps produce more readable and resilient selectors, especially for accessibility-first applications.

### Prioritize language-agnostic selectors (for i18n)

In multilingual applications, selectors based on text or labels may change between locales. Prefer stable, language-agnostic attributes like `data-*`, `role`, and `aria-labelledby`.

```
Cypress.ElementSelector.defaults({  selectorPriority: [    'data-cy',    'attribute:role',    'attribute:aria-labelledby',    'name',    'id',    'class',    'attributes',  ],})
```

This ensures selectors are resilient to translation changes in text or labels.

### Avoid dynamic or auto-generated selectors

Many frameworks produce dynamic ids or class names such as:

```
<button  id="button-5a3f9d"  class="Component_button__3XyZ2 css-1a2b3c SeriesIndexFooter-footer-3WmRg"  data-cy="checkout-btn">  Checkout</button>
```

You can configure Cypress to skip attributes that are dynamically generated.

```
Cypress.ElementSelector.defaults({  selectorPriority: [    'data-cy',    'attribute:role',    'attribute:aria-label',    'name',    'attributes', // fallback    // deliberately omit 'id' and 'class'  ],})
```

## History

| Version | Changes |
| --- | --- |
| [15.0.0](/llm/markdown/app/references/changelog.md#15-0-0) | Renamed `Cypress.SelectorPlayground` to `Cypress.ElementSelector`. |

## See also

*   [Cypress Studio](/llm/markdown/app/guides/cypress-studio.md)
*   [cy.prompt()](/llm/markdown/api/commands/prompt.md)
*   [Cypress AI Skills](/llm/markdown/app/tooling/ai-skills.md)