{
"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": "48b03b5502f7aea1d0454750cce208f775403542",
"updated_at": "2026-05-20T19:00:20.270Z",
"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
}
]
},
"content": {
"type": "root",
"children": [
{
"type": "heading",
"depth": 1,
"children": [
{
"type": "text",
"value": "Cypress.ElementSelector"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The ElementSelector API lets you define how Cypress selects elements in tools like "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/app/guides/cypress-studio.md",
"children": [
{
"type": "text",
"value": "Cypress Studio"
}
]
},
{
"type": "text",
"value": " and "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/prompt.md",
"children": [
{
"type": "text",
"value": "cy.prompt()"
}
]
},
{
"type": "text",
"value": "."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "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."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "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."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "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."
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Syntax"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "Cypress.ElementSelector.defaults(options)"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Arguments"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "options (Object)"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "An object containing any or all of the following options:"
}
]
},
{
"type": "table",
"align": [
null,
null,
null
],
"children": [
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Option"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Accepts"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Description"
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`selectorPriority`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`Array of strings`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Determines the order of attributes Cypress uses to generate selectors."
}
]
}
]
}
]
},
{
"type": "heading",
"depth": 5,
"children": [
{
"type": "text",
"value": "API Stability"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "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 "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/app/references/changelog.md",
"children": [
{
"type": "text",
"value": "changelog"
}
]
},
{
"type": "text",
"value": " for any breaking changes."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Accepted values for `selectorPriority` are:"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`attribute:${string}` - for specific attributes like `attribute:aria-label`, `attribute:lang`, etc."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`attributes` - general fallback for any other attributes"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`class`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`data-${string}` - for specific data attributes like `data-cy`, `data-testid`, etc."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`id`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`name`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`nth-child`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`tag`"
}
]
}
]
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Default Selector Priority"
}
]
},
{
"type": "list",
"ordered": true,
"start": 1,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`data-cy`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`data-test`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`data-testid`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`data-qa`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`name`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`id`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`class`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`tag`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`attributes`"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`nth-child`"
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Consider the following HTML:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": ""
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "With the default selector priority, Cypress prioritizes `id`, so the selector would be `#submit-btn`."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "$el (Object)"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The "
},
{
"type": "link",
"title": null,
"url": "http://api.jquery.com/Types/#jQuery",
"children": [
{
"type": "text",
"value": "jQuery element"
}
]
},
{
"type": "text",
"value": " for which you want to retrieve a selector."
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Examples"
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Set custom selector priority"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "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 "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/app/guides/cypress-studio.md",
"children": [
{
"type": "text",
"value": "Cypress Studio"
}
]
},
{
"type": "text",
"value": " and "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/prompt.md",
"children": [
{
"type": "text",
"value": "cy.prompt()"
}
]
},
{
"type": "text",
"value": ", and is also respected by "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/app/tooling/ai-skills.md",
"children": [
{
"type": "text",
"value": "Cypress AI Skills"
}
]
},
{
"type": "text",
"value": " when your AI coding tool generates selectors."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "For example, this config tells Cypress to prefer semantic and accessibility attributes before falling back to styling details like class names."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "Cypress.ElementSelector.defaults({ selectorPriority: [ 'attribute:role', 'attribute:aria-label', 'name', 'class', 'attributes', ],})"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Prioritize accessible attributes"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Accessibility-first apps often use ARIA roles and labels. You can configure Cypress to prioritize these when generating selectors:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "Cypress.ElementSelector.defaults({ selectorPriority: ['attribute:aria-label', 'attribute:role', 'id', 'class'],})"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "This helps produce more readable and resilient selectors, especially for accessibility-first applications."
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Prioritize language-agnostic selectors (for i18n)"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "In multilingual applications, selectors based on text or labels may change between locales. Prefer stable, language-agnostic attributes like `data-*`, `role`, and `aria-labelledby`."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "Cypress.ElementSelector.defaults({ selectorPriority: [ 'data-cy', 'attribute:role', 'attribute:aria-labelledby', 'name', 'id', 'class', 'attributes', ],})"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "This ensures selectors are resilient to translation changes in text or labels."
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Avoid dynamic or auto-generated selectors"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Many frameworks produce dynamic ids or class names such as:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": ""
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "You can configure Cypress to skip attributes that are dynamically generated."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "Cypress.ElementSelector.defaults({ selectorPriority: [ 'data-cy', 'attribute:role', 'attribute:aria-label', 'name', 'attributes', // fallback // deliberately omit 'id' and 'class' ],})"
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "History"
}
]
},
{
"type": "table",
"align": [
null,
null
],
"children": [
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Version"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Changes"
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/app/references/changelog.md#15-0-0",
"children": [
{
"type": "text",
"value": "15.0.0"
}
]
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Renamed `Cypress.SelectorPlayground` to `Cypress.ElementSelector`."
}
]
}
]
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "See also"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/app/guides/cypress-studio.md",
"children": [
{
"type": "text",
"value": "Cypress Studio"
}
]
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/prompt.md",
"children": [
{
"type": "text",
"value": "cy.prompt()"
}
]
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/app/tooling/ai-skills.md",
"children": [
{
"type": "text",
"value": "Cypress AI Skills"
}
]
}
]
}
]
}
]
}
]
},
"token_estimate": 763
}