Guideway

https://guideway.dev/docs
Admin
Guideway is a hook-first library for React Native and Expo that adds animated in-app product tours,...
Tokens:13,928
Snippets:152
Trust Score:2.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start tour with useTour start method

Source: https://guideway.dev/docs/quick-start

useTour() returns the controller. Call start(tourId) to begin the tour; here it starts the 'main' tour from a button press.

```tsx
import { useTour } from 'guideway';


function HelpButton() {
  const { start } = useTour();
  return <Button title="Show me around" onPress={() => start('main')} />;
}
```

--------------------------------

### Install Guideway with npm

Source: https://guideway.dev/docs/installation

Use npm install to add Guideway and its required peer dependencies to your project.

```bash
npm install guideway react-native-reanimated react-native-svg
```

--------------------------------

### Install Guideway with Expo

Source: https://guideway.dev/docs/compare/rn-tourguide

Install command using npx expo install for guideway, react-native-reanimated, and react-native-svg.

```bash
npx expo install guideway react-native-reanimated react-native-svg
```

--------------------------------

### Install Guideway with pnpm

Source: https://guideway.dev/docs/installation

Use pnpm add to add Guideway and its required peer dependencies to your project.

```bash
pnpm add guideway react-native-reanimated react-native-svg
```

--------------------------------

### Install Guideway with yarn

Source: https://guideway.dev/docs/installation

Use yarn add to add Guideway and its required peer dependencies to your project.

```bash
yarn add guideway react-native-reanimated react-native-svg
```

--------------------------------

### Guideway migration example

Source: https://guideway.dev/docs/compare/react-native-spotlight-tour

Shows the new approach with useTourTarget refs, data-driven steps, and TourProvider. Includes a single snippet combining the component, steps data, and provider.

```jsx
function Screen() {
  const search = useTourTarget('search');
  return <SearchBar ref={search} />;
}

```

```jsx
const tours = [{
  id: 'main',
  steps: [{ id: 'search', title: 'Find anything', body: 'Search your library', cutout: { shape: 'circle' } }],
}];

```

```jsx
<TourProvider tours={tours}><Screen /></TourProvider>

```

--------------------------------

### TourDefinition

Source: https://guideway.dev/docs/api/types

Defines a tour with an id, an array of steps, and optional callbacks for completion and skipping. The showOnce flag enables auto-start once per install when storage is provided.

```APIDOC
## TourDefinition

### Description
Defines a tour with an id, an array of steps, and optional callbacks for completion and skipping. The showOnce flag enables auto-start once per install when storage is provided.

### Interface
```typescript
interface TourDefinition {
  id: string;
  steps: StepDefinition[];
  showOnce?: boolean;              // auto-start once per install (needs `storage`)
  onComplete?: () => void;
  onSkip?: (atIndex: number) => void;
}
```

### Properties
- **id** (string) - Required - The unique identifier for the tour.
- **steps** (StepDefinition[]) - Required - The list of steps in the tour.
- **showOnce** (boolean) - Optional - If true, the tour auto-starts once per install (requires storage).
- **onComplete** (() => void) - Optional - Callback invoked when the tour is completed.
- **onSkip** ((atIndex: number) => void) - Optional - Callback invoked when the tour is skipped, receiving the index at which it was skipped.
```

--------------------------------

### useTour()

Source: https://guideway.dev/docs/api/hooks

Returns the controller for starting and driving tours. Provides methods to control tour flow and state about the active tour.

```APIDOC
## useTour()

### Description
Returns the controller for starting and driving tours. Must be used inside a TourProvider.

### Usage
```
const { start, next, back, skip, stop, isActive, stepIndex, totalSteps } = useTour();
```

### Methods
- **start** (tourId: string, options?: { fromIndex?: number }) => void - Start a tour, optionally from a given step index.
- **next** () => void - Advance one step. Fires the tour's onComplete on the last step.
- **back** () => void - Go back one step.
- **skip** () => void - End the tour and fire onSkip(atIndex).
- **stop** () => void - End the tour silently.
- **reset** (tourId: string) => void - Clear a showOnce tour's "seen" flag so it can auto-start again. No-op without storage.

### State
- **isActive** (boolean) - Whether a tour is currently running.
- **activeTourId** (string | null) - The running tour's id.
- **currentStep** (StepDefinition | null) - The current step.
- **stepIndex** (number) - Zero-based index of the current step.
- **totalSteps** (number) - Number of steps in the active tour.
- **progress** (number) - Progress through the tour, from 0 to 1.
```

--------------------------------

### Access the tour controller with useTour

Source: https://guideway.dev/docs/concepts

Any component inside TourProvider can reach the controller with useTour(). The returned object includes start, next, back, skip, and isActive. Calling start('main') activates the tour at step 0.

```javascript
const { start, next, back, skip, isActive } = useTour();
start('main');
```

--------------------------------

### useTour() hook usage

Source: https://guideway.dev/docs/api/hooks

Returns the controller for starting and driving tours. Must be used inside a TourProvider.

```javascript
const { start, next, back, skip, stop, isActive, stepIndex, totalSteps } = useTour();
```

--------------------------------

### TourDefinition interface

Source: https://guideway.dev/docs/api/types

Defines a tour with an id, steps, optional showOnce flag for auto-starting once per install (requires storage), and optional onComplete and onSkip callbacks.

```typescript
interface TourDefinition {
  id: string;
  steps: StepDefinition[];
  showOnce?: boolean;              // auto-start once per install (needs `storage`)
  onComplete?: () => void;
  onSkip?: (atIndex: number) => void;
}
```

--------------------------------

### Attach a target ref to a view with useTourTarget

Source: https://guideway.dev/docs/concepts

A step highlights a view by connecting them via id. Call useTourTarget('search') to get a ref and attach it to the view. When the step becomes active, Guideway measures the ref's view and draws the spotlight around it.

```javascript
const ref = useTourTarget('search');
<TextInput ref={ref} />
```

--------------------------------

### Guideway usage with useTourTarget and tours array

Source: https://guideway.dev/docs/compare/rn-tourguide

Shows the Guideway pattern: using useTourTarget to get a ref, defining tours as data with stable string ids, and wrapping with TourProvider. This is the 'after' state in the migration.

```jsx
function Screen() {
  const search = useTourTarget('search');
  return <SearchBar ref={search} />;
}


const tours = [{
  id: 'main',
  steps: [{ id: 'search', title: 'Find anything', body: 'Search your library' }],
}];


<TourProvider tours={tours}><Screen /></TourProvider>
```

--------------------------------

### TourProvider with custom theme and storage

Source: https://guideway.dev/docs/api/tour-provider

Configure TourProvider with colorScheme auto, a custom accent color, overlayTapBehavior skip, allowTargetInteraction, and AsyncStorage for showOnce tours.

```jsx
<TourProvider
  tours={tours}
  insets={insets}
  colorScheme="auto"
  theme={{ accent: '#397fbc' }}
  overlayTapBehavior="skip"
  allowTargetInteraction
  storage={AsyncStorage}
>
  <App />
</TourProvider>

```

--------------------------------

### react-native-spotlight-tour provider with AttachStep

Source: https://guideway.dev/docs/compare/react-native-spotlight-tour

Shows the previous step definition using required render/AttachStep wrappers.

```jsx
<SpotlightTourProvider steps={steps}>
  <AttachStep index={0}>
    <SearchBar />
  </AttachStep>
</SpotlightTourProvider>

```

--------------------------------

### Basic TourProvider usage

Source: https://guideway.dev/docs/api/tour-provider

Mount TourProvider once near the root of your app, wrapping everything that needs a tour. Pass tours and insets (from useSafeAreaInsets) as props.

```jsx
import { TourProvider } from 'guideway';


<TourProvider tours={tours} insets={insets}>
  <App />
</TourProvider>

```

--------------------------------

### Mark a tour show-once

Source: https://guideway.dev/docs/guides/persistence

Set showOnce: true on the tour. The first unseen showOnce tour auto-starts when the provider mounts. The tour is marked seen up front, so it shows exactly once even if the app is killed mid-tour. Without a storage adapter, showOnce is a no-op.

```js
const tours = [
  {
    id: 'welcome',
    showOnce: true,
    steps: [
      { id: 'inbox', title: 'Your inbox', body: 'Everything lands here.' },
      { id: 'compose', title: 'Compose', body: 'Start a new message.' },
    ],
  },
];
```

--------------------------------

### Define a tour with steps and onComplete callback

Source: https://guideway.dev/docs/concepts

A tour is a plain object with an id and an array of steps. Each step has an id, optional title/body, and optional placement and cutout. The tour can set showOnce and onComplete/onSkip callbacks.

```javascript
const tours = [
  {
    id: 'main',
    steps: [
      { id: 'search', title: 'Find anything', body: 'Search from here.' },
      { id: 'create', title: 'Create', body: 'Tap + to start.' },
    ],
    onComplete: () => console.log('done'),
  },
];
```

--------------------------------

### useTourTarget(id, options?)

Source: https://guideway.dev/docs/api/hooks

Returns a ref to attach to the view a step should highlight. The id must match a step's id.

```APIDOC
## useTourTarget(id, options?)

### Description
Returns a ref to attach to the view a step should highlight. The id must match a step's id.

### Usage
```
const ref = useTourTarget('search');
// ...
<TextInput ref={ref} placeholder="Search" />
```

### Options
- **scrollRef** (RefObject<ScrollView | FlatList>) - The scroll container holding this target, so Guideway can scroll it into view before highlighting. See Auto-scroll.
- **index** (number) - The item's index in a FlatList, used with scrollToIndex for virtualized rows. See FlatList and lists.
- **enabled** (boolean) - Set false to skip registering this target (for example, behind a feature flag).
```

--------------------------------

### Define a tour target with Guideway

Source: https://guideway.dev/docs/compare/react-native-copilot

The modern approach using refs and a centralized data array to define tour targets.

```javascript
function Screen() {
  const search = useTourTarget('search');
  return <Text ref={search}>Search</Text>;
}


const tours = [{
  id: 'main',
  steps: [{ id: 'search', title: 'Find anything', body: 'Search your library' }],
}];
```

--------------------------------

### useTourTarget(id, options?) hook usage

Source: https://guideway.dev/docs/api/hooks

Returns a ref to attach to the view a step should highlight. The id must match a step’s id.

```javascript
const ref = useTourTarget('search');
// ...
<TextInput ref={ref} placeholder="Search" />
```

--------------------------------

### Set overlayTapBehavior to 'skip' on TourProvider

Source: https://guideway.dev/docs/guides/interaction

Configures the scrim tap behavior to end the tour (firing `onSkip`) instead of advancing to the next step. Use this when you want tapping outside the spotlight to skip the tour.

```jsx
<TourProvider tours={tours} overlayTapBehavior="skip">{/* ... */}</TourProvider>
```

--------------------------------

### TourStorage

Source: https://guideway.dev/docs/api/types

A pluggable adapter for showOnce persistence. It matches the shape of AsyncStorage and MMKV, and tolerates sync or async implementations.

```APIDOC
## TourStorage

### Description
A pluggable adapter for showOnce persistence. It matches the shape of AsyncStorage and MMKV, and tolerates sync or async implementations.

### Interface
```typescript
interface TourStorage {
  getItem(key: string): Promise<string | null> | string | null;
  setItem(key: string, value: string): Promise<void> | void;
  removeItem?(key: string): Promise<void> | void;
}
```

### Methods
- **getItem(key: string)** - Returns a promise or string or null. Retrieves the value for the given key.
- **setItem(key: string, value: string)** - Returns a promise or void. Sets the value for the given key.
- **removeItem?(key: string)** - Optional. Returns a promise or void. Removes the value for the given key.
```

--------------------------------

### GuidewayTheme and ThemeOverride interfaces

Source: https://guideway.dev/docs/api/types

GuidewayTheme defines the full theme structure. ThemeOverride is passed to the provider's theme prop and is deep-merged over the chosen light or dark base. Both interfaces are shown together as they are related.

```typescript
interface GuidewayTheme {
  overlayColor: string;            // scrim color (include opacity in the rgba)
  accent: string;                  // primary button color
  tooltip: {
    backgroundColor: string;
    textColor: string;
    titleColor: string;
    borderRadius: number;
    padding: number;
    maxWidth: number;
    fontFamily?: string;
  };
  labels: { next: string; back: string; skip: string; done: string };
}
```

```typescript
interface ThemeOverride {
  overlayColor?: string;
  accent?: string;
  tooltip?: Partial<GuidewayTheme['tooltip']>;
  labels?: Partial<GuidewayTheme['labels']>;
}
```

--------------------------------

### Provide storage adapter to TourProvider

Source: https://guideway.dev/docs/guides/persistence

Pass a storage adapter to the provider. It matches the shape of AsyncStorage and MMKV, and accepts sync or async implementations.

```jsx
import AsyncStorage from '@react-native-async-storage/async-storage';


<TourProvider tours={tours} storage={AsyncStorage}>{/* ... */}</TourProvider>
```

--------------------------------

### TourStorage interface

Source: https://guideway.dev/docs/api/types

A pluggable adapter for showOnce persistence. Matches the shape of AsyncStorage and MMKV, and tolerates sync or async implementations.

```typescript
interface TourStorage {
  getItem(key: string): Promise<string | null> | string | null;
  setItem(key: string, value: string): Promise<void> | void;
  removeItem?(key: string): Promise<void> | void;
}
```

--------------------------------

### Configure circular cutout with padding

Source: https://guideway.dev/docs/guides/placement

Use the `cutout` property to set the spotlight shape and padding for a step.

```javascript
{ id: 'fab', title: 'Create', body: 'Tap +.', cutout: { shape: 'circle', padding: 6 } }
```

--------------------------------

### Set global default cutout with TourProvider

Source: https://guideway.dev/docs/guides/placement

Use the `defaultCutout` prop on `TourProvider` to set a global default cutout. Per-step `cutout` values are merged over it.

```jsx
<TourProvider tours={tours} defaultCutout={{ shape: 'rounded', padding: 10 }}>
  {/* a circular avatar step can still set cutout: { shape: 'circle' } */}
</TourProvider>
```

--------------------------------

### GuidewayTheme and ThemeOverride

Source: https://guideway.dev/docs/api/types

Defines the theme structure for the guideway UI and the override type used with the provider's theme prop.

```APIDOC
## GuidewayTheme and ThemeOverride

### Description
Defines the theme structure for the guideway UI and the override type used with the provider's theme prop. ThemeOverride is deep-merged over the chosen light or dark base.

### Interface
```typescript
interface GuidewayTheme {
  overlayColor: string;            // scrim color (include opacity in the rgba)
  accent: string;                  // primary button color
  tooltip: {
    backgroundColor: string;
    textColor: string;
    titleColor: string;
    borderRadius: number;
    padding: number;
    maxWidth: number;
    fontFamily?: string;
  };
  labels: { next: string; back: string; skip: string; done: string };
}

interface ThemeOverride {
  overlayColor?: string;
  accent?: string;
  tooltip?: Partial<GuidewayTheme['tooltip']>;
  labels?: Partial<GuidewayTheme['labels']>;
}
```

### Properties (GuidewayTheme)
- **overlayColor** (string) - Required - Scrim color, include opacity in the rgba.
- **accent** (string) - Required - Primary button color.
- **tooltip** (object) - Required - Tooltip styling properties.
  - **backgroundColor** (string) - Required
  - **textColor** (string) - Required
  - **titleColor** (string) - Required
  - **borderRadius** (number) - Required
  - **padding** (number) - Required
  - **maxWidth** (number) - Required
  - **fontFamily** (string) - Optional
- **labels** (object) - Required - Labels for navigation buttons.
  - **next** (string) - Required
  - **back** (string) - Required
  - **skip** (string) - Required
  - **done** (string) - Required

### Properties (ThemeOverride)
- **overlayColor** (string) - Optional
- **accent** (string) - Optional
- **tooltip** (Partial<GuidewayTheme['tooltip']>) - Optional
- **labels** (Partial<GuidewayTheme['labels']>) - Optional
```

--------------------------------

### rn-tourguide usage with TourGuideProvider and TourGuideZone

Source: https://guideway.dev/docs/compare/rn-tourguide

Shows the rn-tourguide pattern: wrapping a component in TourGuideZone with a zone number and text. This is the 'before' state in the migration.

```jsx
<TourGuideProvider>
  <TourGuideZone zone={1} text="Search your library">
    <SearchBar />
  </TourGuideZone>
</TourGuideProvider>
```

--------------------------------

### StepDefinition

Source: https://guideway.dev/docs/api/types

Defines a single step in a tour, including the target id, optional title and body, placement, cutout shape, and custom tooltip renderer.

```APIDOC
## StepDefinition

### Description
Defines a single step in a tour, including the target id, optional title and body, placement, cutout shape, and custom tooltip renderer.

### Interface
```typescript
interface StepDefinition {
  id: string;                      // must match a useTourTarget(id)
  title?: string;
  body?: string | ReactNode;
  placement?: 'top' | 'bottom' | 'left' | 'right' | 'auto';  // default 'bottom'
  cutout?: Cutout;                 // per-step spotlight shape
  render?: TooltipComponent;       // per-step custom tooltip
}
``` n
### Properties
- **id** (string) - Required - Must match a useTourTarget(id).
- **title** (string) - Optional - The title of the step.
- **body** (string | ReactNode) - Optional - The body content of the step.
- **placement** ('top' | 'bottom' | 'left' | 'right' | 'auto') - Optional - Placement of the tooltip, default 'bottom'.
- **cutout** (Cutout) - Optional - Per-step spotlight shape.
- **render** (TooltipComponent) - Optional - Per-step custom tooltip component.
```

--------------------------------

### Wrap app with TourProvider and tours data

Source: https://guideway.dev/docs/quick-start

Pass tours (plain data) and safe-area insets to TourProvider near the root. The tours array defines steps with ids that must match the target refs used later.

```tsx
import { TourProvider } from 'guideway';
import { useSafeAreaInsets } from 'react-native-safe-area-context';


const tours = [
  {
    id: 'main',
    steps: [
      { id: 'search', title: 'Find anything', body: 'Search your whole workspace from here.' },
      { id: 'create', title: 'Create instantly', body: 'Tap + to start something new.' },
    ],
  },
];


export default function App() {
  const insets = useSafeAreaInsets();
  return (
    <TourProvider tours={tours} insets={insets}>
      <HomeScreen />
    </TourProvider>
  );
}
```

--------------------------------

### Implement a custom tooltip component

Source: https://guideway.dev/docs/guides/theming

Provide a custom component to the tooltipComponent prop on the TourProvider to gain full control over the tooltip rendering using TooltipRenderProps.

```tsx
import type { TooltipRenderProps } from 'guideway';


function MyTooltip({ step, stepIndex, totalSteps, isLast, next, skip }: TooltipRenderProps) {
  return (
    <View style={styles.card}>
      <Text style={styles.title}>{step.title}</Text>
      <Text style={styles.body}>{step.body}</Text>
      <View style={styles.row}>
        <Pressable onPress={skip}><Text>Skip</Text></Pressable>
        <Pressable onPress={next}>
          <Text>{isLast ? 'Done' : `Next (${stepIndex + 1}/${totalSteps})`}</Text>
        </Pressable>
      </View>
    </View>
  );
}


<TourProvider tours={tours} tooltipComponent={MyTooltip}>{/* ... */}</TourProvider>
```

--------------------------------

### Customize storage key prefix

Source: https://guideway.dev/docs/guides/persistence

Persisted flags are stored under guideway:seen:<tourId>. Change the prefix with storageKeyPrefix.

```jsx
<TourProvider tours={tours} storage={AsyncStorage} storageKeyPrefix="myapp:onboarding:" />
```

--------------------------------

### UseTourTargetOptions

Source: https://guideway.dev/docs/api/types

Options for the useTourTarget hook, including a scroll reference, index, and enabled flag.

```APIDOC
## UseTourTargetOptions

### Description
Options for the useTourTarget hook, including a scroll reference, index, and enabled flag.

### Interface
```typescript
interface UseTourTargetOptions {
  scrollRef?: RefObject<ScrollView | FlatList>;
  index?: number;
  enabled?: boolean;
}
``` n
### Properties
- **scrollRef** (RefObject<ScrollView | FlatList>) - Optional - A reference to a scroll view or flat list.
- **index** (number) - Optional - The index of the target.
- **enabled** (boolean) - Optional - Whether the target is enabled.
```

--------------------------------

### Set colorScheme on TourProvider

Source: https://guideway.dev/docs/guides/theming

Set the colorScheme prop on the TourProvider to 'auto' to follow the device's theme settings.

```jsx
<TourProvider tours={tours} colorScheme="auto">{/* ... */}</TourProvider>
```

--------------------------------

### Enable allowTargetInteraction on TourProvider

Source: https://guideway.dev/docs/guides/interaction

Lets taps reach the highlighted element itself, making the spotlight hole interactive while the rest of the screen stays dimmed. Use this for flows like 'tap the + button to continue' where the user must perform the real action.

```jsx
<TourProvider tours={tours} allowTargetInteraction>{/* ... */}</TourProvider>
```

--------------------------------

### Configure Reanimated Babel plugin

Source: https://guideway.dev/docs/installation

Add the appropriate Reanimated plugin as the last entry in your babel.config.js file.

```javascript
// Reanimated 3.x (Expo SDK 53 and earlier):
plugins: ['react-native-reanimated/plugin'],


// Reanimated 4 (Expo SDK 54+) uses worklets:
plugins: ['react-native-worklets/plugin'],
```

--------------------------------

### Define a tour target with react-native-copilot

Source: https://guideway.dev/docs/compare/react-native-copilot

The legacy approach using HOC wrappers and CopilotStep components to define tour targets.

```javascript
const WalkthroughableText = walkthroughable(Text);


<CopilotStep text="Search your library" order={1} name="search">
  <WalkthroughableText>Search</WalkthroughableText>
</CopilotStep>
```

--------------------------------

### StepDefinition interface

Source: https://guideway.dev/docs/api/types

Defines a single step in a tour. The id must match a useTourTarget(id). placement defaults to 'bottom'. Supports per-step cutout and custom tooltip via render.

```typescript
interface StepDefinition {
  id: string;                      // must match a useTourTarget(id)
  title?: string;
  body?: string | ReactNode;
  placement?: 'top' | 'bottom' | 'left' | 'right' | 'auto';  // default 'bottom'
  cutout?: Cutout;                 // per-step spotlight shape
  render?: TooltipComponent;       // per-step custom tooltip
}
```

--------------------------------

### Set tooltip placement to bottom

Source: https://guideway.dev/docs/guides/placement

Use the `placement` property to prefer a side for the tooltip. The default is 'bottom'.

```javascript
{ id: 'avatar', title: 'Your profile', body: 'Tap to edit.', placement: 'bottom' }
```

--------------------------------

### Pass safe-area insets to TourProvider with SafeAreaProvider

Source: https://guideway.dev/docs/guides/android

Wrap the app in SafeAreaProvider and pass useSafeAreaInsets() to TourProvider. Required on Android 15 to correct the spotlight offset caused by edge-to-edge layout; also recommended on iOS to keep tooltips clear of the notch and home indicator.

```jsx
import { SafeAreaProvider, useSafeAreaInsets } from 'react-native-safe-area-context';
import { TourProvider } from 'guideway';


function Root() {
  const insets = useSafeAreaInsets();
  return (
    <TourProvider tours={tours} insets={insets}>
      <App />
    </TourProvider>
  );
}


export default function Main() {
  return (
    <SafeAreaProvider>
      <Root />
    </SafeAreaProvider>
  );
}
```

--------------------------------

### TooltipRenderProps interface

Source: https://guideway.dev/docs/api/types

The full contract handed to a custom tooltip, either a step's render or the provider's tooltipComponent. Provides step data, navigation callbacks, and progress information.

```typescript
interface TooltipRenderProps {
  step: StepDefinition;
  stepIndex: number;
  totalSteps: number;
  progress: number;
  isFirst: boolean;
  isLast: boolean;
  next: () => void;
  back: () => void;
  skip: () => void;
  stop: () => void;
}
```

--------------------------------

### Mark targets with useTourTarget refs

Source: https://guideway.dev/docs/quick-start

useTourTarget(id) returns a ref to attach to the view that the step should highlight. The id must match the step's id defined in the tours data.

```tsx
import { useTourTarget } from 'guideway';


function HomeScreen() {
  const searchRef = useTourTarget('search');
  const createRef = useTourTarget('create');
  return (
    <View>
      <TextInput ref={searchRef} placeholder="Search" />
      <Pressable ref={createRef}>
        <Text>+</Text>
      </Pressable>
    </View>
  );
}
```

--------------------------------

### Re-arm a tour with reset(tourId)

Source: https://guideway.dev/docs/guides/persistence

Use reset(tourId) from the controller to clear a tour's seen flag, allowing it to run again. Guideway also exports clearSeen(tourId, storage, prefix?) and seenKey(tourId, prefix?) for use outside a component.

```jsx
const { reset } = useTour();
<Button title="Replay tour" onPress={() => reset('welcome')} />
```

--------------------------------

### Override theme tokens

Source: https://guideway.dev/docs/guides/theming

Pass a partial theme object to the TourProvider to deep-merge custom values over the base theme.

```jsx
<TourProvider
  tours={tours}
  theme={{
    accent: '#397fbc',
    overlayColor: 'rgba(11,13,18,0.8)',
    tooltip: { borderRadius: 20, maxWidth: 300, fontFamily: 'Hanken Grotesk' },
  }}
>
  {/* ... */}
</TourProvider>
```

--------------------------------

### Pass the list ref and the row index to useTourTarget

Source: https://guideway.dev/docs/guides/flatlist

Provide both the list's scrollRef and the row's index to useTourTarget. Ensure getItemLayout is defined to allow scrollToIndex to jump reliably to off-screen rows.

```typescript
import { useRef } from 'react';
import { FlatList, View, Text } from 'react-native';
import { useTourTarget } from 'guideway';


function Feed({ data }) {
  const listRef = useRef<FlatList>(null);


  return (
    <FlatList
      ref={listRef}
      data={data}
      getItemLayout={(_, index) => ({ length: ROW_H, offset: ROW_H * index, index })}
      renderItem={({ item, index }) => <Row item={item} index={index} listRef={listRef} />}
    />
  );
}


function Row({ item, index, listRef }) {
  // highlight, say, row 12 in a tour
  const ref = index === 12 ? useTourTarget('featured-row', { scrollRef: listRef, index }) : undefined;
  return (
    <View ref={ref}>
      <Text>{item.label}</Text>
    </View>
  );
}
```

--------------------------------

### Cutout interface

Source: https://guideway.dev/docs/api/types

Defines the spotlight shape around a target. shape can be 'rect', 'rounded', 'circle', or 'pill'. padding adds extra space around the target in pixels. radius is the corner radius for 'rounded' shape, defaulting to 8.

```typescript
interface Cutout {
  shape?: 'rect' | 'rounded' | 'circle' | 'pill';
  padding?: number;                // extra space around the target, in px
  radius?: number;                 // corner radius for shape 'rounded' (default 8)
}
```

--------------------------------

### Pass scroll container ref via scrollRef option

Source: https://guideway.dev/docs/guides/auto-scroll

Use the scrollRef option to give useTourTarget the ScrollView's ref. The returned ref still goes on the target view. Guideway scrolls the container, lets it settle, then highlights the view in either direction.

```tsx
import { useRef } from 'react';
import { ScrollView, View, Text } from 'react-native';
import { useTourTarget } from 'guideway';


function SettingsScreen() {
  const scrollRef = useRef<ScrollView>(null);
  const dangerZone = useTourTarget('danger-zone', { scrollRef });


  return (
    <ScrollView ref={scrollRef}>
      {/* lots of content above the fold */}
      <View ref={dangerZone}>
        <Text>Delete account</Text>
      </View>
    </ScrollView>
  );
}
```

--------------------------------

### Localize tooltip labels

Source: https://guideway.dev/docs/guides/theming

Customize the tooltip button labels by providing a labels object within the theme prop.

```jsx
theme={{ labels: { next: 'Suivant', back: 'Retour', skip: 'Passer', done: 'Terminer' } }}
```

--------------------------------

### UseTourTargetOptions interface

Source: https://guideway.dev/docs/api/types

Options for the useTourTarget hook, including an optional scrollRef, index, and enabled flag.

```typescript
interface UseTourTargetOptions {
  scrollRef?: RefObject<ScrollView | FlatList>;
  index?: number;
  enabled?: boolean;
}
```

--------------------------------

### Cutout

Source: https://guideway.dev/docs/api/types

Defines the shape and padding of the spotlight cutout around a target element.

```APIDOC
## Cutout

### Description
Defines the shape and padding of the spotlight cutout around a target element.

### Interface
```typescript
interface Cutout {
  shape?: 'rect' | 'rounded' | 'circle' | 'pill';
  padding?: number;                // extra space around the target, in px
  radius?: number;                 // corner radius for shape 'rounded' (default 8)
}
``` n
### Properties
- **shape** ('rect' | 'rounded' | 'circle' | 'pill') - Optional - The shape of the cutout.
- **padding** (number) - Optional - Extra space around the target, in pixels.
- **radius** (number) - Optional - Corner radius for shape 'rounded', default 8.
```

--------------------------------

### Insets

Source: https://guideway.dev/docs/api/types

Represents inset values for top, right, bottom, and left.

```APIDOC
## Insets

### Description
Represents inset values for top, right, bottom, and left.

### Interface
```typescript
interface Insets {
  top: number;
  right: number;
  bottom: number;
  left: number;
}
```

### Properties
- **top** (number) - Required - Top inset.
- **right** (number) - Required - Right inset.
- **bottom** (number) - Required - Bottom inset.
- **left** (number) - Required - Left inset.
```

--------------------------------

### TooltipRenderProps

Source: https://guideway.dev/docs/api/types

The full contract handed to a custom tooltip (a step's render or the provider's tooltipComponent).

```APIDOC
## TooltipRenderProps

### Description
The full contract handed to a custom tooltip (a step's render or the provider's tooltipComponent). n
### Interface
```typescript
interface TooltipRenderProps {
  step: StepDefinition;
  stepIndex: number;
  totalSteps: number;
  progress: number;
  isFirst: boolean;
  isLast: boolean;
  next: () => void;
  back: () => void;
  skip: () => void;
  stop: () => void;
}
``` n
### Properties
- **step** (StepDefinition) - Required - The current step definition.
- **stepIndex** (number) - Required - The index of the current step.
- **totalSteps** (number) - Required - The total number of steps in the tour.
- **progress** (number) - Required - The progress value (likely 0 to 1). n- **isFirst** (boolean) - Required - Whether the current step is the first.
- **isLast** (boolean) - Required - Whether the current step is the last.
- **next** (() => void) - Required - Function to advance to the next step.
- **back** (() => void) - Required - Function to go back to the previous step.
- **skip** (() => void) - Required - Function to skip the tour.
- **stop** (() => void) - Required - Function to stop the tour.
```

--------------------------------

### Pass safe-area insets to TourProvider

Source: https://guideway.dev/docs/installation

Use react-native-safe-area-context to pass insets to the TourProvider, which is required for correct spotlight positioning on Android.

```javascript
import { useSafeAreaInsets } from 'react-native-safe-area-context';
import { TourProvider } from 'guideway';


function App() {
  const insets = useSafeAreaInsets();
  return (
    <TourProvider tours={tours} insets={insets}>
      {/* your app */}
    </TourProvider>
  );
}
```

--------------------------------

### Insets interface

Source: https://guideway.dev/docs/api/types

Represents inset values for top, right, bottom, and left edges.

```typescript
interface Insets {
  top: number;
  right: number;
  bottom: number;
  left: number;
}
```
Tokens:
Raw