Tooltips are for non-essential information only. Never put critical instructions, form errors, or content that must be read to complete a task inside a tooltip.
When to use
Use tooltips when
- Exposing names of icon-only controls that have no visible label
- Providing a short definition for a technical term or inline item
- Supplying optional context without cluttering the layout
- The element can receive focus and extra guidance helps decision-making
Do not use tooltips when
- The information is essential to completing the task
- The content is too lengthy or detailed to fit in a small box
- The element is interacted with frequently (repeated dismissal adds friction)
- You would be restating visible UI text
Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Trigger | The element a user interacts with to reveal the tooltip (trigger slot) |
| 2 | Panel | The floating content box that carries the tooltip text (panel slot) |
| 3 | Content | The actual tooltip content, which can be plain text or any HTML content (default slot) |
| 3 | Arrow | The directional pointer connecting the panel to the trigger (hidden with hide-arrow) |
Design guidelines
Use tooltips for short contextual help attached to a specific control or value. Keep content brief, avoid placing essential instructions only inside a tooltip, and make sure the trigger remains understandable without the tooltip.Usage
Default
By default the tooltip appears above the trigger on hover. Tooltip content goes in the default slot; the interactive element goes in thetrigger slot.
Placement
Useplacement to control which side of the trigger the tooltip appears on. The four primary values are top (default), right, bottom, and left. Each also supports -start and -end sub-variants for fine-grained alignment.
Display on click
Setdisplay-on="click" when the trigger element is not naturally focusable (e.g., a plain icon or image) or when hover behavior would conflict with touch devices. The tooltip toggles on each click and closes on Esc or an outside click.
Always visible
Usealways-visible to keep the tooltip permanently displayed regardless of user interaction. Useful for onboarding callouts, feature highlights, or design previews.
When
always-visible is set, the programmatic hide() method has no effect.Controlled visibility
Use thevisible prop when your application needs to control the tooltip’s open/closed state declaratively — for example, showing a tooltip in response to a data-loading event, a validation result, or any app logic that is not tied to the trigger element’s own interaction.
Unlike always-visible, a controlled tooltip can still be dismissed by the user moving focus away (hover mode) or pressing Esc (click mode).
Programmatic control
Theshow() and hide() async methods give you imperative control over the tooltip from outside the component — useful when another UI element or an application event should trigger the tooltip rather than the trigger element’s own interaction.
Cancelling default behavior
All five tooltip events supportpreventDefault(). Calling it inside a handler cancels the tooltip’s default open or close action — the event still fires and your handler runs, but the panel will not toggle. This is useful for temporarily suppressing the tooltip while an async operation is in progress or based on application state.
Options
Hide arrow
Addhide-arrow to remove the directional pointer. Use this when the tooltip is associated with a wide trigger element or when the arrow would visually conflict with nearby content.
Same width
Setsame-width to match the tooltip panel width to the trigger element. Useful when the tooltip content is shorter than the trigger and you want a more contained alignment.
Distance
Thedistance prop controls the gap in pixels between the trigger and the tooltip panel. The default is 10. Increase it for more breathing room; decrease it for a tighter alignment.
Best practices
DoKeep tooltip content short and scannable — one sentence at most. If you need more space, consider a popover or inline helper text instead.
Don’tDon’t use tooltips for lengthy explanations or content that includes interactive elements like links or buttons — those can’t be reached by keyboard or touch.
DoUse tooltips to label icon-only controls where the action is not immediately obvious from the icon alone.
Don’tDon’t restate visible UI text in a tooltip — it provides no new value and adds noise for screen reader users.
DoKeep the tooltip positioned in view. Prefer
top for most cases; switch to bottom, left, or right when the tooltip would be clipped by the viewport edge.Don’tDon’t place the tooltip inside a parent that is both a scroll container and a containing block for positioned elements. An ancestor with
overflow: hidden or overflow: auto that also establishes a containing block will clip the panel regardless of the positioning strategy used.DoKeep the trigger label or icon understandable without the tooltip so the interface still works on touch devices and assistive technologies.
Don’tDo not put required instructions only in a tooltip. Move essential guidance into visible helper text or the main content.
Accessibility
- Not the only source of truth — tooltips are hidden by default and not guaranteed to be seen by all users. Never place critical instructions, error messages, or required form guidance inside a tooltip.
- Keyboard accessible — when
display-onishover(default), the tooltip also opens on focus so keyboard users can access the content by tabbing to the trigger. Pressing Esc (click mode) or moving focus away closes it. - Screen reader support — the panel sets
aria-hiddenwhen not visible and is announced when shown. Use thetriggerslot with a naturally focusable element (button, link, input) so the tooltip is reachable via keyboard. - Avoid hover-only for non-focusable triggers — for elements that cannot receive keyboard focus, use
display-on="click"to ensure touch and keyboard users can still trigger the tooltip. - WCAG 1.4.13 (Content on Hover or Focus) — revealed content must be dismissible (via Esc), hoverable (pointer can move over the panel), and persistent (does not close while the pointer is over it).
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
alwaysVisible | always-visible | If true, the tooltip stays visible at all times and cannot be hidden | boolean | false |
displayOn | display-on | The interaction that triggers the tooltip — hover (default) or click | 'click' | 'hover' | 'hover' |
distance | distance | Gap in pixels between the trigger element and the tooltip panel | number | 10 |
hideArrow | hide-arrow | If true, the directional arrow on the tooltip panel is hidden | boolean | false |
placement | placement | Position of the tooltip relative to the trigger | 'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'top' |
sameWidth | same-width | If true, the tooltip panel width matches the trigger element width | boolean | false |
visible | visible | If true, the tooltip is visible on first render and after each user interaction | boolean | false |
Events
| Event | Description | Type |
|---|---|---|
bqClick | Fires when the tooltip trigger is clicked | CustomEvent<HTMLBqTooltipElement> |
bqFocusIn | Fires when the tooltip trigger receives focus | CustomEvent<HTMLBqTooltipElement> |
bqFocusOut | Fires when the tooltip trigger loses focus | CustomEvent<HTMLBqTooltipElement> |
bqHoverIn | Fires when the pointer enters the tooltip trigger | CustomEvent<HTMLBqTooltipElement> |
bqHoverOut | Fires when the pointer leaves the tooltip trigger | CustomEvent<HTMLBqTooltipElement> |
- In React, prefix events with
on:onBqClick,onBqFocusIn,onBqFocusOut,onBqHoverIn,onBqHoverOut. - In Angular, use the event binding syntax:
(bqClick),(bqFocusIn),(bqFocusOut),(bqHoverIn),(bqHoverOut). - In Vue, use the
@shorthand with camelCase:@bqClick,@bqFocusIn,@bqFocusOut,@bqHoverIn,@bqHoverOut. preventDefault()is supported on all five events. Callingevent.preventDefault()inside a handler will cancel the tooltip’s default open/close action for that interaction — the event still fires and your handler still runs, but the panel will not toggle. See the Cancelling default behavior example in the Usage section.
Methods
| Method | Description | Signature |
|---|---|---|
show() | Programmatically shows the tooltip | show() => Promise<void> |
hide() | Programmatically hides the tooltip | hide() => Promise<void> |
Slots
| Slot | Description |
|---|---|
| (default) | The tooltip panel content |
trigger | The element a user interacts with to show the tooltip |
Shadow parts
| Part | Description |
|---|---|
base | The outermost <div> wrapper inside the shadow DOM |
trigger | The <div> container wrapping the trigger slot |
panel | The <div> floating container that holds the tooltip content |
CSS custom properties
Resources
Use Storybook to test behavior and states interactively, or review the source if you need implementation details.Interactive playground
Explore all tooltip properties and states in the live Storybook playground.
Source code
Browse the full source code, including the component implementation, tests, and styles.