A simple and highly customizable walkthrough library which can be used in your react apps to guide users through your website
npm install trail-jstrail-js is a lightweight, highly-customizable, and feature-rich walkthrough library for React apps. It allows developers to guide users through product features using interactive steps, tooltips, and navigation logic.
canGoNext validations for conditional progression
beforeNext async hooks for side effects
bash
npm install trail-js
or
yarn add trail-js
`
---
🧠 Basic Usage
`tsx
import {
WalkthroughProvider,
Walkthrough,
useWalkthrough,
type WalkthroughStep,
} from "trail-js";
const steps: WalkthroughStep[] = [
{
selector: "#start-button",
content: "Click this button to get started!",
placement: "bottom",
},
{
selector: "#name-input",
content: "Enter your name before continuing.",
placement: "top",
canGoNext: {
validate: () => !!document.getElementById("name-input")?.value,
errorString: "Name is required!",
},
},
];
const App = () => (
);
`
---
🛠️ API Reference
$3
Wrap your app with this provider and pass the list of steps.
`tsx
`
$3
The tooltip and highlight overlay component. Should be placed inside WalkthroughProvider.
`tsx
`
🔁 Step Object (
WalkthroughStep)
`ts
type WalkthroughStep = {
selector: string;
content: string | ReactNode;
placement?: "top" | "bottom" | "left" | "right" | "auto";
triggerEvent?: string;
onEnter?: () => void;
onExit?: () => void;
beforeNext?: () => void | Promise;
canGoNext?: {
validate: () => boolean | Promise;
errorString?: string;
};
showBackdrop?: boolean;
tooltipClassName?: string;
tooltipStyle?: React.CSSProperties;
navButtonClassName?: string;
navButtonStyle?: React.CSSProperties;
customNavigation?: (controls: WalkthroughControls) => ReactNode;
}
`
$3
`ts
type WalkthroughControls = {
next: () => void;
back: () => void;
skip: () => void;
goToStep: (index: number) => void;
};
`
---
$3
Main hook to control walkthrough progression.
#### Returns
| Property | Type | Description |
|------------------|--------------------------|----------------------------------------------|
| steps | WalkthroughStep[] | All defined steps for the current walkthrough |
| currentStepIndex | number | Index of the current active step |
| isActive | boolean | Whether walkthrough is active or not |
| next | () => void | Move to the next step |
| back | () => void | Move to the previous step |
| skip | () => void | Skip and end the walkthrough |
| goToStep | (index: number) => void| Jump to a specific step |
---
Use Cases
- User onboarding flows
- Feature discovery in SaaS apps
- Interactive documentation
- Admin dashboards and tutorials
- Demo mode for products
---
🎯 Examples
$3
`ts
{
selector: "#submit-button",
content: "Click to submit the form",
placement: "right",
}
`
$3
`ts
{
selector: "#email",
content: "Please enter a valid email",
canGoNext: {
validate: () => /\S+@\S+\.\S+/.test(document.getElementById("email")?.value || ""),
errorString: "Valid email required!",
},
}
`
$3
`ts
{
selector: "#next-step",
content: "Custom nav UI",
customNavigation: ({ next, back }) => (
),
}
`
---
🎨 Styling
You can override default styles with CSS classes:
`css
.walkthrough-tooltip {
background: white;
padding: 1rem;
border-radius: 8px;
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.25);
}
.walkthrough-overlay {
background: rgba(0, 0, 0, 0.5);
}
`
Or use tooltipClassName, tooltipStyle, navButtonClassName, and navButtonStyle props per step.
---
🧪 Dev / Example
To run the demo locally:
`bash
npm install
npm run dev
``