mozilla
Your Search Results

    Using the aria-labelledby attribute

    Description

    This technique demonstrates how to use the aria-labelledby attribute.

    The aria-labelledby attribute is used to indicate the IDs of the elements that are the labels for the object. It is used to establish a relationship between widgets or groups and their labels. Users of assistive technologies such as screen readers typically navigate a page by tabbing between areas of the screen. If a label is not associated with an input element, widget or group, it will not be read by a screen reader.

    aria-labelledby is very similar to aria-describedby: a label describes the essence of an object, while a description provides more information that the user might need.

    The aria-labelledby attribute is not used only for form elements; it is also used to associate static text with widgets, groups of elements, panes, regions that have a heading, definitions, and more. The Examples section below provides more information about how to use the attribute in these cases.

    aria-labelledby can be used in conjunction with the <label> element (using the for attribute) to improve compatibility with user agents that do not yet support ARIA.

    This attribute can be used with any typical HTML form element; it is not limited to elements that have an ARIA role assigned.

    Value

    a space-separated list of element IDs

    Possible effects on user agents and assistive technology 

    When both aria-labelledby and aria-label are used, user agents give precedence to aria-labelledby when computing the accessible name property.

    Note: Opinons may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and therefore not normative.

    Examples

    Example 1: Multiple Labels

    In the example below, each input field is labelled by both its own individual label and by the label for the group:

    <div id="billing">Billing Address</div>
    
    <div>
        <div id="name">Name</div>
        <input type="text" aria-labelledby="name billing"/>
    </div>
    <div>
        <div id="address">Address</div>
        <input type="text" aria-labelledby="address billing"/>
    </div>
    

    Example 2: Associating Headings With Regions

    In the example below, header elements are associated with the content they head. Note that the region being referenced is the region that contains the header.

    <div role="main" aria-labelledby="foo">
       <h1 id="foo">Wild fires spread across the San Diego Hills</h1>
       Strong winds expand fires ignited by high temperatures ...
    </div>
    

    Example 3: Radio Groups

    In the example below, the container of a radiogroup is associated with its label using the aria-labelledby attribute:

    <div id="radio_label">My radio label</div>
    <ul role="radiogroup" aria-labelledby="radio_label">
        <li role="radio">Item #1</li>
        <li role="radio">Item #2</li>
        <li role="radio">Item #3</li>
    </ul>
    

    Example 4: Dialog Label

    In the example below, the header element that labels the dialog is referred to by the aria-labelledby attribute:

    <div role="dialog" aria-labelledby="dialogheader">
        <h2 id="dialogheader">Choose a File</h2>
        ... Dialog contents
    </div>
    

    Example 5: Inline Definition

    In the example below, the definition of a term that is described in the natural flow of the narrative is associated with the term itself using the aria-labelledby attribute:

    <p>The doctor explained it had been a <dfn id="placebo">placebo</dfn>, or <span role="definition" aria-labelledby="placebo">  
    or an inert preparation prescribed more for the mental relief of the patient than for its actual effect on a disorder.</span>
    </p>
    

    Example 6: Definition Lists

    In the example below, the definitions in a formal definition list are associated with the terms they define using the aria-labelledby attribute:

    <dl>
        <dt id="anathema">anthema</dt>
        <dd role="definition" aria-labelledby="anathema">a ban or curse solemnly pronounced by ecclesiastical authority
                                                         and accompanied by excommunication</dd>
        <dd role="definition" aria-labelledby="anathema">a vigorous denunciation : cursor</dd>
    
        <dt id="homily">homily</dt>
        <dd role="definition" aria-labelledby="homily">a usually short sermon</dd>
        <dd role="definition" aria-labelledby="homily">a lecture or discourse on or of a moral theme</dd>
    
    </dl>
    

    Example 7: Menus

    In the example below, a popup menu is associated with its label using the aria-labelledby attribute:

    <div role="menubar">
        <div role="menuitem" aria-haspopup="true" id="fileMenu">File</div>
        <div role="menu" aria-labelledby="fileMenu">
            <div role="menuitem">Open</div>
            <div role="menuitem">Save</div>
            <div role="menuitem">Save as ...</div>
            ...
        </div>
        ...
    </div>
    

    Working Examples:

    Notes 

    The most common accessibility API mapping for a label is the accessible name property

    Used by ARIA roles

    all elements of the base markup

    Compatibility

    TBD: Add support information for common UA and AT product combinations

    Additional resources

    Document Tags and Contributors

    Contributors to this page: Sheppy, SteveFaulkner, hhillen, anastasia, Jeremie, geeljire
    Last updated by: Sheppy,