🔦 React Torchlight

---

✨ Features

- 🎯 Type-Safe Tour IDs - Auto-generated TypeScript types for your tour IDs
- 🎨 Customizable Styling - Full control over appearance with CSS variables and custom props
- ♿ Accessibility First - Built with WCAG guidelines in mind, keyboard navigation included
- 🔧 Developer Experience - Vite and TypeScript plugins for seamless integration
- 🎭 Flexible Positioning - Smart tooltip positioning that adapts to screen boundaries
- ⚡ Performance Optimized - Minimal bundle size with tree-shaking support

📦 Installation

``bash


npm

`tsx
import "react-torchlight/css/styles.css";
`

🚀 Quick Start

$3

`tsx
import React from "react";
import { TorchlightProvider } from "react-torchlight";
import "react-torchlight/css/styles.css";

function App() {
return (



);
}
`

$3

`tsx
import React from "react";
import { useTorchlightSteps } from "react-torchlight";

function Dashboard() {
// Define your tour steps with type safety
const refs = useTorchlightSteps("dashboard-tour", [
{
id: "welcome-message",
order: 1,
title: "Welcome!",
content: "This is your dashboard where you can see all your data.",
placement: "bottom",
},
{
id: "user-profile",
order: 2,
title: "Your Profile",
content: "Click here to edit your profile information.",
placement: "left",
},
{
id: "settings-menu",
order: 3,
title: "Settings",
content: "Access all your preferences from here.",
placement: "bottom",
},
]);

return (


`tsx
import React from "react";
import { useTorchlight } from "react-torchlight";

function StartTourButton() {
const { startTour } = useTorchlight();

return (
startTour("dashboard-tour")}>
Start Dashboard Tour

);
}
`

🔧 Setup with Vite (Recommended)

For the best developer experience with auto-generated TypeScript types:

$3

`bash
npm install --save-dev react-torchlight
`

$3

`ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { torchlightVitePlugin } from "react-torchlight/plugins/vite";

export default defineConfig({
plugins: [
react(),
torchlightVitePlugin({
rootFolder: "src",
outputPath: "torchlight.gen.ts",
}),
],
});
`

$3

`ts
// This enables type safety for your tour IDs
import "./torchlight.gen";
`

Now you'll get TypeScript autocomplete and validation for all your tour IDs! 🎉

📖 API Reference

$3

####

The main provider component that manages tour state.

`tsx
config={{
locale: {
nextButtonText: "Next",
prevButtonText: "Previous",
skipButtonText: "Skip",
doneButtonText: "Finish",
},
}}
overlayProps={{
overlayColor: "#000000",
overlayOpacity: 0.7,
highlightPadding: 8,
borderRadius: 8,
animationDuration: 300,
}}
>
{children}

`

$3

#### useTorchlight()

Access tour control functions.

`tsx
const {
tours, // Map of all registered tours
activeTour, // Currently active tour ID
startTour, // Start a tour by ID
stopTour, // Stop a tour by ID
nextStep, // Go to next step
prevStep, // Go to previous step
goToStep, // Jump to specific step
} = useTorchlight();
`

#### useTorchlightSteps(tourId, steps)

Register tour steps and get element refs.

`tsx
const refs = useTorchlightSteps("my-tour", [
{
id: "step-1",
order: 1,
title: "Step Title",
content: "Step description",
placement: "bottom", // 'top' | 'bottom' | 'left' | 'right'
},
]);

// Use the refs


`css
:root {
--torchlight-overlay-color: #000000;
--torchlight-overlay-opacity: 0.7;
--torchlight-highlight-border: #3b82f6;
--torchlight-tooltip-bg: #ffffff;
--torchlight-tooltip-text: #1f2937;
--torchlight-border-radius: 8px;
}
`

$3

`tsx
overlayProps={{
className: 'my-custom-overlay',
overlayColor: '#1a202c',
overlayOpacity: 0.8,
highlightPadding: 12,
borderRadius: 12,
animationDuration: 400,
showTooltip: true,
tooltipClassName: 'my-custom-tooltip'
}}
>
`

🌟 Examples

$3

`tsx
function BasicExample() {
const { startTour } = useTorchlight();
const refs = useTorchlightSteps("intro-tour", [
{
id: "header",
order: 1,
title: "Main Header",
content: "This is the main navigation area.",
placement: "bottom",
},
{
id: "sidebar",
order: 2,
title: "Sidebar",
content: "Use this sidebar to navigate between sections.",
placement: "right",
},
]);

return (


`tsx
function OnboardingFlow() {
const { startTour, activeTour, stopTour } = useTorchlight();

const welcomeRefs = useTorchlightSteps("welcome-tour", [
{
id: "welcome",
order: 1,
title: "Welcome! 👋",
content: "Let's get you started with a quick tour.",
placement: "bottom",
},
]);

const featureRefs = useTorchlightSteps("features-tour", [
{
id: "feature-1",
order: 1,
title: "Feature One",
content: "This is an amazing feature you'll love!",
placement: "right",
},
{
id: "feature-2",
order: 2,
title: "Feature Two",
content: "And this one will save you tons of time.",
placement: "left",
},
]);

const handleStartOnboarding = () => {
startTour("welcome-tour");
// You can chain tours or use tour completion callbacks
};

return (


- Escape - Exit current tour
- Arrow Right or Space - Next step
- Arrow Left - Previous step

🛠️ Development

$3

- ✅ Vite - Full plugin support with auto-generated types
- ✅ TypeScript - Built-in TypeScript plugin
- ✅ Webpack - Works out of the box
- ✅ Next.js - Compatible with SSR

$3

The library provides excellent TypeScript support with auto-generated types for your tour IDs when using the Vite plugin.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

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

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

- Inspired by the need for better user onboarding experiences
- Built with modern React patterns and TypeScript best practices
- Thanks to all contributors who help make this library better

---