Skip to content

Toggletip

Overlay – Disclosure

A toggletip is a small popup that appears when a user clicks a trigger or activates it with the keyboard, showing helpful information or interactive content such as buttons and links. Its read-only counterpart is the tooltip, which appears on hover or focus and holds short supplemental text only. Both are documented here — they look alike and share a trigger, but differ in how they open and what they may contain.

  • CSS

Maintained by Platform and Foundation

Ready to use

DesignCSSAccessibility

A toggletip is a small popup that opens when someone clicks a trigger or activates it with the keyboard. It carries helpful information or interactive content — a link, a button, a short block of copy — and stays until it is dismissed. Its read-only counterpart is the tooltip: it appears on hover or focus, holds a few words of supplemental text, and never contains anything you can interact with. The two look alike and share an icon-based trigger, but they differ in how they open and in what they are allowed to contain.

Anatomy

Section titled “Anatomy”
Title
Link
  1. Toggletip
  2. Arrow
  3. Container
  4. Close button
  5. Title (optional)
  6. Content
  7. Link (optional)

The Container holds everything and sets the width — it hugs its content between a 200px floor and a 340px ceiling. The Arrow points back at the trigger and can sit on any of the four sides. Inside, an optional Title names the toggletip, the Close button dismisses it, and the Content slot takes whatever the consumer puts there. An optional Link closes the block when the toggletip leads somewhere.

A tooltip uses a reduced version of the same anatomy: arrow, container, and a single line of text. It has no title, no close button, no content slot and no link — if you need any of those, you need a toggletip.

When to use it

Section titled “When to use it”

The quickest way to choose is to ask what the content is, then how long it runs:

  • Not contextual, helpful and non-essential? It doesn’t belong in either — show it on the page.
  • Four words or fewer, read-only? Tooltip.
  • Longer than that, but under ~350 characters? Toggletip.
  • Longer than ~350 characters? Modal.

Use a toggletip when:

  • An interactive element — a link, a button, a control — has to live inside the overlay.
  • Someone needs to make a quick, in-context edit without leaving the page.

Use a tooltip when:

  • An icon-only button needs its purpose spelled out.
  • A control, value or label needs a quick clarification.
  • A word, abbreviation or data label inside text or a table needs a definition.

Avoid both when:

  • The information is important or legal — anything someone must see to finish a task, such as errors, instructions or pricing. Use visible helper text, or a modal.
  • The content repeats something already visible on the page.
  • The content is long. Reach for a modal or a dedicated page section rather than letting the overlay scroll.

Tooltips carry two extra restrictions: never put interactive content inside one (that makes it a toggletip), and never rely on one for information that matters on touch devices.

Properties

Section titled “Properties”

Activation

A toggletip opens on click or Enter and stays until it is dismissed. A tooltip appears on hover or focus and hides again on blur, pointer-leave or Escape. This is the property everything else follows from — it decides whether focus can move inside, and therefore whether the overlay may hold controls.

Content

A toggletip takes text and interactive elements. A tooltip takes read-only text only. There is no middle ground: the moment an overlay contains something focusable, it stops being a tooltip.

Placement

Both forms auto-position by default so they stay fully visible in the viewport. They can also be pinned to the top, right, bottom or left of the trigger. Whichever you pick, the overlay should not cover important content, and should not be clipped by the viewport or a neighbouring element.

Content slot

The toggletip’s replaceable slot accepts custom content — formatted text, a small set of controls, or a component instance. Anything interactive inside it takes part in the toggletip’s focus order, so keep the sequence predictable and the set small.

Width

The toggletip hugs its content between a 200px minimum and a 340px maximum, so short labels and longer translations both fit without truncation or horizontal scrolling. A tooltip drops the minimum and hugs freely, which keeps a two-word chip tight; it keeps the maximum, so a long string wraps rather than running off-screen.

Platform considerations

Section titled “Platform considerations”

Desktop

Both forms work. Tooltips open on hover or keyboard focus; toggletips open on click and persist until dismissed. This is the only platform where a tooltip is fully reliable, because it is the only one with a real hover state.

Tablet

Mixed input. Toggletips are unaffected — a tap is a click. Tooltips become unreliable as hover disappears; reserve them for controls that can take keyboard focus, and don’t let anything important depend on them.

Mobile

Avoid tooltips: there is no hover, so the content is simply unreachable. Replace them with a toggletip, which a tap opens correctly. Don’t reach for a long-press instead — it isn’t a native pattern and people don’t discover it. If the content feels important enough that you’re wondering how to surface it on mobile, it probably shouldn’t be a tooltip at all: tooltips are non-essential by definition, and if it matters on mobile it matters everywhere, so display it permanently.

Best practices

Section titled “Best practices”

Pick the form that matches the interaction, then keep the content small enough that the form still fits.

Do

Use tooltips for short, read-only explanations on hover or focus, and toggletips whenever the overlay needs a control. Give every toggletip an explicit close affordance. Keep the content compact enough that it never scrolls. Stick to one topic per overlay, splitting anything more complex into separate tips or a larger component. Position the arrow so it clearly points back at its trigger. Replace tooltips with toggletips on touch.

Don't

Don’t put buttons, links or form controls inside a tooltip — that’s a toggletip. Don’t use either form for information required to complete a task, or for errors, instructions and pricing. Don’t let an overlay scroll; if it needs a scrollbar, it needs a modal or a page section. Don’t repeat copy that is already on the page. Don’t rely on a long-press to surface a tooltip on touch.

Content guidelines

Section titled “Content guidelines”

Keep the copy short, plain and focused on one idea, and lead with the most important word so it can be scanned rather than read.

Tooltips are the tighter of the two. An icon-button label runs two to four words; a definition, one sentence; a piece of supplemental help, one or two short sentences. For an icon-only button the tooltip should normally say the same thing as the button’s own name — “Delete item” paired with the label “Delete item”, not a re-worded “Remove this item permanently”. Avoid lists, headings and italics inside a tooltip; if the copy needs structure, it has outgrown the form.

Toggletips stretch to one to three short sentences and may carry a link or a button, but only ones that are genuinely necessary. Keep the title, body and link in that order so the reading and announcement sequence stays predictable, and check the wrapping at longer languages such as German and Finnish — both forms grow vertically, so avoid fixed heights.