Skip to main content
BEEQ Tooltip component overviewBEEQ Tooltip component overview

Tooltip component overview

Tooltips provide supplemental context about an element without cluttering the interface. They appear on hover or click and disappear automatically, making them ideal for short clarifying text like control names, definitions, or brief instructions.
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
Choose bq-dialog instead of bq-tooltip when the content is essential or the user must respond before continuing, and bq-drawer when the content needs a larger panel with interactive controls.

​
Anatomy

Tooltip anatomyTooltip anatomy

Tooltip anatomy

​
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. Open tooltips follow their trigger automatically when it moves, including during CSS animations or changes to a parent layout. You do not need to call a repositioning method. Movement tracking runs while the tooltip is open. On pages with many tooltips, keep only the ones you need open: use hide() or set visible to false to stop tracking. For an always-visible tooltip, remove that setting first. Hiding an open tooltip with CSS alone does not stop its tracking.

​
Usage

​
Default

By default the tooltip appears above the trigger on hover. Tooltip content goes in the default slot; the interactive element goes in the trigger slot.
You can use any element as the trigger, but for accessibility reasons, it should be something that can receive keyboard focus (e.g., a button, link, or input). If you need to attach a tooltip to a non-focusable element like an icon, set display-on="click" so touch users can access the content. The trigger wrapper is not focusable, so keyboard users still need a focusable trigger such as a button.

​
Placement

Use placement 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. Allowed placement values: top (default), top-start, top-end, right, right-start, right-end, bottom, bottom-start, bottom-end, left, left-start, left-end.
The full set of placement values also includes sub-positions: top-start, top-end, right-start, right-end, bottom-start, bottom-end, left-start, left-end. Use these when you need the tooltip to align with one edge of the trigger rather than centering on it.

​
Display on click

You should set display-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. Allowed display-on values: hover (default), click.

​
Always visible

Use always-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 the visible 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

The show() 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 support preventDefault(). 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

Add hide-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

Set same-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

The distance 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’tAvoid tooltips for lengthy explanations. Don’t put interactive elements like links or buttons inside a tooltip, because keyboard and touch users can’t reach them.
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. You must not place critical instructions, error messages, or required form guidance inside a tooltip.
  • Keyboard accessible — when display-on is hover (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 has role="tooltip" and toggles aria-hidden with visibility. The component does not create an aria-describedby association or live region, so showing the panel does not guarantee an announcement. You must give the trigger an understandable accessible name and must keep essential guidance in visible text.
  • Use focusable triggers — the tooltip does not make its trigger focusable. display-on="click" helps touch users, but keyboard users can only reach the tooltip through a focusable trigger such as a button, so the trigger should be focusable.
  • Preserve control semantics — the trigger wrapper delegates events without adding a role or a tab stop. The slotted control keeps its accessible name, existing descriptions, and native keyboard activation. You must not turn the wrapper into another button or point a light-DOM aria-describedby at the panel inside the tooltip’s shadow root; that ID reference cannot cross the shadow boundary.
  • WCAG 1.4.13 (Content on Hover or Focus) — hover-mode tooltips close when the pointer leaves the trigger or focus moves away, and the panel itself is not hoverable. Esc dismisses only click-mode tooltips. You should keep tooltip content short and non-essential, and should use display-on="click" when users need time to read it.

​
Keyboard interaction

Escape has no effect in hover mode or when always-visible is set.

​
Rules

​
API reference

​
Properties

​
Invalid combinations

​
Events

  • 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. Calling event.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

​
Slots

​
Shadow parts

​
CSS custom properties

Learn more about styling with shadow parts and 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.