A common requirement for many apps today is a UI walk-through. There are a number of packages that exist for the web such as Intro.js — a VanillaJS package, and Joyride — a React library, but none that work specifically for React Native apps. This is why we at OK GROW! have created React Native Copilot — a package that lets you easily create step-by-step walk-throughs for React Native apps.
Let’s start with implementing a simple screen.
Now let’s use react-native-copilot to add the walk-through to the screen. First, we should apply the
copilot() higher order component to the main component:
It will wrap the
App component within a
View element which will later be used to add the walk-through components to the screen. In addition to, it will inject the state of the walk-through to the child context.
Now we need to make a
walkthroughable component that would be used as one of the copilot steps. A
walkthroughable component is a component that accepts an object named copilot as a prop, that contains two functions,
ref. These functions are used to keep track of the elements positions in order to make the walk-through modals the right size and be in the right position. In most cases, these functions can simply be passed directly to the native elements, however, they also can be invoked manually with some arbitrary algorithms as well if needed.
The easiest way to make a
walkthroughable component for the native components would be using the
walkthroughable higher-order component:
Now we can replace some
Image components with WalkthroughableText and
WalkthroughableImage. The next step would be to wrap the elements that we want to have a walk-through step for inside a
CopilotStep element. The
CopilotStep component accepts these as props:
name: A unique name for the walk-through step.
order: A positive number indicating the
order of the step in the entire walk-through. text: The text shown as the description for the step.
copilot() higher-order component, injects some essential props to the main component:
start: A function that you can invoke to start the walk-through. currentStep: An object of the currentStep's information.
visible: True, if the walk-through modal is visible. Let's make the button onPress event trigger the walk-through:
Now it’s time turn our screen into a completely
Everything is happening in the copilot higher-order component. The global state of the walk-through is stored and handled within this component. Whenever a
CopilotStep component is mounted, it registers itself as a new step in the entire walk-through by calling the
registerStep() method through the context. The position and the size of the component is always stored as a part of the step data. The child element inside the
CopilotStep takes an additional
copilot prop which is an object that has two methods:
onLayout. These two methods need to be applied to the outermost native component i.e. View, Image, Text, etc. which are needed in order to measure the component's layout. Whenever the start function is invoked, it starts measuring the position and the sizes of the copilot step components.
Copilot offers two types of overlays:
view. The first one provides a smoother animation but it requires react-native-svg. This mask is rendered using a
path svg element whose path describes a rectangle within a larger rectangle that fills the entire screen. You may ask why we didn't use ART for that. We didn't because it doesn't support fill-rules. But what is
fill-rule and why do we need it for drawing the mask?
fill-rule essentially describes how the interior of the shape should be painted.
fill-rule: evenodd allows us to paint only the outer rectangle leaving the inner one empty. It determines the "insideness" of a point is determined by drawing a trial ray from it to some random point in infinity. If the number of path segments that it crosses along the way is even it is considered as "outside" otherwise it is "inside". Here's an example svg similar to what we use for the copilot's mask.
We hope that now you can easily create a step-by-step walk-through for any of your React Native apps. If you have questions, problems, or simply wish to let us know what you love most about the release, please let us know via Twitter or on Github!
Originally published at www.okgrow.com