The Australian Government coat of Arms

Communities of practice

Communities of practice



We conducted research and found that the experience of many users was positively augmented by tooltips.

Unfortunately many implementations rely on attribute-based content such as:

<sometag title=“tooltip” rel=“tooltip”>

This is hidden to many users.

A better approach is to use a dedicated tag which is aria-describedby the actuator and hidden by CSS by default. JS can trigger and toggle ARIA.



Currently, there is no HTML element to mark up a tooltip. The lack of a semantic element can create a challenge for Assistive Technologies, including screeen readers.

The ARIA role=“tooltip” lets ATs know that this element is a tooltip.

There is a circumstance in which the use of JavaScript is noit necessary in making tooltips accessible, and that is providing tooltips for form fields.

Advice on how to do this is available on this webpage:

In other situations, such as providing an accessible tooltip over an icon or a link, it is necessasry to use JavaScript to manage the ARIA roles and attributes.

This webpage demonstrates some techniques that can be used:

Both these resources are referenced in a very good article on the subject by Sara Soueidan (sorry can’t link to it), in which she reaches the conclusion, “Some ARIA roles and attributes are absolutely necessary to make components accessible, and many of those will simply not behave as they need to unless you make them work with JavaScript.”

Hope that helps.


We have been working on accessible tooltips and I would be interested to hear your thoughts on this approach:

The term is wrapped in a definition tag:

<dfn role="tooltip" aria-expanded="false" aria-describedby="definition-1">Term 1</dfn>

The definition is stored in a hidden definition list, with the definition’s ID matching the term’s aria-describedby:

<dl aria-hidden="true">
  <dt>Term 1</dt>
  <dd id="definition-1">Definition 1</dd>
  <dt>Term 2</dt>
  <dd id="definition-2">Definition 2</dd>

The end result is that:

  • When Javascript is turned off aria-describedby connects the term to its definition for assistive technologies. Please note that in this situation no tooltip will be shown as we are not using a title attribute, as recommended by W3C.
  • When Javascript is turned on aria-describedby maintains the same connection. A tooltip library can then be augmented over the tags to provide a tooltip.

The <dfn>, <dl> and aria-attributes do the bulk of the semantics.

How’s this approach sound?


Thanks for the replies @ronsman @Maedi.

Our dev team have reviewed the techniques described and referenced and have implemented something very similar to @maedi’s approach. This is an accessible ‘baseline’ and we use Tippy JS to progressively enhance it to add the tooltip (content taken from the <dd>).

Some points of note:

  1. We have two implementations: one where the definitions are on the same page as the term being defined (as per the example); the other where the definitions are all on a separate page (i.e. glossary page) and are linked to via <a href="page#term">.

  2. According to The <dfn> tag should be used when the definition is adjacent to the term being defined (e.g. in a section or paragraph):

The HTML Definition element (<dfn>) is used to indicate the term being defined within the context of a definition phrase or sentence. The <p> element, the <dt>/<dd> pairing, or the <section> element which is the nearest ancestor of the <dfn> is considered to be the definition of the term.

Therefore, I question whether the tag is appropriate using this approach. Mozilla’s article, however, goes on to state:

It’s worth noting that functionally, there is very little that the <dfn> element does for you; its main purpose is in providing an established form of semantic markup to use for marking terms. You could just as well use a custom class on elements and not really lose much or any functionality.

When we have something live I’ll share a link.


[Maedi and I have been looking at this together.]

Looking at the <dfn> tag some more, the W3C appears to be even more strict than Mozilla:

If the dfn element is specified, nearest parent of the dfn element(paragraph, description list group, or section) must also contain the definitions for the defining term.

So yeah, maybe the <dfn> is not needed in Maedi’s example as there is no definition provided in the parent. The main point in Maedi’s code is that we can have some nice structure inside the <dl> linked up via the aria-describedby.

For our particular use case, a term can appear multiple times on a page and so we wanted a single place to put all of the terms and definitions. We felt that this was better than repeating definitions all through the document. That is why we have the <dl> for all the definitions at the bottom of the page.

Looking more broadly, the aria-describedby will help ATs. However, for desktop browsers, there is no visual indication that there is extra information. A tool such as TippyJS can work in with the markup to provide the tooltip popup in this case. What is needed is some guidance on the recommended mechanism to do this. TippyJS is one solution but maybe there are others which are preferred.


Also worth noting that tooltips are not only for definitions. They can also be used for things like contextual help.