jsx-a11y-control-has-associated-label.md

@typehut/jsx-a11y-control-has-associated-label

Enforce that a control (an interactive element) has a text label

Rule Details

There are two supported ways to supply a control with a text label:

• Provide text content inside the element.
• Use the aria-label attribute on the element, with a text value.
• Use the aria-labelledby attribute on the element, and point the IDREF value to an element with an accessible label.
• Alternatively, with an img tag, you may use the alt attribute to supply a text description of the image.

The rule is permissive in the sense that it will assume that expressions will eventually provide a label. So an element like this will pass.

<button type="button">{maybeSomethingThatContainsALabel}</button>

How do I resolve this error?

Case: I have a simple button that requires a label.

Provide text content in the button element.

<button type="button">Save</button>

Case: I have an icon button and I don't want visible text.

Use the aria-label attribute and provide the text label as the value.

<button type="button" aria-label="Save" class="icon-save" />

Case: The label for my element is already located on the page and I don't want to repeat the text in my source code.

Use the aria-labelledby attribute and point the IDREF value to an element with an accessible label.

<div id="js_1">Comment</div>
<textarea aria-labelledby="js_1"></textarea>

Case: My label and input components are custom components, but I still want to require that they have an accessible text label.

You can configure the rule to be aware of your custom components. Refer to the Rule Details below.

<CustomInput label="Surname" type="text" value={value} />

Succeed

<button type="button" aria-label="Save" class="icon-save" />

Fail

<button type="button" class="icon-save" />

Options

This rule takes one optional object argument of type object:

{
  "rules": {
    "jsx-a11y/control-has-associated-label": [
      2,
      {
        "labelAttributes": ["label"],
        "controlComponents": ["CustomComponent"],
        "ignoreElements": [
          "audio",
          "canvas",
          "embed",
          "input",
          "textarea",
          "tr",
          "video"
        ],
        "ignoreRoles": [
          "grid",
          "listbox",
          "menu",
          "menubar",
          "radiogroup",
          "row",
          "tablist",
          "toolbar",
          "tree",
          "treegrid"
        ],
        "depth": 3
      }
    ]
  }
}

• labelAttributes is a list of attributes to check on the control component and its children for a label. Use this if you have a custom component that uses a string passed on a prop to render an HTML label, for example.
• controlComponents is a list of custom React Components names that will render down to an interactive element.
• ignoreElements is an array of elements that should not be considered control (interactive) elements and therefore they do not require a text label.
• ignoreRoles is an array of ARIA roles that should not be considered control (interactive) roles and therefore they do not require a text label.
• depth (default 2, max 25) is an integer that determines how deep within a JSXElement the rule should look for text content or an element with a label to determine if the interactive element will have an accessible label.
• "ignoreAttributeInner" false (default: true) Ignore rule if element is inside component attribute.
• "attributeTracingDepth" -1 (default: 4) The number of AST nodes trace when applying ignoreAttributeInner. Specify -1 to trace indefinitely.

Accessibility guidelines

• WCAG 1.3.1
• WCAG 3.3.2
• WCAG 4.1.2

Implementation

• Rule source
• Test source