@moontra/moonui

v6.19.0

Published

19 hours ago

Premium React component library with modern design and customization

0High
0Medium
0Low

oguzhanayyldz

ui components design-system react nextjs tailwindcss radix-ui

MoonUI 🌙

A premium React component library built for modern web applications. MoonUI provides beautifully designed, accessible, and highly customizable components that help you build stunning user interfaces faster.

✨ Features

🎨 Beautiful Design

50+ Premium Components - Carefully crafted with attention to detail
Modern Aesthetics - Clean, minimalist design that works everywhere
Consistent Typography - Harmonious text hierarchy and spacing
Smooth Animations - Delightful micro-interactions powered by Framer Motion

🌙 Dark Mode Ready

Built-in Dark Mode - Seamless light/dark theme switching
CSS Variables - Easy customization with design tokens
Theme Provider - Consistent theming across your application
Custom Themes - Create your own color palettes

♿ Accessibility First

WCAG Compliant - Meets accessibility standards
Keyboard Navigation - Full keyboard support
Screen Reader Friendly - Proper ARIA labels and descriptions
Focus Management - Intuitive focus handling

🔧 Developer Experience

TypeScript - Full type safety and IntelliSense
Tree Shaking - Import only what you use
Tailwind Preset - One line in your config wires up every design token
CLI Tool - Easy installation with the @moontra/moonui-cli CLI
Storybook - Interactive component documentation

📱 Responsive & Performance

Mobile First - Optimized for all screen sizes
Lightweight - Minimal bundle impact
React 18+ Compatible - Latest React features
SSR Ready - Next.js and other SSR frameworks

🚀 Quick Start

Installation

# Install the package
npm install @moontra/moonui

# Tailwind is a peer dependency; the components also use the animate plugin
npm install -D tailwindcss tailwindcss-animate

Optionally scaffold the project files (moonui.config.js, src/lib/utils.ts, src/components/ui/) with the CLI. It does not edit your Tailwind config or global CSS — steps 1 and 2 below are still yours to add:

npx @moontra/moonui-cli init

Setup

Steps 1 and 2 are both required. Skip either one and the components render unstyled — the utility classes they rely on are simply never generated.

Add the Tailwind preset (required)

The preset maps Tailwind's color, radius and animation scales onto MoonUI's CSS variables. Without it, classes such as bg-primary, border-border and animate-accordion-down are never produced. The content entry for dist/** matters just as much: Tailwind only generates classes it can see, and the component classes live inside the package bundle.

// tailwind.config.js  (Tailwind v3 config format)
module.exports = {
    presets: [require("@moontra/moonui/tailwind-preset")],
    content: [
        "./src/**/*.{js,ts,jsx,tsx,mdx}",
        "./node_modules/@moontra/moonui/dist/**/*.{js,mjs}",
    ],
    // Radix-driven components use animate-in / fade-in-0 / slide-in-from-*
    plugins: [require("tailwindcss-animate")],
};

Everything the preset sets is still yours to override — add your own theme.extend block and it wins.

Import the design tokens (required)

The preset only maps the variables; this file defines them (light and dark).

/* globals.css */
@import "@moontra/moonui/src/styles/tokens.css";

@tailwind base;
@tailwind components;
@tailwind utilities;

Why the src/styles/… path and not @moontra/moonui/tokens.css? Because the two are resolved by different machinery. postcss-import — what handles CSS @import in the usual Tailwind v3 + PostCSS setup — does not read a package's exports map, so in CSS it needs the physical path (it ships in the tarball via the package files field). Bundler/Node resolution is the mirror image: it is exports-aware, so from JavaScript use the subpath instead:
// app/layout.tsx
import "@moontra/moonui/tokens.css";
Either route loads the same file — pick one, not both.

Recommended: also add the semantic layer. It defines extra tokens (elevation, duration, easing) and the handful of utilities that have no Tailwind equivalent — shadow-xs, animate-fade-in, duration-fast, ease-bounce. Every token the preset reads already lives in tokens.css, so components still render correctly without it; you only lose those extras (for example the Skeleton fade-in).

@import "@moontra/moonui/src/styles/design-system.css";

Start using components

import { Button, Card, Input } from "@moontra/moonui";

function App() {
    return (
        <Card className="p-6">
            <h1 className="text-2xl font-bold mb-4">Welcome to MoonUI</h1>
            <div className="space-y-4">
                <Input placeholder="Enter your name" />
                <Button variant="primary" size="lg">
                    Get Started
                </Button>
            </div>
        </Card>
    );
}

📚 Components

A selection of what ships in the package — every name below is a real export of @moontra/moonui. The full, always-current list lives at moonui.dev/docs/components.

Layout & Structure

Card - Flexible content containers
Separator - Visual content dividers
AspectRatio - Responsive aspect ratio containers
ScrollArea - Custom scrollable areas
Collapsible - Expandable content

Navigation

Breadcrumb - Hierarchical navigation
Pagination - Page navigation controls
Tabs - Tabbed interfaces
DropdownMenu - Context menus
Command - Command palette interface

Form Controls

Button, ButtonGroup - Interactive buttons with variants
Input, Textarea - Text input fields
Select - Dropdown selections
Checkbox, CheckboxGroup - Boolean selections
RadioGroup - Single choice selections
Switch, Toggle, ToggleGroup - Toggle controls
Slider - Range inputs
Label - Form field labels
InputOTP - One-time-code input
PhoneInput, TagsInput - Specialized inputs
CardNumberInput, CardExpiryInput, CardCVCInput, CardZipInput - Payment fields
Rating - Star ratings
FileUpload - File upload interface

Feedback & Overlays

Dialog, DialogForm - Modal dialogs
Toast / Toaster - Notification messages
Alert - Inline notifications
Tooltip, SimpleTooltip - Contextual information
Popover - Floating content panels
Spinner - Inline loading indicator

Data Display

Avatar, AvatarGroup - User profile images
Badge - Status indicators
Kbd - Keyboard shortcut hints
Progress - Loading indicators
Skeleton (+ SkeletonText, SkeletonCard, SkeletonAvatar) - Loading placeholders
Table - Structured data display
MoonUIDataTableBasic - Basic TanStack-powered data table
Accordion - Collapsible content
Carousel - Slideshows

Dates & Color

MoonUICalendar - Date selection
DatePicker, DateRangePicker, DateTimePicker, MonthPicker - Date input controls
ColorPicker, SimpleColorPicker, GradientPicker - Color selection

Interaction & Motion

DraggableList - Sortable lists
SwipeableCard - Touch-friendly cards
GestureDrawer - Gesture-driven drawer
ScrollReveal (+ ScrollRevealContainer, ScrollRevealItem) - Scroll-driven reveals

Editors

RichTextEditor - WYSIWYG editor
SimpleEditor - Lightweight text editor

Components are also exported under a MoonUI-prefixed alias (for example MoonUIButton, MoonUICard) if you need to avoid name collisions. Two of them — Calendar and DataTableBasic — are available only under their prefixed names: MoonUICalendar and MoonUIDataTableBasic.

🎨 Theming

CSS Variables

MoonUI uses CSS variables for theming. These are the values tokens.css ships with — components read them as hsl(var(--primary)) and friends:

:root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 217.2 91.2% 51%;
    --primary-foreground: 210 40% 98%;
    --border: 214.3 31.8% 91.4%;
    --ring: 217.2 91.2% 51%;
    --radius: 0.5rem;
    /* ... more variables */
}

.dark {
    --background: 224 71% 4%;
    --foreground: 213 31% 91%;
    --primary: 210 40% 98%;
    --primary-foreground: 222.2 47.4% 1.2%;
    /* ... dark theme variables */
}

Dark Mode

Dark mode is class-based: tokens.css defines a .dark block and the preset sets darkMode: "class". Put the dark class on your root element — yourself, or with a library such as next-themes — and every component follows:

<html className="dark">
    <body>{children}</body>
</html>

Theme Provider

ThemeProvider is optional and does something different from dark mode: it swaps whole colour presets at runtime. The default preset is the static tokens.css, so mounting the provider changes nothing until you pick another one.

import { ThemeProvider } from "@moontra/moonui/theme";

function App() {
    return (
        <ThemeProvider defaultPreset="ocean" persist>
            <YourApp />
        </ThemeProvider>
    );
}

| Prop | Type | Default | Description | | --------------- | --------------------------------- | ----------- | ---------------------------------------- | | defaultPreset | ThemePresetName | "default" | Preset used on first render | | preset | ThemePresetName | — | Controlled preset (overrides internal state) | | overrides | Partial<ThemeTokens> | — | Per-token overrides | | persist | boolean | false | Persist the selection to localStorage | | storageKey | string | — | Key used when persist is on |

Available presets: default, brand, corporate, creative, nature, minimal, ocean. Read the active one with useTheme() (it must be called inside a ThemeProvider).

Custom Colors

Redeclare any token in your own :root block after the import and it wins:

:root {
    --primary: 142 76% 36%; /* Custom green */
    --secondary: 210 40% 95%;
}

🔧 CLI Tool

The MoonUI CLI helps you add components easily:

# Initialize MoonUI in your project
npx @moontra/moonui-cli init

# Add specific components
npx @moontra/moonui-cli add button
npx @moontra/moonui-cli add card input

# Add multiple components
npx @moontra/moonui-cli add button card input dialog

# Browse what is available
npx @moontra/moonui-cli list

Other commands: theme, templates, license, login, logout, whoami. Run npx @moontra/moonui-cli --help for the full list.

📖 Documentation

🌐 Website: moonui.dev
📚 Components: moonui.dev/docs/components
🎨 Theming: moonui.dev/docs/theming
🔧 CLI: moonui.dev/docs/cli

🤖 AI Integration

MoonUI includes MCP (Model Context Protocol) support for AI assistants:

npm install -g @moontra/moonui-mcp-server

Then register it with your MCP client (Claude Desktop shown here):

{
    "mcpServers": {
        "moonui": {
            "command": "npx",
            "args": ["@moontra/moonui-mcp-server"]
        }
    }
}

AI assistants can then help you:

🎯 Find the right components for your use case
🔧 Generate component code automatically
🐛 Fix import issues
🎨 Configure theming and customization

💼 Pro Version

Upgrade to MoonUI Pro for advanced components:

DataTable - Advanced data grids with sorting, filtering, export, bulk actions
AdvancedChart, ChartWidget - Data visualization built on Recharts
RichTextEditor - WYSIWYG editor
FormWizard - Multi-step forms with validation
AdvancedCalendar - Event calendars and advanced date/time pickers
DraggableList - Sortable lists
FileTree - Hierarchical data display
Timeline - Event timelines
Kanban - Drag-and-drop board layouts
BentoGrid, Spotlight, VirtualList - Layout, search and virtualization

Learn more about Pro →

🛠️ Development

Requirements

Declared peer dependencies:

React 18 or 19 (react, react-dom)
Tailwind CSS 3 or 4

Recommended for development: Node.js 18+ and TypeScript 5+.

Local Development

git clone https://github.com/oguzhanayyldz/moonuikit
cd moonuikit/packages/moonui
npm install
npm run dev

Building

npm run build      # Build for production
npm run build:dts  # Generate type definitions
npm run lint       # Lint code
npm run test       # Run tests

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch
Make your changes
Add tests and documentation
Submit a pull request

Component Guidelines

Follow accessibility best practices
Include TypeScript types
Add Storybook stories
Write comprehensive tests
Document props and usage

📦 Package Details

Bundle Size (v6.17.0, unminified): ~311 KB dist/index.mjs, ~335 KB dist/index.js
Formats: ESM + CJS, both marked "use client" for the Next.js App Router
Type Definitions: Full TypeScript support (dist/index.d.ts)
Tree Shaking: Enabled — sideEffects is limited to **/*.css, so unused components are dropped by the bundler
Subpath exports: ., ./theme, ./hooks, ./tokens.css, ./design-system.css, ./tailwind-preset

🔗 Ecosystem

@moontra/moonui-pro - Premium components
@moontra/moonui-cli - Command line tool
@moontra/moonui-mcp-server - AI integration

📄 License

Licensed under the MIT License.

🙏 Acknowledgments

Built with:

Website • Documentation • Components • GitHub

Made with ❤️ by the MoonUI team