Components/Overlays/Tooltip
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/tooltip
Tooltips provide additional explanation on how a specific element functions. A user can trigger a tooltip by mouse hover, keyboard focus or touch.
<IconButton/>.<Text/> or <InfoIcon/>.<SectionHelper/> or <FloatingNotification/>.<Text/> in the main layout.<TextButton/>, in the tooltip's content, since keyboard and screen reader users can't access them.To display a tooltip, two parts need to be defined:
<IconButton/>). The trigger element goes inside the <Tooltip/> wrapper as its child item.content, which is the text displayed inside of a tooltip.Control tooltip dimensions with the size prop:
small.medium.Control tooltip width with maxWidth. When the maximum width is reached, text inside the tooltip will wrap onto multiple lines.
Default maxWidth is 204 px.
Use the placement prop to select the position of a tooltip in relation to its trigger element:
top (default)rightbottomleftIn each of these standard positions, the tooltip aligns itself to the center of the corresponding axis and appears outside the trigger element.
The textAlign prop controls how tooltip content is aligned:
start (default)centerDelay the showing or hiding of a tooltip, for a specific amount of time, by using enterDelay and exitDelay.
Delay times are counted by milliseconds and both are 0 by default.
Decide whether tooltip can be hovered on not by using interactive prop.
By default, disabled trigger elements (e.g., <Button disabled/>) do not show tooltips on mouse hover or keyboard focus.
To show a tooltip on mouse hover, set the disabled prop to false.
Note: such tooltip content will not be accessible to keyboard focus, so it's best not to use tooltip to give additional information on a disabled component. Instead, use <InfoIcon/>, <Text/> or other components near the disabled component.
Show a text label or other brief helpful information for an <IconButton/> in a tooltip.
| Name | Type | Default | Description |
|---|---|---|---|
appendTo | null | Element | "window" | "scrollParent" | "viewport" | "parent" | Predicate | — | Calculates tooltip's position in relation to a DOM element. Can be either: 'window', 'scrollParent', 'viewport', 'parent', element or function based predicate. I.e., (elm) => elm.getAttribute('data-hook') === 'value. |
aria-describedby | string | — | Connects tooltip's trigger element to tooltip's descriptive content for assistive technologies. Use this when you want to provide information in addition to actions visual information, i.e. TextButton. Currently only one, either aria-labelledby or aria-describedby is supported. If both are provided aria-labelledby takes priority. |
aria-labelledby | string | — | Connects tooltip's trigger element to tooltip's label content for assistive technologies. Use this when the action doesn't have any visual text content, i.e. Icon Button. Currently only one, either aria-labelledby or aria-describedby is supported. If both are provided aria-labelledby takes priority. |
children (required) | ReactNode | FC<TooltipChildrenProps> | — | Defines tooltip's trigger element. |
content | ReactNode | — | Defines the content to be shown inside a tooltip. |
dataHook | string | — | Applies a data-hook HTML attribute to be used in the tests. |
disabled | boolean | — | Allows showing a tooltip when hovering on a disabled trigger element with mouse. |
enterDelay | number | 200 | Sets time to wait before showing the tooltip (in milliseconds) |
exitDelay | number | 100 | Sets time to wait before hiding the tooltip (in milliseconds) |
fixed | boolean | — | Enables keeping a tooltip at its original placement even when it is being positioned outside the boundary. |
flip | boolean | true | Flips a tooltip's placement when it starts to overlap its trigger element. |
fluid | boolean | — | Stretches the root element to the width of its container. |
inline | boolean | — | Enables inline-block behaviour for the tooltip trigger element. Use this when working with inline based elements i.e. Text, TextButton, Button etc. |
interactive | boolean | true | Enables hovering the tooltip itself. |
maxWidth | string | number | string & {} | — | Defines max width of a tooltip in px. If content is wider than maxWidth allows, it wraps into multiple lines. |
moveArrowTo | number | — | Moves a tooltip's arrow by a defined amount. |
moveBy | Partial<{ x: number; y: number; }> | — | Moves a tooltip in relation to its trigger element on x or y axis. |
onHide | () => void | — | Defines a callback function on tooltip's hide event. |
onShow | () => void | — | Defines a callback function on tooltip's show event. |
placement | "right" | "left" | "top" | "bottom" | "auto" | "auto-start" | "auto-end" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-end" | "bottom-start" | "left-end" | "left-start" | — | Sets tooltip's placement in relation to its trigger element. |
ref | null | string | (instance: TooltipActions | null) => void | RefObject<TooltipActions> | — | Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). |
size | "small" | "medium" | — | Controls the size of a tooltip. |
textAlign | "center" | "start" | — | Controls the alignment of tooltip's content. |
zIndex | string & {} | "-moz-initial" | "inherit" | "initial" | "revert" | "revert-layer" | "unset" | "auto" | number & {} | — | Controls the tooltip's z-index. |
Import the driver matching your test environment:
| Method | Description |
|---|---|
click | Clicks on the target element |
tooltipExists | returns true if tooltip element exists on the DOM |
mouseEnter | mouse over the target element |
mouseLeave | mouse leaves the target element |
clickOutside | clicks outside the tooltip target |
getTooltipText | returns tooltips content value in string |
hasSize | Checks whether tooltip has a given size |
exists | Checks whether the component found with the given data hook. |
element | Gets the component root element. |
base | Returns UniDriver for the base element. |
enterDelay (200ms) and exitDelay (100ms) introduced in 1.325.0 now fall back to 0 when NODE_ENV is test, so unit tests that hover and assert on a tooltip in the same tick pass again without changes. Explicit enterDelay/exitDelay props are untouched. Tooltip is now supported by WixDesignSystemDefaultPropsProvider, and the truncation tooltips of Text, Heading and Caption follow that provider default instead of hardcoding their own. The test-environment fallback is scheduled for removal in the next major release. (#17154)wds-tooltip* ones, and Tooltip.st.css no longer exists — Stylable files that @st-import it or use -st-extends: Tooltip (with ::content, ::arrow, ::element or ::text overrides) will fail to build. Drop the import and target :global(.wds-popover-content__content), :global(.wds-popover-content__arrow), :global(.wds-popover__element) and :global(.wds-tooltip__text) instead. (#16900)Last updated: 30 October 2026