# Tooltip Documentation Displays supplementary information when users hover over or interact with an element. This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue. Copy Page ### [Epicenter](https://github.com/EpicenterHQ/epicenter) [Open source, local first apps](https://github.com/EpicenterHQ/epicenter) [Special Sponsor](https://github.com/EpicenterHQ/epicenter) ```svelte ``` ## Structure ```svelte ``` ## Provider Component The `Tooltip.Provider` component is required to be an ancestor of the `Tooltip.Root` component. It provides shared state for the tooltip components used within it. You can set a single `delayDuration` or `disableHoverableContent` prop on the provider component to apply to all the tooltip components within it. ```svelte ``` It also ensures that only a single tooltip within the same provider can be open at a time. It's recommended to wrap your root layout content with the provider component, setting your sensible default props there. +layout.svelte ```svelte {@render children()} ``` ## Managing Open State This section covers how to manage the `open` state of the component. ### Two-Way Binding Use `bind:open` for simple, automatic state synchronization: ```svelte ``` ### Fully Controlled Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes. ```svelte ``` ## Tether `tether` is a shared connection object that lets `Tooltip.Trigger` and `Tooltip.Root` communicate even when they are not in the same component subtree. Without a tether, each root/trigger pair is local, which makes detached layouts harder (for example, a toolbar trigger rendered in one place and tooltip content rendered elsewhere). A tether solves that by giving both sides shared state for the active trigger, open/close behavior, and trigger payload, so you can build singleton-style tooltip patterns without duplicating tooltip content instances. `tether` is inspired by [Base UI](https://base-ui.com/react/components/tooltip#detached-triggers)'s `handle` concept. ### Detached Triggers Use a shared tether when action controls and the tooltip root are not colocated (for example, a dashboard with toolbar actions in different regions): ```svelte Sync now {#snippet children({ payload })}

{payload?.label}

{payload?.description}

{payload?.shortcut} {/snippet} ``` Expand Code ```svelte

Data sources

Pull live data from connected integrations

Sync now

Sharing

Share a live view with your team

Copy link

Automation

Send recurring summaries to your team

Schedule digest Pause digest

{#snippet children({ payload })} {/snippet} ``` ### Singleton Tooltip with Payload A single tooltip can be reused by multiple triggers. The active trigger payload is available from `Tooltip.Root` snippet props: ```svelte {#snippet children({ payload })} Blocked Done

{payload?.name}

{payload?.description}

{/snippet} ``` Expand Code ```svelte {#snippet children({ payload })}

{#each columns as column (column.id)} {column.label} {/each}

{/snippet} ``` ### Controlled Active Trigger In controlled mode, bind both `open` and `triggerId` to open a specific trigger programmatically (useful for guided onboarding flows): ```svelte ``` Expand Code ```svelte

Project Members Deploy

open directly

{#snippet children({ payload })} {/snippet} ``` ## Mobile Tooltips Tooltips are *not* supported on mobile devices. The intent of a tooltip is to provide a "tip" about a "tool" before the user interacts with that tool (in most cases, a button). This is not possible on mobile devices, because there is no sense of hover on mobile. If a user were to press/touch a button with a tooltip, the action that button triggers would be taken before they were even able to see the tooltip, which renders it useless. If you are using a tooltip on a button without an action, you should consider using a [Popover](/docs/components/popover) instead. If you'd like to learn more about how we came to this decision, here are some useful resources: > The tooltip is not the appropriate role for the more information "i" icon, ⓘ. A tooltip is directly associated with the owning element. The ⓘ isn't 'described by' detailed information; the tool or control is. > > [MDN ARIA Tooltips](https://arc.net/l/quote/zfvjgalg) > Tooltips should only ever contain non-essential content. The best approach to writing tooltip content is to always assume it may never be read. > > [Tooltips in the time of WCAG 2.1](https://arc.net/l/quote/gdrkepxb) ## Reusable Components It's recommended to use the `Tooltip` primitives to build your own custom tooltip component that can be used throughout your application. Below is an example of how you might create a reusable tooltip component that can be used throughout your application. Of course, this isn't the only way to do it, but it should give you a good idea of how to compose the primitives. MyTooltip.svelte ```svelte {@render trigger()} {@render children?.()} ``` You could then use the `MyTooltip` component in your application like so: +page.svelte ```svelte alert("changed to bold!") }}> {#snippet trigger()} {/snippet} Change font to bold ``` ## Delay Duration You can change how long a user needs to hover over a trigger before the tooltip appears by setting the `delayDuration` prop on the `Tooltip.Root` or `Tooltip.Provider` component. ```svelte ``` ## Skip Delay Duration When multiple tooltips share a `Tooltip.Provider`, moving quickly from one trigger to another would normally require waiting through the full `delayDuration` each time. The `skipDelayDuration` prop controls a grace period: if the user re-enters any trigger within that window after closing a tooltip, it opens instantly instead of waiting. ```svelte ``` This is ideal for toolbars, nav items, or any group of controls where the user's intent to scan tooltips is clear once they've opened the first one. Hover any button below, then move across the rest. Subsequent tooltips will open without the delay. Expand Code ```svelte

{#each tools as tool, i (tool.label)} {#if i === 4}

{/if} {/each}

``` ## Close on Trigger Click By default, the tooltip will close when the user clicks the trigger. If you want to disable this behavior, you can set the `disableCloseOnTriggerClick` prop to `true`. ```svelte ``` ## Hoverable Content By default, the tooltip will remain open when the user hovers over the content. If you instead want the tooltip to close as the user moves their mouse towards the content, you can set the `disableHoverableContent` prop to `true`. ```svelte ``` ## Non-Keyboard Focus If you want to prevent opening the tooltip when the user focuses the trigger without using the keyboard, you can set the `ignoreNonKeyboardFocus` prop to `true`. ```svelte ``` ## Svelte Transitions You can use the `forceMount` prop along with the `child` snippet to forcefully mount the `Tooltip.Content` component to use Svelte Transitions or another animation library that requires more control. ```svelte {#snippet child({ wrapperProps, props, open })} {#if open}

{/if} {/snippet} ``` Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content components that handles this logic if you intend to use this approach throughout your app. For more information on using transitions with Bits UI components, see the [Transitions](/docs/transitions) documentation. Expand Code ```svelte {#snippet child({ wrapperProps, props, open })} {#if open}

{/if} {/snippet} ``` You can combine the same force-mount transition pattern with singleton triggers: Expand Code ```svelte {#snippet children({ payload })}

{#each plans as plan (plan.id)} {plan.label} {/each}

{#snippet child({ wrapperProps, props, open })} {#if open}

{/if} {/snippet} {/snippet} ``` ## Opt-out of Floating UI When you use the `Tooltip.Content` component, Bits UI uses [Floating UI](https://floating-ui.com/) to position the content relative to the trigger, similar to other popover-like components. You can opt-out of this behavior by instead using the `Tooltip.ContentStatic` component. This component does not use Floating UI and leaves positioning the content entirely up to you. ```svelte Hello ``` ##### Note When using the `Tooltip.ContentStatic` component, the `Tooltip.Arrow` component will not be rendered relative to it as it is designed to be used with `Tooltip.Content`. ## Custom Anchor By default, the `Tooltip.Content` is anchored to the `Tooltip.Trigger` component, which determines where the content is positioned. If you wish to instead anchor the content to a different element, you can pass either a selector `string` or an `HTMLElement` to the `customAnchor` prop of the `Tooltip.Content` component. ```svelte

``` Expand Code ```svelte

Custom Anchor

``` ## API Reference ### Tooltip.Provider A provider component which contains shared state and logic for the tooltips within its subtree. | Property | Type | Description | Details | | ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `delayDuration` | `number` | The amount of time in milliseconds to delay opening the tooltip when hovering over the trigger.`Default: 700` | | | `disableHoverableContent` | `boolean` | Whether or not to disable the hoverable content. This is useful when the content contains interactive elements.`Default: false` | | | `disabled` | `boolean` | Whether or not the tooltip is disabled.`Default: false` | | | `disableCloseOnTriggerClick` | `boolean` | Whether or not to close the tooltip when pressing the escape key. This is useful when the content contains interactive elements.`Default: false` | | | `skipDelayDuration` | `number` | The amount of time in milliseconds to delay opening the tooltip when the user has used their mouse to hover over the trigger.`Default: 300` | | | `ignoreNonKeyboardFocus` | `boolean` | Whether or not to ignore the tooltip when the focus is not on the trigger. This is useful when the content contains interactive elements.`Default: false` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | ### Tooltip.Root The root component containing the parts of the tooltip. Must be a descendant of a `Tooltip.Provider` component. In singleton mode, root children snippet props include `open`, `triggerId`, and `payload`. | Property | Type | Description | Details | | ---------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `open` $bindable | `boolean` | The open state of the component.`Default: false` | | | `onOpenChange` | `function` - (open: boolean) => void | A callback function called when the open state changes.`Default: —— undefined` | | | `onOpenChangeComplete` | `function` - (open: boolean) => void | A callback function called after the open state changes and all animations have completed.`Default: —— undefined` | | | `disabled` | `boolean` | Whether or not the tooltip is disabled.`Default: false` | | | `delayDuration` | `number` | The amount of time in milliseconds to delay opening the tooltip when hovering over the trigger.`Default: 700` | | | `disableHoverableContent` | `boolean` | Whether or not to disable the hoverable content. This is useful when the content contains interactive elements.`Default: false` | | | `disableCloseOnTriggerClick` | `boolean` | Whether or not to close the tooltip when pressing the escape key. This is useful when the content contains interactive elements.`Default: false` | | | `ignoreNonKeyboardFocus` | `boolean` | Whether or not to ignore the tooltip when the focus is not on the trigger. This is useful when the content contains interactive elements.`Default: false` | | | `triggerId` $bindable | `string \| null` | The active trigger id for controlled singleton tooltips. Useful with `bind:triggerId` and programmatic open behavior.`Default: null` | | | `tether` | `TooltipTether` | A shared tether object created by `Tooltip.createTether()` used to connect detached triggers and infer root snippet payload types.`Default: —— undefined` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | ### Tooltip.Trigger A component which triggers the opening and closing of the tooltip on hover or focus. | Property | Type | Description | Details | | --------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `disabled` | `boolean` | Whether or not the tooltip trigger is disabled.`Default: false` | | | `payload` | `Payload` | Payload associated with this trigger. The active payload is available from the `Tooltip.Root` children snippet props.`Default: —— undefined` | | | `tether` | `TooltipTether` | A shared tether object created by `Tooltip.createTether()` used to connect detached triggers and infer root snippet payload types.`Default: —— undefined` | | | `ref` $bindable | `HTMLButtonElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | ---------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `data-state` | `enum` - 'delayed-open' \| 'instant-open' \| 'closed' | Whether/how the tooltip is open or closed. When open, if there is a delay, the value will be 'delayed-open', otherwise it will be 'instant-open'. When closed, the value will be 'closed'. | | | `data-tooltip-trigger` | `''` | Present on the tooltip trigger element. | | ### Tooltip.Content The contents of the tooltip which are displayed when the tooltip is open. | Property | Type | Description | Details | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `side` | `enum` - 'top' \| 'bottom' \| 'left' \| 'right' | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: 'bottom'` | | | `sideOffset` | `number` | The distance in pixels from the anchor to the floating element.`Default: 0` | | | `align` | `enum` - 'start' \| 'center' \| 'end' | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: 'start'` | | | `alignOffset` | `number` | The distance in pixels from the anchor to the floating element.`Default: 0` | | | `arrowPadding` | `number` | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0` | | | `avoidCollisions` | `boolean` | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true` | | | `collisionBoundary` | `union` - Element \| null | A boundary element or array of elements to check for collisions against.`Default: —— undefined` | | | `collisionPadding` | `union` - number \| Partial\> | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0` | | | `sticky` | `enum` - 'partial' \| 'always' | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: 'partial'` | | | `hideWhenDetached` | `boolean` | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true` | | | `updatePositionStrategy` | `enum` - 'optimized' \| 'always' | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: 'optimized'` | | | `strategy` | `enum` - 'fixed' \| 'absolute' | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: 'fixed'` | | | `preventScroll` | `boolean` | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: true` | | | `customAnchor` | `union` - string \| HTMLElement \| Measurable \| null | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null` | | | `onInteractOutside` | `function` - (event: PointerEvent) => void | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default: —— undefined` | | | `onFocusOutside` | `function` - (event: FocusEvent) => void | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default: —— undefined` | | | `interactOutsideBehavior` | `enum` - 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: 'close'` | | | `onEscapeKeydown` | `function` - (event: KeyboardEvent) => void | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default: —— undefined` | | | `escapeKeydownBehavior` | `enum` - 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: 'close'` | | | `forceMount` | `boolean` | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false` | | | `dir` | `enum` - 'ltr' \| 'rtl' | The reading direction of the app.`Default: 'ltr'` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type ChildSnippetProps = { /\*\* \* Props for the positioning wrapper \* Do not style this element - \* styling should be applied to the content element \*/ wrapperProps: Record\; /\*\* \* Props for your content element \* Apply your custom styles here \*/ props: Record\; /\*\* \* Content visibility state \* Use this for conditional rendering with \* Svelte transitions \*/ open: boolean; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | ---------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `data-state` | `enum` - 'delayed-open' \| 'instant-open' \| 'closed' | Whether/how the tooltip is open or closed. When open, if there is a delay, the value will be 'delayed-open', otherwise it will be 'instant-open'. When closed, the value will be 'closed'. | | | `data-tooltip-content` | `''` | Present on the tooltip content element. | | | CSS Variable | Description | Details | | ----------------------------------------- | -------------------------------------------- | ------- | | `--bits-tooltip-content-transform-origin` | The transform origin of the content element. | | | `--bits-tooltip-content-available-width` | The available width of the content element. | | | `--bits-tooltip-content-available-height` | The available height of the content element. | | | `--bits-tooltip-anchor-width` | The width of the anchor element. | | | `--bits-tooltip-anchor-height` | The height of the anchor element. | | ### Tooltip.ContentStatic The contents of the tooltip which are displayed when the tooltip is open. (Static/No Floating UI) | Property | Type | Description | Details | | ------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `onInteractOutside` | `function` - (event: PointerEvent) => void | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default: —— undefined` | | | `onFocusOutside` | `function` - (event: FocusEvent) => void | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default: —— undefined` | | | `interactOutsideBehavior` | `enum` - 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: 'close'` | | | `onEscapeKeydown` | `function` - (event: KeyboardEvent) => void | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default: —— undefined` | | | `escapeKeydownBehavior` | `enum` - 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: 'close'` | | | `forceMount` | `boolean` | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false` | | | `dir` | `enum` - 'ltr' \| 'rtl' | The reading direction of the app.`Default: 'ltr'` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type ChildSnippetProps = { open: boolean; props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | ---------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `data-state` | `enum` - 'delayed-open' \| 'instant-open' \| 'closed' | Whether/how the tooltip is open or closed. When open, if there is a delay, the value will be 'delayed-open', otherwise it will be 'instant-open'. When closed, the value will be 'closed'. | | | `data-tooltip-content` | `''` | Present on the tooltip content element. | | ### Tooltip.Arrow An optional arrow element which points to the trigger when the tooltip is open. | Property | Type | Description | Details | | --------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `width` | `number` | The width of the arrow in pixels.`Default: 8` | | | `height` | `number` | The height of the arrow in pixels.`Default: 8` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | -------------------- | ----------------------------------------------- | --------------------------------------------- | ------- | | `data-arrow` | `''` | Present on the arrow element. | | | `data-tooltip-arrow` | `''` | Present on the arrow element. | | | `data-side` | `enum` - 'top' \| 'right' \| 'bottom' \| 'left' | The side of the tooltip that the arrow is on. | | ### Tooltip.Portal When used, will render the tooltip content into the body or custom `to` element when open | Property | Type | Description | Details | | ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------- | | `to` | `union` - Element \| string | Where to render the content when it is open. Defaults to the body.`Default: document.body` | | | `disabled` | `boolean` | Whether the portal is disabled or not. When disabled, the content will be rendered in its original DOM location.`Default: false` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | [Previous Toolbar](/docs/components/toolbar) [Next BitsConfig](/docs/utilities/bits-config)