react-native-walkthrough - GitLite

KO | EN

gitlite — search

#hacktoberfest #react #llm #android #machine-learning #rust #linux #docker #macos #nodejs #java #vue #pytorch #open-source

react-native-walkthrough

(★ 104)

A lightweight walkthrough library for React Native utilizing React's Context API

File Explorer

Download Latest Version (.zip)

- - App-test.js
- - build.gradle
  - gradle.properties
  - gradlew
  - gradlew.bat
  - settings.gradle
- - Podfile
  - Podfile.lock
- - App.js
  - NavigationStack.js
- .buckconfig
- .eslintrc.js
- .flowconfig
- .gitattributes
- .gitignore
- .prettierrc.js
- .watchmanconfig
- app.json
- babel.config.js
- index.js
- metro.config.js
- package.json
- yarn.lock
- ContextWrapper.tsx
- index.ts
- WalkthroughElement.tsx
- WalkthroughProvider.tsx
.eslintrc.js
.gitignore
.npmignore
.nvmrc
.prettierrc
jest.config.js
package.json
README.md
tsconfig.json
yarn.lock

# Installation Guide

1. Get the code

git clone https://github.com/jasongaare/react-native-walkthrough

Downloads the entire project code from GitHub to your computer.

cd react-native-walkthrough

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

yarn add react-native-walkthrough

Type this command into your terminal and run it.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# React Native Walkthrough [![npm](https://img.shields.io/npm/v/react-native-walkthrough.svg)](https://www.npmjs.com/package/react-native-walkthrough) [![npm](https://img.shields.io/npm/dm/react-native-walkthrough.svg)](https://www.npmjs.com/package/react-native-walkthrough)

## Walkthrough

> _**NOTE**: This library is currently under development, and should primarly be considered as being in a beta stage._

React Native Walkthrough is an app-wide walkthrough library, with a minimal footprint.

### Installation

```
yarn add react-native-walkthrough
```

### Roadmap
- [ ] Move library to Typescript (soon!)
- [ ] add ability to pass external EventEmitter instance via props
- [ ] add props for changing timeout durations
- [ ] ???

### Basic Usage

React Native Walkthrough exports the following:

- [`WalkthroughProvider` component](#walkthroughprovider)
  - [`WalkthroughElement component`](#walkthroughelement)
  - [`startWalkthrough` function](#startwalkthrough)
  - [`dispatchWalkthroughEvent` function](#dispatchwalkthroughevent)
  - [`goToWalkthroughElementWithId` function](#gotowalkthroughelementwithid)

#### `WalkthroughProvider`

First, you will need to wrap your entire app in the `WalkthroughProvider` component (no props or additional config required)

```js
import { WalkthroughProvider } from 'react-native-walkthrough';

render() {
  return (
    <WalkthroughProvider>
      <YourAppHere />
    </WalkthroughProvider>
  )  
}
```

#### `WalkthroughElement`

When you wish to highlight something as a part of a Walkthrough, you simply wrap the component in a `WalkthroughElement` and give it a unique id.

```js
import { WalkthroughElement } from 'react-native-walkthrough';

<WalkthroughElement id="profile-button">   // just add this!
  <TouchableOpacity
    style={styles.profileButton}
    onPress={() => navigate('Profile', {name: 'Jane'})}
  >
    <Text>{"Go to Jane's profile"}</Text>
  </TouchableOpacity>
</WalkthroughElement>
```

This library utilizes [`react-native-walkthrough-tooltip`](https://github.com/jasongaare/react-native-walkthrough-tooltip) to render the content bubbles that point to a `WalkthroughElement`. You can edit the content of the tooltip in the [walkthrough guide](#creating-a-walkthrough-guide), or by providing the optional `content` prop directly on the `WalkthroughElement` component.

#### `startWalkthrough`

Function that accepts a walkthrough guide array and begins the walkthrough by setting the current element as the first element from the walkthrough guide array. [Learn about walkthrough guides here](#creating-a-walkthrough-guide)

```js
import { startWalkthrough } from 'react-native-walkthrough';

import profileWalkthrough from '../guides/profileWalkthrough';

<TouchableOpacity
  onPress={() => startWalkthrough(profileWalkthrough)}
>
  <Text>{"Show me how to view a profile"}</Text>
</TouchableOpacity>
```

#### `dispatchWalkthroughEvent`

Function that accepts a string event name. Walkthrough events are used to wait-then-show the next element in a walkthrough. Add a `triggerEvent` to the walkthrough element in a guide, then be sure to dispatch the walkthrough event when it occurs to trigger the tooltip to be displayed.

```js
import { NavigationEvents } from 'react-navigation';
import { dispatchWalkthroughEvent } from 'react-native-walkthrough';

render (
  <React.Fragment>
    <NavigationEvents
      onDidFocus={() => dispatchWalkthroughEvent('profile-focus')}
    />
    ...
  </React.Fragment>
)
```

#### `goToWalkthroughElementWithId`

Function that accepts a string element id. Finds the first element in the current walkthrough with a matching `id` and sets that element as the current element.

```js
import { goToWalkthroughElementWithId } from 'react-native-walkthrough';

<TouchableOpacity
  onPress={() => goToWalkthroughElementWithId('step-3')}
>
  <Text>{"Skip to next step"}</Text>
</TouchableOpacity>

```

### Creating a Walkthrough Guide

A walkthrough guide is simply an array of objects, where each object correlates to a `WalkthroughElement`. Each element object in the guide must have an `id` and `content` to display in the tooltip bubble.

#### Example guide
```js
import React from 'react';
import {View, Text, StyleSheet} from 'react-native';

const styles = StyleSheet.create({
  tooltipView: {
    paddingHorizontal: 24,
    paddingVertical: 8,
  },
  tooltipText: {
    color: 'black',
    fontSize: 18,
  },
});

const makeTooltipContent = text => (
  <View style={styles.tooltipView}>
    <Text style={styles.tooltipText}>{text}</Text>
  </View>
);

export default [
  {
    id: 'profile-button',
    content: makeTooltipContent('Tap here to view a profile'),
  },
  {
    id: 'profile-name',
    content: makeTooltipContent("Here is the user's name"),
    placement: 'bottom',
    triggerEvent: 'profile-focus',
  },
];
```

#### Guide values

|Key|Type|Required|Description|
|---|----|-----|----|
|content|function/Element| YES | This is the view displayed in the tooltip popover bubble |
|id|string|YES|id string that matches the corresponding WalkthroughElement|
|placement|string|NO | Determines placement of tooltip in relation to the element it is wrapping
|possibleOutcomes|array|NO|An array of objects with keys (`event`, `action`) that creates event listeners for multiple events to provide the ability to have an outcome tree that responds to a user's actions (listens to events dispatched via `dispatchWalkthroughEvent`|
|tooltipProps|object|NO|additional props to customize the tooltip functionality and style
|triggerEvent|string|NO|string event id, this element will not appear until the triggerEvent is dispatched via `dispatchWalkthroughEvent`

> To learn more about `placement` options and all the options for `tooltipProps` view the [`react-native-walkthrough-tooltip` README](https://github.com/jasongaare/react-native-walkthrough-tooltip#props)