{
  "doc": {
    "id": "accessibility/configuration/attributefilters",
    "title": "Attribute Filters | Cypress Accessibility",
    "description": "The `attributeFilters` configuration property allows users to specify patterns for attributes and their values that should not be used for identifying and grouping elements.",
    "section": "accessibility",
    "source_path": "/llm/markdown/accessibility/configuration/attributefilters.md",
    "version": "524ff5211e60b5d53e55d6ad976d83966f66e7cd",
    "updated_at": "2026-04-30T14:20:05.396Z",
    "headings": [
      {
        "id": "accessibility/configuration/attributefilters#attributefilters",
        "text": "attributeFilters",
        "level": 1
      },
      {
        "id": "accessibility/configuration/attributefilters#why-use-attribute-filters",
        "text": "Why use attribute filters?",
        "level": 2
      },
      {
        "id": "accessibility/configuration/attributefilters#scope",
        "text": "Scope",
        "level": 2
      },
      {
        "id": "accessibility/configuration/attributefilters#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "accessibility/configuration/attributefilters#options",
        "text": "Options",
        "level": 3
      },
      {
        "id": "accessibility/configuration/attributefilters#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "accessibility/configuration/attributefilters#excluding-common-auto-generated-id-values",
        "text": "Excluding common auto-generated ID values",
        "level": 3
      },
      {
        "id": "accessibility/configuration/attributefilters#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "accessibility/configuration/attributefilters#element-identifiers-displayed",
        "text": "Element identifiers displayed",
        "level": 4
      },
      {
        "id": "accessibility/configuration/attributefilters#filtering-related-dynamic-attributes",
        "text": "Filtering related dynamic attributes",
        "level": 3
      },
      {
        "id": "accessibility/configuration/attributefilters#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "accessibility/configuration/attributefilters#element-identifiers-displayed",
        "text": "Element identifiers displayed",
        "level": 4
      },
      {
        "id": "accessibility/configuration/attributefilters#excluding-auto-generated-attribute-names",
        "text": "Excluding auto-generated attribute names",
        "level": 3
      },
      {
        "id": "accessibility/configuration/attributefilters#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "accessibility/configuration/attributefilters#element-identifiers-displayed",
        "text": "Element identifiers displayed",
        "level": 4
      },
      {
        "id": "accessibility/configuration/attributefilters#ignoring-dynamic-attributes-for-accurate-grouping",
        "text": "Ignoring dynamic attributes for accurate grouping",
        "level": 3
      },
      {
        "id": "accessibility/configuration/attributefilters#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "accessibility/configuration/attributefilters#element-identifiers-displayed",
        "text": "Element identifiers displayed",
        "level": 4
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "attributeFilters"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Cypress Accessibility "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/ui-coverage/core-concepts/element-identification.md",
            "children": [
              {
                "type": "text",
                "value": "identifies elements"
              }
            ]
          },
          {
            "type": "text",
            "value": " based on a combination of attributes and the surrounding DOM structure."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Some attributes used for identification may be auto-generated, dynamic, or state-based, leading to inaccurate identification or grouping. The `attributeFilters` configuration property allows you to exclude specific attributes or patterns that should not be used for these purposes."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "By using `attributeFilters`, you can ensure Cypress selects more appropriate identifiers, leading to cleaner and more accurate reports, with better element de-deduplication across distinct states of the application being tested."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Why use attribute filters?"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Handling library-specific attributes: Attributes generated by libraries may not represent the element's purpose and should be ignored."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Improving grouping accuracy: By filtering out irrelevant attributes, you ensure similar elements are grouped correctly."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Avoiding state-based duplication: Classes like `link--focused` can clutter report findings."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Scope"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Note: setting `attributeFilters` impacts both Cypress Accessibility and UI Coverage reports if set at the root of the configuration. Nesting this property under an `accessibility` or `uiCoverage` key is supported, if you need to split them up."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Syntax"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "{  \"attributeFilters\": [    {      \"attribute\": string,      \"value\": string,      \"include\": boolean,      \"comment\": string    }  ]}"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Options"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Whether Cypress is allowed to use a certain attribute to identify an element when processing it for UI Coverage or Cypress Accessibility reports will be controlled by the first filter that matches the name and value of that attribute."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "This means that catch-all rules can be added at the bottom of the list by setting `include` to `false`, and exceptions can be defined earlier in the list using `include: true`. For example, you could avoid all use of `aria-label` for identification of elements as a catch-call filter, but then define exceptions for certain values it may have where it is a good identifier."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Attributes that do not match any rules are included by default and used if needed, so `include: true` is only required for defining exceptions. If you want to make sure an attribute is preferred as an identifier when available, add it to your "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/accessibility/configuration/attributefilters.md",
            "children": [
              {
                "type": "text",
                "value": "attributeFilters"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "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": "Required"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": []
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "A regex string to match attribute names"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`value`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Optional"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`.*`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "A regex string to match attribute values"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`include`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Optional"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`true`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "A boolean to specify whether the matched attribute should be included."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`comment`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Optional"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": []
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "A comment describing the purpose of this filter rule."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Examples"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Excluding common auto-generated ID values"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Some component libraries generate"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "{  \"attributeFilters\": [    {      \"attribute\": \"id\",      \"value\": \":r.*\",      \"include\": false    }  ]}"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "HTML"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<body>  <button id=\":r11:\" name=\"my-button\">Button 1</button>  <button id=\":r12:\" name=\"other-button\">Button 2</button></body>"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Element identifiers displayed"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "[name=\"my-button\"][name=\"other-button\"]"
      },
      {
        "type": "thematicBreak"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Filtering related dynamic attributes"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When filtering dynamic `id` attributes, you should also filter attributes that reference those IDs to prevent elements from being identified by these related dynamic values. Common relationships include:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Form associations (`for` attributes on labels)"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "ARIA relationships (`aria-labelledby`, `aria-describedby`, `aria-controls`, `aria-owns`, `aria-details`)"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Name attributes that may mirror IDs in certain frameworks"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "{  \"attributeFilters\": [    {      \"attribute\": \"id|for|name|aria-.*\",      \"value\": \"dynamic-.*\",      \"include\": false    }  ]}"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "HTML"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<div>  <label for=\"dynamic-input-1\">First Name</label>  <input id=\"dynamic-input-1\" name=\"dynamic-input-1\" aria-describedby=\"dynamic-help-1\" />  <p id=\"dynamic-help-1\">Enter your first name</p></div>"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Element identifiers displayed"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "labelinputp"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Excluding auto-generated attribute names"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "{  \"attributeFilters\": [    {      \"attribute\": \"ng-include-me\",      \"value\": \".*\",      \"include\": true    },    {      \"attribute\": \"ng-.*|_ng.*\",      \"value\": \".*\",      \"include\": false    }  ]}"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "HTML"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<body>  <button ng-include-me=\"my-button\">Button 1</button>  <button ng-but-not-me=\"other-button\">Button 2</button></body>"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Element identifiers displayed"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "[ng-include-me=\"my-button\"]:nth-child(2)"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Ignoring dynamic attributes for accurate grouping"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "{  \"attributeFilters\": [    {      \"attribute\": \"data-cy\",      \"value\": \"user-\\\\d+\",      \"include\": false    }  ]}"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "HTML"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<button data-cy=\"user-123\" class=\"user\">Harper</button><button data-cy=\"user-456\" class=\"user\">Amara</button>"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Element identifiers displayed"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": ".user (2 instances)"
      }
    ]
  },
  "token_estimate": 869
}