Nudge.js

Nudges that convert — without the dark patterns.

Ethical, open-source product tours for React. MIT licensed.

Status

🚧 Pre-alpha. The API is being designed. This repository currently holds scaffolding and a name reservation on npm. Do not use in production yet.

Follow progress: github.com/nudgejs/nudge

Why Nudge?

The name comes from Richard Thaler's Nudge (2008) and its core idea, choice architecture: don't force, don't forbid — guide gently at the moment of decision. Product tours, done right, are exactly that.

Nudge.js is extracted from a production SaaS onboarding engine. It focuses on the engineering details most open-source tour libraries skip: fault tolerance when target elements disappear, CSS isolation via iframes, conditional theming, and SPA-friendly element finding.

How it compares

| Feature | Nudge.js | driver.js | React Joyride | Shepherd.js | Intro.js | | ------------------------------------ | :------: | :-------: | :-----------: | :---------: | :------: | | License | MIT | MIT | MIT | MIT | GPLv3† | | React-first API | ✅ | ❌ | ✅ | ❌ | ❌ | | Positioning engine | Floating UI | custom | popper.js | Floating UI | custom | | Theme variations (conditional theme) | ✅ | ❌ | ❌ | ❌ | ❌ | | Missing-target fault tolerance | ✅ | ❌ | partial | ❌ | ❌ | | iframe CSS isolation | ✅ | ❌ | ❌ | ❌ | ❌ | | Conditional triggers | ✅ | ❌ | ❌ | ❌ | ❌ | | Theme-token granularity | ~20 groups | low | low | medium | low | | Multi-strategy element finder (SPA) | ✅ | ❌ | ❌ | ❌ | ❌ |

† Intro.js uses GPLv3 with a commercial dual-license.

Installation

npm install @nudgejs/core
# or
pnpm add @nudgejs/core
# or
yarn add @nudgejs/core

Peer dependencies: react ^18, react-dom ^18.

Quick start

API preview — not yet implemented.

import { Nudge } from '@nudgejs/core';

const nudge = new Nudge({
  theme: { /* theme tokens */ },
  onEvent: (event) => analytics.track(event),
});

nudge.loadFlow({
  id: 'welcome',
  steps: [
    {
      id: 'step-1',
      type: 'tooltip',
      target: { selector: '.signup-button' },
      title: 'Start here',
      body: '<p>Click to create your account</p>',
      side: 'bottom',
      align: 'center',
    },
  ],
});

nudge.start('welcome');

License

MIT © Nudge.js contributors