react-neu-ui

A Neumorphism-inspired React UI component library built with React, Tailwind CSS, and Base UI.

Designed to work seamlessly with SPA frameworks (Vite, CRA) and SSR frameworks like Next.js.

✨ Features

• Neumorphic UI components
• Tailwind CSS powered design tokens
• Built-in ThemeProvider with light / dark / system support
• SSR-safe (usable with Next.js)
• Fully customizable via CSS variables

📦 Installation

npm install react-neu-ui
# or
yarn add react-neu-ui

🎨 Styles Setup (Required)

Import Tailwind first, then the library styles.

@import "tailwindcss";
@import "react-neu-ui/styles";

⚠️ Make sure Tailwind is already configured in your project.

🌗 ThemeProvider (Light / Dark / System)

react-neu-ui exposes a ThemeProvider and useTheme hook that works in both SPA and SSR environments.

1️⃣ Wrap your application

import { ThemeProvider } from "react-neu-ui";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider
      defaultTheme="system"
      storage="localStorage"
      storageKey="neu-theme"
    >
      {children}
    </ThemeProvider>
  );
}

2️⃣ Toggle theme anywhere

import { useTheme, Button } from "react-neu-ui";

export function ThemeToggle() {
  const { theme, resolvedTheme, setTheme } = useTheme();

  return (
    <Button onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}>
      Switch Theme
    </Button>
  );
}

Available theme values

• "light"
• "dark"
• "system" (follows OS preference)

🧠 Storage Strategies (SPA & SSR)

You can control how (or if) the theme is persisted using the storage prop.

SPA (default)

<ThemeProvider storage="localStorage" />

SSR / Next.js (no persistence)

<ThemeProvider storage="none" />

SSR-friendly (cookie-based)

<ThemeProvider storage="cookie" storageKey="neu-theme" />

Custom storage adapter

<ThemeProvider
  storage={{
    get: () => "dark",
    set: (v) => console.log(v),
  }}
/>

ℹ️ The ThemeProvider is a Client Component when used in Next.js.

🎛️ Overriding Theme Styles (CSS Variables)

You can fully customize the look and feel by overriding CSS variables after importing the library styles.

Light theme variables

:root {
  --color-background: #f3f4f6;
  --color-foreground: #111827;
  --color-card: #f9fafb;
  --color-primary: #10b981;
  --color-primary-foreground: #ffffff;
  --color-muted: #e5e7eb;
  --color-muted-foreground: #6b7280;
  --color-border: #d1d5db;

  --shadow-raised:
    6px 6px 12px rgba(0,0,0,.15),
    -6px -6px 12px rgba(255,255,255,.9);

  --shadow-inset:
    inset 6px 6px 12px rgba(0,0,0,.15),
    inset -6px -6px 12px rgba(255,255,255,.9);
}

Dark theme variables

.dark {
  --color-background: #0b1220;
  --color-foreground: #e5e7eb;
  --color-card: #111827;
  --color-primary: #34d399;
  --color-primary-foreground: #022c22;
  --color-muted: #1f2937;
  --color-muted-foreground: #9ca3af;
  --color-border: #020617;

  --shadow-raised:
    6px 6px 14px rgba(0,0,0,.7),
    -6px -6px 14px rgba(255,255,255,.05);

  --shadow-inset:
    inset 6px 6px 14px rgba(0,0,0,.7),
    inset -6px -6px 14px rgba(255,255,255,.05);
}

Runtime overrides (advanced)

document.documentElement.style.setProperty("--color-primary", "#8b5cf6");

🧩 Components

• Button
• Card
• Input
• Checkbox
• Switch
• Slider
• Tabs
• Progress
• Badge
• Navigation (optional/demo)

📄 License

MIT