๐ฏ NFSFU234TourGuide
Plug-and-play React tour guide library โ perfect for onboarding, walkthroughs, and product tours. Lightweight, extensible, and zero heavy dependencies by default.
---
## ๐ Why Use NFSFU234TourGuide?
โ
Interactive onboarding, tooltips & walkthroughs
โก Extremely lightweight โ **~3-4 kB gzipped** (real app contribution, tree-shaken)
๐๏ธ Fully customizable styling (className props + optional Tailwind)
๐ Dark / light / custom theme support
๐ฑ Mobile-aware steps & device-specific content
๐ Clean API + lifecycle callbacks
๐น๏ธ Keyboard navigation (arrows, Enter, Esc)
๐ท Full TypeScript support
๐ฆ Works with React 18+ / 19+
---
## ๐ฆ Installation
```bash
npm install nfsfu234-tour-guide
# or
yarn add nfsfu234-tour-guide
# or
pnpm add nfsfu234-tour-guide
```
Only **React** and **React DOM** are required as peer dependencies. Zero other dependencies.
---
## ๐งช Quick Example
```tsx
'use client';
import { Tour } from 'nfsfu234-tour-guide';
const steps = [
{
target: '#hero',
content: 'This is the hero section!',
position: 'bottom',
device: 'both',
},
{
target: '#cta',
content: 'Click here to get started.',
contentMobile: 'Tap to get started.',
position: 'top',
device: 'both',
},
];
export default function MyComponent() {
return (
console.log('Tour started')}
onStepChange={(step) => console.log(`Step ${step + 1}`)}
onSkip={() => console.log('Skipped')}
onComplete={() => console.log('Completed')}
/>
Call to Action
);
}
```
> **Note**: Make sure target elements (`#hero`, etc.) exist in the DOM when the tour starts.
---
## ๐ง Props Reference
| Prop | Type | Description | Default |
|---------------------|------------------------------------|--------------------------------------------------|---------------|
| `tourId` | `string` | Unique tour identifier | `'tour-guide'`|
| `steps` | `TourStep[]` | Array of tour steps (required) | โ |
| `isActive` | `boolean` | Show/hide the tour | `true` |
| `theme` | `'light' \| 'dark' \| 'custom'` | Visual theme | `'dark'` |
| `customTheme` | `ThemeConfig` | Full color override (use with `theme="custom"`) | โ |
| `accentColor` | `string` | Color for progress bar, buttons, highlights | `'#10b981'` |
| `welcomeScreen` | `WelcomeScreenConfig` | Optional intro screen | `{ enabled: false }` |
| `buttonLabels` | `ButtonLabels` | Customize button text | English defaults |
| `showProgress` | `boolean` | Show progress bar | `true` |
| `showBranding` | `boolean` | Show "Built with NFSFU234TourGuide" badge on the welcome screen | `true` |
| `className` | `string` | Class for root overlay | โ |
| `overlayClassName` | `string` | Class for backdrop | โ |
| `tooltipClassName` | `string` | Class for tooltip/welcome box | โ |
| `highlightClassName`| `string` | Class for highlighted elements | `'nfsfu234-tour-highlight'` |
| `onStart` | `() => void` | Fires when tour starts | โ |
| `onStepChange` | `(index: number) => void` | Fires on every step change | โ |
| `onSkip` | `() => void` | Fires when user skips | โ |
| `onComplete` | `() => void` | Fires when tour finishes | โ |
---
## ๐งฉ TourStep Interface
| Property | Type | Description |
|-----------------|-------------------------------------------|---------------------------------------------|
| `target` | `string` | CSS selector (e.g. `'#hero'`, `'.sidebar'`) |
| `content` | `string` | Main tooltip text |
| `contentMobile` | `string?` | Mobile-specific text (optional) |
| `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | Tooltip placement (auto-flips if no space) |
| `offset` | `{ x?: number; y?: number }` | Pixel offset from target |
| `device` | `'desktop' \| 'mobile' \| 'both'` | Show step on specific devices only |
---
## ๐จ ThemeConfig Interface
Pass this to `customTheme` when `theme="custom"`:
| Property | Type | Description |
|-----------------|----------|---------------------------------------|
| `backdrop` | `string` | Overlay background color |
| `tooltipBg` | `string` | Tooltip background color |
| `tooltipText` | `string` | Tooltip text color |
| `tooltipBorder` | `string` | Tooltip border color |
| `buttonBg` | `string` | Secondary button background |
| `buttonText` | `string` | Secondary button text color |
| `progressBar` | `string` | Progress bar track color |
| `highlightRing` | `string` | Glow ring color around target element |
```tsx
