Is There A Semantic Way In HTML5 And WAI-ARIA To Describe "Toggleable Help Content"?

- 1 answer

I'm trying to find the semantically correct way to describe an HTML element that represent a way to get help (e.g. help icon) and its help content. I tried to search on this topics but searching help on help isn't an easy business. Here would be a simple example of what I have in mind (using a simple script to show/hide the help content as well as leveraging the "title" attribute):

    Please enter your password 
    <a class="help" title="Your password must have 5 characters">
        <img src="/images/help.svg" alt="">
    <span class="helpText displayNone">
        Your password must have 5 characters.
    <input type="password>

Is there a better way to represent this (in this format). The idea is to have an accessible and SEO friendly way to describe "toggleable help content".

The question is about HTML/HTML5 and WAI-ARIA attributes (not JavaScript) - I'm looking for the best element representation of my example (if such concept exists).



I think this question is larger than you intend based on your markup. First let's clean up your example so there are appropriate semantic and structural elements in place that also make this accessible to users:

  <label for="pwd">Please enter your password</label>
  <input type="password" id="pwd">

That makes for an accessible field. No script, no ARIA. Just a <label> that is properly associated with the field.

Now you want to offer some help to the user and still associate it with the field.

First, do not use an anchor. That tells users of assistive technology that it will take them away from the page and they may not want to click or activate the control. Use <button>.

Then you can use ARIA to associate that tip with the field. In this case aria-describedby will be announced along with the field.

You also need to fill out the alt attribute, or your image will not be announced to a screen reader user at all.

The best ARIA role to use in this context is the role=tooltip (read more in the ARIA spec).

Here is one way you could approach it:

  <label for="pwd">Please enter your password</label>
  <button><img src="/images/help.svg" alt="Help"></button>
  <span id="pwd-tip" role="tooltip">Your password must have 5 characters.</span>
  <input type="password" id="pwd" aria-describedby="pwd-tip">

You can use CSS to determine if the button has focus and display the following sibling span (button:focus + span) if you must avoid script, but that is sloppy. You can use script to toggle a class on the button which uses similar CSS to then display the span.

You can put the text into the <label> and hide it by using a CSS off-screen technique, meaning it will always be announced to screen readers and then you can dump the aria-describedby.

Frankly, you can skin this a few different ways. Check out the keyboard interactions you must consider also over at the ARIA Practices description for a tooltip.

However, for the most part you are better off making your help text always visible (especially if you want to satisfy the nebulous notion of SEO). In a vacuum I would just put this text in the <label> and be done with it.