npm package: @fierroapp/native-copilot
Description: Guided tours for React Native with full Fabric support
Author: Fierro
Latest version: 1.1.3

# @fierroapp/native-copilot

Guided tours for React Native with full Fabric support. Built for onboarding flows, contextual guidance, and ScrollView-based walkthroughs.

> Origin note: this library takes `react-native-copilot` as a starting point and reimplements refs + measurement so it works reliably with Fabric.

## Installation

```bash
pnpm add @fierroapp/native-copilot react-native-svg
# or
npm i @fierroapp/native-copilot react-native-svg
# or
yarn add @fierroapp/native-copilot react-native-svg
```

## Quickstart

```tsx
import React, { useRef } from "react";
import { ScrollView, Text, TouchableOpacity } from "react-native";
import {
  CopilotProvider,
  CopilotStep,
  useCopilot,
  walkthroughable,
} from "@fierroapp/native-copilot";

const WalkthroughableText = walkthroughable(Text);
const WalkthroughableTouchableOpacity = walkthroughable(TouchableOpacity);

function Screen() {
  const { start } = useCopilot();
  const scrollViewRef = useRef<ScrollView>(null);

  return (
    <ScrollView ref={scrollViewRef}>
      <CopilotStep name="step1" order={1} text="This is the first step">
        <WalkthroughableText>Step 1</WalkthroughableText>
      </CopilotStep>

      <CopilotStep name="step2" order={2} text="This is the second step">
        <WalkthroughableTouchableOpacity onPress={() => {}}>
          <Text>Step 2</Text>
        </WalkthroughableTouchableOpacity>
      </CopilotStep>

      <TouchableOpacity onPress={() => start(undefined, scrollViewRef.current)}>
        <Text>Start tour</Text>
      </TouchableOpacity>
    </ScrollView>
  );
}

export default function App() {
  return (
    <CopilotProvider
      labels={{ skip: "Skip", previous: "Previous", next: "Next", finish: "Finish" }}
    >
      <Screen />
    </CopilotProvider>
  );
}
```

## Documentation

- `docs/EXAMPLES.md` — advanced usage snippets
- `docs/MIGRATION.md` — migration guide from `react-native-copilot`
- `docs/TROUBLESHOOTING.md` — common issues and fixes
- `docs/ARCHITECTURE.md` — internal architecture overview
- `CONTRIBUTING.md` — contribution guide
- `CHANGELOG.md` — release notes

## API

### CopilotProvider

Main props:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `verticalOffset` | `number` | `0` | Vertical offset for positioning |
| `animationDuration` | `number` | `300` | Animation duration in ms |
| `animated` | `boolean` | `true` | Enable/disable animations |
| `labels` | `Labels` | `{}` | Button labels |
| `tooltipComponent` | `Component` | `Tooltip` | Custom tooltip component |
| `tooltipStyle` | `ViewStyle` | - | Tooltip styles |
| `backdropColor` | `string` | `rgba(0,0,0,0.4)` | Overlay color |
| `arrowColor` | `string` | `#fff` | Arrow color |
| `arrowSize` | `number` | `8` | Arrow size |
| `margin` | `number` | `12` | Tooltip margin |
| `stopOnOutsideClick` | `boolean` | `false` | Close on outside press |
| `androidStatusBarVisible` | `boolean` | `false` | Translucent status bar on Android |
| `highlightBorderColor` | `string` | - | Highlight border color |
| `highlightBorderWidth` | `number` | `2` | Highlight border width |
| `highlightBorderRadius` | `number` | `8` | Highlight border radius |
| `highlightPadding` | `number` | `8` | Extra highlight padding |
| `defaultGroupId` | `string` | `"default"` | Default tour group |

Notes:
- `overlay` and `svgMaskPath` are reserved for a future version. Current overlay is view-based.

### useCopilot

```typescript
const {
  start,           // (fromStep?: string, scrollView?: ScrollView, groupId?: string) => Promise<void>
  stop,            // () => Promise<void>
  goToNext,        // () => Promise<void>
  goToPrev,        // () => Promise<void>
  goToNth,         // (n: number) => Promise<void>
  currentStep,     // Step | undefined
  visible,         // boolean
  isFirstStep,     // boolean
  isLastStep,      // boolean
  currentStepNumber,  // number
  totalStepsNumber,   // number
  copilotEvents,      // EventEmitter
  activeGroupId,      // string
  setActiveGroup,     // (groupId: string) => void
} = useCopilot();
```

### CopilotStep

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | - | Unique step id |
| `order` | `number` | - | Step order |
| `text` | `string` | - | Tooltip text |
| `active` | `boolean` | `true` | Enable/disable the step |
| `groupId` | `string` | `"default"` | Tour group id |

## Grouped tours

```tsx
function Screen() {
  const { start } = useCopilot();
  const scrollViewRef = useRef<ScrollView>(null);

  return (
    <ScrollView ref={scrollViewRef}>
      <CopilotStep name="home.step1" order={1} text="Home step" groupId="home">
        <WalkthroughableText>Home</WalkthroughableText>
      </CopilotStep>

      <CopilotStep name="settings.step1" order={1} text="Settings step" groupId="settings">
        <WalkthroughableText>Settings</WalkthroughableText>
      </CopilotStep>

      <TouchableOpacity onPress={() => start(undefined, scrollViewRef.current, "home")}>
        <Text>Start Home tour</Text>
      </TouchableOpacity>

      <TouchableOpacity onPress={() => start(undefined, scrollViewRef.current, "settings")}>
        <Text>Start Settings tour</Text>
      </TouchableOpacity>
    </ScrollView>
  );
}
```

Grouped tours let you run isolated walkthroughs in the same screen. Use `groupId` to scope steps, then pass the group id to `start(...)`.

Example:

```tsx
start(undefined, scrollViewRef.current, "home");
```

## Compatibility

- React Native >= 0.73.0 (New Architecture / Fabric)
- Expo SDK >= 50
- React >= 18.0.0

## License

MIT