PSA: Stop using the title attribute as tooltip!

by Daniela Kubesch published on Dec 22, 2024

It's almost 2025, so it's time to stop using the title attribute everywhere. Images, text, buttons, ... you name it, devs really like to put it on any element in sight. Most of the time, people actually want to create a tooltip. You know, that little bubble of information designed to clarify the purpose of otherwise unclear elements, that pops up attached to an element when its receives focus or a user hovers their mouse over it.

The identifying thing about tooltips is that they contain no interactive elements (aka. only plain text), and are always attached to existing interactive elements.
Whenever you want to add interactive elements inside your information bubble, it's not called tooltip, but toggletip. Toggletips can contain semantic markup, rich content and interactive elements, and usually only appear when an element is clicked. The great thing about toggletips is that they're accessible on touchscreens and easier to find and recognise for users with low vision.

So depending on your use case, you need to implement a tooltip or a toggletip.

But let's circle back to the title attribute. Often, people use it to create a tooltip. However, this is not the recommended way to go.

But why, I love my title!?

It's simple. The title attribute is inaccessible. Users of mobile phones and tablets, users of assistive technologies, and keyboard only users cannot interact with it.
If you want a tooltip, a much better, and accessible, option is using the popover attribute.

Note: The only place where you should (& must) use the title attribute is on an iframe! See Steve Faulkner's post for more information.

How to use popover

Firstly, before we get started, it is always better to display clear, permanently visible information. So, if space permits, do not use tooltips. Instead, provide clear labels and sufficient text. This is particularly important for forms!

However, if you wanna go down that path, the popover attribute provides a starting point for building popover-like interactions on the web. Its purpose is simply to add 'popover/tooltip behaviour'. So we'll use it to create our custom plain-text tooltip.

To start, we just need an interactive element (like a button) which is used to trigger the tooltip, even when navigating with a keyboard only, and a <div> containing the tooltip content.

The <button> is linked to the tooltip with aria-describedby.
The <div> receives the popover attribute and an id.
As the popover attribute just adds behaviour, not semantics, we need to add our own role when it makes sense. Therefore we add role='tooltip' to the <div>.

<p>
  There is a
  <button type="button" aria-describedby="tooltip">secret</button> to accessible
  HTML!
</p>

<div popover role="tooltip" id="tooltip">
  <div>a div is not a button ✨</div>
</div>

Let's make it interactive

If we would want to create a toggletip, which opens onClick, we could simply add popovertarget="ID" to the <button>, with the id of the toggletip.

There is a 
<button type="button" aria-describedby="toggletip" popovertarget="toggletip">
  secret
</button>
to accessible HTML!

<div popover id="toggletip">
  <div>a div is not a button ✨</div>
</div>

However, if we want our tooltip, that is triggered when the interactive element is hovered or focused, we need JavaScript.
We can display the tooltip by using .hidePopover() and .showPopover().
If showPopover() is called on an element with the popover attribute that is currently hidden, the element is added to the top rendering layer.

A tooltip usually disappears when hitting the Escape key or when the mouse is moved away from the interactive element.
But it's also important to make sure that the tooltip content is reachable with the mouse pointer. That way, users can copy the text or read it with magnification software.
That's why, with the help of JavaScript, we show the tooltip on mouseover of the interactive element and keep it visible when the tooltip itself is hovered (by also listening to mouseover).
With mouseout we can hide the tooltip as soon as the mouse leaves either the tooltip or the interactive element that triggered it.

To open or close the tooltip with keyboard navigation, we must listen to the focusin and focusout events of the button.
The tooltip must be easy to dismiss (e.g. by pressing the Escape key).
It's also worth noting that tooltips don't actually get the focus themselves. The focus stays on the element that triggered the tooltip.
However, it's content is still read to screen reader users and is accessible by the screen readers virtual cursor.
But remember, in general, if we're showing content automatically when an element receives focus, it's important not to suddenly change context and confuse users.

Wait, is this new attribute supported?

Good news! The popover attribute is supported by all modern browsers with versions released between mid-2023 and 2024 (starting with Safari 17.0, Firefox 125, Chrome 114 and Edge 114).

Looks bad though

That's why the last thing to do is use CSS to style the tooltip.
If you want to change how the tooltip looks when it's displayed, you can use the :popover-open pseudo-class.

We also need to make sure the tooltip is correctly positioned.
We can use position-anchor and position-area for Chrome and Edge, but they're still in the experimental phase, so we need an alternative for other browsers. The simplest option would be to use a library like Floating UI.

There is a secret to accessible HTML!

And that's it, you just created a custom tooltip!
Find the detailed code in this CodePen.

About Daniela Kubesch

Daniela Kubesch is an accessibility engineer who is passionate about user experience and inclusive design. She strongly believes in equality and inclusion and is committed to making digital services accessible. Daniela is also a co-creator of a11yphant.com, a platform that teaches the basics of web accessibility.

Website/Blog: dnikub.dev
Mastodon: front-end.social/@dnikub
Twitter: @dnikub
LinkedIn: danikubesch

More articles