Reusable, Next.js-friendly walkthrough overlay that highlights elements, locks the UI behind an animated blur, and guides users through multi-page onboarding steps.
npm install @coledon/cld-walkthroughautoStart flag.
emitWalkthroughStart helper included).
bash
npm install cld-walkthrough
or
yarn add cld-walkthrough
`
Until the package is published you can add it to a Next.js project via a local path (e.g. using npm link or workspace:).
---
Quick Start
1. Create your steps JSON
`jsonc
// walkthrough-steps.json
{
"steps": [
{
"stepCategory": "Getting Started",
"pageUrl": "/settings/global",
"stepName": "Open Global Settings",
"stepDescription": "Configure global branding and defaults.",
"highlightElement": "global-settings-tab",
"tooltipPosition": "right"
}
]
}
`
2. Add data-highlight attributes
`tsx
General
`
3. Render the component
`tsx
import stepsJson from "./walkthrough-steps.json";
import { Walkthrough } from "cld-walkthrough";
export default function AppLayout({ children }: { children: React.ReactNode }) {
return (
<>
{children}
steps={stepsJson.steps}
autoStart={!!session.user?.first_login}
dismissedStorageKey={walkthrough-${session.user?.id}}
/>
>
);
}
`
4. Restart on demand
`tsx
import { emitWalkthroughStart } from "cld-walkthrough";
const handleClick = () => emitWalkthroughStart(0); // optional start index
`
5. Import the styles (one time)
`tsx
import "cld-walkthrough/dist/styles/walkthrough.css";
`
---
Props
| Prop | Type | Description |
| --- | --- | --- |
| steps | WalkthroughStep[] | Required list of steps. |
| autoStart | boolean | Automatically show the walkthrough when the component mounts (skipped if previously dismissed). |
| initialStep | number | Optional starting index (default 0). |
| dismissedStorageKey | string | Local-storage key used to remember dismissal (cld-walkthrough-dismissed by default). |
| startEventName | string | Custom DOM event name for programmatic restarts (cld-walkthrough:start by default). |
| onDismiss | () => void | Called when the user clicks “Dismiss” or reaches the final step. |
| onStepChange | (index, step) => void | Called whenever the active step changes. |
---
Step Schema
`ts
type WalkthroughTooltipPosition = "top" | "right" | "bottom" | "left";
interface WalkthroughStep {
stepCategory: string;
pageUrl: string;
stepName: string;
stepDescription: string;
highlightElement: string; // matches data-highlight attribute
tooltipPosition: WalkthroughTooltipPosition;
}
`
---
Additional Tips
- The overlay locks pointer events to ensure users can only interact via the tooltip controls.
- Each step’s pageUrl should match the Next.js route (including critical query params). The walkthrough automatically advances when the URL matches the next step.
- When building long forms, wrap the target element in a div with a distinct background so the cloned highlight looks consistent.
- Use emitWalkthroughStart(stepIndex) anywhere (e.g., help menus) to replay the guide.
---
Local Development
1. npm install
2. npm run build – type-checks and emits dist/.
3. Link the package into another app (npm link ../cld-walkthrough`) to verify the integration.