{
"doc": {
"id": "accessibility/configuration/components",
"title": "components: add component and team context to Cypress Accessibility selectors",
"description": "Make Cypress Accessibility append component-identifying attributes, such as data-component-name, data-team, or data-page-area, to violation target selectors so every finding shows which component, team, or region it belongs to.",
"section": "accessibility",
"source_path": "/llm/markdown/accessibility/configuration/components.md",
"version": "e6c8d867c21227247f14714fb5690c7c018983c5",
"updated_at": "2026-08-08T12:39:37.868Z",
"headings": [
{
"id": "accessibility/configuration/components#add-component-context-components",
"text": "Add component context - components",
"level": 1
},
{
"id": "accessibility/configuration/components#why-use-components",
"text": "Why use components?",
"level": 2
},
{
"id": "accessibility/configuration/components#how-component-attributes-appear-in-selectors",
"text": "How component attributes appear in selectors",
"level": 2
},
{
"id": "accessibility/configuration/components#scope",
"text": "Scope",
"level": 2
},
{
"id": "accessibility/configuration/components#setting-components",
"text": "Setting components",
"level": 2
},
{
"id": "accessibility/configuration/components#syntax",
"text": "Syntax",
"level": 2
},
{
"id": "accessibility/configuration/components#componentattributes",
"text": "componentAttributes",
"level": 3
},
{
"id": "accessibility/configuration/components#componentattributefilters",
"text": "componentAttributeFilters",
"level": 3
},
{
"id": "accessibility/configuration/components#how-are-components-rules-applied",
"text": "How are components rules applied?",
"level": 3
},
{
"id": "accessibility/configuration/components#validation-rules",
"text": "Validation rules",
"level": 3
},
{
"id": "accessibility/configuration/components#examples",
"text": "Examples",
"level": 2
},
{
"id": "accessibility/configuration/components#append-the-design-system-component-name",
"text": "Append the design-system component name",
"level": 3
},
{
"id": "accessibility/configuration/components#config",
"text": "Config",
"level": 4
},
{
"id": "accessibility/configuration/components#html",
"text": "HTML",
"level": 4
},
{
"id": "accessibility/configuration/components#result",
"text": "Result",
"level": 4
},
{
"id": "accessibility/configuration/components#add-component-and-team-context-together",
"text": "Add component and team context together",
"level": 3
},
{
"id": "accessibility/configuration/components#config",
"text": "Config",
"level": 4
},
{
"id": "accessibility/configuration/components#html",
"text": "HTML",
"level": 4
},
{
"id": "accessibility/configuration/components#result",
"text": "Result",
"level": 4
},
{
"id": "accessibility/configuration/components#add-the-surrounding-page-region",
"text": "Add the surrounding page region",
"level": 3
},
{
"id": "accessibility/configuration/components#config",
"text": "Config",
"level": 4
},
{
"id": "accessibility/configuration/components#html",
"text": "HTML",
"level": 4
},
{
"id": "accessibility/configuration/components#result",
"text": "Result",
"level": 4
},
{
"id": "accessibility/configuration/components#keep-a-generic-component-name-out-of-selectors",
"text": "Keep a generic component name out of selectors",
"level": 3
},
{
"id": "accessibility/configuration/components#config",
"text": "Config",
"level": 4
},
{
"id": "accessibility/configuration/components#html",
"text": "HTML",
"level": 4
},
{
"id": "accessibility/configuration/components#result",
"text": "Result",
"level": 4
},
{
"id": "accessibility/configuration/components#how-components-compares-to-other-options",
"text": "How components compares to other options",
"level": 2
},
{
"id": "accessibility/configuration/components#see-also",
"text": "See also",
"level": 2
}
]
},
"content": {
"type": "root",
"children": [
{
"type": "heading",
"depth": 1,
"children": [
{
"type": "text",
"value": "Add component context - `components`"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The components configuration adds context to the selectors in your accessibility reports. When an element has a violation, Cypress Accessibility shows a violation target selector that points to it. components lets you add your own component-identifying attributes, such as `data-component-name`, `data-team`, or `data-page-area`, to that selector, so a finding reads as `[data-cy=\"signup\"][data-component=\"IconButton\"]` instead of a bare `[data-cy=\"signup\"]`."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "That extra context tells whoever picks up the issue, whether a developer, a Jira ticket, or an "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/work-with-ai-agents.md",
"children": [
{
"type": "text",
"value": "AI agent triaging through Cypress Cloud MCP"
}
]
},
{
"type": "text",
"value": ", which component, team, or region the element belongs to, without having to open the page HTML or search the codebase to place it. Many teams already render attributes like these for testing or design-system tracing; when they exist, components puts them into your selectors in a predictable, consistent way."
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Why use components?"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Place every finding in context: A selector like `[data-cy=\"row-action\"][data-component=\"DataGridDeleteButton\"]` says exactly which component is responsible, where a bare identifier could be any button in your application."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Route issues to the right owner: Append an attribute like `data-team` and you can assign accessibility findings, or group them in a report, by the team that owns the DOM."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Speed up handoffs to people and AI: Selectors that carry component and page context can be dropped into a Jira ticket or handed to an LLM for triage without the surrounding page HTML."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Cross-reference your design system: Attributes such as `data-design-system-version` in the selector let you correlate accessibility issues with the component library version that produced them."
}
]
}
]
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "How component attributes appear in selectors"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Cypress Accessibility identifies each element with a stable selector, replacing the default Axe-Core® target so results for the same element can be deduplicated across the many snapshots in a run. That identifier is chosen from a prioritized list of attributes ("
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/significantattributes.md",
"children": [
{
"type": "text",
"value": "`significantAttributes`"
}
]
},
{
"type": "text",
"value": " followed by defaults like `data-cy` and `id`) and is usually the shortest thing that uniquely identifies the element."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Every attribute you list in `componentAttributes` is treated as required: wherever it appears on the element or one of its ancestors, Cypress keeps it in the selector. Take this button, which fails an accessibility check because its label text is hidden:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": ""
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "By default, the violation target selector is just the identifier:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "[data-cy=\"signup\"]"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Viewed on its own, that could be any button. List `data-component` as a component attribute:"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "App Quality Config"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "{ \"accessibility\": { \"components\": { \"componentAttributes\": [ { \"attributeName\": \"data-component\", \"includeInSelector\": true } ] } }}"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Now the component name is appended, even though the selector was already unique:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "[data-cy=\"signup\"][data-component=\"IconButton\"]"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "When a required attribute is on an ancestor instead of the element itself, Cypress adds it as context with a descendant combinator. Given a `data-page-area` on a wrapping section:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": ""
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "listing `data-page-area` reports the button with that region in front:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "[data-page-area=\"checkout\"] [data-cy=\"pay\"]"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "components adds context on top of whatever already identifies an element. To change which attribute identifies it, use "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/significantattributes.md",
"children": [
{
"type": "text",
"value": "`significantAttributes`"
}
]
},
{
"type": "text",
"value": " instead."
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Scope"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The components object is only valid under an `accessibility` key in your App Quality configuration. Unlike "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/significantattributes.md",
"children": [
{
"type": "text",
"value": "`significantAttributes`"
}
]
},
{
"type": "text",
"value": " or "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/attributefilters.md",
"children": [
{
"type": "text",
"value": "`attributeFilters`"
}
]
},
{
"type": "text",
"value": ", it has no root-level or UI Coverage form. It can also be set inside a "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/profiles.md",
"children": [
{
"type": "text",
"value": "`profiles`"
}
]
},
{
"type": "text",
"value": " entry to apply to tagged runs."
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Setting components"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "To add or edit components, open the App Quality tab in your project settings in Cypress Cloud. See "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/overview.md#Setting-Configuration",
"children": [
{
"type": "text",
"value": "Setting configuration"
}
]
},
{
"type": "text",
"value": " for details, including how to regenerate past reports with a new configuration without rerunning your tests."
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Syntax"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "App Quality Config"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "{ \"accessibility\": { \"components\": { \"componentAttributes\": [ { \"attributeName\": string, \"includeInSelector\": boolean, \"comment\": string } ], \"componentAttributeFilters\": [ { \"attribute\": string, \"value\": string, \"include\": boolean, \"comment\": string } ], \"comment\": string } }}"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "`componentAttributes`"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Each entry names an attribute to append to the selector when it's present on the element with the violation. Attribute names are stored in lowercase and must be unique in the list."
}
]
},
{
"type": "table",
"align": [
null,
null,
null,
null
],
"children": [
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Option"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Required"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Default"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Description"
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`attributeName`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Yes"
}
]
},
{
"type": "tableCell",
"children": []
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "The HTML attribute name to append, for example `data-component-name`. `class` is also supported."
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`includeInSelector`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "No"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`true`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "When `true`, the attribute is appended to the selector wherever the element has it."
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`comment`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "No"
}
]
},
{
"type": "tableCell",
"children": []
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "A note for your team explaining why the entry exists. Comments never appear in reports."
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "When `includeInSelector` is `false`, the entry is kept for documentation or future use but doesn't change selector generation, the same as leaving it out."
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "`componentAttributeFilters`"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "These filters fine-tune which attribute values are appended. They apply only to the attributes in `componentAttributes`, using the same regular-expression style as "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/attributefilters.md",
"children": [
{
"type": "text",
"value": "`attributeFilters`"
}
]
},
{
"type": "text",
"value": ": `attribute` and `value` are regex patterns. For a given attribute value, the first rule whose `attribute` and `value` both match decides whether it's appended. A filter with no matching `componentAttributes` entry does nothing."
}
]
},
{
"type": "table",
"align": [
null,
null,
null,
null
],
"children": [
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Option"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Required"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Default"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Description"
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`attribute`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Yes"
}
]
},
{
"type": "tableCell",
"children": []
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Regex matched against the component attribute's name."
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`value`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "No"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`.*`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Regex matched against the attribute's value."
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`include`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "No"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`true`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "When `false`, matching values are not appended to the selector."
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`comment`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "No"
}
]
},
{
"type": "tableCell",
"children": []
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "A note for your team. Comments never appear in reports."
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Use `include: false` to keep a noisy or generic value out of your selectors, such as a layout primitive whose name adds no context, while still appending the meaningful ones."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "You can also add a `comment` to the components object itself to document the whole block. Comments are for your team, never appear in reports, and are the supported place for notes because Cypress Cloud rejects properties it doesn't recognize. See "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/overview.md#Comments",
"children": [
{
"type": "text",
"value": "Comments"
}
]
},
{
"type": "text",
"value": "."
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "How are components rules applied?"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Keep these behaviors in mind when building your configuration:"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Listed attributes are kept wherever they appear. A component attribute on the element is appended to its selector; the same attribute on an ancestor is added in front as descendant-combinator context. An element whose ancestor chain has none of the listed attributes is unaffected."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "They're added on top of the identifier, not instead of it. The element is still identified by `significantAttributes` and the defaults; component attributes add context. They're added even when the selector is already unique."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "They help with uniqueness and deduplication. Because a required attribute is part of the selector, one that distinguishes the element can make the selector shorter and more stable than the positional fallback Cypress would use otherwise, which keeps the same element from splitting into several across snapshots."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "On one element, appended attributes follow your list order. Multiple attributes appended to the same element appear in the order you list them in `componentAttributes`. An attribute that already identifies the element isn't added a second time."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Default attribute filters don't apply here. The "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/attributefilters.md",
"children": [
{
"type": "text",
"value": "default filters"
}
]
},
{
"type": "text",
"value": " that keep dynamic, UUID-like values out of identifying selectors don't touch component attributes. `componentAttributeFilters` are the only way to exclude component-attribute values, so list a rule if an attribute's value is sometimes noisy."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`class` is supported. Listing `class` as a component attribute appends the element's class value; `componentAttributeFilters` apply to it the same way."
}
]
}
]
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Validation rules"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Cypress Cloud validates the whole configuration before saving it and rejects a components block that breaks any of these:"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Each `attributeName` must be a valid HTML attribute name. Names are compared in lowercase and must be unique across `componentAttributes`."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Each `componentAttributeFilters` `attribute` and `value` must be a valid regular expression."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "No two `componentAttributeFilters` rules may be identical across `attribute`, `value`, and `include`."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Only the properties documented above are allowed. An unrecognized key is rejected rather than ignored."
}
]
}
]
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Examples"
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Append the design-system component name"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The button below fails `button-name` because its label is hidden. It carries a `data-cy` test id and a `data-component` name from the design system. Listing `data-component` appends the component name to the selector, so the finding names the component instead of a generic id."
}
]
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Config"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "App Quality Config"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "{ \"accessibility\": { \"components\": { \"componentAttributes\": [ { \"attributeName\": \"data-component\", \"includeInSelector\": true } ] } }}"
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "HTML"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": ""
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Result"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The violation target selector displayed in the report:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "[data-cy=\"signup\"][data-component=\"IconButton\"]"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Add component and team context together"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`componentAttributes` is a list, so you can append more than one attribute. Here the design-system component name and the owning team are both added, so findings can be read, filtered, or assigned by either."
}
]
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Config"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "App Quality Config"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "{ \"accessibility\": { \"components\": { \"componentAttributes\": [ { \"attributeName\": \"data-component\", \"includeInSelector\": true }, { \"attributeName\": \"data-team\", \"includeInSelector\": true } ] } }}"
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "HTML"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "![](\"hero.png\"/)
"
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Result"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The image fails `image-alt`, and its selector now shows the component and the team that owns it:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "[data-testid=\"hero-banner\"][data-component=\"HeroBanner\"][data-team=\"marketing\"]"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Add the surrounding page region"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Component attributes don't have to be on the element itself. When a listed attribute sits on an ancestor, such as a `data-page-area` on the wrapping landmark, Cypress adds it in front of the identifier as context, so a violation reads as belonging to a region of the page."
}
]
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Config"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "App Quality Config"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "{ \"accessibility\": { \"components\": { \"componentAttributes\": [ { \"attributeName\": \"data-page-area\", \"includeInSelector\": true } ] } }}"
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "HTML"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": ""
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Result"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The button is identified by its own `data-cy`, with the region prepended as ancestor context:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "[data-page-area=\"global-header\"] [data-cy=\"menu-toggle\"]"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Keep a generic component name out of selectors"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Some component names add no context. A layout primitive like `Box` wraps elements all over the application, so appending it to every selector is noise. Keep `data-component` appended in general, but use a `componentAttributeFilters` rule to skip the values that don't help."
}
]
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Config"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "App Quality Config"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "{ \"accessibility\": { \"components\": { \"componentAttributes\": [ { \"attributeName\": \"data-component\", \"includeInSelector\": true } ], \"componentAttributeFilters\": [ { \"attribute\": \"data-component\", \"value\": \"^(Box|Stack|Flex)$\", \"include\": false, \"comment\": \"Layout primitives add no useful context\" } ] } }}"
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "HTML"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": ""
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Result"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The meaningful component name is appended; the layout primitive is filtered out, leaving that element on its identifier alone:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "[data-cy=\"row-delete\"][data-component=\"DataGridDeleteButton\"][data-cy=\"page-close\"]"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "After saving configuration changes, regenerate a recent run to preview the effect of your rules without rerunning your tests. See "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/overview.md#Setting-Configuration",
"children": [
{
"type": "text",
"value": "Setting configuration"
}
]
},
{
"type": "text",
"value": " for how to regenerate a report."
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "How components compares to other options"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Three configuration properties all work with attributes, but they do different jobs:"
}
]
},
{
"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/accessibility/configuration/significantattributes.md",
"children": [
{
"type": "text",
"value": "`significantAttributes`"
}
]
},
{
"type": "text",
"value": " chooses the single attribute that identifies the element and becomes its selector."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/attributefilters.md",
"children": [
{
"type": "text",
"value": "`attributeFilters`"
}
]
},
{
"type": "text",
"value": " removes dynamic or generated attribute values from identification, so they can't be used as selectors."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "components adds context to the selector, from the element or its ancestors, on top of whatever identifies the element, without changing which attribute identifies it."
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "For background on how Cypress picks identifiers, see "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/core-concepts/element-identification.md",
"children": [
{
"type": "text",
"value": "Element identification"
}
]
},
{
"type": "text",
"value": "."
}
]
},
{
"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/accessibility/core-concepts/element-identification.md",
"children": [
{
"type": "text",
"value": "Element identification"
}
]
},
{
"type": "text",
"value": ": how elements are identified across snapshots."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/significantattributes.md",
"children": [
{
"type": "text",
"value": "`significantAttributes`"
}
]
},
{
"type": "text",
"value": ": choose which attribute identifies an element."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/attributefilters.md",
"children": [
{
"type": "text",
"value": "`attributeFilters`"
}
]
},
{
"type": "text",
"value": ": stop dynamic or generated attribute values from identifying elements."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/guides/inspecting-violation-details.md",
"children": [
{
"type": "text",
"value": "Inspecting violation details"
}
]
},
{
"type": "text",
"value": ": where violation target selectors appear in reports."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/work-with-ai-agents.md",
"children": [
{
"type": "text",
"value": "Work with AI agents"
}
]
},
{
"type": "text",
"value": ": triage findings through Cypress Cloud MCP."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/configuration/overview.md",
"children": [
{
"type": "text",
"value": "Configuration overview"
}
]
},
{
"type": "text",
"value": ": where to set configuration and regenerate reports."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/accessibility/faq.md",
"children": [
{
"type": "text",
"value": "Cypress Accessibility FAQ"
}
]
},
{
"type": "text",
"value": ": common questions and troubleshooting."
}
]
}
]
}
]
}
]
},
"token_estimate": 2575
}