React Tour Guide Ukey

A modern, customizable React-based onboarding/tour library with smooth animations and flexible configuration options. Perfect for creating interactive product tours, feature walkthroughs, and onboarding experiences.

Features

• 🎯 Step-by-step guided tours
• 🎨 Customizable themes and styles
• ⌨️ Keyboard navigation support
• 🎭 Smooth animations with Framer Motion
• 📱 Responsive design
• 🎯 Smart positioning with Floating UI
• 🔍 Auto-scroll to target elements
• 🌐 Internationalization support
• 🎨 Customizable UI components
• 📦 Zero dependencies (except peer dependencies)

Installation

npm install react-tour-guide-ukey
# or
yarn add react-tour-guide-ukey

Quick Start

import { Tour } from 'react-tour-guide-ukey';

const steps = [
  {
    target: '#first-element',
    title: 'Welcome!',
    content: 'This is the first step of the tour.',
    placement: 'bottom',
  },
  {
    target: '#second-element',
    title: 'Features',
    content: 'Check out these amazing features!',
    placement: 'right',
  },
];

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>Start Tour</button>
      
      <Tour
        steps={steps}
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        onFinish={() => setIsOpen(false)}
      />
    </div>
  );
}

Props

Tour Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | steps | Step[] | required | Array of tour steps | | isOpen | boolean | false | Controls tour visibility | | onClose | () => void | - | Called when tour is closed | | onFinish | () => void | - | Called when tour is completed | | onSkip | () => void | - | Called when tour is skipped | | onStepChange | (stepIndex: number) => void | - | Called when step changes | | showSkipButton | boolean | true | Show skip button | | showBackButton | boolean | true | Show back button | | showNavigation | boolean | true | Show navigation buttons | | showProgress | boolean | true | Show progress indicator | | showNumber | boolean | true | Show step numbers | | disableKeyboardNavigation | boolean | false | Disable keyboard navigation | | disableOverlayClose | boolean | false | Disable closing on overlay click | | disableOverlay | boolean | false | Disable overlay | | disableScrolling | boolean | false | Disable auto-scrolling | | scrollOffset | number | 0 | Offset for auto-scrolling | | scrollDuration | number | 300 | Duration of scroll animation | | spotlightClicks | boolean | false | Allow clicks in spotlight | | spotlightPadding | number | 0 | Padding around spotlight | | styles | object | defaultStyles | Custom styles | | locale | object | defaultLocale | Custom translations |

Step Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | target | string | HTMLElement | required | Target element selector or element | | title | ReactNode | - | Step title | | content | ReactNode | required | Step content | | placement | Placement | 'bottom' | Tooltip placement | | disableBeacon | boolean | false | Disable beacon | | spotlightPadding | number | 0 | Padding around spotlight | | spotlightClicks | boolean | false | Allow clicks in spotlight | | styles | object | - | Step-specific styles |

Styling

You can customize the appearance of the tour using the styles prop:

const customStyles = {
  options: {
    zIndex: 1000,
    backgroundColor: '#ffffff',
    overlayColor: 'rgba(0, 0, 0, 0.5)',
    textColor: '#333333',
    primaryColor: '#007bff',
    arrowColor: '#ffffff',
  },
};

<Tour
  steps={steps}
  styles={customStyles}
  // ... other props
/>

Internationalization

You can customize the button text using the locale prop:

const customLocale = {
  back: 'Zurück',
  close: 'Schließen',
  last: 'Fertig',
  next: 'Weiter',
  skip: 'Überspringen',
};

<Tour
  steps={steps}
  locale={customLocale}
  // ... other props
/>

Keyboard Navigation

The tour supports keyboard navigation:

• Esc - Close the tour
• Arrow Right - Next step
• Arrow Left - Previous step
• Space - Next step
• Enter - Next step

Examples

Check out the example directory for a complete working example of the tour library.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © mrunmay-24-ukey