ANDI Help

Skip to Content

Developer Guide

This page provides helpful information to aid developers and web content authors in creating accessible HTML.

Accessibility of Interactive Elements

All interactive elements on web page must have explicitly defined text to distinguish the element, or else a screen reader will not know what to speak, thus the element will not be accessible to screen reader users. This distinguishing text is called the accessible name of the element.

In addition to the required accessible name, interactive elements may be given text that further describes the element or provides more information. This supporting description text is called the accessible description of the element.


Namers

Web authors must take additional steps to ensure that the accessible name of each interactive element is properly identified. There are several different components that can be used to provide a required accessible name. ANDI calls these "Namers".

Namers provide the distinct name or identifier of an element (the accessible name).

ANDI defines the following components as Namers:

  • aria-labelledby
  • aria-label
  • label (form elements)
  • alt (images)
  • value (input buttons)
  • figcaption (figure)
  • caption (table)
  • innerHTML (container elements)

Use Only One Namer

Following ANDI's methodology of using only one Namer component per element will provide consistent screen reader output and minimize accessibility issues.


Describers

In addition to a required accessible name, web authors may add additional support text to further describe interactive elements. There are several different components that can be used to provide an accessible description. ANDI calls these "Describers".

Describers provide additional information about an element (the accessible description).

ANDI defines the following components as Describers:

  • aria-describedby
  • legend (form elements & only with label)
  • title

Use Only One Describer

Following ANDI's methodology of using only one Describer, when a Namer is present, will provide consistent screen reader output and minimize accessibility issues.

Namers: Provide An Accessible Name

aria-labelledby

The global attribute aria-labelledby references other elements to provide an accessible name.

How To Use

The aria-labelledby attribute establishes an association between an element and the text that provides the accessible name. It indicates the ids of other elements which contain the naming text. The benefit of the aria-labelledby attribute is that it can reference multiple elements in a specific order.

For example, consider this radio button which is labelled by an h1 heading and a <label> tag:
<h1 id='id1'>Famous People</h1>
<label id='id2'> Andy Williams
<input type='radio' aria-labelledby='id1 id2'/>
</label>

The accessible name for the radio button will be "Famous People Andy Williams". In the example above, a space delimited list of ids was provided as the value of the aria-labelledby.

Screen Reader Usage

Screen readers will speak the text contained within the elements referenced by the aria-labelledby.

The aria-labelledby attribute is a powerful Namer since it can be used to reference several elements which contain text that can contribute to an accessible name. Screen readers give it a high precedence over other Namers.

Improper Use

This attribute cannot take literal text; it expects an id or a space delimited list of ids only.


aria-label

The global attribute aria-label provides an accessible name.

How To Use

The value given to the aria-label attribute should contain the literal text that that will explicitly name an element. The text will not appear on the screen.

Screen Reader Usage

A screen reader will speak the literal text value of this attribute. Screen readers give it a high precedence over other Namers.

For example, the screen reader output of this button will be the text in the aria-label not the innerHTML of the button:
<button aria-label='Andy Warhol's Can of Soup'><img src='soup_can.jpg' alt="" />soup</button>

This attribute provides additional details about an element to a person who is visually impaired. When focus moves to the button, the screen reader would read "Andy Warhol's Can of Soup button". In the example, the image and the innerHTML "soup" provides information about the button to a sighted user. The text in the aria-label "Andy Warhol's Can of Soup" would not appear on screen, but would be read by the screen reader.

Improper Use

Do not use it together with aria-labelledby on the same element.


alt

The alt attribute is the HTML attribute used to specify alternative text (alt text) that is to be displayed when the image to which it is applied cannot be rendered. The alt attribute is a required attribute of the <img>, <area>, and <input[type=image]> tags. When applied to images, the alt attribute provides an accessible name.

How To Use

The alt attribute should only be placed on <img>, <area>, and <input[type=image]> tags. The text of the alt should concisely describe the image. If the image is purely decorative, does not require explanation, and does not gain focus, then an empty string should be used for the value such as alt="".

Screen Reader Usage

The alt attribute is used by screen readers to speak the content of images to a person who cannot see the image because of a disablity. If the alt has been intentionally set to empty string alt="", then the screen reader will ignore the image.


<label>

The <label> tag, when properly associated, provides an accessible name for a form element. In addition, clicking on a label that is properly associated will move focus to the form element with which it associates.

How To Use

Labels must have explicit associations with the form elements to which they refer.
There are two methods to form the association:

Label/For with Matching Id - explicit association
Adding a for attribute to the label, which references the id of the form element. Example:
<label for='someId'> Enter Text: </label>
<input type='text' id='someId' />
Nested Label (Label as a container) - implicit association
Using the label as a container which contains the form element. Example:
<label> Enter Text:
<input type='text' />
</label>

Screen Reader Usage

For a form element with an association to the label, a screen reader will read the <label>. There are some limitations depending on the screen reader and the element. Typically, screen readers prefer that when labels are being used for radio buttons <input[radio]> and checkboxes <input[checkbox]> the elements should be contained within a <fieldset>.

Low Mobility Users

Clicking on a label that is associated with a form element will move focus to the form element (this is handled by default in the browser). This functionality aids users with low mobility who have difficulties using a mouse by increasing the clickable area of a form element. This is especially beneficial when a label is associated with radio buttons and checkboxes which are relatively small click "targets". If the label is not properly associated the size of the clickable area will not be automatically increased.

Improper Use

The following example is an improper use of the <label> tag. The <label> tag does not make an association to the form element.

<label> Improper Use: </label>
<input type='text' />

The example above will generate an accessibility defect.


value

The value property provides an accessible name for an <input> button. The text of the value will also visually appear on the button.

How To Use

The text of the value attribute should contain the literal text that will explicitly name an <input> button element: <input type="submit">, <input type="button">, <input type="reset">, <input type="image">

Screen Reader Usage

For input buttons a screen reader will speak the literal text value of this attribute.


<figcaption>

Introduced in HTML5, the <figcaption> tag provides an accessible name for a <figure>.

How To Use

The <figcaption> must be contained within a <figure> and there must not be more than one <figcaption> within. The <figcaption> should be the first or last child in the <figure>.

Screen Reader Usage

For a <figure>, a screen reader will read the <figcaption>.


<caption>

Introduced in HTML5, the <caption> tag provides an accessible name for a <table>.

How To Use

The <caption> must be contained within a <table> and there must not be more than one <caption> within. The <caption> should be the first child in the <table>.

Screen Reader Usage

For a <table>, a screen reader will read the <caption> first.


innerHTML

The contents of an element: screen text and/or child nodes.

How To Use

Adding screen text to an element is perhaps the best way to add an accessible name, since every type of user will be able to read the exact same text. For elements that cannot contain innerHTML such as <img> or <input> additional components are needed to be accessible.

For basic HTML tags such as <p>, <div>, <li> It is perfectly reasonable to rely on the text within these basic elements to provide an accessible name. If for some reason this text is not descriptive enough for users relying on screen readers, change the text!

ANDI Terminiology

ANDI breaks down the innerHTML into two components.

  1. innerText more info
  2. child element components more info

Screen Reader Usage

A screen reader will read the text contents of the element and should read the accessibility components of child nodes.

Describers: Provide An Accessible Description

aria-describedby

The global attribute aria-describedby references other elements to provide an accessible description.

How To Use

The aria-describedby attribute is used to indicate the IDs of other elements that describe this element. It establishes an association between an element and the text that provides a description.

For example, consider this button which is described by some paragraph text:
<button aria-describedby='pId'>Submit</button>
<p id='pId'>Clicking on this button will send an email to Andy Cooper</p>

The accessible name for this element will be "Submit Button" and the accessible description will be "Clicking on this button will send an email to Andy Cooper".

This attribute is very similar to aria-labelledby which defines the essence of the element, while aria-describedby provides a description or more information that the user might need pertaining to the element.

Screen Reader Usage

Screen readers will speak the aria-describedby at the end of its spoken phrase. However, when multiple Describers are used on the same element (such as title), one or the other might not be spoken and information could be lost. Therefore, use only one Describer for an element.

Improper Use

This attribute cannot take literal text; it expects an id or a space delimited list of ids only.


<legend>

Within a <fieldset>, the <legend> tag associates a group of form elements.

Screen Reader Usage

For form elements, excluding buttons, a screen reader will read the legend first and then the accessible name. When <legend> is used with non-form elements and buttons, screen reader output is inconsistent, and therefore such combinations are discouraged.

How To Use

The <legend> tag is strictly meant to be used in this specific scenario:

  1. Within a <fieldset>
  2. The first child of the <fieldset>
  3. Describing a form element group
  4. Each form element must have an associating <label> tag and be contained in the <fieldset>
  5. The <legend> text will be spoken before the <label> text.
  6. Do not use with buttons (place buttons outside the <fieldset>)
  7. Do not use other Accessibility Components including title

Here is a code example of the proper usage of legend:

<fieldset>
  <legend>What Is Your Favorite Color?</legend>
    <label>Red: <input type="radio" name="color" value="1" /></label>
    <label>Yellow: <input type="radio" name="color" value="2" /></label>
    <label>Blue: <input type="radio" name="color" value="3" /></label>
</fieldset>
<button>Submit</button>

When used this way, each <label> provides the distinctive name for its associating form element, and the <legend> describes the grouping relationship of the elements within the <fieldset>.

Improper Use

Combining <legend> with any other accessibility components and outside of the recommended scenario described above will cause screen reader inconsistencies or accessibility issues. Furthermore, the <legend> tag should not be used alone without <label>.

Legend Alternative

If a form element group needs more information than labels with a legend can provide, remove the <legend> tag and use aria-labelledby or aria-label.


title

The global attribute title can be placed on any HTML element. It will also generate a "tooltip" when a mouse user hovers over the element.

How To Use

The value given to the title attribute should contain the literal text that that will explicitly describe an element. The length of the value is limited to 512 total characters in Internet Explorer (source).

Screen Reader Usage

A screen reader will speak the literal text value of this attribute.

Add-On Properties (States, Roles, and Other Properties)

Add-On Properties is a term used by ANDI to classify additional states, roles, and properties of elements. These components are not part of the accessible name and description calculation, but are still important to an element's accessibility. Depending on the element, they will appear in ANDI's Output.

Add-On Properties that ANDI scans for are:

  • tabindex
  • accesskey
  • role
  • aria-controls
  • aria-disabled
  • aria-expanded
  • aria-haspopup
  • aria-invalid
  • aria-pressed
  • aria-sort
  • aria-readonly
  • readonly
  • aria-required
  • required

How To Use

For information on how to use these states, roles, and properties see the WAI-ARIA States and Properties

Screen Reader Usage

Screen readers may insert their own phrasing to signify the presence of Add-On Properties.


tabindex

The global attribute tabindex provides a resting location for keyboard focus.

How To Use

The value given to the tabindex attribute should contain a numeric value. The number specifies the tab order of an element (when the "tab" key is used for navigation).

The tabindex value does not have to be unique. A tabindex value of zero (tabindex="0") is the most common usage which places it in the "normal" or literal sequence in which it exists in the DOM tree.

A tabindex value can be negative (tabindex="-1") but this will remove the element from the tab order, in which case, users will not be able to tab to the element. This technique is useful for sending focus to an element programmatically where normal tab key navigation is not intended.

Screen Reader Usage

A screen reader will not speak the tabindex.


accesskey

The global attribute accesskey also referred to as "hotkeys", provide the ability to hit a key combination and shift focus or "click" a button.

Different browsers use different key combinations: Internet Explorer, Chrome, and Safari use the "alt" key. Firefox uses "alt+shift" together.

How To Use

When adding an accesskey to an element, ensure that the element is focusable (natively or has a tabindex).

Also ensure that the accesskey does not interfere with other accesskeys on the page. As a best practice, accesskeys should be unique. It is possible, however not supported by all browsers, to use duplicate accesskeys to jump around to several focusable sections of a page. However, accesskeys on buttons and links must be unique since the moment the accesskey is pressed, the button or link is selected.

Most browsers use hotkeys to kick off browser menu functions, such as "File" or "Help". Care should be taken not to override these keys. Modern browsers allow for this, but from an accessibility standpoint, it should be avoided if possible.

Screen Reader Usage

A screen reader will announce the value of the accesskey when the element with the accesskey receives focus.

How To Associate Table Cells

The cells of data tables must have additional markup to indicate the correct associations between table header cells and table data cells. Simply declaring a cell a <th> does not always automatically imply the correct association. Table cell associations can be programatically identifed by using one of two methods, the Scope Method or Headers/id Method. The method chosen is often dictated by the design/structure of the table. Moreover, only one association method should be used at a time per table for the sake of simplicity and maintainability.

Scope Method

To use the Scope Method, the scope attribute should be assigned to each table header <th> that forms a column header or row header. Example:
<table>
<caption>scope method</caption>
<tr>
 <th scope="col">col 1</th>
 <th scope="col">col 2</th>
 <th scope="col">col 3</th>
</tr>
<tr>
 <th scope="row">row 1</th>
 <td>col 2</td>
 <td>col 3</td>
</tr>
<tr>
 <th scope="row">row 2</th>
 <td>cell</td>
 <td>cell</td>
</tr>
<tr>
 <th scope="row">row 3</th>
 <td>cell</td>
 <td>cell</td>
</tr>
</table>

Headers/id Method

To use the Headers/id Method, each table header <th> should have a unique id attribute and all cells which associated with that table header should have a headers attribute whose value references the id of the table header cell. Example:
<table>
<caption>headers method</caption>
<tr>
 <th id="col1">col 1</th>
 <th id="col2">col 2</th>
 <th id="col3">col 3</th>
</tr>
<tr>
 <th id="row1" headers="col1">row 1</th>
 <td headers="row1 col2">col 2</td>
 <td headers="row1 col3">col 3</td>
</tr>
<tr>
 <th id="row2">row 2</th>
 <td headers="row2 col2">cell</td>
 <td headers="row2 col3">cell</td>
</tr>
<tr>
 <th id="row3">row 3</th>
 <td headers="row3 col2">cell</td>
 <td headers="row3 col3">cell</td>
</tr>
</table>

Which Table Cell Association Method should be used?

Since only one method should be used at a time, deciding between the Scope Method and the Headers/id Method method mostly depends on the design/structure of the table.

Most tables can use the Scope Method, even in some "complex" designs. If text alignment, font size, color or other style adjustments are being used to differentiate table headers within the same column or row, the Headers/id Method should be used.

Many web authors would agree that the Scope Method is easier to maintain and reduces the likelihood of any existing accessibility becoming "broken" with future table modifications. However, the Headers/id Method offers an explicit way of making associations in a specific order for highly complex tables. Remember that all users benefit from readability when table design is simplified.