# React Native Product Tour and Coachmarks (Pro)

> A React Native product tour for iOS, Android and the web: a spotlight that glides between the parts of a screen, a card with the step count, progress dots and Back, Next, Skip and Done, targets scrolled into view, cards that flip to the side with room, arrow keys on the web, a seen flag you store anywhere, and pulsing hotspots for single new features. No native modules. Part of Patine Pro.

# Product tour Pro

`TourProvider` walks people through a screen the way Intercom, Linear and Notion do the first time you open them: the screen dims, a spotlight glides from one `TourStep` to the next, and a card beside each says what it does. The card shows the step count and progress dots, and has **Back**, **Next**, **Skip** and **Done**. Targets out of view are scrolled to first, the card flips to whichever side has room, and on the web the arrow keys step through and Escape skips.

Use it for a first run, a redesigned screen or a feature launch. For one new thing people can find on their own, use a [hotspot](#hotspots) instead; for a list of setup tasks, the [onboarding checklist](./onboarding-checklist).

```tsx
import { TourProvider, TourStep, TourHotspot, useTour } from '@patine-ui/pro';
```

```tsx live
import { View } from 'react-native';
import { Button, Text } from 'patine-ui';
import { Icon, TourProvider, TourStep, useTour } from '@patine-ui/pro';

const StartButton = () => {
  const tour = useTour();
  return <Button onPress={() => tour.start()}>Take the tour</Button>;
};

export default function Example() {
  return (
    <TourProvider>
      <View style={{ gap: 16 }}>
        <View style={{ flexDirection: 'row', alignItems: 'center', gap: 12 }}>
          <TourStep name="search" title="Search everything" description="Jump to any issue, project or teammate. Press / from anywhere." style={{ flex: 1 }}>
            <View style={{ height: 40, borderRadius: 10, borderWidth: 1, borderColor: '#8884', justifyContent: 'center', paddingHorizontal: 12 }}>
              <Text color="textSecondary">Search…</Text>
            </View>
          </TourStep>
          <TourStep name="create" title="Create an issue" description="Capture a bug or an idea in seconds. C is the shortcut." radius="circle">
            <Button size="icon" accessibilityLabel="New issue">
              <Icon name="plus" color="onPrimary" />
            </Button>
          </TourStep>
        </View>
        <TourStep name="inbox" title="Your inbox" description="Mentions, reviews and assignments land here, newest first.">
          <View style={{ padding: 16, borderRadius: 12, borderWidth: 1, borderColor: '#8884', gap: 6 }}>
            <Text weight="medium">Maya mentioned you in ENG-412</Text>
            <Text size="sm" color="textSecondary">“Can you take the checkout bug?”</Text>
          </View>
        </TourStep>
        <StartButton />
      </View>
    </TourProvider>
  );
}
```

Steps run in the order they mount; give `order` to set it yourself. `useTour()` starts, steps and stops the tour from anywhere under the provider.

## Example: what's new in a dashboard

An analytics dashboard after an update: What's new points at the three things that changed, and once the tour is done or skipped, `onSeen` turns the button into Replay. In your app, add `autoStart` and store `seen` to show it once by itself.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Badge, Button, HStack, Text, VStack } from 'patine-ui';
import { Icon, TourProvider, TourStep, useTour } from '@patine-ui/pro';

const Start = ({ seen }: { seen: boolean }) => {
  const tour = useTour();
  return (
    <Button size="sm" variant={seen ? 'ghost' : 'default'} startIcon={seen ? undefined : <Icon name="sparkles" size="sm" color="onPrimary" />} onPress={() => tour.start()}>
      {seen ? 'Replay tour' : 'What’s new'}
    </Button>
  );
};

export default function Example() {
  const [seen, setSeen] = useState(false);
  return (
    <TourProvider onSeen={() => setSeen(true)}>
      <VStack gap="md" style={{ width: '100%', maxWidth: 560 }}>
        <HStack justify="space-between" align="center" wrap>
          <Text size="lg" weight="semibold">Revenue</Text>
          <HStack gap="sm">
            <TourStep name="range" title="Compare periods" description="Pick any two ranges and every chart shows both.">
              <Button size="sm" variant="outline" startIcon={<Icon name="calendar" size="sm" />}>
                Last 30 days
              </Button>
            </TourStep>
            <TourStep name="export" title="Export to CSV" description="Downloads what you see, with your filters applied." radius="circle">
              <Button size="icon" variant="outline" accessibilityLabel="Export">
                <Icon name="download" />
              </Button>
            </TourStep>
          </HStack>
        </HStack>
        <TourStep name="insight" title="Insights" description="We flag what moved the number most. Press one to see the orders behind it.">
          <View style={{ padding: 16, borderRadius: 12, borderWidth: 1, borderColor: '#8884', gap: 6 }}>
            <HStack gap="sm" align="center">
              <Badge variant="success">+18%</Badge>
              <Text weight="medium">€48,210 this month</Text>
            </HStack>
            <Text size="sm" color="textSecondary">Most of the rise came from repeat customers in Germany.</Text>
          </View>
        </TourStep>
        <HStack justify="flex-end">
          <Start seen={seen} />
        </HStack>
      </VStack>
    </TourProvider>
  );
}
```

## Show it once

`autoStart` begins as soon as the steps have laid out, unless `seen` is true. `onSeen` fires once, when they reach **Done** or skip: write the flag there, in whatever storage your app already uses.

```tsx
const [seen, setSeen] = useStoredFlag('tour:projects'); // AsyncStorage, MMKV, localStorage, your API…

<TourProvider autoStart seen={seen} onSeen={() => setSeen(true)} onFinish={({ completed, step }) => track('tour_end', { completed, step })}>
  <ProjectsScreen />
</TourProvider>
```

`onFinish` also tells you whether they finished or skipped, and on which step, for your analytics. `onStepChange` fires on each step.

## Long screens

A target near the top or bottom edge is scrolled into view before the spotlight moves to it. On the web the page scrolls by itself; on iOS and Android, pass the ScrollView the steps sit in.

```tsx
const scrollRef = useRef(null);

<TourProvider scrollRef={scrollRef}>
  <ScrollView ref={scrollRef}>…</ScrollView>
</TourProvider>
```

## Placement and shape

Cards go under or over their target when there's room, and flip when there isn't. Set `placement` to `'top'`, `'bottom'`, `'left'` or `'right'` to ask for a side (it still flips at the edge), or `'center'` for a welcome card with no target. `radius="circle"` rounds the spotlight for avatars and round buttons; `padding` sets the space around the target.

```tsx live
import { View } from 'react-native';
import { Avatar, Button, Text } from 'patine-ui';
import { TourProvider, TourStep, useTour } from '@patine-ui/pro';

const Start = () => {
  const tour = useTour();
  return <Button variant="outline" onPress={() => tour.start()}>Start</Button>;
};

export default function Example() {
  return (
    <TourProvider labels={{ next: 'Continue', done: 'Get started' }}>
      <View style={{ flexDirection: 'row', alignItems: 'center', gap: 16 }}>
        <TourStep name="welcome" order={0} placement="center" title="Welcome to Acme" description="A one-minute look around. You can leave any time.">
          <View />
        </TourStep>
        <TourStep name="profile" order={1} radius="circle" padding={6} placement="right" title="Your profile" description="Set your photo, status and working hours here.">
          <Avatar name="Maya Lindqvist" />
        </TourStep>
        <Text style={{ flex: 1 }}>Maya Lindqvist</Text>
        <Start />
      </View>
    </TourProvider>
  );
}
```

## Hotspots

`TourHotspot` puts a pulsing beacon on one new thing. Tapping it spotlights what it marks with a card; **Got it** closes it and calls `onSeen`, after which `seen` hides the beacon.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Button } from 'patine-ui';
import { TourHotspot } from '@patine-ui/pro';

export default function Example() {
  const [seen, setSeen] = useState(false);
  return (
    <View style={{ flexDirection: 'row', gap: 12, padding: 12 }}>
      <Button variant="outline">Sort</Button>
      <TourHotspot seen={seen} onSeen={() => setSeen(true)} title="New: saved views" description="Save any filter as a view and pin it to your sidebar.">
        <Button variant="outline">Filter</Button>
      </TourHotspot>
    </View>
  );
}
```

## Accessibility

- The card is a modal dialog named by its title, and takes focus on each step, so screen readers read it and keyboard focus stays in it.
- On the web, → and ← step, Escape skips. On Android the back button skips.
- Every button is at least 44 points, and the close button reads "Skip".
- The spotlight glides and the card fades in; with the OS set to reduce motion, both jump.

## Props

### TourProvider

| Prop | Type | Default |
| --- | --- | --- |
| `autoStart` | `boolean`: starts once its steps have mounted, unless `seen` | `false` |
| `seen` | `boolean`: they've taken or skipped it | `false` |
| `onSeen` | `() => void`: once, on Done or Skip; store the flag here | |
| `onFinish` | `({ completed, step }) => void` | |
| `onStepChange` | `(name, index) => void` | |
| `scrollRef` | `RefObject<ScrollView>`: scrolls targets into view on iOS and Android | |
| `showDots` | `boolean` | `true` |
| `skippable` | `boolean` | `true` |
| `labels` | `{ next, back, skip, done, count(step, total) }` | English |

### TourStep

| Prop | Type | Default |
| --- | --- | --- |
| `name` | `string`, required: `start(name)` starts from it | |
| `title` | `string`, required | |
| `description` | `string` | |
| `content` | `ReactNode`: anything more in the card | |
| `order` | `number` | mount order |
| `placement` | `'auto' \| 'top' \| 'bottom' \| 'left' \| 'right' \| 'center'` | `'auto'` |
| `padding` | `number` | `8` |
| `radius` | `number \| 'circle'` | theme |

### useTour()

Returns `{ active, index, count, start(from?), next(), back(), skip(), stop() }`. `stop()` ends it without calling `onSeen` or `onFinish`.

### TourHotspot

Takes `title`, `description`, `content`, `placement`, `padding` and `radius` like a step, plus `seen`, `onSeen`, `corner` (`'top-right'` by default) and `dismissLabel` (`'Got it'`).

## Related

- [Onboarding checklist](./onboarding-checklist): the setup tasks that come after the tour.
- [Popover](./popover) and [Tooltip](./tooltip): a hint on one control, free.
- [Motion effects](./motion): `Beacon`, the pulse the hotspot uses.
