cypress-io · jennifer-shehane · Mar 31, 2025 · Apr 7, 2025 · Apr 8, 2025 · Apr 22, 2025
diff --git a/docs/api/cypress-api/element-selector-api.mdx b/docs/api/cypress-api/element-selector-api.mdx
@@ -0,0 +1,153 @@
+---
+title: 'Cypress.ElementSelector | Cypress Documentation'
+description: 'Customize how Cypress chooses selectors in Studio and Selector Playground by setting your preferred selector strategy.'
+sidebar_label: ElementSelector
+sidebar_position: 105
+---
+
+<ProductHeading product="app" />
+
+# Cypress.ElementSelector
+
+The ElementSelector API lets you define how Cypress selects elements in tools like [Cypress Studio](/app/guides/cypress-studio) and the [Selector Playground](/app/core-concepts/open-mode#Selector-Playground).
+
+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
+
+```javascript
+Cypress.ElementSelector.defaults(options)
+```
+
+### Arguments
+
+<Icon name="angle-right" /> **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. |
+
+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`
+
+<DefaultSelectorPriority />
+
+Consider the following HTML:
+
+```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`.
+
+<Icon name="angle-right" /> **$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](/app/guides/cypress-studio) and the [Selector Playground](/app/core-concepts/open-mode#Selector-Playground).
+
+For example, this config tells Cypress to prefer semantic and accessibility attributes before falling back to styling details like class names.
+
+```javascript
+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:
+
+```js
+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`.
+
+```js
+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:
+
+```html
+<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.
+
+```js
+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](/app/references/changelog#15-0-0) | Renamed `Cypress.SelectorPlayground` to `Cypress.ElementSelector`. |
+
+## See also
+
+- [Cypress Studio](/app/guides/cypress-studio)
+- [Selector Playground](/app/core-concepts/open-mode#Selector-Playground)
diff --git a/docs/api/cypress-api/selector-playground-api.mdx b/docs/api/cypress-api/selector-playground-api.mdx
diff --git a/docs/api/table-of-contents.mdx b/docs/api/table-of-contents.mdx
@@ -190,29 +190,29 @@ The _key_ difference between Cypress APIs and Cypress commands is that Cypress
 APIs execute the moment they are invoked and are **not** enqueued to run at a
 later time.
 
-| Property                                                                 | Usage                                                                                                                          |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| [`Cypress.arch`](/api/cypress-api/arch)                                  | CPU architecture name of the underlying OS, as returned from Node's `os.arch()`.                                               |
-| [`Cypress.browser`](/api/cypress-api/browser)                            | Information about the current browser, such as browser family and version.                                                     |
-| [`Cypress.Commands`](/api/cypress-api/custom-commands)                   | Create new custom commands and extend or override existing ones.                                                               |
-| [`Cypress.config()`](/api/cypress-api/config)                            | Get and set Cypress configuration from inside your tests.                                                                      |
-| [`Cypress.Cookies.debug()`](/api/cypress-api/cookies)                    | Generate console logs whenever a cookie is modified.                                                                           |
-| [`Cypress.currentRetry`](/api/cypress-api/currentretry)                  | A number representing the current test retry count.                                                                            |
-| [`Cypress.currentTest`](/api/cypress-api/currenttest)                    | An object with information about the currently executing test.                                                                 |
-| [`Cypress.log`](/api/cypress-api/cypress-log)                            | This is the internal API for controlling what gets printed to the Command Log. Useful when writing your own custom commands.   |
-| [`Cypress.dom`](/api/cypress-api/dom)                                    | A collection of DOM related helper methods.                                                                                    |
-| [`Cypress.env`](/api/cypress-api/env)                                    | Get environment variables from inside your tests.                                                                              |
-| [`Cypress.isBrowser()`](/api/cypress-api/isbrowser)                      | Checks if the current browser matches the given name or filter.                                                                |
-| [`Cypress.isCy()`](/api/cypress-api/iscy)                                | checks if a variable is a valid instance of cy or a cy chainable.                                                              |
-| [`Cypress.Keyboard.defaults()`](/api/cypress-api/keyboard-api)           | Set default values for how the `.type()` command is executed.                                                                  |
-| [`Cypress.platform`](/api/cypress-api/platform)                          | The underlaying OS name, as returned by Node's `os.platform()`.                                                                |
-| [`Cypress.require`](/api/cypress-api/require)                            | Enables utilizing dependencies within the [cy.origin()](/api/commands/origin) callback function.                               |
-| [`Cypress.Screenshot.defaults()`](/api/cypress-api/screenshot-api)       | Set defaults for screenshots captured by the `.screenshot()` command and the automatic screenshots taken during test failures. |
-| [`Cypress.SelectorPlayground`](/api/cypress-api/selector-playground-api) | Configure options used by the [Selector Playground](/app/core-concepts/open-mode#Selector-Playground).                         |
-| [`Cypress.session`](/api/cypress-api/session)                            | A collection of helper methods related to the `.session()` command.                                                            |
-| [`Cypress.spec`](/api/cypress-api/spec)                                  | An object with information about the currently executing spec file.                                                            |
-| [`Cypress.testingType`](/api/cypress-api/testing-type)                   | The current testing type, eg. `"e2e"` or `"component".                                                                         |
-| [`Cypress.version`](/api/cypress-api/version)                            | The current Cypress version.                                                                                                   |
+| Property                                                           | Usage                                                                                                                                                         |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`Cypress.arch`](/api/cypress-api/arch)                            | CPU architecture name of the underlying OS, as returned from Node's `os.arch()`.                                                                              |
+| [`Cypress.browser`](/api/cypress-api/browser)                      | Information about the current browser, such as browser family and version.                                                                                    |
+| [`Cypress.Commands`](/api/cypress-api/custom-commands)             | Create new custom commands and extend or override existing ones.                                                                                              |
+| [`Cypress.config()`](/api/cypress-api/config)                      | Get and set Cypress configuration from inside your tests.                                                                                                     |
+| [`Cypress.Cookies.debug()`](/api/cypress-api/cookies)              | Generate console logs whenever a cookie is modified.                                                                                                          |
+| [`Cypress.currentRetry`](/api/cypress-api/currentretry)            | A number representing the current test retry count.                                                                                                           |
+| [`Cypress.currentTest`](/api/cypress-api/currenttest)              | An object with information about the currently executing test.                                                                                                |
+| [`Cypress.log`](/api/cypress-api/cypress-log)                      | This is the internal API for controlling what gets printed to the Command Log. Useful when writing your own custom commands.                                  |
+| [`Cypress.dom`](/api/cypress-api/dom)                              | A collection of DOM related helper methods.                                                                                                                   |
+| [`Cypress.ElementSelector`](/api/cypress-api/element-selector-api) | Configure selector priority used by [Cypress Studio](/app/guides/cypress-studio) and [Selector Playground](/app/core-concepts/open-mode#Selector-Playground). |
+| [`Cypress.env`](/api/cypress-api/env)                              | Get environment variables from inside your tests.                                                                                                             |
+| [`Cypress.isBrowser()`](/api/cypress-api/isbrowser)                | Checks if the current browser matches the given name or filter.                                                                                               |
+| [`Cypress.isCy()`](/api/cypress-api/iscy)                          | checks if a variable is a valid instance of cy or a cy chainable.                                                                                             |
+| [`Cypress.Keyboard.defaults()`](/api/cypress-api/keyboard-api)     | Set default values for how the `.type()` command is executed.                                                                                                 |
+| [`Cypress.platform`](/api/cypress-api/platform)                    | The underlaying OS name, as returned by Node's `os.platform()`.                                                                                               |
+| [`Cypress.require`](/api/cypress-api/require)                      | Enables utilizing dependencies within the [cy.origin()](/api/commands/origin) callback function.                                                              |
+| [`Cypress.Screenshot.defaults()`](/api/cypress-api/screenshot-api) | Set defaults for screenshots captured by the `.screenshot()` command and the automatic screenshots taken during test failures.                                |
+| [`Cypress.session`](/api/cypress-api/session)                      | A collection of helper methods related to the `.session()` command.                                                                                           |
+| [`Cypress.spec`](/api/cypress-api/spec)                            | An object with information about the currently executing spec file.                                                                                           |
+| [`Cypress.testingType`](/api/cypress-api/testing-type)             | The current testing type, eg. `"e2e"` or `"component".                                                                                                        |
+| [`Cypress.version`](/api/cypress-api/version)                      | The current Cypress version.                                                                                                                                  |
 
 ## Utilities
 

diff --git a/docs/app/component-testing/angular/overview.mdx b/docs/app/component-testing/angular/overview.mdx
@@ -20,7 +20,7 @@ sidebar_label: Overview
 
 ## Framework Support
 
-Cypress Component Testing supports Angular 17.2.0+.
+Cypress Component Testing supports Angular `^18.0.0` and `^19.0.0`.
 
 ## Tutorial