1# control-has-associated-label
2
3Enforce that a control (an interactive element) has a text label.
4
5There are two supported ways to supply a control with a text label:
6
7- Provide text content inside the element.
8- Use the `aria-label` attribute on the element, with a text value.
9- Use the `aria-labelledby` attribute on the element, and point the IDREF value to an element with an accessible label.
10- Alternatively, with an `img` tag, you may use the `alt` attribute to supply a text description of the image.
11
12The rule is permissive in the sense that it will assume that expressions will eventually provide a label. So an element like this will pass.
13
14```jsx
15<button type="button">{maybeSomethingThatContainsALabel}</button>
16```
17
18## How do I resolve this error?
19
20### Case: I have a simple button that requires a label.
21
22Provide text content in the `button` element.
23
24```jsx
25<button type="button">Save</button>
26```
27
28### Case: I have an icon button and I don't want visible text.
29
30Use the `aria-label` attribute and provide the text label as the value.
31
32```jsx
33<button type="button" aria-label="Save" class="icon-save" />
34```
35
36### 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.
37
38Use the `aria-labelledby` attribute and point the IDREF value to an element with an accessible label.
39
40```jsx
41<div id="js_1">Comment</div>
42<textarea aria-labelledby="js_1"></textarea>
43```
44
45### Case: My label and input components are custom components, but I still want to require that they have an accessible text label.
46
47You can configure the rule to be aware of your custom components. Refer to the Rule Details below.
48
49```jsx
50<CustomInput label="Surname" type="text" value={value} />
51```
52
53## Rule details
54
55This rule takes one optional object argument of type object:
56
57```json
58{
59  "rules": {
60    "jsx-a11y/control-has-associated-label": [ 2, {
61      "labelAttributes": ["label"],
62      "controlComponents": ["CustomComponent"],
63      "ignoreElements": [
64        "audio",
65        "canvas",
66        "embed",
67        "input",
68        "textarea",
69        "tr",
70        "video",
71      ],
72      "ignoreRoles": [
73        "grid",
74        "listbox",
75        "menu",
76        "menubar",
77        "radiogroup",
78        "row",
79        "tablist",
80        "toolbar",
81        "tree",
82        "treegrid",
83      ],
84      "depth": 3,
85    }],
86  }
87}
88```
89
90- `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.
91- `controlComponents` is a list of custom React Components names that will render down to an interactive element.
92- `ignoreElements` is an array of elements that should not be considered control (interactive) elements and therefore they do not require a text label.
93- `ignoreRoles` is an array of ARIA roles that should not be considered control (interactive) roles and therefore they do not require a text label.
94- `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.
95
96### Succeed
97```jsx
98<button type="button" aria-label="Save" class="icon-save" />
99```
100
101### Fail
102```jsx
103<button type="button" class="icon-save" />
104```
105
106## Accessibility guidelines
107- [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)
108- [WCAG 3.3.2](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions)
109- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
110