{
  "doc": {
    "id": "accessibility/configuration/components",
    "title": "Components | Cypress Accessibility",
    "description": "The accessibility `components` configuration controls how component-related HTML attributes appear in stable violation-target selectors.",
    "section": "accessibility",
    "source_path": "/llm/markdown/accessibility/configuration/components.md",
    "version": "3cf5b86b3403f604bdf7f3e35025c3bc3865e02c",
    "updated_at": "2026-05-07T17:44:31.931Z",
    "headings": [
      {
        "id": "accessibility/configuration/components#components",
        "text": "components",
        "level": 1
      },
      {
        "id": "accessibility/configuration/components#why-use-this",
        "text": "Why use this?",
        "level": 2
      },
      {
        "id": "accessibility/configuration/components#scope",
        "text": "Scope",
        "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#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "accessibility/configuration/components#require-a-component-slot-attribute",
        "text": "Require a component slot attribute",
        "level": 3
      },
      {
        "id": "accessibility/configuration/components#require-multiple-attributes",
        "text": "Require multiple attributes",
        "level": 3
      },
      {
        "id": "accessibility/configuration/components#skip-injection-for-specific-attribute-values",
        "text": "Skip injection for specific attribute values",
        "level": 3
      },
      {
        "id": "accessibility/configuration/components#comparison-to-other-config-properties",
        "text": "Comparison to other config properties",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "accessibility/configuration/components#why-use-this",
      "doc_id": "accessibility/configuration/components",
      "heading": "Why use this?",
      "heading_level": 2,
      "content_markdown": "## Why use this?\n\nThis can improve the readability of selectors and make it easier to work with your accessibility findings. Many teams already have attributes like this for testing purposes or component identification when debugging and tracing things back to the design system or other source. If not, it can be easy to add them.\n\nThis is especially useful for handoffs between people or systems, because it can prevent the need to go back to the full page HTML contents just to understand where something is or what code is responsible for it. Here are some examples:\n\n*   Reference elements in a Jira ticket\n*   Process elements with an LLM to propose solutions or triage them\n*   Assign team ownership based on signals in the DOM\n*   Cross-reference accessibility issues with design system versions\n\nWe have seen that customers have attributes like `data-team`, `data-cy-component`, `data-component-filepath`, `data-design-system-version` in projects currently tested with Cypress Accessibility.\n",
      "section": "accessibility",
      "anchors": [
        "why-use-this"
      ],
      "path": "/llm/json/chunked/accessibility/configuration/components.json",
      "token_estimate": 205
    },
    {
      "id": "accessibility/configuration/components#syntax",
      "doc_id": "accessibility/configuration/components",
      "heading": "Syntax",
      "heading_level": 2,
      "content_markdown": "## Syntax\n\n```\n{  \"accessibility\": {    \"components\": {      \"componentAttributes\": [        {          \"attributeName\": string,          \"includeInSelector\": boolean,          \"comment\": string        }      ],      \"componentAttributeFilters\": [        {          \"attribute\": string,          \"value\": string,          \"include\": boolean,          \"comment\": string        }      ],      \"comment\": string    }  }}\n```\n\n### `componentAttributes`\n\nEach entry names an attribute that may be **required** in the generated selector when it is present on the element. Attribute names are stored case-insensitively and **must be unique** in the list.\n\n| Option | Required | Default | Description |\n| --- | --- | --- | --- |\n| `attributeName` | Required |  | The HTML attribute name (for example, `data-component-name`). |\n| `includeInSelector` | Optional | `true` | When `true`, the attribute is eligible to appear as a required segment in the stable selector. |\n| `comment` | Optional |  | Optional note for your team explaining why this entry exists. |\n\nWhen `includeInSelector` is `false`, the attribute is listed for documentation or future use but does not change selector generation (equivalent to omitting it for selector purposes).\n\n### `componentAttributeFilters`\n\nThese filters fine-tune **which attribute values** actually receive the required-attribute treatment from `componentAttributes`. They use the same regular-expression style as [`attributeFilters`](/llm/markdown/accessibility/configuration/attributefilters.md): `attribute` and `value` are regex patterns. **The first rule that matches both the attribute name and value** controls whether that value is included.\n\n| Option | Required | Default | Description |\n| --- | --- | --- | --- |\n| `attribute` | Required |  | Regex string matched against the attribute name. |\n| `value` | Optional | `.*` | Regex string matched against the attribute value. |\n| `include` | Optional | `true` | If `false`, matching values skip required injection for component attributes. |\n| `comment` | Optional |  | Optional note for maintainers. |\n\nUse `include: false` to omit noisy or redundant segments (for example, skip a slot name on one branch while keeping it on another).\n",
      "section": "accessibility",
      "anchors": [
        "syntax"
      ],
      "path": "/llm/json/chunked/accessibility/configuration/components.json",
      "token_estimate": 420
    },
    {
      "id": "accessibility/configuration/components#componentattributes",
      "doc_id": "accessibility/configuration/components",
      "heading": "componentAttributes",
      "heading_level": 3,
      "content_markdown": "### `componentAttributes`\n\nEach entry names an attribute that may be **required** in the generated selector when it is present on the element. Attribute names are stored case-insensitively and **must be unique** in the list.\n\n| Option | Required | Default | Description |\n| --- | --- | --- | --- |\n| `attributeName` | Required |  | The HTML attribute name (for example, `data-component-name`). |\n| `includeInSelector` | Optional | `true` | When `true`, the attribute is eligible to appear as a required segment in the stable selector. |\n| `comment` | Optional |  | Optional note for your team explaining why this entry exists. |\n\nWhen `includeInSelector` is `false`, the attribute is listed for documentation or future use but does not change selector generation (equivalent to omitting it for selector purposes).\n",
      "section": "accessibility",
      "anchors": [
        "componentattributes"
      ],
      "path": "/llm/json/chunked/accessibility/configuration/components.json",
      "token_estimate": 177
    },
    {
      "id": "accessibility/configuration/components#componentattributefilters",
      "doc_id": "accessibility/configuration/components",
      "heading": "componentAttributeFilters",
      "heading_level": 3,
      "content_markdown": "### `componentAttributeFilters`\n\nThese filters fine-tune **which attribute values** actually receive the required-attribute treatment from `componentAttributes`. They use the same regular-expression style as [`attributeFilters`](/llm/markdown/accessibility/configuration/attributefilters.md): `attribute` and `value` are regex patterns. **The first rule that matches both the attribute name and value** controls whether that value is included.\n\n| Option | Required | Default | Description |\n| --- | --- | --- | --- |\n| `attribute` | Required |  | Regex string matched against the attribute name. |\n| `value` | Optional | `.*` | Regex string matched against the attribute value. |\n| `include` | Optional | `true` | If `false`, matching values skip required injection for component attributes. |\n| `comment` | Optional |  | Optional note for maintainers. |\n\nUse `include: false` to omit noisy or redundant segments (for example, skip a slot name on one branch while keeping it on another).\n",
      "section": "accessibility",
      "anchors": [
        "componentattributefilters"
      ],
      "path": "/llm/json/chunked/accessibility/configuration/components.json",
      "token_estimate": 193
    },
    {
      "id": "accessibility/configuration/components#examples",
      "doc_id": "accessibility/configuration/components",
      "heading": "Examples",
      "heading_level": 2,
      "content_markdown": "## Examples\n\n### Require a component slot attribute\n\n```\n{  \"accessibility\": {    \"components\": {      \"componentAttributes\": [        { \"attributeName\": \"data-component-name\", \"includeInSelector\": true }      ]    }  }}\n```\n\n### Require multiple attributes\n\nRequire both a component identifier and Cypress test id when both are present, even if neither would otherwise be unique in the page:\n\n```\n{  \"accessibility\": {    \"components\": {      \"componentAttributes\": [        { \"attributeName\": \"data-component-name\", \"includeInSelector\": true },        { \"attributeName\": \"data-cy\", \"includeInSelector\": true }      ]    }  }}\n```\n\n### Skip injection for specific attribute values\n\nKeep both attributes required in general, but **exclude** the component segment when the slot is `primary-slot`:\n\n```\n{  \"accessibility\": {    \"components\": {      \"componentAttributes\": [        { \"attributeName\": \"data-component-name\", \"includeInSelector\": true },        { \"attributeName\": \"data-cy\", \"includeInSelector\": true }      ],      \"componentAttributeFilters\": [        {          \"attribute\": \"data-component-name\",          \"value\": \"^primary-slot$\",          \"include\": false        }      ]    }  }}\n```\n\nAfter saving configuration in the [App Quality settings](/llm/markdown/accessibility/configuration/overview.md), you can [reprocess an existing run](/llm/markdown/accessibility/configuration/overview.md#Viewing-Configuration-for-a-Run) to preview selector changes without a new test run.\n",
      "section": "accessibility",
      "anchors": [
        "examples"
      ],
      "path": "/llm/json/chunked/accessibility/configuration/components.json",
      "token_estimate": 211
    },
    {
      "id": "accessibility/configuration/components#require-multiple-attributes",
      "doc_id": "accessibility/configuration/components",
      "heading": "Require multiple attributes",
      "heading_level": 3,
      "content_markdown": "### Require multiple attributes\n\nRequire both a component identifier and Cypress test id when both are present, even if neither would otherwise be unique in the page:\n\n```\n{  \"accessibility\": {    \"components\": {      \"componentAttributes\": [        { \"attributeName\": \"data-component-name\", \"includeInSelector\": true },        { \"attributeName\": \"data-cy\", \"includeInSelector\": true }      ]    }  }}\n```\n",
      "section": "accessibility",
      "anchors": [
        "require-multiple-attributes"
      ],
      "path": "/llm/json/chunked/accessibility/configuration/components.json",
      "token_estimate": 68
    },
    {
      "id": "accessibility/configuration/components#skip-injection-for-specific-attribute-values",
      "doc_id": "accessibility/configuration/components",
      "heading": "Skip injection for specific attribute values",
      "heading_level": 3,
      "content_markdown": "### Skip injection for specific attribute values\n\nKeep both attributes required in general, but **exclude** the component segment when the slot is `primary-slot`:\n\n```\n{  \"accessibility\": {    \"components\": {      \"componentAttributes\": [        { \"attributeName\": \"data-component-name\", \"includeInSelector\": true },        { \"attributeName\": \"data-cy\", \"includeInSelector\": true }      ],      \"componentAttributeFilters\": [        {          \"attribute\": \"data-component-name\",          \"value\": \"^primary-slot$\",          \"include\": false        }      ]    }  }}\n```\n\nAfter saving configuration in the [App Quality settings](/llm/markdown/accessibility/configuration/overview.md), you can [reprocess an existing run](/llm/markdown/accessibility/configuration/overview.md#Viewing-Configuration-for-a-Run) to preview selector changes without a new test run.\n",
      "section": "accessibility",
      "anchors": [
        "skip-injection-for-specific-attribute-values"
      ],
      "path": "/llm/json/chunked/accessibility/configuration/components.json",
      "token_estimate": 108
    },
    {
      "id": "accessibility/configuration/components#comparison-to-other-config-properties",
      "doc_id": "accessibility/configuration/components",
      "heading": "Comparison to other config properties",
      "heading_level": 2,
      "content_markdown": "## Comparison to other config properties\n\nThis is separate from [`attributeFilters`](/llm/markdown/accessibility/configuration/attributefilters.md) and [`significantAttributes`](/llm/markdown/accessibility/configuration/significantattributes.md):\n\n*   `attributeFilters` are used to avoid specific attributes and values being used for element identification and tracking\n*   `significantAttributes` indicate preferred attributes for element identification and tracking, when the attributes would uniquely identify elements within a given state in a page.\n\nFor background on how Cypress picks identifiers, see [Element identification](/llm/markdown/accessibility/core-concepts/element-identification.md).\n",
      "section": "accessibility",
      "anchors": [
        "comparison-to-other-config-properties"
      ],
      "path": "/llm/json/chunked/accessibility/configuration/components.json",
      "token_estimate": 85
    }
  ]
}