Tooltips

Variations Design Guidelines Code Reference Accessibility

Tooltips
updated

HTML/CSS Available
Web Component Available
Last Updated
2.20.0

Tooltips provide a short description of a page element or control.

Variations Design Guidelines Code Reference Accessibility

Variations

Default

Use to provide a short description of an object without a label.

Default

Hover for Tooltip

HTML

Web Component

<div class="mds-tooltip__wrapper">
    <button class="mds-button mds-button--secondary" type="button" aria-describedby="tooltip1">
        Hover for Tooltip
    </button>
    <div id="tooltip1" class="mds-tooltip mds-tooltip--default mds-tooltip--width-m mds-tooltip--right-center" role="tooltip" aria-hidden="false" aria-labelledby="tooltiptext1">
        <div class="mds-tooltip__text " id="tooltiptext1">
            Tooltip Text
        </div>
    </div>
</div>

<mds-button variation="secondary" id="default-trigger" type="button"> Hover for Tooltip </mds-button>
<!-- Tooltip must be appended at the end of the <body> -->
<mds-tooltip triggered-by="default-trigger" id="default-tooltip" position="right-center"> Tooltip Text </mds-tooltip>

Triggered by hovering over an object.

Prompt

Use to temporarily direct attention to an object or functionality.

Default

Add to List

HTML

Web Component

<div class="mds-tooltip__wrapper">
    <button class="mds-button mds-button--icon-only mds-tooltip__target mds-tooltip__target--block" type="button" aria-describedby="tooltip2">
        <svg class="mds-icon mds-button__icon mds-button__icon--right">
            <use xlink:href="/icons/mds.svg#plus">
                <title>Add to list</title>
            </use>
        </svg>
    </button>
    <div id="tooltip2" class="mds-tooltip mds-tooltip--prompt mds-tooltip--width-l mds-tooltip--sticky mds-tooltip--closable mds-tooltip--right-center" role="tooltip" aria-hidden="false" aria-labelledby="tooltiptext2">
        <div class="mds-tooltip__text " id="tooltiptext2">
            Your list is empty. Add some investments to get started.
        </div>
        <div class=" mds-tooltip__close-button">
            <button class="mds-button mds-button--small mds-button--icon-only">
                <svg class="mds-icon mds-button__icon">
                    <use xlink:href="/icons/mds.svg#remove--s">
                        <title>Close</title>
                    </use>
                </svg>
            </button>
        </div>
    </div>
</div>

<mds-button variation="icon-only" icon="plus" id="prompt-trigger" type="button"> Add to List </mds-button>
<!-- Tooltip must be appended to end of <body> -->
<mds-tooltip variation="prompt" triggered-by="prompt-trigger" id="prompt-tooltip" position="right-center"> Your list is empty. Add some investments to get started. </mds-tooltip>

Dismissable by clicking the close button.

Error

Use to direct attention to an error.

Default

Submit

HTML

Web Component

<div class="mds-tooltip__wrapper">
    <button class="mds-button mds-button--primary" type="button" disabled aria-describedby="tooltip3">
        Submit
    </button>
    <div id="tooltip3" class="mds-tooltip mds-tooltip--error mds-tooltip--width-l mds-tooltip--sticky mds-tooltip--right-center" role="tooltip" aria-hidden="false" aria-labelledby="tooltiptext3">
        <div class="mds-tooltip__text " id="tooltiptext3">
            There’s a problem. Please correct all errors before submitting.
        </div>
    </div>
</div>

<mds-button variation="primary" id="error-trigger" type="button" disabled> Submit </mds-button>
<!-- Tooltip must be appended at the end of the <body> -->
<mds-tooltip variation="error" triggered-by="error-trigger" id="error-tooltip" position="right-center" visible>
    There’s a problem. Please correct all errors before submitting.
</mds-tooltip>

Dismissable by correcting error.
Not commonly used. For inline errors, please see Field Errors.

There are 12 possible positions. Choose one that keeps the tooltip’s content in the viewport. For all positioning options see class references or props.

Positioning

Top Center

Right Bottom

HTML

Web Component

<div class="mds-tooltip__wrapper">
    <button class="mds-button " type="button" aria-describedby="tooltip4">
        Top Center
    </button>
    <div id="tooltip4" class="mds-tooltip mds-tooltip--default mds-tooltip--width-m mds-tooltip--top-center" role="tooltip" aria-hidden="true" aria-labelledby="tooltiptext4">
        <div class="mds-tooltip__text " id="tooltiptext4">
            Top Center
        </div>
    </div>
</div>
<div class="mds-tooltip__wrapper">
    <button class="mds-button " type="button" aria-describedby="tooltip5">
        Right Bottom
    </button>
    <div id="tooltip5" class="mds-tooltip mds-tooltip--default mds-tooltip--width-m mds-tooltip--right-bottom" role="tooltip" aria-hidden="true" aria-labelledby="tooltiptext4">
        <div class="mds-tooltip__text " id="tooltiptext4">
            Right Bottom
        </div>
    </div>
</div>

<mds-button variation="secondary" id="top-center-trigger" type="button"> Top Center </mds-button>
<mds-button variation="secondary" id="right-bottom-trigger" type="button"> Right Bottom </mds-button>
<!-- Tooltip must be appended at the end of the <body> -->
<mds-tooltip triggered-by="top-center-trigger" id="top-center-tooltip" position="top-center">
    Top Center
</mds-tooltip>
<mds-tooltip triggered-by="right-bottom-trigger" id="right-bottom-tooltip" position="right-bottom">
    Right Bottom
</mds-tooltip>

The web component includes built-in edge detection logic that always keeps the tooltip within the viewport. To use this logic, omit the position prop from the custom element.

Web Component Auto Positioning

Sizing

Sizing affects the text size and internal spacing. The default size is medium, and you can use modifier classes or props to make the tooltip smaller or larger.

Small

Medium (Default)

Large

Small

Hover for Tooltip

Medium (Default)

Hover for Tooltip

Large

Hover for Tooltip

HTML

Web Component

<div class="mds-tooltip__wrapper">
    <button class="mds-button mds-button--secondary" type="button" aria-describedby="small-tooltip">
        Hover for Tooltip
    </button>
    <div id="small-tooltip" class="mds-tooltip mds-tooltip--default mds-tooltip--small mds-tooltip--width-m mds-tooltip--right-center" role="tooltip" aria-hidden="false" aria-labelledby="false">
        <div class="mds-tooltip__text " id="false">
            Tooltip Text
        </div>
    </div>
</div>

<mds-button variation="secondary" id="small-trigger" type="button"> Hover for Tooltip </mds-button>
<!-- Tooltip must be appended at the end of the <body> -->
<mds-tooltip size="small" triggered-by="default-trigger" id="default-tooltip" position="right-center"> Tooltip Text </mds-tooltip>

Prompt and error tooltips are only available in the small size.

Use When

Providing a short description of a page element or control.
Describing the action of an icon-only button.
Revealing the full text of truncated data.

Revealing the purpose of a menu that has a dynamic title.

Lists & Screens menu inside Direct Cloud.

Don’t Use When

Providing a description longer than 10 words. Instead, use a Popover.

Visual Language

Consider applying a custom z-index value when you compose this component with other layered components, e.g., Dialogs, Modals, Popovers or Notifications to meet your product requirements.

Do center the tooltip’s tail on its associated object, even if the tooltip’s balloon is offset.

Don‘t offset the tooltip’s tail or orient and/or move the tooltip locked with the cursor.

Do use tooltips which are the same size as, or smaller than, the <a class="mds-link" href="/components/buttons.html">Button</a> they are attached to. — Do use tooltips which are the same size as, or smaller than, the Button they are attached to.

Don‘t use tooltips which are bigger than the <a class="mds-link" href="/components/buttons.html">Button</a> they are attached to. — Don‘t use tooltips which are bigger than the Button they are attached to.

Editorial

Keep it brief—aim for fewer than 10 words.
End full sentences with a period. Using “&” is OK. No “!”.
For brevity, don’t spell out numbers: Use 12, not twelve.

Errors

CSS

Class References

Class	Applies to	Outcome
`mds-tooltip__wrapper`	Any block, or inline-block element, most likely a `<div>`	This class should be on the immediate parent of the tooltip’s target element, and it must wrap the target and the tooltip itself. If the tooltip is triggered on hover, this is the element on which that hover is triggered.
`mds-tooltip__target`	Any inline, block, or inline-block element	This is used to enable showing/hiding the tooltip on keyboard focus of a focusable tooltip target element. For example, if the tooltip target is an `<a>` or `<button>`, focusing the element will show the tip.
`mds-tooltip--default`	`mds-tooltip`	Sets background color, drop shadow and text styling for a default tooltip.
`mds-tooltip--small`	`mds-tooltip`	Adjusts styling to render a small tooltip.
`mds-tooltip--large`	`mds-tooltip`	Adjusts styling to render a large tooltip.
`mds-tooltip--prompt`	`mds-tooltip`	Sets background color, drop shadow and text styling for a prompt tooltip.
`mds-tooltip--error`	`mds-tooltip`	Sets background color, drop shadow and text styling for an error tooltip.
`mds-tooltip--closable`	`mds-tooltip--prompt`	Gives a tooltip padding space to account for a close button.
`mds-tooltip__target--help`	Any block, inline-block, or inline element	Changes cursor to (?) symbol on hover indicating help information.
`mds-tooltip--top-center`	`mds-tooltip`	Aligns tooltip to the top center of the invoking element.
`mds-tooltip--top-right`	`mds-tooltip`	Aligns tooltip to the top right of the invoking element.
`mds-tooltip--top-left`	`mds-tooltip`	Aligns tooltip to the top left of the invoking element.
`mds-tooltip--bottom-center`	`mds-tooltip`	Aligns tooltip to the bottom center of the invoking element.
`mds-tooltip--bottom-right`	`mds-tooltip`	Aligns tooltip to the bottom right of the invoking element.
`mds-tooltip--bottom-left`	`mds-tooltip`	Aligns tooltip to the bottom left of the invoking element.
`mds-tooltip--right-center`	`mds-tooltip`	Aligns tooltip to the right center of the invoking element.
`mds-tooltip--right-top`	`mds-tooltip`	Aligns tooltip to the right top of the invoking element.
`mds-tooltip--right-bottom`	`mds-tooltip`	Aligns tooltip to the right bottom of the invoking element.
`mds-tooltip--left-center`	`mds-tooltip`	Aligns tooltip to the left center of the invoking element.
`mds-tooltip--left-top`	`mds-tooltip`	Aligns tooltip to the left top of the invoking element.
`mds-tooltip--left-bottom`	`mds-tooltip`	Aligns tooltip to the left bottom of the invoking element.

Web Component

Props

When setting props as attributes on a custom HTML element, use kebab-case instead of camelCase.

Prop	Type	Validation	Default	Description
`additionalClass`	String	—	—	A space-separated list of class names that will be appended to the default `mds-tooltip` class.
`dismissIconAriaLabel`	String	—	`Dismiss`	Sets the `aria-label` attribute on the icon-only dismiss button.
`position`	String	One of: `top-center`, `top-right`, `top-left`, `bottom-center`, `bottom-right`, `bottom-left`, `right-center`, `right-top`, `right-bottom`, `left-center`, `left-top`, `left-bottom`	`top-center`	Sets position of the tooltip relative to its trigger.
`size`	String	One of: `small`, `medium`, `large`	`medium`	Alters size of the tooltip.
`text`	String	Required	—	Sets the tooltip text. Can also be passed via the default slot.
`triggeredBy`	String	Required	—	The `id` of the tooltip trigger element.
`variation`	String	One of: `default`, `error`, `prompt`	`default`	Sets the tooltip variation.
`visible`	Boolean	—	`false`	Sets visibility of the tooltip.

Slots

Default Slot

Any text passed in between the <mds-tooltip></mds-tooltip> tags will be used as the tooltip’s text content.

Methods

Method Name	Description
`open()`	Shows tooltip. Called on `mouseenter` or focus of trigger element.
`dismiss()`	Hides tooltip. Called on `mouseleave` or blur of trigger element.

Events

Event Name	Description
`mds-tooltip-dismissed`	Triggers when the tooltip is dismissed.

Usage Examples

Setting triggeredBy and size via props. Using the default slot for text content:

<mds-button id="tip-1" type="button"> Tooltip </mds-button>
<!-- Appended at end of <body> -->
<mds-tooltip triggered-by="tip-1" size="small"> Tooltip text </mds-tooltip>

Setting triggeredBy and variation via props. Using the default slot for text content:

<mds-button id="tip-2" type="button"> Tooltip </mds-button>
<!-- Appended at end of <body> -->
<mds-tooltip triggered-by="tip-2" variation="prompt" visible> Prompt tooltip text </mds-tooltip>

Implementation

A tooltip’s trigger should be focusable, the tooltip should show on focus and hide on blur.
Use aria-hidden="true" to prevent screenreaders from reading hidden tooltips. Change value to false when tooltip is visible.
Tooltip trigger element should have a aria-describedby attribute which references to the id of the associated tooltip.

Best Practices

By default, tooltips use role="tooltip".

Variations

Default

Prompt

Error

Tooltip Positioning

Sizing

Use When

Don’t Use When

Visual Language

Editorial

Related UX Patterns

CSS

Class References

Web Component

Props

Slots

Default Slot

Methods

Events

Usage Examples

Implementation

Best Practices