Tooltip for form entry


Tooltip is a hover and focus-activated flyout.

A tooltip provides descriptive or advisory content (i.e. a hint or tip) about a control. This content appears inside of an overlay whenever the control has mouseover or focus.

In desktop software tooltips are most commonly used in relation to toolbar buttons. Web tooltips are more commonly experienced in relation to links, buttons and form controls.

Working Examples

You can take a look at the tooltip pattern in action on our examples site.


We use the following terminology when discussing this pattern.

  • tooltip
    • the composite pattern as a whole, containing a host and overlay
  • host
    • the control that hosts the overlay
  • overlay
    • the overlay that contains the tip

Best Practices

First of all, the HTML title attribute is not an accessible tooltip. Read the title tooltip anti-pattern for more details.

Secondly, the tooltip must describe the host element only. Do not create a host element (e.g. a button) purely for the sake of displaying an overlay. If that is your wish, consider the Bubble Help pattern instead.

Tooltip must not be applied to static elements. See the non-interactive hover anti-pattern.

Tooltip must not use the aria-haspopup attribute. Tooltips are not considered 'popups' in this context.

Tooltip should not be more than one sentence. Consider using the Bubble Help pattern for longer content.

Tooltip should follow the principal of progressive disclosure - revealing the right information, at the right time.

If the tooltip conveys crucial information, overlay content should be visible in a no-JavaScript state (i.e. use progressive enhancement).

Interaction Design

This section provides the pattern interaction design for keyboard, screen reader, mouse & touch.


Host must be keyboard focusable.

Overlay must appear after short delay when host receives focus.

Focus must move from host to first focusable control in overlay.

Overlay must dissapear when focus leaves flyout.

Focus should not move to overlay element itself, only it's focusable children.


Assistive technology that supports tooltip role will announce the overlay content after a short delay. This delay is configurable in most screen readers.

Reading order must flow directly from host into overlay.


Overlay must appear after short delay whenever host receives mouseover.

Overlay must disappear when neither the host or overlay have mouseover.


Many touch devices do not support hover interactions!

You should consider using the click-activated Bubble Help pattern instead.

Developer Guide 1

Our first developer guide focuses on a non-progressive enhancement scenario.

This is actually a common scenario for most button-based tooltips. Often the tooltip content relates to a behaviour or action performed by a button. For example, toolbar buttons on an inline HTML editor. Without JavaScript, the button is non-operable and so the tooltip is redundant.

Developer guide coming soon, in the meantime please read the progressive enhancement guide below.

Developer Guide 2 - Progressive Enhancement

Our next guide follows the Progressive Enhancement strategy. Building in a layered fashion allows everyone to access the basic content and functionality of a web page.

The three layers are:

  1. Content (HTML)
  2. Presentation (CSS)
  3. Behaviour (JS)

The tooltip content is fully visible and accessible without CSS and JavaScript.

Content (HTML)

The goal of our content layer is to add helpful, advisory content to an existing page control.

Identify Element

First we identify the host that requires a tooltip.

We will use the "Add to Cart" submit button below:

  <input type="submit" value="Add to Cart" />

This button is a form submit button and does not require client-side script to operate.

Add Content

We now need to add our hint content to the base markup.

We place our content directly after the submit button:

  <input type="submit" value="Add to Cart" />
  <span>Your cart contains <a href="http://cart.payments.ebay.com/sc/view">6 items</a></span>

The content sits in a new span element which will later act as the overlay.

Notice that our tooltip content contains a nested hyperlink. We must also ensure that any content inside of the overlay is accessible too.


Now let's add our ARIA attributes:

  <input type="submit" value="Add to Cart" aria-describedby="tooltip1" />
  <span id="tooltip1" role="tooltip">Your cart contains <a href="http://cart.payments.ebay.com/sc/view">6 items</a></span>

The span element now has role=tooltip and a unique id. The button references this id in it's own aria-describedby attribute.

Widget Hooks

We wrap our host and overlay elements together in a new parent element to form the root element for our tooltip widget:

  <span class="tooltip">
    <input type="submit" value="Add to Cart" aria-describedby="tooltip1" />
    <span id="tooltip1" role="tooltip">(Your cart contains <a href="http://cart.payments.ebay.com/sc/view">6 items</a>)</span>

We give our widget a class of 'tooltip' to act as the hook for CSS and JavaScript.


Our markup is now complete. The button, it's hint content and the link inside of the hint content are all functional and accessible.

Presentation (CSS)

We could use pure CSS and display the hint using the :hover and :focus pseudo selectors. However, we would soon run into accessibility issues. When keyboard users tab away from the button, the tooltip overlay would dissapear. This behaviour prevents focus on any links inside of the tooltip overlay. We need to use JavaScript to prevent this behaviour.


To be able to position the overlay with JavaScript, we set either absolute or fixed positioning:

.tooltip--js [role=tooltip] {
    display: none;
    position: absolute;
    white-space: nowrap;
    z-index: 1;

Notice we are using the tooltip--js selector. JavaScript can add this modifier class when the widget has fully initialised. Our tooltip isn't hidden until that time. This ensures that the tooltip content is readable and accessible without JavaScript.


Our presentation is now complete. At this point, the content remains fully visible and accessible.

Behaviour (JS)

The goal of our JavaScript layer is control the visibility of the tooltip content.


The overlay must display when hovering with mouse or focusing with keyboard.

Our overlay element is a descendant of the widget element. This DOM hierarchy makes it trivial to use mouse and focus events to hide and show the overlay.

$tooltip.on('focusin', showOverlay);
$tooltip.on('focusExit', hideOverlay);;

NOTE: focusExit is a custom event created by the jquery-focus-exit plugin. This plugin makes it a little easier to figure out when keyboard has left the widget.

Final Checkpoint

Our accessibility behaviour is now complete.

This pattern lays the foundation for creating an accessible tooltip.

The following additional behaviour is outside the scope of this guide:

  • Re-positioning the overlay when near edge of screen
    • A good candidate for a jQuery plugin (if it doesn't already exist)
  • Adding mouseenter and mouseleave event handlers
    • The tooltip must display for mouse users too, remember!


This is different to the way Bootstrap Tooltip works. Why?

The fundamental difference is that the Bootstrap Tooltip get it's content from the title attribute, whereas the pattern presented here gets it's content from an element's innerHTML. This allows us to more easily place HTML such as hyperlinks inside of our tooltips and, unlike Bootstrap, the tooltip content will be fully accessible without JavaScript.

Why do we need JavaScript at all? Can't we do a tooltip with just CSS?

A pure CSS solution only gets us so far, it could not cover the following situations:

  • Delay before showing overlay
  • Keyboard focus management
  • Overlay re-positioning logic when scrolling or near edge of screen

results matching ""

    No results matching ""