> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Tooltip Component

## Article: Tooltip Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/overlays/tooltip-component.md

## Article Content:

# Tooltip

_Components/Overlays/Tooltip_

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

## Overview

```jsx
<StorybookComponents.Stack flexDirection="column" alignItems="center">
  <Tooltip appendTo="window" content="This is a tooltip.">
    <TextButton>To view tooltip, hover or focus here. </TextButton>
  </Tooltip>
</StorybookComponents.Stack>;
```

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.

```jsx
<Tooltip inline content="Tooltip content goes here.">
  <TextButton>Hover or focus to see tooltip</TextButton>
</Tooltip>;
```

#### 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`.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Tooltip inline content="This is a small tooltip." size="small">
    <TextButton>Small tooltip</TextButton>
  </Tooltip>
  <Tooltip inline content="This is a medium (default) tooltip.">
    <TextButton>Medium tooltip</TextButton>
  </Tooltip>
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Tooltip
    inline
    content="This is a tooltip with content wrapped using the default max width."
  >
    <TextButton>Default max width</TextButton>
  </Tooltip>
  <Tooltip
    inline
    content="This is a tooltip with content wrapped using 360px max width."
    maxWidth={360}
  >
    <TextButton>Max width = 360 px</TextButton>
  </Tooltip>
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column" alignItems="center">
  <Tooltip inline content="Top (default)">
    <TextButton>Top (default)</TextButton>
  </Tooltip>
  <Box gap="24">
    <Tooltip inline content="Left" placement="left">
      <TextButton>Left</TextButton>
    </Tooltip>
    <Tooltip inline content="Right" placement="right">
      <TextButton>Right</TextButton>
    </Tooltip>
  </Box>
  <Tooltip inline content="Bottom" placement="bottom">
    <TextButton>Bottom</TextButton>
  </Tooltip>
</StorybookComponents.Stack>;
```

#### Text alignment

The `textAlign` prop controls how tooltip content is aligned:

- `start` (default)
- `center`

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Tooltip inline content="Content is aligned to the left (default).">
    <TextButton>Start (default)</TextButton>
  </Tooltip>
  <Tooltip
    inline
    content="Content is aligned to the center."
    textAlign="center"
  >
    <TextButton>Center</TextButton>
  </Tooltip>
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Tooltip inline content="Tooltip was shown after 450 ms." enterDelay={450}>
    <TextButton>Enter delay</TextButton>
  </Tooltip>
  <Tooltip inline content="Tooltip will fade after 450 ms." exitDelay={450}>
    <TextButton>Exit delay</TextButton>
  </Tooltip>
</StorybookComponents.Stack>;
```

#### Interactive

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Tooltip
    inline
    content={
      <Box direction="vertical">
        <Text size="small" light>
          This is an interactive tooltip.
        </Text>
      </Box>
    }
  >
    <TextButton>Interactive</TextButton>
  </Tooltip>
  <Tooltip
    inline
    interactive={false}
    content="This is a non-interactive tooltip."
  >
    <TextButton>Non-Interactive</TextButton>
  </Tooltip>
</StorybookComponents.Stack>;
```

#### 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/>`](https://wix-pages.com/design-system-documentation/#/component/infoicon), [`<Text/>`](https://wix-pages.com/design-system-documentation/#/component/text) or other components near the disabled component.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Tooltip inline content="Tooltip content will not be shown">
    <TextButton disabled>No tooltip (default)</TextButton>
  </Tooltip>
  <Tooltip
    inline
    content="Tooltip content is shown on mouse hover"
    disabled={false}
  >
    <TextButton disabled>Tooltip on mouse hover</TextButton>
  </Tooltip>
</StorybookComponents.Stack>;
```

### Common use case examples

#### To label icon buttons

Show a text label or other brief helpful information for an [`<IconButton/>`](https://wix-pages.com/design-system-documentation/#/component/iconbutton) in a tooltip.

```jsx
<Card>
  <Box direction="horizontal">
    <Image
      height="120px"
      width="180px"
      borderRadius="8px 0px 0px 8px"
      src="running_man.png"
    />
    <Box
      direction="vertical"
      borderRadius="0px 8px 8px 0px"
      verticalAlign="space-between"
      padding="18px 24px"
      backgroundColor="D80"
      flexGrow={1}
    >
      <Box verticalAlign="space-between" flexGrow={1}>
        <Box direction="vertical" gap="3px">
          <Heading size="small">Running for beginners program</Heading>
          <Text size="small" secondary>
            Scheduled | 57 days
          </Text>
        </Box>
        <Tooltip content="Edit program">
          <IconButton priority="secondary" size="small">
            <Icons.Edit />
          </IconButton>
        </Tooltip>
      </Box>
      <Box marginRight={3}>
        <Text size="small" secondary>
          Created on September 26, 2022
        </Text>
      </Box>
    </Box>
  </Box>
</Card>;
```

## Code

```jsx
import { Tooltip } from '@wix/design-system';
```

### Props

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

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { TooltipUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { TooltipTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { TooltipTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { TooltipTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

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

## 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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **1.245.1** (2026-01-06) — maintenance release, no component-specific changes
- **1.243.0** (2025-12-23) — fix: height issues ([#15723](invalid-url))
- **1.243.0** (2025-12-23) — fix: fixed tooltip alignment ([#15720](invalid-url))
- **1.242.0** (2025-12-19) — maintenance release, no component-specific changes
- **1.236.0** (2025-12-04) — fix: fixed onEscPress handler ([#15614](invalid-url))
- **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](invalid-url))
- **1.206.0** (2025-07-16) — fix: shadow token applied ([#14848](invalid-url))
- **1.188.0** (2025-05-12) — maintenance release, no component-specific changes
- **1.179.0** (2025-04-09) — feat: border-radius token ([#14730](invalid-url))
- **1.165.0** (2025-02-27) — breaking: tooltip color change in studio theme ([#14536](invalid-url))
- **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](invalid-url))
- **1.137.0** (2024-10-25) — maintenance release, no component-specific changes
- **1.123.1** (2024-09-05) — breaking: tokenize ([#14082](invalid-url))
- **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](invalid-url))
- **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