Onborda for Next.js: target-based onboarding tours

Onborda's target-based Next.js onboarding model

Onborda solves the problem of explaining a newly rendered application through an interactive onboarding sequence. It is aimed at Next.js teams building an onboarding wizard, product tour, or feature introduction whose steps correspond to controls and content already present in the interface. The library does not create a separate series of full-page slides. Instead, each step points at an element with a CSS selector, and Onborda places its card relative to that element while the rest of the application remains visible beneath an overlay.

That distinction matters for product tours. The user can relate instructions such as "Tour 1, Step 1" to the interface control being explained. A step specifies a `selector`, a preferred `side`, and optional properties for controls and pointer geometry. The target itself remains an ordinary element in the application. Based on the repository layout, the package publishes compiled JavaScript and TypeScript declarations from `dist/`, while `src/` contains the TypeScript implementation.

The intended audience is therefore narrower than users looking for a general React dialog system. Onborda assumes a Next.js application, accepts React content inside its steps, and uses the App Router's `next/navigation` behavior for optional route changes. Its package metadata lists React 18 or newer, Next.js 13 or newer, framer-motion 11 or newer, and `@radix-ui/react-portal` 1.1.1 or newer as peer dependencies.

How Onborda connects steps, routes, and overlays

The central data structure is an array of tours, with each tour containing its own `steps` array. This structure was introduced after v1.2.3, while the original step format remains supported. A tour has a `tour` identifier and a list of step objects, allowing an application to define separate sequences such as an initial introduction and a later feature tour.

Each step contains a `selector` string that matches an element's `id`. For example, a selector of `#onborda-step1` corresponds to a page element declared with `id="onborda-step1"`. The documented positioning values are `top`, `bottom`, `left`, and `right`. Onborda also accepts `icon`, `title`, and React content for the card, plus optional properties including `showControls`, `pointerPadding`, and `pointerRadius`.

Navigation is represented by `nextStep` and `prevStep` in the custom card API. The default card can expose navigation controls when `showControls` is enabled. If navigation must cross application routes, a step can specify `nextRoute` or `prevRoute`. The README states that both routes wait 500ms before setting the next step because the destination application may need time to load. No configurable delay API is documented at version 1.2.5.

The overlay's state is controlled through `Onborda` properties. `showOnborda` determines visibility and defaults to `false`, which allows application code to decide when a tour should appear, including for first-time visitors. `interact` controls whether the onboarding overlay is interactive and also defaults to `false`. The library also accepts `shadowRgb` and `shadowOpacity` for the shaded area surrounding the highlighted target.

Installing Onborda and wrapping a Next.js layout

Install the package with the package manager used by the Next.js project. The README lists npm, pnpm, and Yarn commands, while `package.json` declares `[email protected]` as the repository package manager. The host application must also provide the peer dependencies listed by Onborda.

Use this command when the project uses npm:

npm i onborda

The README's equivalent pnpm command is:

pnpm add onborda

After installation, wrap the application content in `OnbordaProvider` and pass the configured steps to `Onborda`. The README gives this layout-level structure:

<OnbordaProvider>
  <Onborda steps={steps}>
    {children}
  </Onborda>
 </OnbordaProvider>

`children` represents the website or application content. The `steps` value must be populated elsewhere with the tour data described below. Since the README labels this snippet as `layout.tsx`, the provider belongs at a layout level rather than inside each tour target.

Creating the first Onborda tour

A real tour requires both configuration and matching DOM targets. The following is the target shape shown in the README:

<div id="onborda-step1">Onboard Step</div>

The tour configuration groups those steps under a named tour. The README's first entry uses `firsttour`, while a later tour uses `secondtour`:

{
  tour: "firsttour",
  steps: [
    {
      title: "Tour 1, Step 1",
      content: <>First tour, first step</>,
      selector: "#tour1-step1",
      side: "top",
      showControls: true,
      nextRoute: "/foo"
    }
  ]
}

The selector in this configuration is `#tour1-step1`, so the corresponding rendered element needs that exact ID. This is the first integration point to verify because the documented mechanism depends on a CSS selector resolving to the intended element.

For default Tailwind CSS classes to be detected when Onborda is not using a custom component, the README says Tailwind must scan the package's distributed files. Add the documented path to the Tailwind `content` configuration:

const config: Config = {
  content: [
    './node_modules/onborda/dist/**/*.{js,ts,jsx,tsx}'
  ]
}

This step is unnecessary when the project supplies its own card component and its own styling, according to the README.

Replacing Onborda's default card with application UI

Onborda permits a custom card component when the default presentation is too restrictive. This is useful for applications that already use a component library or need their onboarding content to match an existing settings or help interface. The exported props expose the current step, its position, the total number of steps, navigation functions, and a directional arrow.

The documented implementation uses a client component, imports `CardComponentProps` from `onborda`, and accepts the current step, position, total steps, navigation functions, and directional arrow as props.

The README's fuller example renders `step.icon` and `step.title`, includes the current index out of `totalSteps`, displays `step.content`, attaches `prevStep` and `nextStep` to buttons, and renders `arrow`. `currentStep` is described as the index of the current step, while `totalSteps` is the number of steps in the onboarding process. `arrow` is an SVG whose orientation is controlled by the step's `side` property.

This API gives application code control over card layout without changing the target-selection model. It does not, however, document persistence for tour completion, automatic tour startup, analytics callbacks, conditional steps, or asynchronous data loading before a step advances.

Route delay and selector coupling limit some applications

The clearest limitation is route timing. Onborda's `nextRoute` and `prevRoute` properties use `next/navigation`, but the README states that each waits 500ms before setting the next step. The documentation explicitly says a function to control this delay is planned, which means applications with slower loading behavior cannot adjust it through the documented v1.2.5 API. The delay may also add a fixed wait to applications that render immediately.

Selector-based positioning also couples tour configuration to the DOM. A route must expose an element with the expected `id` when its step becomes active. Renaming an ID, changing a component's render structure, or conditionally removing the target can prevent the documented selector from resolving. The README does not describe retries, missing-target handling, or a fallback card position for this case.

The package is specifically a Next.js component rather than a framework-neutral React library. Its peer dependency floor of Next.js 13 excludes older Next.js applications, while the requirement for framer-motion 11 or newer adds a separate animation package to the host project's dependency set. Portal support also depends on `@radix-ui/react-portal` version 1.1.1 or newer. These requirements make dependency alignment an adoption check rather than an implementation detail.

Comparing Onborda with a static onboarding wizard

A static wizard is a real alternative for products that introduce concepts in sequence without pointing to existing interface controls. Such a wizard can present one destination screen at a time, own its page transitions directly, and avoid target selectors entirely. Onborda takes a different approach: it keeps the application visible, anchors the active step to a selected DOM element, and positions the card on a specified side.

That difference favors contextual feature tours. It also moves complexity into target selection, responsive placement, and route timing. Onborda has direct configuration for pointer padding, pointer radius, target side, card controls, multiple tours, and route navigation. The README does not claim support for automatic element discovery, scroll management, completion persistence, or arbitrary delay control. If a product needs a linear setup flow with validation between stages, a conventional page-based wizard may map more directly to that requirement.

For release planning, the package is not archived and its last push was on 2026-06-08. However, the listed releases are v1.2.4 from 2024-08-15 and v1.2.5 from 2024-12-22, so upgrade planning should account for the gap between repository activity and published package history. `package.json` identifies the license as MIT, allowing redistribution and modification under that license's terms, subject to its notice and license conditions. Upgrade review should therefore include both peer dependency compatibility and any source changes beyond the documented v1.2.5 behavior.

Editorial conclusion

Onborda is suitable for Next.js teams that want application-specific onboarding anchored to stable element IDs, multiple tour definitions, and custom React cards. It is a poor fit if you need server-triggered overlays, precise control over route transition delays, or broader framework support than React 18, Next.js 13, framer-motion 11, and Radix Portal 1.1.1. Before adopting it, verify the MIT license for your intended use, confirm that the required peer dependencies fit the application, and test each tour selector against rendered routes. The first version-specific check should be whether the documented 500ms route delay matches the navigation experience you intend to ship.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. uixmat/onborda on GitHub