react-custom-tours/README.md

A library with tips that you can attach to blocks on your sites so that users can more easily understand how to use your site

# React-custom-tours 👩‍🏫🆘🔖

🪲 We recommend installing version starting from 1.7.0 <br>
🎉 A library for creating step-by-step hints in your applications ([Click to open in npm](https://www.npmjs.com/package/react-custom-tours))<br>
🧪 Tested on projects in production <br>
🔧 Before each update, the library is checked by autotests <br>
⭐ I would be grateful if you put a star on the [GitHub repo](https://github.com/kdubasov/react-tours)

### Preview GIF 📹:

![ScreenRecording2024-07-21at1 49 43PM-ezgif com-video-to-gif-converter](https://github.com/user-attachments/assets/4af0b92a-922b-4903-ac29-1bbeee428476)

### Custom themes 🌗:

![Screenshot 2024-07-21 at 1 48 34 PM](https://github.com/user-attachments/assets/6219edf6-72b1-4224-ad01-b7cfcab67926)
![Screenshot 2024-07-21 at 1 47 54 PM](https://github.com/user-attachments/assets/7976574a-3a0c-470c-a8a0-f4354c7ab4ec)

### Custom colors 💅:

![Screenshot 2024-07-21 at 1 49 16 PM](https://github.com/user-attachments/assets/61d4318f-13a2-4473-8dd9-a8cec97d0160)

## Installation 🔥:

`npm install react-custom-tours`
`pnpm install react-custom-tours`
`yarn add react-custom-tours`

## Features 💫:

- Easy to install in any application (installation time up to 10 minutes);
- Full customization;
- Light/dark mode support out of the box;
- Adaptable to all screen sizes;
- Keyboard control support;
- Animations and smoothness out of the box;
- Can be connected to any components. Also, modal windows with closing on the mousedown event will work, since this event has a stopPropagation listener;

## The gist 👩‍💻:

```javascript
import React from 'react';
import { TipsProvider, useTips } from 'react-custom-tours/dist/app/main';

function App() {
  const { setShow } = useTips(); // you should use this hook inside the provider

  // you can start showing tooltips when rendering the component, or add playback conditions
  // useEffect(() => {
  //     setShow(true);
  // }, []);

  return (
    <div>
      {/* click this button to start a tour */}
      <button onClick={() => setShow(true)}>Show tips!</button>
      <div id="tip-block">
        <h3>First block with tip!</h3>
      </div>

      <p id="tip-text">Text with tip!</p>
    </div>
  );
}

function Main() {
  <TipsProvider
    tips={[
      {
        idx: 1, // decent number of tip playback
        nodeId: 'tip-block', // block with tip id
        title: 'First block tip title!', // tip title (optional key)
        text: 'First block tip text!', // tip text
      },
      {
        idx: 2,
        nodeId: 'tip-text',
        text: 'Text block tip text!',
        maxWidth: 400, // max width of tooltip (in pixels)
        onClick: {
          // handlers for tooltip buttons
          nextButton: async () => {
            await new Promise((resolve) => setTimeout(resolve, 2000));
          }, // callback can be as promise and next step start after resolve
          prevButton: () => console.log('prev'),
          closeButton: () => console.log('close'),
        },
      },
    ]}
    theme="dark" // light is default (optional)
    customColors={{
      // custom tooltip colors for dark/light themes
      dark: {
        primary: '#0dcaf0',
        textPrimary: '#ffffff',
        bgPrimary: '#808080',
        layoutPrimary: 'rgba(9, 12, 23, .25)',
      },
      light: {
        primary: 'rgb(21,194,30)',
        textPrimary: '#808080',
        bgPrimary: '#ffffff',
        layoutPrimary: 'rgba(9, 12, 23, .25)',
      },
    }}
    highlightPadding={10} // padding for highlighting current block
    escapeToClose // adding closing tour using escape keydown (optional)
    isHiddenClose // hide the close tour button until the last step (optional, default = false) (added in v1.3.8)
  >
    <App />
  </TipsProvider>;
}
```

## Projects that use this library 👍:

- [Merlin Clone](https://merlinclone.com/ru)
- [Quick Offer](https://quick-offer.ru)