Provides additional information or context when users hover over or interact with an element.
Structure
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.
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.
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.
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.
You could then use the MyTooltip component in your application like so:
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.
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.
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.
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 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.
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.
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
openbindable prop
boolean
The open state of the tooltip component.
Default: false
onOpenChange
function
A callback that fires when the open state changes.
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
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
refbindable prop
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 delegation 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 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 completes, which is either a pointerup, mouseup, or touchend event, depending on the user's input device. You can call event.preventDefault() to prevent the default behavior of handling the outside interaction.
Default: ——undefined
onInteractOutsideStart
function
Callback fired when an outside interaction event starts, which is either a pointerdown, mousedown, or touchstart event, depending on the user's input device. You can call event.preventDefault() to prevent the continuation of the outside interaction.
Default: ——undefined
onFocusOutside
function
Callback fired when focus leaves the dismissable 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
refbindable prop
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 delegation 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 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
refbindable prop
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 delegation docs for more information.