{}

{} {children &&

{children}

}

; };

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 ## Anatomy Tooltip 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 the `trigger` slot. :host { min-height: 15rem !important; } Yuhu! I'm a tooltip 🙃 And I can present additional context for this action Hover me `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Yuhu! I'm a tooltip 🙃 And I can present additional context for this action Hover me ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqButton, BqTooltip } from "@beeq/react"; Yuhu! I'm a tooltip 🙃 And I can present additional context for this action Hover me ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqButton, BqTooltip } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqButton, BqTooltip], template: ` Yuhu! I'm a tooltip 🙃 And I can present additional context for this action Hover me ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` 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 keyboard and touch users can still access the content. ### 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. :host { min-height: 15rem !important; } Top placement Top

Right placement Right

Bottom placement Bottom

Left placement Left `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Top placement Top

Right placement Right

Bottom placement Bottom

Left placement Left ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqButton, BqTooltip } from "@beeq/react"; Top placement Top Right placement Right Bottom placement Bottom Left placement Left ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqButton, BqTooltip } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqButton, BqTooltip], template: ` Top placement Top

Right placement Right

Bottom placement Bottom

Left placement Left ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` 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 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. :host { min-height: 15rem !important; } Click again or press Esc to close Click me `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Click again or press Esc to close Click me ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqButton, BqTooltip } from "@beeq/react"; Click again or press Esc to close Click me ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqButton, BqTooltip } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqButton, BqTooltip], template: ` Click again or press Esc to close Click me ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### 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. :host { min-height: 15rem !important; } I'm always here Trigger `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} I'm always here Trigger ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqButton, BqTooltip } from "@beeq/react"; I'm always here Trigger ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqButton, BqTooltip } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqButton, BqTooltip], template: ` I'm always here Trigger ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### 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). :host { min-height: 15rem !important; }

Controlled by app state Trigger (hover also works)

Show

Hide

`} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { useState } from "react"; import { BqButton, BqTooltip } from "@beeq/react"; export function ControlledTooltip() { const [isVisible, setIsVisible] = useState(false); return (

setIsVisible(false)} onBqHoverOut={() => setIsVisible(false)} > Controlled by app state setIsVisible(!isVisible)}> Toggle

); } ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqButton, BqTooltip } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqButton, BqTooltip], template: ` Controlled by app state Toggle ` }) export class AppComponent { isTooltipVisible = false; } ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### 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. :host { min-height: 15rem !important; }

Show tooltip

Hide tooltip

`} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}

Show tooltip

Hide tooltip

``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { useRef } from "react"; import { BqButton, BqTooltip } from "@beeq/react"; export function ProgrammaticTooltip() { const tooltipRef = useRef(null); return (

Programmatically controlled Trigger (hover also works) tooltipRef.current?.show()}>Show tooltip tooltipRef.current?.hide()}>Hide tooltip

Show tooltip

Hide tooltip ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### 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. :host { min-height: 15rem !important; }

You can only see me when unlocked! Hover me

Click to lock/unlock hover

Unlocked — hover opens the tooltip normally

`} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}

Click to lock/unlock hover

``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { useRef, useState } from "react"; import { BqButton, BqTooltip, BqSwitch } from "@beeq/react"; export function PreventDefaultTooltip() { const [locked, setLocked] = useState(false); const handleHoverIn = (e) => { if (locked) e.preventDefault(); }; const handleFocusIn = (e) => { if (locked) e.preventDefault(); }; return (

You can only see me when unlocked! Hover me setLocked(e.detail.checked)}> Click to lock/unlock hover

); } ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqButton, BqSwitch, BqTooltip } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqButton, BqSwitch, BqTooltip], template: ` You can only see me when unlocked! Hover me Lock tooltip ` }) export class AppComponent { locked = false; onHoverIn(event: CustomEvent): void { if (this.locked) event.preventDefault(); } onFocusIn(event: CustomEvent): void { if (this.locked) event.preventDefault(); } } ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## 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. :host { min-height: 15rem !important; } With arrow (default) Arrow Without arrow No arrow `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}

With arrow (default) Arrow

Without arrow No arrow ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqButton, BqTooltip } from "@beeq/react"; {/* Default: arrow is shown */} With arrow (default) Arrow {/* No arrow */} Without arrow No arrow ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqButton, BqTooltip } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqButton, BqTooltip], template: `

With arrow (default) Arrow

Without arrow No arrow ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### 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. :host { min-height: 15rem !important; } Same width as trigger, even if content is shorter or longer Same width as trigger `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Same width as trigger, even if content is shorter or longer Same width as trigger ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqButton, BqTooltip } from "@beeq/react"; Same width as trigger, even if content is shorter or longer Same width as trigger ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqButton, BqTooltip } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqButton, BqTooltip], template: ` Same width as trigger, even if content is shorter or longer Same width as trigger ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### 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. :host { min-height: 15rem !important; gap: 1rem !important; } 4px gap Close (4px)

10px gap (default) Default (10px)

24px gap Far (24px) `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} 4px gap Close (4px)

10px gap (default) Default (10px)

24px gap Far (24px) ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqButton, BqTooltip } from "@beeq/react"; 4px gap Close (4px) 10px gap (default) Default (10px) 24px gap Far (24px) ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqButton, BqTooltip } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqButton, BqTooltip], template: ` 4px gap Close (4px)

10px gap (default) Default (10px)

24px gap Far (24px) ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Keep tooltip content short and scannable — one sentence at most. If you need more space, consider a popover or inline helper text instead. Don't Don'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. Do Use tooltips to label icon-only controls where the action is not immediately obvious from the icon alone. Don't Don't restate visible UI text in a tooltip — it provides no new value and adds noise for screen reader users. Do Keep 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't Don'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. Do Keep the trigger label or icon understandable without the tooltip so the interface still works on touch devices and assistive technologies. Don't Do 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-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 sets `aria-hidden` when not visible and is announced when shown. Use the `trigger` slot 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` | | `bqFocusIn` | Fires when the tooltip trigger receives focus | `CustomEvent` | | `bqFocusOut` | Fires when the tooltip trigger loses focus | `CustomEvent` | | `bqHoverIn` | Fires when the pointer enters the tooltip trigger | `CustomEvent` | | `bqHoverOut` | Fires when the pointer leaves the tooltip trigger | `CustomEvent` | * 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](#cancelling-default-behavior) example in the Usage section. ### Methods | Method | Description | Signature | | -------- | ---------------------------------- | ------------------------- | | `show()` | Programmatically shows the tooltip | `show() => Promise` | | `hide()` | Programmatically hides the tooltip | `hide() => Promise` | ### 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 `

` wrapper inside the shadow DOM | | `trigger` | The `

` container wrapping the `trigger` slot | | `panel` | The `

` floating container that holds the tooltip content | ### CSS custom properties | Variable | Description | Default | | -------------------------------- | ------------------------ | ------------------------------------- | | `--bq-tooltip--background-color` | Tooltip background color | `var(--bq-ui--inverse)` | | `--bq-tooltip--box-shadow` | Tooltip box shadow | `var(--bq-box-shadow--m)` | | `--bq-tooltip--font-size` | Tooltip font size | `var(--bq-font-size--m)` | | `--bq-tooltip--line-height` | Tooltip line height | `var(--bq-font-line-height--regular)` | | `--bq-tooltip--text-color` | Tooltip text color | `var(--bq-text--inverse)` | | `--bq-tooltip--paddingX` | Horizontal padding | `var(--bq-spacing-xs)` | | `--bq-tooltip--paddingY` | Vertical padding | `var(--bq-spacing-xs2)` | | `--bq-tooltip--border-color` | Border color | `transparent` | | `--bq-tooltip--border-radius` | Border radius | `var(--bq-radius--s)` | | `--bq-tooltip--border-style` | Border style | `none` | | `--bq-tooltip--border-width` | Border width | `unset` | | `--bq-tooltip--z-index` | Stack order of the panel | `10` | Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties). ## Resources Use Storybook to test behavior and states interactively, or review the source if you need implementation details. Explore all tooltip properties and states in the live Storybook playground. Browse the full source code, including the component implementation, tests, and styles.