🎯 React First Steps

A beautiful, lightweight, and fully customizable onboarding tour library for React and Next.js applications.

Create stunning product tours and user guides with zero configuration. Perfect for onboarding new users, showcasing features, or providing guided tutorials.

✨ Features

🎨 Fully Customizable - Style every element to match your brand
🎯 Smart Positioning - Automatically finds the best tooltip placement
📱 Responsive - Works flawlessly on all screen sizes
⚡ Lightweight - Under 10KB gzipped, zero dependencies
🔧 TypeScript - Full type safety and IntelliSense support
🌙 Theme Support - Pre-built themes included (dark, modern, minimal, colorful)
🎭 Spotlight Effect - Beautiful element highlighting with overlay
🔄 Auto-scroll - Automatically scrolls to highlighted elements
💫 Smooth Animations - Buttery smooth transitions
🚫 Smart Placement - Tooltips never cover highlighted elements
🎮 Full Control - Programmatic API for complete control

📦 Installation

npm install rc-first-steps

yarn add rc-first-steps

pnpm add rc-first-steps

🚀 Quick Start

import { OnboardingProvider } from 'rc-first-steps';

function App() {
  const config = {
    steps: [
      {
        target: '#welcome',
        title: 'Welcome! 👋',
        content: 'Let me show you around our platform',
        placement: 'bottom',
      },
      {
        target: '#dashboard',
        title: 'Your Dashboard',
        content: 'This is where all the magic happens',
        placement: 'right',
      },
    ],
    showProgress: true,
    showSkipButton: true,
  };

  return (
    <OnboardingProvider 
      config={config} 
      run={true}
      onComplete={() => console.log('Tour completed!')}
    >
      <YourApp />
    </OnboardingProvider>
  );
}

📖 Complete Documentation

Basic Setup

1. Wrap Your Application

import { OnboardingProvider } from 'rc-first-steps';

function App() {
  return (
    <OnboardingProvider config={config} run={shouldRun}>
      <YourApp />
    </OnboardingProvider>
  );
}

2. Define Tour Steps

const config = {
  steps: [
    {
      target: '#element-id',           // CSS selector
      title: 'Step Title',
      content: 'Step description here',
      placement: 'bottom',              // 'top' | 'bottom' | 'left' | 'right' | 'auto'
      spotlightClicks: false,           // Allow clicks on highlighted element
    },
    // Add more steps...
  ],
  showProgress: true,                   // Show "Step 1 of 3"
  showSkipButton: true,                 // Show skip button
  scrollToSteps: true,                  // Auto-scroll to elements
  scrollOffset: 100,                    // Scroll offset in pixels
  spotlightPadding: 8,                  // Padding around spotlight
};

3. Control the Tour Programmatically

import { useOnboarding } from 'rc-first-steps';

function MyComponent() {
  const { start, stop, next, back, isActive } = useOnboarding();
  
  return (
    <div>
      <button onClick={start}>Start Tour</button>
      <button onClick={stop}>Stop Tour</button>
      <button onClick={next}>Next Step</button>
      <button onClick={back}>Previous Step</button>
    </div>
  );
}

🎨 Customization

Custom Styling

const config = {
  steps: [...],
  styles: {
    // Customize the spotlight
    spotlight: {
      borderRadius: '16px',
      border: '3px solid #3b82f6',
      boxShadow: '0 0 0 9999px rgba(0, 0, 0, 0.8)',
    },
    // Customize the tooltip container
    tooltip: {
      filter: 'drop-shadow(0 10px 40px rgba(0, 0, 0, 0.3))',
    },
    // Customize Next button
    buttonNext: {
      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      padding: '12px 28px',
      fontSize: '16px',
      fontWeight: '600',
      borderRadius: '10px',
    },
    // Customize Back button
    buttonBack: {
      background: '#f3f4f6',
      border: '2px solid #e5e7eb',
      color: '#374151',
    },
    // Customize Skip button
    buttonSkip: {
      color: '#ef4444',
      fontWeight: '600',
    },
  },
};

Using Pre-built Themes

import { OnboardingProvider, darkTheme } from 'rc-first-steps';

const config = {
  steps: [...],
  ...darkTheme, // Apply dark theme
};

// Available themes:
// - darkTheme
// - modernTheme
// - minimalTheme
// - colorfulTheme

🎯 Advanced Usage

Conditional Tour Display

function App() {
  const [showTour, setShowTour] = useState(() => {
    // Only show to new users
    return !localStorage.getItem('tourCompleted');
  });

  const handleComplete = () => {
    localStorage.setItem('tourCompleted', 'true');
    setShowTour(false);
  };

  return (
    <OnboardingProvider
      config={config}
      run={showTour}
      onComplete={handleComplete}
    >
      <YourApp />
    </OnboardingProvider>
  );
}

Multi-page Tours

// Page 1
const step1Config = {
  steps: [
    { target: '#feature-1', title: 'Feature 1', content: 'Description' },
  ],
};

// Page 2
const step2Config = {
  steps: [
    { target: '#feature-2', title: 'Feature 2', content: 'Description' },
  ],
};

// Use different configs on different pages

Dynamic Steps

function App() {
  const [userType, setUserType] = useState('beginner');
  
  const config = {
    steps: userType === 'beginner' 
      ? beginnerSteps 
      : advancedSteps,
  };

  return <OnboardingProvider config={config} />;
}

🔧 API Reference

`OnboardingProvider` Props

Prop	Type	Default	Description
`config`	`OnboardingConfig`	required	Tour configuration object
`run`	`boolean`	`false`	Start/stop the tour
`onComplete`	`() => void`	-	Callback when tour completes
`onSkip`	`() => void`	-	Callback when tour is skipped
`children`	`ReactNode`	required	Your app components

`OnboardingConfig` Object

Property	Type	Default	Description
`steps`	`OnboardingStep[]`	required	Array of tour steps
`showProgress`	`boolean`	`false`	Show step counter
`showSkipButton`	`boolean`	`false`	Show skip button
`scrollToSteps`	`boolean`	`false`	Auto-scroll to elements
`scrollOffset`	`number`	`100`	Scroll offset in pixels
`spotlightPadding`	`number`	`8`	Padding around spotlight
`disableOverlay`	`boolean`	`false`	Disable dark overlay
`styles`	`StyleConfig`	`{}`	Custom styles object

`OnboardingStep` Object

Property	Type	Default	Description
`target`	`string`	required	CSS selector (#id, .class, [data-attr])
`title`	`string`	required	Step title
`content`	`string`	required	Step description
`placement`	`'top' \| 'bottom' \| 'left' \| 'right' \| 'auto'`	`'auto'`	Tooltip position
`spotlightClicks`	`boolean`	`false`	Allow clicks on element during tour

`useOnboarding` Hook

const {
  isActive,      // boolean - Is tour currently running
  currentStep,   // number - Current step index (0-based)
  start,         // () => void - Start the tour
  stop,          // () => void - Stop the tour
  next,          // () => void - Go to next step
  back,          // () => void - Go to previous step
  goToStep,      // (step: number) => void - Jump to specific step
} = useOnboarding();

🌟 Examples

Next.js App Router

// app/layout.tsx
import { OnboardingProvider } from 'rc-first-steps';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <OnboardingProvider config={config} run={true}>
          {children}
        </OnboardingProvider>
      </body>
    </html>
  );
}

Next.js Pages Router

// pages/_app.tsx
import { OnboardingProvider } from 'rc-first-steps';

function MyApp({ Component, pageProps }) {
  return (
    <OnboardingProvider config={config}>
      <Component {...pageProps} />
    </OnboardingProvider>
  );
}

Vite + React

// src/main.tsx
import { OnboardingProvider } from 'rc-first-steps';

createRoot(document.getElementById('root')).render(
  <OnboardingProvider config={config}>
    <App />
  </OnboardingProvider>
);

💡 Best Practices

Keep Tours Short - 3-5 steps is ideal for user retention
Use Descriptive Titles - Make it clear what each step teaches
Auto-placement - Use placement: 'auto' for best results
Save Completion State - Don't annoy returning users
Test on Mobile - Ensure responsive design works everywhere
Use Semantic Selectors - Prefer IDs over generic classes
Provide Skip Option - Always allow users to exit
Track Analytics - Monitor tour completion rates

🎓 Tips & Tricks

Restart Tour

function RestartButton() {
  const { start } = useOnboarding();
  
  return <button onClick={start}>Restart Tour</button>;
}

Conditional Steps

const steps = features.map(feature => ({
  target: `#${feature.id}`,
  title: feature.name,
  content: feature.description,
}));

Track Analytics

<OnboardingProvider
  config={config}
  onComplete={() => {
    analytics.track('Onboarding Completed');
  }}
  onSkip={() => {
    analytics.track('Onboarding Skipped');
  }}
/>

🐛 Troubleshooting

Element Not Found

// Make sure element exists before starting tour
useEffect(() => {
  const element = document.querySelector('#my-element');
  if (element) {
    setRunTour(true);
  }
}, []);

Tooltip Behind Modal

// Increase z-index in styles
styles: {
  tooltip: {
    zIndex: 10000,
  }
}

Tour Not Starting

// Check that run prop is true
<OnboardingProvider config={config} run={true} />

// Or use the hook
const { start } = useOnboarding();
start();

📊 Browser Support

✅ Chrome (latest)
✅ Firefox (latest)
✅ Safari (latest)
✅ Edge (latest)
✅ Mobile browsers (iOS Safari, Chrome Mobile)

🔒 TypeScript Support

Full TypeScript support out of the box with complete type definitions.

import type { OnboardingConfig, OnboardingStep } from 'rc-first-steps';

const steps: OnboardingStep[] = [
  {
    target: '#welcome',
    title: 'Welcome',
    content: 'Get started here',
    placement: 'bottom',
  }, 
];

const config: OnboardingConfig = {
  steps,
  showProgress: true,
};

📄 License

MIT License

Copyright (c) 2025 Ossama KHARBAQ

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Built with ❤️ for the React community

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
src		src
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
demo.gif		demo.gif
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🎯 React First Steps

✨ Features

📦 Installation

🚀 Quick Start

📖 Complete Documentation

Basic Setup

1. Wrap Your Application

2. Define Tour Steps

3. Control the Tour Programmatically

🎨 Customization

Custom Styling

Using Pre-built Themes

🎯 Advanced Usage

Conditional Tour Display

Multi-page Tours

Dynamic Steps

🔧 API Reference

OnboardingProvider Props

OnboardingConfig Object

OnboardingStep Object

useOnboarding Hook

🌟 Examples

Next.js App Router

Next.js Pages Router

Vite + React

💡 Best Practices

🎓 Tips & Tricks

Restart Tour

Conditional Steps

Track Analytics

🐛 Troubleshooting

Element Not Found

Tooltip Behind Modal

Tour Not Starting

📊 Browser Support

🔒 TypeScript Support

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`OnboardingProvider` Props

`OnboardingConfig` Object

`OnboardingStep` Object

`useOnboarding` Hook

Packages