This repository has been archived by the owner on May 17, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 37
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore: updated README to include useShepherdTour (#781)
- Loading branch information
1 parent
26cc506
commit 99026a2
Showing
3 changed files
with
210 additions
and
17 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,166 @@ | ||
# react-shepherd | ||
|
||
<div> | ||
<a href="https://shipshape.io"> | ||
<img align="left" src="http://i.imgur.com/DWHQjA5.png" alt="Ship Shape" width="50" height="50"/> | ||
</a> | ||
|
||
**[react-shepherd is built and maintained by Ship Shape. Contact us for web app consulting, development, and training for your project](https://shipshape.io/)**. | ||
|
||
</div> | ||
|
||
[![NPM](https://img.shields.io/npm/v/react-shepherd.svg)](https://www.npmjs.com/package/react-shepherd) | ||
[![Test Status](https://github.com/shipshapecode/react-shepherd/workflows/Test/badge.svg)](https://github.com/shipshapecode/react-shepherd/actions?query=workflow%3ATest) | ||
[![Maintainability](https://api.codeclimate.com/v1/badges/d5273e1d465352a6df4e/maintainability)](https://codeclimate.com/github/shipshapecode/react-shepherd/maintainability) | ||
[![Test Coverage](https://api.codeclimate.com/v1/badges/d5273e1d465352a6df4e/test_coverage)](https://codeclimate.com/github/shipshapecode/react-shepherd/test_coverage) | ||
[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com) | ||
|
||
This is a React wrapper for the [Shepherd](https://github.com/shipshapecode/shepherd), site tour, library. | ||
It's mainly a wrapper around the Shepherd library that exposes the tour object and methods to the context object | ||
that can be passed into props for dynamic interactivity. | ||
|
||
## Install | ||
|
||
```bash | ||
npm install --save react-shepherd | ||
``` | ||
|
||
## Usage | ||
|
||
### Via Provider/Context | ||
|
||
```jsx | ||
import React, { Component, useContext } from "react"; | ||
import { ShepherdTour, ShepherdTourContext } from "react-shepherd"; | ||
import newSteps from "./steps"; | ||
|
||
const tourOptions = { | ||
defaultStepOptions: { | ||
cancelIcon: { | ||
enabled: true, | ||
}, | ||
}, | ||
useModalOverlay: true, | ||
}; | ||
|
||
function Button() { | ||
const tour = useContext(ShepherdTourContext); | ||
|
||
return ( | ||
<button className="button dark" onClick={tour.start}> | ||
Start Tour | ||
</button> | ||
); | ||
} | ||
|
||
export default function App() { | ||
return ( | ||
<div> | ||
<ShepherdTour steps={newSteps} tourOptions={tourOptions}> | ||
<Button /> | ||
</ShepherdTour> | ||
</div> | ||
); | ||
} | ||
``` | ||
|
||
### Via Hook | ||
|
||
```jsx | ||
import React, { Component } from "react"; | ||
import { useShepherdTour } from "react-shepherd"; | ||
import newSteps from "./steps"; | ||
|
||
const tourOptions = { | ||
defaultStepOptions: { | ||
cancelIcon: { | ||
enabled: true, | ||
}, | ||
}, | ||
useModalOverlay: true, | ||
}; | ||
|
||
export default function App() { | ||
const tour = useShepherdTour({ tourOptions, steps: newSteps }); | ||
|
||
return ( | ||
<button class="button dark" onClick={tour.start}> | ||
Start Tour | ||
</button> | ||
); | ||
} | ||
``` | ||
|
||
## Configuration | ||
|
||
The following configuration options for a tour can be set on the ShepherdTour to control the way that Shepherd is used. This is simply a POJO passed to Shepherd to use the options noted in the Shepherd Tour [options](https://shepherdjs.dev/docs/Tour.html). | ||
**The only required option is `steps`, which is an array passed to the props.** | ||
|
||
### tourOptions | ||
|
||
`PropTypes.object` | ||
Used to set the options that will be applied to each step by default. You can pass in any of the options that you can with Shepherd. | ||
|
||
### steps | ||
|
||
`PropTypes.array` | ||
You must pass an array of steps to `steps`, something like this: | ||
|
||
```js | ||
const steps = [ | ||
{ | ||
id: 'intro', | ||
attachTo: { element: '.first-element', on: 'bottom' }, | ||
beforeShowPromise: function () { | ||
return new Promise(function (resolve) { | ||
setTimeout(function () { | ||
window.scrollTo(0, 0); | ||
resolve(); | ||
}, 500); | ||
}); | ||
}, | ||
buttons: [ | ||
{ | ||
classes: 'shepherd-button-secondary', | ||
text: 'Exit', | ||
type: 'cancel' | ||
}, | ||
{ | ||
classes: 'shepherd-button-primary', | ||
text: 'Back', | ||
type: 'back' | ||
}, | ||
{ | ||
classes: 'shepherd-button-primary', | ||
text: 'Next', | ||
type: 'next' | ||
} | ||
], | ||
classes: 'custom-class-name-1 custom-class-name-2', | ||
highlightClass: 'highlight', | ||
scrollTo: false, | ||
cancelIcon: { | ||
enabled: true, | ||
}, | ||
title: 'Welcome to React-Shepherd!', | ||
text: ['React-Shepherd is a JavaScript library for guiding users through your React app.'], | ||
when: { | ||
show: () => { | ||
console.log('show step'); | ||
}, | ||
hide: () => { | ||
console.log('hide step'); | ||
} | ||
} | ||
}, | ||
// ... | ||
]; | ||
``` | ||
|
||
## Steps | ||
|
||
The options are the same as Shepherd [options](https://shepherdjs.dev/docs/Step.html). | ||
|
||
## License | ||
|
||
MIT |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters