{
"doc": {
"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": "/llm/markdown/api/cypress-api/element-selector-api.md",
"version": "24a73f8a97175663aaffd3b016289fb2a523a4ea",
"updated_at": "2026-05-14T20:17:33.301Z",
"headings": [
{
"id": "api/cypress-api/element-selector-api#cypress-elementselector",
"text": "Cypress.ElementSelector",
"level": 1
},
{
"id": "api/cypress-api/element-selector-api#syntax",
"text": "Syntax",
"level": 2
},
{
"id": "api/cypress-api/element-selector-api#arguments",
"text": "Arguments",
"level": 3
},
{
"id": "api/cypress-api/element-selector-api#api-stability",
"text": "API Stability",
"level": 5
},
{
"id": "api/cypress-api/element-selector-api#default-selector-priority",
"text": "Default Selector Priority",
"level": 3
},
{
"id": "api/cypress-api/element-selector-api#examples",
"text": "Examples",
"level": 2
},
{
"id": "api/cypress-api/element-selector-api#set-custom-selector-priority",
"text": "Set custom selector priority",
"level": 3
},
{
"id": "api/cypress-api/element-selector-api#prioritize-accessible-attributes",
"text": "Prioritize accessible attributes",
"level": 3
},
{
"id": "api/cypress-api/element-selector-api#prioritize-language-agnostic-selectors-for-i18n",
"text": "Prioritize language-agnostic selectors (for i18n)",
"level": 3
},
{
"id": "api/cypress-api/element-selector-api#avoid-dynamic-or-auto-generated-selectors",
"text": "Avoid dynamic or auto-generated selectors",
"level": 3
},
{
"id": "api/cypress-api/element-selector-api#history",
"text": "History",
"level": 2
},
{
"id": "api/cypress-api/element-selector-api#see-also",
"text": "See also",
"level": 2
}
]
},
"chunks": [
{
"id": "api/cypress-api/element-selector-api#syntax",
"doc_id": "api/cypress-api/element-selector-api",
"heading": "Syntax",
"heading_level": 2,
"content_markdown": "## Syntax\n\n```\nCypress.ElementSelector.defaults(options)\n```\n\n### Arguments\n\n**options _(Object)_**\n\nAn object containing any or all of the following options:\n\n| Option | Accepts | Description |\n| --- | --- | --- |\n| `selectorPriority` | `Array of strings` | Determines the order of attributes Cypress uses to generate selectors. |\n\n##### API Stability\n\nThe `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.\n\nAccepted values for `selectorPriority` are:\n\n* `attribute:${string}` - for specific attributes like `attribute:aria-label`, `attribute:lang`, etc.\n* `attributes` - general fallback for any other attributes\n* `class`\n* `data-${string}` - for specific data attributes like `data-cy`, `data-testid`, etc.\n* `id`\n* `name`\n* `nth-child`\n* `tag`\n\n### Default Selector Priority\n\n1. `data-cy`\n2. `data-test`\n3. `data-testid`\n4. `data-qa`\n5. `name`\n6. `id`\n7. `class`\n8. `tag`\n9. `attributes`\n10. `nth-child`\n\nConsider the following HTML:\n\n```\n\n```\n\nWith the default selector priority, Cypress prioritizes `id`, so the selector would be `#submit-btn`.\n\n**$el _(Object)_**\n\nThe [jQuery element](http://api.jquery.com/Types/#jQuery) for which you want to retrieve a selector.\n",
"section": "api",
"anchors": [
"syntax"
],
"path": "/llm/json/chunked/api/cypress-api/element-selector-api.json",
"token_estimate": 261
},
{
"id": "api/cypress-api/element-selector-api#arguments",
"doc_id": "api/cypress-api/element-selector-api",
"heading": "Arguments",
"heading_level": 3,
"content_markdown": "### Arguments\n\n**options _(Object)_**\n\nAn object containing any or all of the following options:\n\n| Option | Accepts | Description |\n| --- | --- | --- |\n| `selectorPriority` | `Array of strings` | Determines the order of attributes Cypress uses to generate selectors. |\n\n##### API Stability\n\nThe `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.\n\nAccepted values for `selectorPriority` are:\n\n* `attribute:${string}` - for specific attributes like `attribute:aria-label`, `attribute:lang`, etc.\n* `attributes` - general fallback for any other attributes\n* `class`\n* `data-${string}` - for specific data attributes like `data-cy`, `data-testid`, etc.\n* `id`\n* `name`\n* `nth-child`\n* `tag`\n",
"section": "api",
"anchors": [
"arguments"
],
"path": "/llm/json/chunked/api/cypress-api/element-selector-api.json",
"token_estimate": 171
},
{
"id": "api/cypress-api/element-selector-api#api-stability",
"doc_id": "api/cypress-api/element-selector-api",
"heading": "API Stability",
"heading_level": 5,
"content_markdown": "##### API Stability\n\nThe `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.\n\nAccepted values for `selectorPriority` are:\n\n* `attribute:${string}` - for specific attributes like `attribute:aria-label`, `attribute:lang`, etc.\n* `attributes` - general fallback for any other attributes\n* `class`\n* `data-${string}` - for specific data attributes like `data-cy`, `data-testid`, etc.\n* `id`\n* `name`\n* `nth-child`\n* `tag`\n",
"section": "api",
"anchors": [
"api-stability"
],
"path": "/llm/json/chunked/api/cypress-api/element-selector-api.json",
"token_estimate": 109
},
{
"id": "api/cypress-api/element-selector-api#default-selector-priority",
"doc_id": "api/cypress-api/element-selector-api",
"heading": "Default Selector Priority",
"heading_level": 3,
"content_markdown": "### Default Selector Priority\n\n1. `data-cy`\n2. `data-test`\n3. `data-testid`\n4. `data-qa`\n5. `name`\n6. `id`\n7. `class`\n8. `tag`\n9. `attributes`\n10. `nth-child`\n\nConsider the following HTML:\n\n```\n\n```\n\nWith the default selector priority, Cypress prioritizes `id`, so the selector would be `#submit-btn`.\n\n**$el _(Object)_**\n\nThe [jQuery element](http://api.jquery.com/Types/#jQuery) for which you want to retrieve a selector.\n",
"section": "api",
"anchors": [
"default-selector-priority"
],
"path": "/llm/json/chunked/api/cypress-api/element-selector-api.json",
"token_estimate": 84
},
{
"id": "api/cypress-api/element-selector-api#examples",
"doc_id": "api/cypress-api/element-selector-api",
"heading": "Examples",
"heading_level": 2,
"content_markdown": "## Examples\n\n### Set custom selector priority\n\nYou 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.\n\nFor example, this config tells Cypress to prefer semantic and accessibility attributes before falling back to styling details like class names.\n\n```\nCypress.ElementSelector.defaults({ selectorPriority: [ 'attribute:role', 'attribute:aria-label', 'name', 'class', 'attributes', ],})\n```\n\n### Prioritize accessible attributes\n\nAccessibility-first apps often use ARIA roles and labels. You can configure Cypress to prioritize these when generating selectors:\n\n```\nCypress.ElementSelector.defaults({ selectorPriority: ['attribute:aria-label', 'attribute:role', 'id', 'class'],})\n```\n\nThis helps produce more readable and resilient selectors, especially for accessibility-first applications.\n\n### Prioritize language-agnostic selectors (for i18n)\n\nIn multilingual applications, selectors based on text or labels may change between locales. Prefer stable, language-agnostic attributes like `data-*`, `role`, and `aria-labelledby`.\n\n```\nCypress.ElementSelector.defaults({ selectorPriority: [ 'data-cy', 'attribute:role', 'attribute:aria-labelledby', 'name', 'id', 'class', 'attributes', ],})\n```\n\nThis ensures selectors are resilient to translation changes in text or labels.\n\n### Avoid dynamic or auto-generated selectors\n\nMany frameworks produce dynamic ids or class names such as:\n\n```\n\n```\n\nYou can configure Cypress to skip attributes that are dynamically generated.\n\n```\nCypress.ElementSelector.defaults({ selectorPriority: [ 'data-cy', 'attribute:role', 'attribute:aria-label', 'name', 'attributes', // fallback // deliberately omit 'id' and 'class' ],})\n```\n",
"section": "api",
"anchors": [
"examples"
],
"path": "/llm/json/chunked/api/cypress-api/element-selector-api.json",
"token_estimate": 312
},
{
"id": "api/cypress-api/element-selector-api#set-custom-selector-priority",
"doc_id": "api/cypress-api/element-selector-api",
"heading": "Set custom selector priority",
"heading_level": 3,
"content_markdown": "### Set custom selector priority\n\nYou 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.\n\nFor example, this config tells Cypress to prefer semantic and accessibility attributes before falling back to styling details like class names.\n\n```\nCypress.ElementSelector.defaults({ selectorPriority: [ 'attribute:role', 'attribute:aria-label', 'name', 'class', 'attributes', ],})\n```\n",
"section": "api",
"anchors": [
"set-custom-selector-priority"
],
"path": "/llm/json/chunked/api/cypress-api/element-selector-api.json",
"token_estimate": 109
},
{
"id": "api/cypress-api/element-selector-api#prioritize-accessible-attributes",
"doc_id": "api/cypress-api/element-selector-api",
"heading": "Prioritize accessible attributes",
"heading_level": 3,
"content_markdown": "### Prioritize accessible attributes\n\nAccessibility-first apps often use ARIA roles and labels. You can configure Cypress to prioritize these when generating selectors:\n\n```\nCypress.ElementSelector.defaults({ selectorPriority: ['attribute:aria-label', 'attribute:role', 'id', 'class'],})\n```\n\nThis helps produce more readable and resilient selectors, especially for accessibility-first applications.\n",
"section": "api",
"anchors": [
"prioritize-accessible-attributes"
],
"path": "/llm/json/chunked/api/cypress-api/element-selector-api.json",
"token_estimate": 56
},
{
"id": "api/cypress-api/element-selector-api#prioritize-language-agnostic-selectors-for-i18n",
"doc_id": "api/cypress-api/element-selector-api",
"heading": "Prioritize language-agnostic selectors (for i18n)",
"heading_level": 3,
"content_markdown": "### Prioritize language-agnostic selectors (for i18n)\n\nIn multilingual applications, selectors based on text or labels may change between locales. Prefer stable, language-agnostic attributes like `data-*`, `role`, and `aria-labelledby`.\n\n```\nCypress.ElementSelector.defaults({ selectorPriority: [ 'data-cy', 'attribute:role', 'attribute:aria-labelledby', 'name', 'id', 'class', 'attributes', ],})\n```\n\nThis ensures selectors are resilient to translation changes in text or labels.\n",
"section": "api",
"anchors": [
"prioritize-language-agnostic-selectors-for-i18n"
],
"path": "/llm/json/chunked/api/cypress-api/element-selector-api.json",
"token_estimate": 71
},
{
"id": "api/cypress-api/element-selector-api#avoid-dynamic-or-auto-generated-selectors",
"doc_id": "api/cypress-api/element-selector-api",
"heading": "Avoid dynamic or auto-generated selectors",
"heading_level": 3,
"content_markdown": "### Avoid dynamic or auto-generated selectors\n\nMany frameworks produce dynamic ids or class names such as:\n\n```\n\n```\n\nYou can configure Cypress to skip attributes that are dynamically generated.\n\n```\nCypress.ElementSelector.defaults({ selectorPriority: [ 'data-cy', 'attribute:role', 'attribute:aria-label', 'name', 'attributes', // fallback // deliberately omit 'id' and 'class' ],})\n```\n",
"section": "api",
"anchors": [
"avoid-dynamic-or-auto-generated-selectors"
],
"path": "/llm/json/chunked/api/cypress-api/element-selector-api.json",
"token_estimate": 73
}
]
}