🎭 Onstage

The premium, plug-and-play onboarding wizard for React.

Turn your new user experience into a polished, professional tour in minutes. onstage provides a beautiful, responsive, and fully customizable modal wizard with zero friction.

Try the Interactive Builder & Gallery
Design your modal in real-time and copy the code.

✨ Features

• 🎨 7 Pre-built Themes: From "Glassmorphism" to "Midnight" dark mode.
• 📱 Fully Responsive: Adapts visuals for Mobile, Tablet, and Desktop automatically.
• 🔌 Plug & Play: Just pass an array of steps and it renders.
• 🌫️ Backdrop Control: Choose between dark, blurred, or transparent overlays.
• 🎮 Flexible Control: Strict mode (force completion) or Permissive (click outside to close).
• 💅 Granular Styling: Override any part of the UI with Tailwind classes or CSS variables.

📦 Installation

npm install onstage
# or
pnpm add onstage
# or
yarn add onstage

🚀 Quick Start

1. Import Styles

Add this once to your root file (e.g., main.tsx or App.tsx):

import "onstage/styles.css";

2. Wrap & Use

Wrap your app (or just the section you need) with the Provider and place the Modal.

import { OnboardingProvider, OnboardingModal } from "onstage";

const steps = [
  {
    title: "Welcome! 👋",
    description: "We are **thrilled** to have you here.",
    image: "/images/welcome-desktop.png"
  },
  {
    title: "Features",
    description: "Explore our new dashboard.",
    image: "/images/dashboard.png"
  }
];

export default function App() {
  return (
    <OnboardingProvider steps={steps} defaultOpen={true}>
      <YourApp />
      <OnboardingModal />
    </OnboardingProvider>
  );
}

🎨 Themes & Aesthetics

onstage comes with professional presets so you don't have to design from scratch.

Preset Themes

Pass the theme prop to switch styles instantly.

// 🌑 Professional Dark Mode
<OnboardingModal theme="dark" />

// 🪟 Frosted Glass Effect
<OnboardingModal theme="glass" />

// 🌌 Deep Purple "Midnight"
<OnboardingModal theme="midnight" />

// 📐 Minimalist (Brutalist / Sharp)
<OnboardingModal theme="minimal" />

Available Themes:

• light (Default)
• dark
• glass
• midnight
• minimal
• ocean
• sunset

Backdrop Effects

Control the overlay behind the modal.

// 🌫️ Frosted background
<OnboardingModal backdrop="blur" />

// 👻 Invisible overlay (content visible but not clickable)
<OnboardingModal backdrop="transparent" />

📱 Responsive Images

Don't serve a desktop screenshot on a mobile phone. onstage lets you define specific images for different devices. It automatically adjusts the aspect ratio (4:5 mobile, 4:3 tablet, 16:9 desktop) to fit the modal perfectly.

const steps = [
  {
    title: "Responsive Magic",
    description: "Resize your browser to see the image change!",
    image: {
      mobile: "/img/hero-portrait.png",  // < 640px (4:5 Ratio)
      tablet: "/img/hero-square.png",    // < 1024px (4:3 Ratio)
      desktop: "/img/hero-landscape.png" // > 1024px (16:9 Ratio)
    }
  }
];

🎮 Interaction & Control

Strict vs. Permissive Mode

Decide if users must complete the onboarding or if they can dismiss it easily.

// 🔓 Permissive Mode (Default)
// Users can click the background or press ESC to dismiss.
<OnboardingModal allowClickOutside={true} />

// 🔒 Strict Mode
// Users MUST finish the steps or click "Skip". Background click is disabled.
<OnboardingModal allowClickOutside={false} />

Programmatic Control

Control the wizard from anywhere in your app using the hook.

import { useOnboarding } from "onstage";

function SettingsPage() {
  const { resetOnboarding } = useOnboarding();

  return (
    <button onClick={resetOnboarding}>
      Show Tutorial Again
    </button>
  );
}

Available Hook Methods:

• resetOnboarding(): Opens modal at step 0.
• setIsOpen(boolean): Manually toggle visibility.
• skipOnboarding(): Closes modal and triggers onSkip.
• finishOnboarding(): Closes modal and triggers onFinish.

🛠️ Advanced Customization

CSS Variables

Tweak the branding colors globally or inline.

<OnboardingModal
  style={{
    '--primary': '262 80% 50%', // Custom Purple
    '--radius': '1rem'          // Rounder corners
  } as React.CSSProperties}
/>

Granular Targeting

Need to style just the "Next" button? Use classNames (supports Tailwind) or styles to target specific elements.

<OnboardingModal
  classNames={{
    // Add red background to next button
    nextButton: "bg-red-500 hover:bg-red-600 font-bold",
    // Make title blue
    title: "text-blue-600 underline",
    // Custom overlay
    overlay: "bg-slate-900/90"
  }}
/>

Targetable Elements: overlay, content, imageContainer, image, header, title, description, footer, stepIndicators, nextButton, prevButton, skipButton, finishButton.

📚 API Reference

OnboardingModal Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | theme | string | "light" | light, dark, glass, minimal, midnight, ocean, sunset | | backdrop | string | "default" | default (dark), blur, transparent | | allowClickOutside | boolean | true | If true, clicking overlay closes the modal. | | gradient | string | "animated" | animated, static, none | | className | string | - | Class for the main modal container. | | classNames | object | {} | Target specific elements (see above). | | style | CSSProperties | {} | Inline styles for the root. |

OnboardingProvider Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | steps | OnboardingStep[] | Required | Array of step data. | | defaultOpen | boolean | false | If true, opens immediately on mount. | | onFinish | () => void | - | Callback when user finishes all steps. | | onSkip | () => void | - | Callback when user clicks "Skip". |

License

MIT © Asad Ullah Khalid