Skip to main content

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 instead; for a list of setup tasks, the onboarding checklist.

import { TourProvider, TourStep, TourHotspot, useTour } from '@patine-ui/pro';
Loading…
<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.

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

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.

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.

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

Loading…
<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​

PropTypeDefault
autoStartboolean: starts once its steps have mounted, unless seenfalse
seenboolean: they've taken or skipped itfalse
onSeen() => void: once, on Done or Skip; store the flag here
onFinish({ completed, step }) => void
onStepChange(name, index) => void
scrollRefRefObject<ScrollView>: scrolls targets into view on iOS and Android
showDotsbooleantrue
skippablebooleantrue
labels{ next, back, skip, done, count(step, total) }English

TourStep​

PropTypeDefault
namestring, required: start(name) starts from it
titlestring, required
descriptionstring
contentReactNode: anything more in the card
ordernumbermount order
placement'auto' | 'top' | 'bottom' | 'left' | 'right' | 'center''auto'
paddingnumber8
radiusnumber | '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').