Next-page-wizard NPM

next-page-wizard

A lightweight and intuitive Next.js package for managing multi-step navigation in wizard-style applications.
With next-page-wizard, you can define a sequence of pages and seamlessly navigate between them using simple hooks and methods.

This package is ideal for form wizards, onboarding flows, or any scenario where users progress through a predefined set of pages.
It provides an easy way to control navigation state, track progress, and manage page transitions dynamically.

Installation
Usage
Typehint
Methods
Contributing
License

Installation

Install the package using npm:

npm install next-page-wizard

Or with yarn:

yarn add next-page-wizard

Usage

Step 1: Wrap your code in the `PageWizardProvider`

"use client";

import { PageWizardProvider } from "next-page-wizard";

export default function Providers({ children }: Readonly<React.ReactNode>) {
  return <PageWizardProvider>{children}</PageWizardProvider>;
}

Step 2: Call the `setSitemap` method passing in an array of strings (the pages - they must be already created)

"use client";

import usePageWizard from "~/hooks/usePageWizard";
import { useEffect } from "react";

const pages = ["/", "/page1", "/page2", "/page3"] as const;

export default function Home() {
  const { setSitemap, goToNextPage } = usePageWizard();

  useEffect(() => {
    setSitemap(pages);
  }, []);

  return (
    <main>
      <h1>Welcome to the Wizard</h1>
      <button onClick={() => goToNextPage()}>Next Page</button>
    </main>
  );
}

Explanation:

Sets the sitemap on mount using setSitemap(pages).
Uses goToNextPage when the button is clicked to navigate to the next page in the sitemap.

Typehint

To enable page hinting when using the methods, you need to make the array of pages readonly and add the typeof that array as a generic parameter when calling usePageWizard.

"use client";

import usePageWizard from "next-page-wizard";
import { useEffect } from "react";

const pages = ["/", "/page1", "/page2", "/page3"] as const;
type TPages = typeof pages;

export default function Home() {
  const { setSitemap, goToNextPage } = usePageWizard<TPages>();

  useEffect(() => {
    setSitemap(pages);
  }, []);

  return (
    <main>
      <h1>Welcome to the Wizard</h1>
      <button onClick={() => goToNextPage()}>Next Page</button>
    </main>
  );
}

Methods

The usePageWizard hook provides the following methods:

Method	Description
`goToPage(page: "" \\| T[number], query?: Record<string, string>): void`	Navigates to a specific page.
`goToNextPage(query?: Record<string, string>): void`	Navigates to the next page in the sitemap.
`goToPrevPage(): void`	Navigates to the previous page in the sitemap.
`goToFirstPage(): void`	Navigates to the first page in the sitemap.
`currentPageIndex: number`	The index of the current page in the sitemap.
`isFirstPage: boolean`	Whether the current page is the first page.
`isLastPage: boolean`	Whether the current page is the last page.
`nextPage: "" \\| T[number]`	The path to the next page in the sitemap.
`sitemap: readonly string[]`	The array of page paths in the sitemap.
`setSitemap(newSitemap: readonly string[]): void`	Sets the sitemap to a new array of page paths.
`replacePage(oldPage: T[number], newPage: string): void`	Replaces a page in the sitemap with a new page.
`removePage(page: T[number]): void`	Removes a page from the sitemap.
`addPage(newPage: string, index?: number): void`	Adds a new page to the sitemap at a specified index.