Onboarding Screen React

A premium, highly customizable onboarding screen component library built with React, Framer Motion, and Tailwind CSS. Featuring 6 distinct styles to provide a stunning first impression for your users.

🎨 6 Unique Styles

Below are the 6 premium onboarding experiences included in this library:

| Style | Preview | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Modern Dark | | | Glassmorphism | | | Neo-Brutalist | | | Playful 3D | | | Vibrant Gradient | | | Minimalist | |

✨ Features

• 🚀 6 Unique Styles: Modern, Glassmorphism, Brutalist, Playful, Gradient, and Minimalist.
• ⚡ High Performance: Built with Vite and React 19 for lightning-fast HMR and low bundle size.
• 🎨 Beautiful Animations: Smooth transitions and interactive elements powered by Framer Motion.
• 📱 Fully Responsive: Designed to look great on all devices.
• 🛠️ Developer Friendly: Written in TypeScript with clear component architecture.

🚀 Installation

Install the package via npm:

npm install onbording-screen-react

📖 Usage

Here is a quick example of how to implement a stunning onboarding flow in your React application:

🎨 Choose Your Aesthetic

We've built 6 distinct layout philosophies into a single component. No need to rewrite your logic when shifting your brand's look.

| Variant | Best For | Visual Vibe | | ------------------------------- | -------------------------- | ----------------------------------------- | | The Classic (split) | B2B SaaS, Dashboards | Professional, data-rich, balanced | | The Immersive (immersive) | Lifestyle, Travel, Apps | Background imagery, white text, cinematic | | The Minimalist (minimal) | Utility, Depth tools | High white-space, high focus | | The Premium (glass) | AI, Fintech, Web3 | Glassmorphism, blurs, glowing accents | | The Modern (side-nav) | Workspaces, Internal tools | Side-navigation, tech-forward | | The Soft Zen (soft) | Wellness, Reading, Art | Small typography, soft colors, peaceful |

🏗️ Architecture

The library follows a structured hierarchy to keep your code clean:

graph TD
    A[Onboarding - Provider] --> B[OnboardingLayout - Animation & Variant]
    B --> C[OnboardingStep - Flexible Content]
    A --> D[OnboardingNavigation - UI Controls]

🧩 Components Reference

1. <Onboarding />

The root component that handles state management and provides context to all child components.

| Prop | Type | Default | Description | | -------------- | ------------------------ | ------- | ---------------------------------------------------------------- | | step | number | - | Required. The current active step (0-indexed). | | totalSteps | number | - | Required. Total number of steps in the flow. | | onStepChange | (step: number) => void | - | Required. Callback when a step change is requested. | | onComplete | () => void | - | Optional. Called when the user clicks 'Finish' on the last step. | | onSkip | () => void | - | Optional. Called when the user clicks 'Skip'. | | className | string | - | Custom styles for the main full-screen overlay. |

2. <OnboardingLayout />

Manages the visual workspace and entrance/exit animations.

| Prop | Type | Default | Description | | ----------- | -------- | --------- | ------------------------------------------------------------- | | variant | string | 'split' | split, immersive, minimal, glass, side-nav, soft. | | className | string | - | Adjust padding, background tints, or layout overrides. |

3. <OnboardingStep />

A "Super Component" that intelligently renders your content based on the parent's variant.

| Prop | Type | Description | | ------------- | ------------ | -------------------------------------------------- | | title | string | Large heading for the step. | | description | string | Supporting text or body content. | | media | ReactNode | An image, video, or custom illustration. | | icon | LucideIcon | A small icon to represent the step feature. | | features | Array | List of { title, desc, icon } for feature grids. | | quote | string | A testimonial or highlight quote. | | author | string | Name of the person being quoted. | | role | string | Job title or context for the author. |

4. <OnboardingNavigation />

Standardized UI controls that adapt to the flow's style.

| Variant | Placement | Description | | ---------- | --------------- | ------------------------------------------ | | bottom | Screen Bottom | Traditional wide bar navigation. | | side | Screen Right | Compact vertical bar with icons/dots. | | floating | Centered Bottom | Modern pill-shaped floating control. | | soft | Minimal Bottom | Tiny typography and subtle progress lines. |

🚀 Quick Implementations

Classic SaaS Setup

<OnboardingLayout variant="split">
  <OnboardingStep
    title="Scale Globally"
    description="Deploy to 200 regions."
    media={<img src="/map.png" />}
  />
</OnboardingLayout>
<OnboardingNavigation variant="bottom" />

Soft Zen Setup

<OnboardingLayout variant="soft">
  <OnboardingStep
    title="Mindful Moments"
    description="Take a breath before you begin."
  />
</OnboardingLayout>
<OnboardingNavigation variant="soft" />

Example

"use client";

import React, { useState, useEffect } from "react";
import {
  Onboarding,
  OnboardingLayout,
  OnboardingNavigation,
  OnboardingStep,
} from "onbording-screen-react";
import {Sun, Moon } from "lucide-react";

export function OnboardingScreen() {
  const [step, setStep] = useState(0);
  const [isVisible, setIsVisible] = useState(false);
  const totalSteps = 3;

  useEffect(() => {
    const hasSeenOnboarding = localStorage.getItem("hasSeenOnboarding");
    if (!hasSeenOnboarding) {
      setIsVisible(true);
    }
  }, []);

  const handleComplete = () => {
    localStorage.setItem("hasSeenOnboarding", "true");
    setIsVisible(false);
  };

  if (!isVisible) return null;
  const softZenSteps = [
  {
    title: "Breathe In",
    description: "Let go of the noise. This is your space for stillness.",
    image: "https://images.unsplash.com/photo-1499750310107-5fef28a66643?q=80&w=1000",
    icon: Sun
  },
  {
    title: "Inner Peace",
    description: "Find clarity in the minimalist corners of your mind.",
    image: "https://images.unsplash.com/photo-1470770841072-f978cf4d019e?q=80&w=1000",
    icon: Moon
  }
]

  return (
    <div className="fixed inset-0 z-[100] bg-background">
       <Onboarding
        step={step}
        totalSteps={softZenSteps.length}
        onStepChange={setStep}
        onComplete={handleComplete}
      >
        <OnboardingLayout variant="soft">
          {softZenSteps.map((s, i) => (
            <OnboardingStep
              key={i}
              {...s}
              media={s.image ? <img src={s.image} className="w-full h-full object-cover" /> : null}
              variant="soft"
            />
          ))}
        </OnboardingLayout>
        <OnboardingNavigation variant="soft" />
      </Onboarding>
    </div>
  );
}

## 🧩 Components & Variants

### `<OnboardingLayout />`

The main wrapper that controls the overall positioning and animation logic.

- **`variant`**: `split` | `immersive` | `minimal` | `glass` | `side-nav` | `soft` | `brutalist` | `playful` | `gradient`

### `<OnboardingStep />`

Individual step content.

- **Props**: `title`, `description`, `media` (ReactNode), `icon`, `quote`, `author`, `role`, `features` (Array)
- **`variant`**: Matches the layout variant for consistent styling.

### `<OnboardingNavigation />`

Progress indicators and navigation buttons.

- **`variant`**: `bottom` | `side` | `floating` | `soft`

## 🛠️ Tech Stack

- **Framework**: [React 19](https://react.dev/)
- **Build Tool**: [Vite 7](https://vite.dev/)
- **Styling**: [Tailwind CSS 4](https://tailwindcss.com/)
- **Animations**: [Framer Motion](https://www.framer.com/motion/)
- **Icons**: [Lucide React](https://lucide.dev/)
- **Language**: [TypeScript](https://www.typescriptlang.org/)

## 📂 Project Structure

```text
src/
├── lib/onboarding/  # Core Library Components
│   ├── index.ts     # Library Entry Point
│   ├── styles/      # Onboarding Style Variants
│   └── components/  # Shared UI components
├── App.tsx          # Demo Application
└── main.tsx         # React mounting

📄 License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

[!IMPORTANT] If you choose to modify this project and redistribute it, you must also release your project under the same GPL-3.0 license, keeping it open source.

See the LICENSE file for the full text.

Built with ❤️ by Itsnishant4

⭐ If you find this project helpful, please give it a star on GitHub!