Repository files navigation

Step-by-step walkthrough for your react native app!

Demo

yarn add react-native-copilot# or with npm:npm install --save react-native-copilot

Optional: If you want to have the smooth SVG animation, you should install and linkreact-native-svg.

Wrap the portion of your app that you want to use copilot with inside<CopilotProvider>:

import{CopilotProvider}from"react-native-copilot";constAppWithCopilot=()=>{return(<CopilotProvider><HomeScreen/></CopilotProvider>);};

NOTE: The old way of using copilot with thecopilot() HOC maker is deprecated in v3. It will continue to work but it's not recommended and may be removed in the future.

Before defining walkthrough steps for your react elements, you must make themwalkthroughable. The easiest way to do that for built-in react native components, is using thewalkthroughable HOC. Then you must wrap the element withCopilotStep.

import{CopilotProvider,CopilotStep,walkthroughable,}from"react-native-copilot";constCopilotText=walkthroughable(Text);constHomeScreen=()=>{return(<View><CopilotSteptext="This is a hello world example!"order={1}name="hello"><CopilotText>Hello world!</CopilotText></CopilotStep></View>);};

EveryCopilotStep must have these props:

1. name: A unique name for the walkthrough step.
2. order: A positive number indicating the order of the step in the entire walkthrough.
3. text: The text shown as the description for the step.

Additionally, a step may set theactive prop, a boolean that controls whether the step is used or skipped.

In order to start the tutorial, you can call thestart function from theuseCopilot hook:

constHomeScreen=()=>{return(<View><Buttontitle="Start tutorial"onPress={()=>start()}/></View>);};

If you are looking for a working example, please check outthis link.

The overlay in react-native-copilot is the component that draws the dark transparent over the screen. React-native-copilot comes with two overlay options:view andsvg.

Theview overlay uses 4 rectangles drawn around the target element using the<View /> component. We don't recommend using animation with this overlay since it's sluggish on some devices specially on Android.

Thesvg overlay uses an SVG path component for drawing the overlay. It offers a nice and smooth animation but it depends onreact-native-svg. If you are using expo, you can install it using:

expo install react-native-svg

Or if you are using react-native-cli:

yarn add react-native-svg# or with npmnpm install --save react-native-svgcd ios && pod install

You can specify the overlay by passing theoverlay prop to the<CopilotProvider /> component:

<CopilotProvideroverlay="svg"{/* or "view" */}><App/></CopilotProvider>

By default, if overlay is not explicitly specified, thesvg overlay will be used ifreact-native-svg is installed, otherwise theview overlay will be used.

You can customize the tooltip and the step number components by passing a component to theCopilotProvider component. If you are looking for an example tooltip component, take a look atthe default ui implementations.

constTooltipComponent=()=>{const{    isFirstStep,    isLastStep,    goToNext,    goToNth,    goToPrev,    stop,    currentStep,}=useCopilot();return(// ...)};<CopilotProvidertooltipComponent={TooltipComponent}stepNumberComponent={StepComponent}><App/></CopilotProvider>

The above code snippet shows the functions passed to the tooltip. These are your primary navigation functions. Some notes on navigation:

• handleNext andhandlePrev will move the mask from the current wrapped component immediately to the next.

• You can usehandleStop in conjunction withhandleNth to effectively "pause" a tour, allowing for user input, animations or any other interaction that shouldn't have the mask applied. Once you want to pick the tour back up, callhandleNth on the next tour step.

Note thathandleNth is 1-indexed, which is in line with what your step orders should look like.

You can customize tooltip's wrapper style:

conststyle={backgroundColor:"#9FA8DA",borderRadius:10,paddingTop:5,};<CopilotProvidertooltipStyle={style}><App/></CopilotProvider>;

By default, the tooltip width is calculated dynamically. You can make it fixed-size by overriding bothwidth andmaxWidth, check the example bellow:

constMARGIN=8;constWIDTH=Dimensions.get("window").width-2*MARGIN;<CopioltProvidertooltipStyle={{width:WIDTH,maxWidth:WIDTH,left:MARGIN}}><App/></CopilotProvider>;

You can customize the tooltip's arrow color:

<CopilotProviderarrowColor="#9FA8DA"><App/></CopilotProvider>

You can customize the mask color - default isrgba(0, 0, 0, 0.4), by passing a color string to theCopilotProvider component.

<CopilotProviderbackdropColor="rgba(50, 50, 100, 0.9)"><App/></CopilotProvider>

You can customize the mask svg path by passing a function to theCopilotProvider component.

functionSvgMaskPathFn(args:{size:Animated.valueXY;position:Animated.valueXY;canvasSize:{x:number;y:number;};step:Step;}):string;

Example with circle:

constcircleSvgPath=({ position, canvasSize})=>`M0,0H${canvasSize.x}V${canvasSize.y}H0V0ZM${position.x._value},${position.y._value}Za50 50 0 1 0 100 0 50 50 0 1 0-100 0`;<CopilotProvidersvgMaskPath={circleSvgPath}><App/></CopilotProvider>;

Example with different overlay for specific step:

Give name prop for the step

<CopilotSteptext="This is a hello world example!"order={1}name="hello"><CopilotText>Hello world!</CopilotText></CopilotStep>

Now you can return different svg path depending on step name

constcustomSvgPath=(args)=>{if(args.step?.name==="hello"){return`M0,0H${canvasSize.x}V${canvasSize.y}H0V0ZM${position.x._value},${position.y._value}Za50 50 0 1 0 100 0 50 50 0 1 0-100 0`;}else{return`M0,0H${canvasSize.x}V${canvasSize.y}H0V0ZM${position.x._value},${position.y._value}H${position.x._value+size.x._value}V${position.y._value+size.y._value}H${position.x._value}V${position.y._value}Z`;}};<CopilotProvidersvgMaskPath={customSvgPath}><App/></CopilotProvider>;

The components wrapped insideCopilotStep, will receive acopilot prop with a mutableref andonLayou which the outermost rendered element of the component or the element that you want the tooltip be shown around, must extend.

import{CopilotStep}from"react-native-copilot";constCustomComponent=({ copilot})=>(<View{...copilot}><Text>Hello world!</Text></View>);constHomeScreen=()=>{return(<View><CopilotSteptext="This is a hello world example!"order={1}name="hello"><CustomComponent/></CopilotStep></View>);};

You can localize labels:

<CopilotProviderlabels={{previous:"Vorheriger",next:"Nächster",skip:"Überspringen",finish:"Beenden"}}>

In order to adjust vertical position passverticalOffset to theCopilotProvider component.

<CopilotProviderverticalOffset={36}>

Useconst {start} = useCopilot() to trigger the tutorial. You can either invoke it with a touch event or inuseEffect to start after the comopnent mounts. Note that the component and all its descendants must be mounted before starting the tutorial since theCopilotSteps need to be registered first.

Pass the ScrollView reference as the second argument to thestart() function.egstart(undefined, scrollViewRef)

import{ScrollView}from"react-native";classHomeScreen{componentDidMount(){// Starting the tutorial and passing the scrollview reference.this.props.start(false,this.scrollView);}componentWillUnmount(){// Don't forget to disable event handlers to prevent errorsthis.props.copilotEvents.off("stop");}render(){<ScrollViewref={(ref)=>(this.scrollView=ref)}>// ...</ScrollView>;}}

useCopilot provides acopilotEvents function prop to allow you to track the progress of the tutorial. It utilizesmitt under the hood.

List of available events is:

• start — Copilot tutorial has started.
• stop — Copilot tutorial has ended or skipped.
• stepChange — Next step is triggered. PassesStep instance as event handler argument.

Example:

import{useCopilot}from"react-native-copilot";constHomeScreen=()=>{const{ copilotEvents}=useCopilot();useEffect(()=>{constlistener=()=>{// Copilot tutorial finished!};copilotEvents.on("stop",listener);return()=>{copilotEvents.off("stop",listener)};},[]);return(// ...);}

Issues and Pull Requests are always welcome.

If you are interested in becoming a maintainer, get in touch with us by sending an email or opening an issue. You should already have code merged into the project. Active contributors are encouraged to get in touch.

Creation of this project was sponsored by OK GROW!