# Using the `aria-describedby` property to provide a descriptive label for user interface controls

ID: ARIA1

Technology: aria

Type: Technique

## When to Use

Technologies that support Accessible Rich Internet Applications (WAI-ARIA).

## Description

The purpose of this technique is to demonstrate how to use the WAI-ARIA `aria-describedby` property to provide programmatically determined, descriptive information about a user interface element. The `aria-describedby` property may be used to attach descriptive information to one or more elements through the use of an `id` reference list. The `id` reference list contains one or more unique element `id`s.

Refer to ARIA in HTML for information on how to provide WAI-ARIA States and Properties with HTML. WAI-ARIA States and Properties are compatible with other languages as well; refer to documentation in those languages.

The `aria-describedby` property is not designed to reference descriptions on an external resource - since it is an `id`, it must reference an element in the same DOM document.

## Examples

### Using `aria-describedby` to associate instructions with form fields

Sample form field using `aria-describedby` to associate instructions with form fields while there is a form label.

    <form>
      <label for="fname">First name</label>
      <input aria-describedby="int2" autocomplete="given-name" id="fname" type="text">
      <p id="int2">Your first name is sometimes called your "given name".</p>
    </form>

### Using `aria-describedby` property to provide more detailed information about the button

    <div>
      <span id="fontDesc">Select the font faces and sizes to be used on this page</span>
      <button aria-describedby="fontDesc" id="fontB" type="button">Fonts</button>
    </div>
    <div>
      <span id="colorDesc">Select the colors to be used on this page</span>
      <button aria-describedby="colorDesc" id="colorB" type="button">Colors</button>
    </div>
    <div>
      <span id="customDesc">Customize the layout and styles used on this page</span>
      <button aria-describedby="customDesc" id="customB" type="button">Customize</button>
    </div>

## Tests

### Procedure

1. Check that there is a user interface control having an `aria-describedby` attribute that references one or more elements via unique `id`.
2. Check that the referenced element or elements provide additional information about the user interface control.

### Expected Results

- Checks #1 and #2 are true.

## Related Techniques

- ARIA2
- ARIA7

## Resources

- WAI-ARIA Overview.
- WAI-ARIA Authoring Practices Guide.
- HTML Accessibility API Mappings
- Accessible Name and Description Computation.
- `aria-describedby` attribute (MDN).
- Using WAI-ARIA in HTML.