diff --git a/docs/api/cypress-api/element-selector-api.mdx b/docs/api/cypress-api/element-selector-api.mdx
new file mode 100644
index 0000000000..c07aa88076
--- /dev/null
+++ b/docs/api/cypress-api/element-selector-api.mdx
@@ -0,0 +1,101 @@
+---
+title: 'Cypress.ElementSelector | Cypress Documentation'
+description: 'The Element Selector exposes APIs that enable you to change the default selector strategy and override the selectors that are returned per element.'
+sidebar_label: ElementSelector
+sidebar_position: 105
+---
+
+
+
+# Cypress.ElementSelector
+
+The Element Selector API is used to get the selector priority for selecting elements in [Cypress Studio](/app/guides/cypress-studio) and [Selector Playground](/app/core-concepts/open-mode#Selector-Playground).
+
+## Syntax
+
+```javascript
+Cypress.ElementSelector.defaults(options)
+Cypress.ElementSelector.getSelector($el)
+```
+
+### Arguments
+
+ **options _(Object)_**
+
+An object containing any or all of the following options:
+
+| Option | Accepts | Description |
+| ------------------ | ------------------ | -------------------------------------------------------------------------------- |
+| `selectorPriority` | `Array of strings` | Determines the order of preference for which selector is chosen for the element. |
+
+`selectorPriority` accepts the following strings:
+
+- `attribute:${string}`
+- `attributes`
+- `class`
+- `data-${string}`
+- `id`
+- `name`
+- `nth-child`
+- `tag`
+
+
+
+ **$el _(Object)_**
+
+The [jQuery element](http://api.jquery.com/Types/#jQuery) that you want to get
+the selector value for.
+
+## Examples
+
+### Selector Priority
+
+Set the selector priority to favor role, then aria-label, then name, then classes, then attributes.
+
+```javascript
+Cypress.ElementSelector.defaults({
+ selectorPriority: [
+ 'attribute:role',
+ 'attribute:aria-label',
+ 'name',
+ 'class',
+ 'attributes',
+ ],
+})
+```
+
+### Get Selector
+
+Returns you the selector value for a given element as determined by the selector
+strategy. This is useful for debugging custom selector priorities you have set.
+
+For example, consider this HTML fragment:
+
+```html
+
+```
+
+With the default selector strategy, the selector value will be `'#bingo'`
+because IDs have priority over classes.
+
+```js
+const $el = Cypress.$('button')
+const selector = Cypress.ElementSelector.getSelector($el) // '#bingo'
+```
+
+With a custom selector strategy that favours classes, the selector value will be
+`'.number3'`.
+
+```js
+Cypress.ElementSelector.defaults({
+ selectorPriority: ['class', 'id'],
+})
+
+const $el = Cypress.$('button')
+const selector = Cypress.ElementSelector.getSelector($el) // '.number3'
+```
+
+## 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
deleted file mode 100644
index b2b700a060..0000000000
--- a/docs/api/cypress-api/selector-playground-api.mdx
+++ /dev/null
@@ -1,100 +0,0 @@
----
-title: 'Cypress.SelectorPlayground | Cypress Documentation'
-description: 'The Selector Playground exposes APIs that enable you to change the default selector strategy and override the selectors that are returned per element.'
-sidebar_label: SelectorPlayground
----
-
-
-
-# Cypress.SelectorPlayground
-
-The [Selector Playground](/app/core-concepts/open-mode#Selector-Playground)
-exposes APIs that enable you to:
-
-- Change the default selector strategy
-- Override the selectors that are returned per element
-
-## Syntax
-
-```javascript
-Cypress.SelectorPlayground.defaults(options)
-Cypress.SelectorPlayground.getSelector($el)
-```
-
-### Arguments
-
- **options _(Object)_**
-
-An object containing any or all of the following options:
-
-| Option | Accepts | Description |
-| ------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `selectorPriority` | `Array of strings` | Determines the order of preference for which selector is chosen for the element. |
-| `onElement` | `function` | A function called with the element that should return a unique selector string for the element. If a falsey value is returned, the default selector function is used. |
-
-
-
- **$el _(Object)_**
-
-The [jQuery element](http://api.jquery.com/Types/#jQuery) that you want to get
-the selector value for.
-
-## Examples
-
-### Selector Priority
-
-Set the selector priority to favor IDs, then classes, then attributes.
-
-```javascript
-Cypress.SelectorPlayground.defaults({
- selectorPriority: ['id', 'class', 'attributes'],
-})
-```
-
-### onElement Callback
-
-Set a custom function for determining the selector for an element. Falls back to
-default behavior if returning a falsey value.
-
-```javascript
-Cypress.SelectorPlayground.defaults({
- onElement: ($el) => {
- const customId = $el.attr('my-custom-attr')
-
- if (customId) {
- return `[my-custom-attr=${customId}]`
- }
- },
-})
-```
-
-### Get Selector
-
-Returns you the selector value for a given element as determined by the selector
-strategy.
-
-For example, consider this HTML fragment.
-
-```html
-
-```
-
-With the default selector strategy, the selector value will be `'#bingo'`
-because IDs have priority over classes.
-
-```js
-const $el = Cypress.$('button')
-const selector = Cypress.SelectorPlayground.getSelector($el) // '#bingo'
-```
-
-With a custom selector strategy that favours classes, the selector value will be
-`'.number3'`.
-
-```js
-Cypress.SelectorPlayground.defaults({
- selectorPriority: ['class', 'id'],
-})
-
-const $el = Cypress.$('button')
-const selector = Cypress.SelectorPlayground.getSelector($el) // '.number3'
-```
diff --git a/docs/api/table-of-contents.mdx b/docs/api/table-of-contents.mdx
index 01c2a7f43f..3eb8becefb 100644
--- 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/core-concepts/open-mode.mdx b/docs/app/core-concepts/open-mode.mdx
index ea937ea614..b206e22705 100644
--- a/docs/app/core-concepts/open-mode.mdx
+++ b/docs/app/core-concepts/open-mode.mdx
@@ -559,19 +559,16 @@ interactions.
title="Selector Playground demo"
/>
-### Uniqueness
+### How are selectors determined?
-Cypress will automatically calculate a **unique selector** to use targeted
+Cypress will automatically calculate a **unique selector** to use for a targeted
element by running through a series of selector strategies.
-:::info
-
-Cypress allows you to control how a selector is determined. Use the [Cypress.SelectorPlayground](/api/cypress-api/selector-playground-api)
-API to control the selectors you want returned.
-
-:::
+Cypress allows you to control how a selector is determined. Use the
+[`Cypress.ElementSelector`](/api/cypress-api/element-selector-api) API to control
+the selectors you want prioritized.
### Best practices
diff --git a/docs/app/guides/cypress-studio.mdx b/docs/app/guides/cypress-studio.mdx
index 1795761aeb..f3fd044b8b 100644
--- a/docs/app/guides/cypress-studio.mdx
+++ b/docs/app/guides/cypress-studio.mdx
@@ -19,7 +19,6 @@ e2eSpecific: true
:::
-
## Overview
Cypress Studio makes test creation faster and easier. With Studio, you can record user interactions in the browser and instantly generate Cypress test code. Add assertions with a rightclick and fine-tune your tests inline.
@@ -84,9 +83,16 @@ You can also extend and update existing tests using Cypress Studio.
5. Right-click to add assertions
6. Click **Save** to save the changes to your spec file
-The selectors are generated according to the
-[`Cypress.ElementSelector` selector priority](/api/cypress-api/selector-playground-api#Default-Selector-Priority).
+### How are selectors determined?
+
+Cypress will automatically calculate a **unique selector** to use for a targeted
+element by running through a series of selector strategies.
+
+
+Cypress allows you to control how a selector is determined. Use the
+[`Cypress.ElementSelector`](/api/cypress-api/element-selector-api) API to control
+the selectors you want prioritized.
## Limitations
diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx
index d3ba0851ec..dfdad48c99 100644
--- a/docs/app/references/changelog.mdx
+++ b/docs/app/references/changelog.mdx
@@ -12,7 +12,6 @@ sidebar_label: Changelog
_Released 7/01/2025 (PENDING)_
-
## 14.5.0
_Released 6/17/2025_
@@ -1831,7 +1830,7 @@ _Released 1/24/2023_
configured to exclude files with those extensions. Addresses
[#24495](https://github.com/cypress-io/cypress/issues/24495).
- Added support for the `data-qa` selector in the
- [Selector Playground](/api/cypress-api/selector-playground-api) in addition to
+ Selector Playground in addition to
`data-cy`, `data-test` and `data-testid`. Addresses
[#25305](https://github.com/cypress-io/cypress/issues/25305).
@@ -10886,14 +10885,14 @@ _Released 3/1/2018_
has been updated to automatically prefer `data-cy`, `data-test` or
`data-testid` attributes when providing the unique selector for an element.
Additionally it now exposes a
- [public API](/api/cypress-api/selector-playground-api) that you can use to
+ public API that you can use to
control how it determines which selector to use. Fixes
[#1135](https://github.com/cypress-io/cypress/issues/1135).
**Documentation Changes:**
- [Added `Selector Playground Guide`](/app/core-concepts/open-mode#Selector-Playground)
-- [Added `Selector Playground API`](/api/cypress-api/selector-playground-api)
+- Added `Selector Playground API`
- [Updated `Best Practices`](/app/core-concepts/best-practices)
- [Updated `FAQ`](/app/faq)
- [Updated `Introduction to Cypress`](/app/core-concepts/introduction-to-cypress)
diff --git a/docs/app/references/migration-guide.mdx b/docs/app/references/migration-guide.mdx
index 121157b1b8..e721cc35a1 100644
--- a/docs/app/references/migration-guide.mdx
+++ b/docs/app/references/migration-guide.mdx
@@ -144,6 +144,32 @@ import { mount } from `cypress/angular`
import { mount } from `@cypress/angular`
```
+### Selector Playground API changes
+
+The `Cypress.SelectorPlayground` API has been renamed to
+[`Cypress.ElementSelector`](/api/cypress-api/element-selector-api). Additionally, the `onElement` function has been removed as an option to the `defaults` method.
+
+This change was made in order to reflect its use in features beyond just the Selector Playground - like Cypress Studio.
+
+The following code shows how to migrate from the `Cypress.SelectorPlayground` API to the
+[`Cypress.ElementSelector`](/api/cypress-api/element-selector-api) API.
+
+Before{' '}
+
+```ts
+Cypress.SelectorPlayground.defaults({
+ selectorPriority: ['class', 'id'],
+})
+```
+
+After
+
+```ts
+Cypress.ElementSelector.defaults({
+ selectorPriority: ['class', 'id'],
+})
+```
+
## Migrating to Cypress 14.0
This guide details the code changes needed to migrate to Cypress
diff --git a/docs/partials/_default-selector-priority.mdx b/docs/partials/_default-selector-priority.mdx
index 5940fe01ab..71e8eed843 100644
--- a/docs/partials/_default-selector-priority.mdx
+++ b/docs/partials/_default-selector-priority.mdx
@@ -4,8 +4,9 @@
2. `data-test`
3. `data-testid`
4. `data-qa`
-5. `id`
-6. `class`
-7. `tag`
-8. `attributes`
-9. `nth-child`
+5. `name`
+6. `id`
+7. `class`
+8. `tag`
+9. `attributes`
+10. `nth-child`