Tooltip

Components/Overlays/Tooltip

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/tooltip

Overview

Copy

Tooltips provide additional explanation on how a specific element functions. A user can trigger a tooltip by mouse hover, keyboard focus or touch.

Do

  • Give additional information about interactive controls.
  • Describe or label non-interactive elements, such as icons or images.
  • Provide labels to <IconButton/>.
  • Use 'aria-describedby' prop to connect the tooltip's content to its trigger element for assistive technologies.

Don't

  • Don't use it to explain disabled components, since keyboard and screen reader users can't access it. Instead, use <Text/> or <InfoIcon/>.
  • Don't use it to provide critical information. Instead, use <SectionHelper/> or <FloatingNotification/>.
  • Don't use it to provide lengthy information. Instead, use <Text/> in the main layout.
  • Don't include interactive elements, such as <TextButton/>, in the tooltip's content, since keyboard and screen reader users can't access them.

Feature examples

Structure

To display a tooltip, two parts need to be defined:

  • A trigger element that calls a tooltip when hover or focus occurs (e.g., an <IconButton/>). The trigger element goes inside the <Tooltip/> wrapper as its child item.
  • The content, which is the text displayed inside of a tooltip.
Copy

Size

Control tooltip dimensions with the size prop:

  • For dense layouts (e.g., in a composer), use small.
  • The default size used in any other case is medium.
Copy

Max width

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.

Copy

Placement

Use the placement prop to select the position of a tooltip in relation to its trigger element:

  • top (default)
  • right
  • bottom
  • left

In each of these standard positions, the tooltip aligns itself to the center of the corresponding axis and appears outside the trigger element.

Copy

Text alignment

The textAlign prop controls how tooltip content is aligned:

  • start (default)
  • center
Copy

Delay

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

Copy

Interactive

Decide whether tooltip can be hovered on not by using interactive prop.

Copy

On disabled trigger elements

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.

Copy

Common use case examples

To label icon buttons

Show a text label or other brief helpful information for an <IconButton/> in a tooltip.

Copy

Code

Copy

Props

NameTypeDefaultDescription
appendTonull | 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-describedbystring—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-labelledbystring—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.
contentReactNode—Defines the content to be shown inside a tooltip.
dataHookstring—Applies a data-hook HTML attribute to be used in the tests.
disabledboolean—Allows showing a tooltip when hovering on a disabled trigger element with mouse.
enterDelaynumber200Sets time to wait before showing the tooltip (in milliseconds)
exitDelaynumber100Sets time to wait before hiding the tooltip (in milliseconds)
fixedboolean—Enables keeping a tooltip at its original placement even when it is being positioned outside the boundary.
flipbooleantrueFlips a tooltip's placement when it starts to overlap its trigger element.
fluidboolean—Stretches the root element to the width of its container.
inlineboolean—Enables inline-block behaviour for the tooltip trigger element. Use this when working with inline based elements i.e. Text, TextButton, Button etc.
interactivebooleantrueEnables hovering the tooltip itself.
maxWidthstring | number | string & {}—Defines max width of a tooltip in px. If content is wider than maxWidth allows, it wraps into multiple lines.
moveArrowTonumber—Moves a tooltip's arrow by a defined amount.
moveByPartial<{ 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.
refnull | 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.
zIndexstring & {} | "-moz-initial" | "inherit" | "initial" | "revert" | "revert-layer" | "unset" | "auto" | number & {}—Controls the tooltip's z-index.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
clickClicks on the target element
tooltipExistsreturns true if tooltip element exists on the DOM
mouseEntermouse over the target element
mouseLeavemouse leaves the target element
clickOutsideclicks outside the tooltip target
getTooltipTextreturns tooltips content value in string
hasSizeChecks whether tooltip has a given size
existsChecks whether the component found with the given data hook.
elementGets the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.337.0 (2026-10-14) — maintenance release, no component-specific changes
  • 1.336.0 (2026-10-13) — maintenance release, no component-specific changes
  • 1.332.0 (2026-10-05) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — feat: the default 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)
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.324.0 (2026-09-14) — fix: opens on tap, making it usable on touch devices. Tapping toggles the tooltip on any trigger; interactive triggers (buttons, links, inputs) also run their own action on the same tap. Tapping the tooltip bubble or anywhere else dismisses it. Mouse behavior for interactive triggers is unchanged; on desktop, clicking a non-interactive trigger now closes an open tooltip. (#16786)
  • 1.318.0 (2026-08-28) — fix: opens and closes with the Harmony (odeditor) motion — the bubble grows out of the trigger edge while its text fades in, and shrinks back on close. Other themes are unchanged, and the motion is disabled when the user prefers reduced motion. (#16904)
  • 1.317.0 (2026-08-26) — feat: styles migrated from Stylable to semantic classnames. Rendering is unchanged, but the Stylable-generated classnames on the tooltip are replaced by 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)
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.294.0 (2026-07-02) — feat: odeditor-dark border + raw-black background tokens (#16460)
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.278.0 (2026-05-08) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.261.0 (2026-03-24) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.246.0 (2026-01-09) — fix: reverted back to popover (#15764)
  • 1.245.1 (2026-01-06) — maintenance release, no component-specific changes
  • 1.243.0 (2025-12-23) — fix: height issues (#15723)
  • 1.243.0 (2025-12-23) — fix: fixed tooltip alignment (#15720)
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.236.0 (2025-12-04) — fix: fixed onEscPress handler (#15614)
  • 1.220.0 (2025-09-29) — maintenance release, no component-specific changes
  • 1.213.0 (2025-08-19) — maintenance release, no component-specific changes
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.211.0 (2025-08-07) — feat: tokenization (#15155)
  • 1.206.0 (2025-07-16) — fix: shadow token applied (#14848)
  • 1.188.0 (2025-05-12) — maintenance release, no component-specific changes
  • 1.179.0 (2025-04-09) — feat: border-radius token (#14730)
  • 1.165.0 (2025-02-27) — breaking: tooltip color change in studio theme (#14536)
  • 1.144.0 (2024-12-03) — maintenance release, no component-specific changes
  • 1.143.0 (2024-11-25) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — fix: set inline container max-width so the ellipsis inside would work (#14250)
  • 1.137.0 (2024-10-25) — maintenance release, no component-specific changes
  • 1.123.1 (2024-09-05) — breaking: tokenize (#14082)
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.114.0 (2024-07-11) — feat: extend zIndex prop type to accept strings (#13920)
  • 1.104.1 (2024-05-14) — maintenance release, no component-specific changes
  • 1.100.0 (2024-04-04) — maintenance release, no component-specific changes
  • 1.93.0 (2024-02-08) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?