# or
yarn add @zag-js/tooltip @zag-js/react
```

## Anatomy

To set up the tooltip correctly, you'll need to understand its anatomy and how
we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

First, import the tooltip package into your project

```jsx
import * as tooltip from "@zag-js/tooltip"
```

The tooltip package exports two key functions:

- `machine` â The state machine logic for the tooltip widget.
- `connect` â The function that translates the machine's state to JSX attributes
  and event handlers.

To get the tooltip working correct, you'll need to:

- Setup the tooltip portal, this is a shared container for all tooltips
- Add the `triggerProps`, and `tooltipProps` to the elements

> You'll also need to provide a unique `id` to the `useMachine` hook. This is
> used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the
tooltip machine in your project ð¥

```jsx
import * as tooltip from "@zag-js/tooltip"
import { useMachine, normalizeProps } from "@zag-js/react"

export function Tooltip() {
  const service = useMachine(tooltip.machine, { id: "1" })

  const api = tooltip.connect(service, normalizeProps)

  return (
    <>
      <button {...api.getTriggerProps()}>Hover me</button>
      {api.open && (
        <div {...api.getPositionerProps()}>
          <div {...api.getContentProps()}>Tooltip</div>
        </div>
      )}
    </>
  )
}
```

### Customizing the timings

By default, the tooltip is designed to open after `1000ms` and close after
`500ms`. You can customize this by passing the `openDelay` and `closeDelay`
context properties.

```jsx {2-3}
const service = useMachine(tooltip.machine, {
  openDelay: 500,
  closeDelay: 200,
})
```

### Changing the placement

The tooltip uses [floating-ui](https://floating-ui.com/) for dynamic
positioning. You can change the placement of the tooltip by passing the
`positioning.placement` context property to the machine.

```jsx {2-4}
const service = useMachine(tooltip.machine, {
  positioning: {
    placement: "bottom-start",
  },
})
```

You can configure other position-related properties in the `positioning` object.
Here's what the positioning API looks like:

```ts
export type PositioningOptions = {
  /**
   * The strategy to use for positioning
   */
  strategy?: "absolute" | "fixed"
  /**
   * The initial placement of the floating element
   */
  placement?: Placement
  /**
   * The offset of the floating element
   */
  offset?: { mainAxis?: number; crossAxis?: number }
  /**
   * The main axis offset or gap between the reference and floating elements
   */
  gutter?: number
  /**
   * Whether to flip the placement
   */
  flip?: boolean
  /**
   * Whether to make the floating element same width as the reference element
   */
  sameWidth?: boolean
  /**
   * The overflow boundary of the reference element
   */
  boundary?: Boundary
  /**
   * Options to activate auto-update listeners
   */
  listeners?: boolean | AutoUpdateOptions
}
```

### Adding an arrow

To render an arrow within the tooltip, use the `api.getArrowProps()` and
`api.getArrowTipProps()`.

```jsx {6-8}
//...
const api = popover.connect(service, normalizeProps)
//...
return (
  <div {...api.getPositionerProps()}>
    <div {...api.getArrowProps()}>
      <div {...api.getArrowTipProps()} />
    </div>
    <div {...api.getContentProps()}>{/* ... */}</div>
  </div>
)
//...
```

### Pointerdown behavior

By default, the tooltip will close when the pointer is down on its trigger. To
prevent this behavior, pass the `closeOnPointerDown` context property and set it
to `false`.

```jsx {2}
const service = useMachine(tooltip.machine, {
  closeOnPointerDown: false,
})
```

### Closing on Esc

The tooltip is designed to close when the escape key is pressed. To prevent
this, pass the `closeOnEscape` context property and set it to `false`.

```jsx {2}
const service = useMachine(tooltip.machine, {
  closeOnEsc: false,
})
```

### Making the tooltip interactive

Set the `interactive` context property to `true` to make them interactive.

When a tooltip is interactive, it'll remain open even the pointer leaves the
trigger and move into the tooltip's content.

```jsx {2}
const service = useMachine(tooltip.machine, {
  interactive: true,
})
```

### Listening for open state changes

When the tooltip is opened or closed, the `onOpenChange` callback is invoked.

```jsx {2-7}
const service = useMachine(tooltip.machine, {
  onOpenChange(details) {
    // details => { open: boolean }
    console.log(details.open)
  },
})
```

## Styling guide

Earlier, we mentioned that each tooltip part has a `data-part` attribute added
to them to select and style them in the DOM.

```css
[data-part="trigger"] {
  /* styles for the content */
}

[data-part="content"] {
  /* styles for the content */
}
```

### Open and close states

When the tooltip is open, the `data-state` attribute is added to the trigger

```css
[data-part="trigger"][data-state="open|closed"] {
  /* styles for the trigger's expanded state */
}

[data-part="content"][data-state="open|closed"] {
  /* styles for the trigger's expanded state */
}
```

### Styling the arrow

When using arrows within the menu, you can style it using css variables.

```css
[data-part="arrow"] {
  --arrow-size: 20px;
  --arrow-background: red;
}
```

## Methods and Properties

### Machine Context

The tooltip machine exposes the following context properties:

**`ids`**
Type: `Partial<{ trigger: string; content: string; arrow: string; positioner: string; }>`
Description: The ids of the elements in the tooltip. Useful for composition.

**`openDelay`**
Type: `number`
Description: The open delay of the tooltip.

**`closeDelay`**
Type: `number`
Description: The close delay of the tooltip.

**`closeOnPointerDown`**
Type: `boolean`
Description: Whether to close the tooltip on pointerdown.

**`closeOnEscape`**
Type: `boolean`
Description: Whether to close the tooltip when the Escape key is pressed.

**`closeOnScroll`**
Type: `boolean`
Description: Whether the tooltip should close on scroll

**`closeOnClick`**
Type: `boolean`
Description: Whether the tooltip should close on click

**`interactive`**
Type: `boolean`
Description: Whether the tooltip's content is interactive.
In this mode, the tooltip will remain open when user hovers over the content.

**`onOpenChange`**
Type: `(details: OpenChangeDetails) => void`
Description: Function called when the tooltip is opened.

**`aria-label`**
Type: `string`
Description: Custom label for the tooltip.

**`positioning`**
Type: `PositioningOptions`
Description: The user provided options used to position the popover content

**`disabled`**
Type: `boolean`
Description: Whether the tooltip is disabled

**`open`**
Type: `boolean`
Description: The controlled open state of the tooltip

**`defaultOpen`**
Type: `boolean`
Description: The initial open state of the tooltip when rendered.
Use when you don't need to control the open state of the tooltip.

**`dir`**
Type: `"ltr" | "rtl"`
Description: The document's text/writing direction.

**`id`**
Type: `string`
Description: The unique identifier of the machine.

**`getRootNode`**
Type: `() => ShadowRoot | Node | Document`
Description: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

### Machine API

The tooltip `api` exposes the following methods:

**`open`**
Type: `boolean`
Description: Whether the tooltip is open.

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open the tooltip.

**`reposition`**
Type: `(options?: Partial<PositioningOptions>) => void`
Description: Function to reposition the popover

### Data Attributes

**`Trigger`**

**`data-scope`**: tooltip
**`data-part`**: trigger
**`data-expanded`**: Present when expanded
**`data-state`**: "open" | "closed"

**`Content`**

**`data-scope`**: tooltip
**`data-part`**: content
**`data-state`**: "open" | "closed"
**`data-placement`**: The placement of the content

### CSS Variables

<CssVarTable name="tooltip" />

## Accessibility

### Keyboard Interactions

**`Tab`**
Description: Opens/closes the tooltip without delay.

**`Escape`**
Description: If open, closes the tooltip without delay.
A tour is an onboarding component used to guide users through a new product
feature or series of steps. It is often used to boost feature discoverability or
onboard new users by highlighting specific elements on the page.

## Resources


[Latest version: v1.33.1](https://www.npmjs.com/package/@zag-js/tour)
[Logic Visualizer](https://zag-visualizer.vercel.app/tour)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/tour)



**Features**

- Support for different step types such as "dialog", "floating", "tooltip" or
  "wait".
- Support for customizable content per step.
- Wait steps for waiting for a specific selector to appear on the page before
  showing the next step.
- Flexible positioning of the tour dialog per step.
- Progress tracking shows users their progress through the tour.

## Installation

To use the tooltip machine in your project, run the following command in your
command line:

```bash
npm install @zag-js/tour @zag-js/react