> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Tour

Feedback`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Guided steps with target positioning, spotlight masks, custom actions and keyboard navigation.

Each example can be copied and run independently. Use the device control on framed previews to switch between desktop and phone widths.

Masked centered steps and steps with `disabledInteraction` contain keyboard focus. Steps that allow target interaction are nonmodal and keep the target focusable. Closing restores focus to the launch control.

## Examples


### Guide users between targets
Targets are read from refs when the tour opens. Next moves to the following target.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function BasicTour() {
  const [open, setOpen] = useState(false);
  const upload = useRef<HTMLButtonElement>(null);
  const save = useRef<HTMLButtonElement>(null);
  return (
    <div style={{ padding: 24, minHeight: 300 }}>
      <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
        <Button ref={upload}>Upload</Button>
        <Button ref={save}>Save</Button>
        <Button onClick={() => setOpen(true)}>Start tour</Button>
      </div>
      <Tour
        open={open}
        onClose={() => setOpen(false)}
        steps={[
          {
            title: 'Upload a file',
            description: 'Choose a document to begin.',
            target: () => upload.current!,
          },
          {
            title: 'Save changes',
            description: 'Review your work, then save.',
            target: () => save.current!,
          },
        ]}
      />
    </div>
  );
}
```

### Controlled current step
Keep current and open in state. Reset the step before starting the tour again.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function ControlledTour() {
  const [open, setOpen] = useState(false);
  const [current, setCurrent] = useState(0);
  const upload = useRef<HTMLButtonElement>(null);
  const save = useRef<HTMLButtonElement>(null);
  return (
    <div style={{ padding: 24, minHeight: 300 }}>
      <div style={{ display: 'flex', gap: 8 }}>
        <Button ref={upload}>Upload</Button>
        <Button ref={save}>Save</Button>
        <Button
          onClick={() => {
            setCurrent(0);
            setOpen(true);
          }}
        >
          Start again
        </Button>
      </div>
      <p>Current step: {current + 1}</p>
      <Tour
        open={open}
        current={current}
        onChange={setCurrent}
        onClose={() => setOpen(false)}
        steps={[
          {
            title: 'Upload a file',
            description: 'Choose a document to begin.',
            target: () => upload.current!,
          },
          {
            title: 'Save changes',
            description: 'Review your work, then save.',
            target: () => save.current!,
          },
        ]}
      />
    </div>
  );
}
```

### A centered introduction
Omit target for an introduction centered in the viewport.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function CenteredTour() {
  const [open, setOpen] = useState(false);
  return (
    <div style={{ padding: 24, minHeight: 300 }}>
      <Button onClick={() => setOpen(true)}>Welcome tour</Button>
      <Tour
        open={open}
        onClose={() => setOpen(false)}
        steps={[
          {
            title: 'Welcome to your workspace',
            description:
              'Organize documents, review changes and share results from one place.',
          },
          {
            title: 'Ready to begin',
            description: 'Choose Done to close this introduction.',
          },
        ]}
      />
    </div>
  );
}
```

### Primary emphasis and a cover
type="primary" changes the panel emphasis. A step can include a cover image or other React content.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
const photo = (color: string) =>
  `data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" width="600" height="400"><rect width="600" height="400" fill="${color}"/><circle cx="420" cy="110" r="46" fill="#fff5"/><path d="M0 400L220 120L420 400Z" fill="#fff8"/><path d="M200 400L430 200L600 400Z" fill="#fff4"/></svg>`)}`;
export default function PrimaryTour() {
  const [open, setOpen] = useState(false);
  return (
    <div style={{ padding: 24, minHeight: 300 }}>
      <Button onClick={() => setOpen(true)}>Discover the workspace</Button>
      <Tour
        open={open}
        type="primary"
        onClose={() => setOpen(false)}
        steps={[
          {
            title: 'A clear place to start',
            description: 'Create your first project when you are ready.',
            cover: <img src={photo('#496f5d')} alt="Mountain illustration" />,
          },
        ]}
      />
    </div>
  );
}
```

### Mask, gap and interaction
gap controls the highlighted rectangle. disabledInteraction prevents clicks on the highlighted target.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function SpotlightTour() {
  const [open, setOpen] = useState(false);
  const upload = useRef<HTMLButtonElement>(null);
  const save = useRef<HTMLButtonElement>(null);
  return (
    <div style={{ padding: 24, minHeight: 300 }}>
      <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
        <Button ref={upload}>Upload</Button>
        <Button ref={save}>Save</Button>
        <Button onClick={() => setOpen(true)}>Start tour</Button>
      </div>
      <Tour
        open={open}
        onClose={() => setOpen(false)}
        gap={{ offset: 10, radius: 10 }}
        mask={{ color: 'rgba(25,34,46,.65)' }}
        disabledInteraction
        steps={[
          {
            title: 'Upload a file',
            description: 'Choose a document to begin.',
            target: () => upload.current!,
          },
          {
            title: 'Save changes',
            description: 'Review your work, then save.',
            target: () => save.current!,
          },
        ]}
      />
    </div>
  );
}
```

### Custom indicators and actions
Keep the default actions and add a Skip action. Per-step button props customize labels and handlers.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function CustomTourActions() {
  const [open, setOpen] = useState(false);
  const upload = useRef<HTMLButtonElement>(null);
  const save = useRef<HTMLButtonElement>(null);
  return (
    <div style={{ padding: 24, minHeight: 300 }}>
      <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
        <Button ref={upload}>Upload</Button>
        <Button ref={save}>Save</Button>
        <Button onClick={() => setOpen(true)}>Start tour</Button>
      </div>
      <Tour
        open={open}
        onClose={() => setOpen(false)}
        indicatorsRender={(current, total) => (
          <span>
            {current + 1} / {total}
          </span>
        )}
        actionsRender={(actions) => (
          <>
            <Button size="small" variant="ghost" onClick={() => setOpen(false)}>
              Skip
            </Button>
            {actions}
          </>
        )}
        steps={[
          {
            title: 'Upload a file',
            target: () => upload.current!,
            nextButtonProps: { children: 'Continue' },
          },
          {
            title: 'Save changes',
            target: () => save.current!,
            nextButtonProps: { children: 'Got it' },
          },
        ]}
      />
    </div>
  );
}
```

### Non-modal guidance
mask:false leaves the page unobscured. keyboard:false disables step navigation and Escape handling; Done still closes this example.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function NonModalTour() {
  const [open, setOpen] = useState(false);
  const target = useRef<HTMLButtonElement>(null);
  return (
    <div style={{ padding: 24, minHeight: 300 }}>
      <Button ref={target} onClick={() => setOpen(true)}>
        Show a hint
      </Button>
      <Tour
        open={open}
        onClose={() => setOpen(false)}
        mask={false}
        keyboard={false}
        closable={false}
        steps={[
          {
            title: 'Save your work',
            description: 'You can continue interacting with the page.',
            target: () => target.current!,
          },
        ]}
      />
    </div>
  );
}
```

### Guide a narrow layout
The panel flips and shifts around its target to stay inside the phone viewport.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function MobileTour() {
  const [open, setOpen] = useState(false);
  const upload = useRef<HTMLButtonElement>(null);
  const save = useRef<HTMLButtonElement>(null);
  return (
    <div style={{ padding: 16, minHeight: 360 }}>
      <h3>Start your project</h3>
      <p>Follow two steps to upload and save.</p>
      <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
        <Button ref={upload}>Upload</Button>
        <Button ref={save}>Save</Button>
        <Button onClick={() => setOpen(true)}>Start tour</Button>
      </div>
      <Tour
        open={open}
        onClose={() => setOpen(false)}
        steps={[
          {
            title: 'Upload a file',
            description: 'Choose a document to begin.',
            target: () => upload.current!,
          },
          {
            title: 'Save changes',
            description: 'Review your work, then save.',
            target: () => save.current!,
          },
        ]}
      />
    </div>
  );
}
```

## API


### [#](#tour)Tour



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |

