Tooltip

Provides additional information or context when users hover over or interact with an element.

	<script lang="ts">
  import { Tooltip } from "bits-ui";
  import MagicWand from "phosphor-svelte/lib/MagicWand";
</script>
 
<Tooltip.Provider>
  <Tooltip.Root delayDuration={200}>
    <Tooltip.Trigger
      class="inline-flex size-10 items-center justify-center rounded-full
		border border-border-input bg-background-alt shadow-btn ring-dark ring-offset-background hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-dark focus-visible:ring-offset-2 focus-visible:ring-offset-background"
    >
      <MagicWand class="size-5" />
    </Tooltip.Trigger>
    <Tooltip.Content sideOffset={8}>
      <div
        class="z-0 flex items-center justify-center rounded-input border border-dark-10 bg-background p-3 text-sm font-medium shadow-popover outline-none"
      >
        Make some magic!
      </div>
    </Tooltip.Content>
  </Tooltip.Root>
</Tooltip.Provider>

Structure

	<script lang="ts">
	import { Tooltip } from "bits-ui";
</script>
 
<Tooltip.Provider>
	<Tooltip.Root>
		<Tooltip.Trigger />
		<Tooltip.Portal>
			<Tooltip.Content>
				<Tooltip.Arrow />
			</Tooltip.Content>
		</Tooltip.Portal>
	</Tooltip.Root>
</Tooltip.Provider>

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.

	<script lang="ts">
	import { Tooltip } from "bits-ui";
</script>
 
<Tooltip.Provider delayDuration={0} disableHoverableContent={true}>
	<!-- Will have a delayDuration of 0 and disableHoverableContent of true -->
	<Tooltip.Root>
		<Tooltip.Trigger />
		<Tooltip.Portal>
			<Tooltip.Content>
				<Tooltip.Arrow />
			</Tooltip.Content>
		</Tooltip.Portal>
	</Tooltip.Root>
	<!-- Will have a delayDuration of 0 and disableHoverableContent of true -->
	<Tooltip.Root>
		<Tooltip.Trigger />
		<Tooltip.Portal>
			<Tooltip.Content>
				<Tooltip.Arrow />
			</Tooltip.Content>
		</Tooltip.Portal>
	</Tooltip.Root>
</Tooltip.Provider>

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
	<script lang="ts">
	import { Tooltip } from "bits-ui";
	let { children } = $props();
</script>
 
<Tooltip.Provider>
	{@render children()}
</Tooltip.Provider>

Managing Open State

Bits UI offers several approaches to manage and synchronize the Tooltip's open state, catering to different levels of control and integration needs.

1. Two-Way Binding

For seamless state synchronization, use Svelte's bind:open directive. This method automatically keeps your local state in sync with the component's internal state.

	<script lang="ts">
	import { Tooltip } from "bits-ui";
	let isOpen = $state(false);
</script>
 
<button onclick={() => (isOpen = true)}>Open Tooltip</button>
 
<Tooltip.Root bind:open={isOpen}>
	<!-- ... -->
</Tooltip.Root>

Key Benefits

  • Simplifies state management
  • Automatically updates isOpen when the tooltip closes (e.g., via escape key)
  • Allows external control (e.g., opening via a separate button)

2. Change Handler

For more granular control or to perform additional logic on state changes, use the onOpenChange prop. This approach is useful when you need to execute custom logic alongside state updates.

	<script lang="ts">
	import { Tooltip } from "bits-ui";
	let isOpen = $state(false);
</script>
 
<Tooltip.Root
	open={isOpen}
	onOpenChange={(o) => {
		isOpen = o;
		// additional logic here.
	}}
>
	<!-- ... -->
</Tooltip.Root>

Use Cases

  • Implementing custom behaviors on open/close
  • Integrating with external state management solutions
  • Triggering side effects (e.g., logging, data fetching)

3. Fully Controlled

For complete control over the dialog's open state, use the controlledOpen prop. This approach requires you to manually manage the open state, giving you full control over when and how the tooltip responds to open/close events.

To implement controlled state:

  1. Set the controlledOpen prop to true on the Tooltip.Root component.
  2. Provide an open prop to Tooltip.Root, which should be a variable holding the current state.
  3. Implement an onOpenChange handler to update the state when the internal state changes.
	<script lang="ts">
	import { Tooltip } from "bits-ui";
 
	let myOpen = $state(false);
</script>
 
<Tooltip.Root controlledOpen open={myOpen} onOpenChange={(o) => (myOpen = o)}>
	<!-- ... -->
</Tooltip.Root>

When to Use

  • Implementing complex open/close logic
  • Coordinating multiple UI elements
  • Debugging state-related issues

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


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

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
	<script lang="ts">
	import { Tooltip } from "bits-ui";
	import { type Snippet } from "svelte";
 
	type Props = Tooltip.RootProps & {
		trigger: Snippet;
		triggerProps?: Tooltip.TriggerProps;
	};
 
	let {
		open = $bindable(false),
		children,
		buttonText,
		triggerProps = {},
		...restProps
	}: Tooltip.RootProps = $props();
</script>
 
<!--
 Ensure you have a `Tooltip.Provider` component wrapping
 your root layout content
-->
<Tooltip.Root bind:open {onOpenChange}>
	<Tooltip.Trigger {...triggerProps}>
		{@render trigger()}
	</Tooltip.Trigger>
	<Tooltip.Portal>
		<Tooltip.Content>
			<Tooltip.Arrow />
			{@render children?.()}
		</Tooltip.Content>
	</Tooltip.Portal>
</Tooltip.Root>

You could then use the MyTooltip component in your application like so:

+page.svelte
	<script lang="ts">
	import MyTooltip from "$lib/components/MyTooltip.svelte";
	import BoldIcon from "..some-icon-library"; // not real
</script>
 
<MyTooltip triggerProps={{ onclick: () => alert("changed to bold!") }}>
	{#snippet trigger()}
		<BoldIcon />
	{/snippet}
	Change font to bold
</MyTooltip>

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.

	<Tooltip.Root delayDuration={200}>
	<!-- .... -->
</Tooltip.Root>

delayDuration=200
delayDuration=1000
delayDuration=2500

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.

	<Tooltip.Root disableCloseOnTriggerClick>
	<!-- .... -->
</Tooltip.Root>

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.

	<Tooltip.Root disableHoverableContent>
	<!-- .... -->
</Tooltip.Root>

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.

	<Tooltip.Root ignoreNonKeyboardFocus>
	<!-- .... -->
</Tooltip.Root>

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.

	<script lang="ts">
	import { Tooltip } from "bits-ui";
	import { fly, fade } from "svelte/transition";
</script>
 
<Tooltip.Root>
	<!-- ... other tooltip components -->
	<Tooltip.Content forceMount>
		{#snippet child({ wrapperProps, props, open })}
			{#if open}
				<div {...wrapperProps}>
					<div {...props} transition:fly>
						<!-- ... -->
					</div>
				</div>
			{/if}
		{/snippet}
	</Tooltip.Content>
</Dialog.Root>

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 documentation.

	<script lang="ts">
  import { Tooltip } from "bits-ui";
  import MagicWand from "phosphor-svelte/lib/MagicWand";
  import { fly } from "svelte/transition";
</script>
 
<Tooltip.Provider>
  <Tooltip.Root delayDuration={200}>
    <Tooltip.Trigger
      class="inline-flex size-10 items-center justify-center rounded-full
		border border-border-input bg-background-alt shadow-btn ring-dark ring-offset-background hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-dark focus-visible:ring-offset-2 focus-visible:ring-offset-background"
    >
      <MagicWand class="size-5" />
    </Tooltip.Trigger>
    <Tooltip.Content sideOffset={8} forceMount>
      {#snippet child({ wrapperProps, props, open })}
        {#if open}
          <div {...wrapperProps}>
            <div {...props} transition:fly={{ duration: 300 }}>
              <div
                class="z-0 flex items-center justify-center rounded-input border border-dark-10 bg-background p-3 text-sm font-medium shadow-popover outline-none"
              >
                Make some magic!
              </div>
            </div>
          </div>
        {/if}
      {/snippet}
    </Tooltip.Content>
  </Tooltip.Root>
</Tooltip.Provider>

Opt-out of Floating UI

When you use the Tooltip.Content component, Bits UI uses Floating UI 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.

	<Tooltip.Root>
	<Tooltip.Trigger>Hello</Tooltip.Trigger>
	<Tooltip.ContentStatic>
		<!-- ... -->
	</Tooltip.ContentStatic>
</Tooltip.Root>

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.

	<script lang="ts">
	import { Tooltip } from "bits-ui";
	let customAnchor = $state<HTMLElement>(null!);
</script>
 
<div bind:this={customAnchor}></div>
 
<Tooltip.Root>
	<Tooltip.Trigger />
	<Tooltip.Content {customAnchor}>
		<!-- ... -->
	</Tooltip.Content>
</Tooltip.Root>

API Reference

Tooltip.Provider

A provider component which contains shared state and logic for the tooltips within its subtree.

Property Type Description
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.

Property Type Description
open $bindable
boolean

The open state of the tooltip component.

Default: false
onOpenChange
function

A callback that fires when the open state changes.

Default: undefined
controlledOpen
boolean

Whether or not the open state is controlled or not. If true, the component will not update the open state internally, instead it will call onOpenChange when it would have otherwise, and it is up to you to update the open prop that is passed to the component.

Default: false
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
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
disabled
boolean

Whether or not the tooltip trigger is disabled.

Default: false
ref $bindable
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

Whether the tooltip is open or 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
side
enum

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

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

A boundary element or array of elements to check for collisions against.

Default: undefined
collisionPadding
union

The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.

Default: 0
sticky
enum

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

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

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

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

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

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

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

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

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

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: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

Whether the tooltip is open or closed.

data-tooltip-content
''

Present on the tooltip content element.

Tooltip.ContentStatic

The contents of the tooltip which are displayed when the tooltip is open. (Static/No Floating UI)

Property Type Description
onInteractOutside
function

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

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

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

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

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

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: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

Whether the tooltip is open or 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
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: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-arrow
''

Present on the arrow element.

data-tooltip-arrow
''

Present on the arrow element.