✨ @arolariu/components

Modern • Accessible • Production Ready

A comprehensive collection of 71+ beautifully crafted React components built on Base UI primitives, styled with CSS Modules, and designed for modern applications that demand both beauty and performance.

🚀 Get Started • 📖 Documentation • 🎨 Storybook demos (Coming soon) • 💡 Examples • 🤝 Contributing

🎯 Why Choose @arolariu/components?

For Developers Who Care About Quality

• 🎨 Beautiful by Default - Carefully designed components that look great out of the box
• ♿ Accessibility First - Built on Base UI primitives with strong keyboard and screen reader support
• 🧩 CSS Modules Architecture - Scoped .module.css styling inside the library
• 🌈 OKLCH Design Tokens - Theme every component with --ac-* CSS custom properties such as --ac-primary and --ac-radius-md
• ⚡ Performance Optimized - Tree-shakeable exports, minimal bundle impact, and source maps included
• 🔧 Developer Experience - Full TypeScript support, comprehensive docs, and debugging tools
• 🌙 Flexible Theming - Light and dark mode via .dark or [data-theme="dark"]
• 🚀 Modern Stack - React 18/19, ESM, SSR compatible, built with RSLib

Version 1.0.0 is the first major release of the new Base UI + CSS Modules architecture.

🚀 Quick Start

Get up and running with @arolariu/components in under 2 minutes.

Installation

npm install @arolariu/components

# Peer dependencies (install if not already in your project)
npm install react react-dom @base-ui/react motion react-hook-form recharts

Basic Setup

import {Button} from "@arolariu/components/button";
import {Card, CardContent, CardHeader, CardTitle} from "@arolariu/components/card";
import styles from "./app-shell.module.css";

export default function MyApp() {
  return (
    <Card className={styles.card}>
      <CardHeader>
        <CardTitle>Welcome to @arolariu/components 1.0.0</CardTitle>
      </CardHeader>
      <CardContent className={styles.content}>
        <Button>Get Started</Button>
      </CardContent>
    </Card>
  );
}

/* app-shell.module.css */
.card {
  width: min(24rem, 100%);
}

.content {
  display: flex;
  justify-content: flex-start;
}

Add Styles (Required)

// Import design tokens only (colors, spacing, radii)
import "@arolariu/components/styles";

// Components auto-load their CSS when imported
import {Button, Card} from "@arolariu/components";

@arolariu/components/styles provides design tokens only. Component CSS is loaded automatically when you import components.

Optional Theme Overrides

/* app-theme.css */
:root {
  --ac-primary: oklch(0.62 0.21 262);
  --ac-primary-foreground: oklch(0.99 0.01 260);
  --ac-radius-md: 0.75rem;
}

.dark {
  --ac-background: oklch(0.18 0.01 286);
  --ac-foreground: oklch(0.98 0 0);
}

That's it. 🎉 You bring your app layout styles with CSS Modules, and the library provides component styling and tokens.

📖 Component Catalog

Explore our collection of 71+ components organized by category.

🎨 Layout & Structure

| Component | Description | Import | | --------------- | --------------------------------------- | ----------------------------------- | | Card | Flexible container for grouping content | @arolariu/components/card | | AspectRatio | Maintain consistent aspect ratios | @arolariu/components/aspect-ratio | | Separator | Visual dividers for content sections | @arolariu/components/separator | | Resizable | Split panes with resizable dividers | @arolariu/components/resizable |

🎭 Interactive Elements

| Component | Description | Import | | ------------ | ----------------------------------------- | ------------------------------- | | Button | Primary action triggers with variants | @arolariu/components/button | | Input | Text input fields with validation support | @arolariu/components/input | | Checkbox | Binary choice selections | @arolariu/components/checkbox | | Select | Dropdown selection menus | @arolariu/components/select | | Slider | Range input controls | @arolariu/components/slider |

🧭 Navigation

| Component | Description | Import | | ------------------ | ------------------------------ | -------------------------------------- | | Tabs | Tabbed content navigation | @arolariu/components/tabs | | Breadcrumb | Hierarchical navigation trails | @arolariu/components/breadcrumb | | NavigationMenu | Complex dropdown navigation | @arolariu/components/navigation-menu | | Sidebar | Collapsible side navigation | @arolariu/components/sidebar | | Menubar | Application and editor menus | @arolariu/components/menubar |

📦 Overlays & Dialogs

| Component | Description | Import | | -------------- | ---------------------------------- | --------------------------------- | | Dialog | Modal dialogs and confirmations | @arolariu/components/dialog | | Sheet | Slide-out panels from screen edges | @arolariu/components/sheet | | Popover | Floating content containers | @arolariu/components/popover | | Tooltip | Contextual information on hover | @arolariu/components/tooltip | | DropDrawer | Advanced drawer with drop zones | @arolariu/components/dropdrawer |

📊 Data Display

| Component | Description | Import | | ------------ | -------------------------------------- | ------------------------------- | | Table | Data tables with sorting/pagination | @arolariu/components/table | | Calendar | Date selection and navigation | @arolariu/components/calendar | | Avatar | User profile pictures and placeholders | @arolariu/components/avatar | | Badge | Status indicators and labels | @arolariu/components/badge | | Chart | Data visualization components | @arolariu/components/chart |

🎛️ Form Controls

| Component | Description | Import | | --------------- | ---------------------------------- | ----------------------------------- | | Form | Form validation and management | @arolariu/components/form | | Field | Form field layout primitives | @arolariu/components/field | | InputOTP | One-time password input fields | @arolariu/components/input-otp | | InputGroup | Grouped text inputs and actions | @arolariu/components/input-group | | RadioGroup | Single-choice option groups | @arolariu/components/radio-group | | Switch | Toggle switches for binary options | @arolariu/components/switch | | Textarea | Multi-line text input areas | @arolariu/components/textarea | | ToggleGroup | Coordinated toggle button groups | @arolariu/components/toggle-group |

💬 Feedback & Status

| Component | Description | Import | | ------------ | ------------------------------- | ------------------------------- | | Alert | Important message notifications | @arolariu/components/alert | | Progress | Task completion indicators | @arolariu/components/progress | | Skeleton | Loading state placeholders | @arolariu/components/skeleton | | Toaster | Base UI-backed toast system | @arolariu/components/sonner | | Spinner | Loading indicators | @arolariu/components/spinner |

🎪 Animated Backgrounds

| Component | Description | Import | | ----------------------- | ------------------------------- | ------------------------------------------- | | DotBackground | Animated dot matrix backgrounds | @arolariu/components/dot-background | | BubbleBackground | Floating bubble animations | @arolariu/components/bubble-background | | FireworksBackground | Particle explosion effects | @arolariu/components/fireworks-background | | GradientBackground | Dynamic gradient animations | @arolariu/components/gradient-background |

Storybook demos: Coming soon.

🔄 Migrating from v0.x

• @radix-ui/* has been replaced internally with @base-ui/react; this is automatic and does not require consumer changes.
• tailwindcss is no longer a peer dependency.
• asChild still works for backward compatibility, but the render prop is now the preferred composition API.
• The sonner toast API is preserved through the compatibility wrapper exported from @arolariu/components/sonner.
• If you previously used badgeVariants or buttonVariants, migrate to component props such as variant and size instead.
• CSS custom properties now use the --ac-* prefix.

🏗️ Architecture

Primitives

• Base layer: @base-ui/react provides the primitive building blocks
• Composition: Base UI's render prop is the preferred composition API
• Backward compatibility: asChild is still supported where available as a shim for Radix-era usage

Styling

• Each component is styled with a colocated CSS Module such as button.module.css
• className remains the public extension point for consumer overrides
• Base UI state attributes such as [data-open], [data-disabled], [data-checked], and [data-selected] drive stateful styling
• cn() now uses clsx only for predictable class composition

Theming

• Design tokens live in src/index.css
• Theme tokens use the --ac- prefix, for example:
  • --ac-primary
  • --ac-background
  • --ac-radius-md
  • --ac-chart-1
• Dark mode is activated with either:
  • a .dark class
  • or a [data-theme="dark"] attribute

Build & Distribution

• Built with RSLib using ESM output
• Tree-shakeable direct imports for components
• TypeScript declarations and source maps included

Common Import Paths

import {Button} from "@arolariu/components/button";
import {useIsMobile} from "@arolariu/components/useIsMobile";
import {cn} from "@arolariu/components/utilities";
import {hexToHsl} from "@arolariu/components/color-conversion-utilities";

💡 Usage Examples

Building a Login Form

import {useState} from "react";

import {Alert, AlertDescription} from "@arolariu/components/alert";
import {Button} from "@arolariu/components/button";
import {Card, CardContent, CardFooter, CardHeader, CardTitle} from "@arolariu/components/card";
import {Checkbox} from "@arolariu/components/checkbox";
import {Input} from "@arolariu/components/input";
import {Label} from "@arolariu/components/label";
import styles from "./login-form.module.css";

export function LoginForm() {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [rememberMe, setRememberMe] = useState(false);
  const [error, setError] = useState("");

  return (
    <div className={styles.wrapper}>
      <Card className={styles.card}>
        <CardHeader>
          <CardTitle>Welcome Back</CardTitle>
        </CardHeader>
        <CardContent className={styles.content}>
          {error ? (
            <Alert variant='destructive'>
              <AlertDescription>{error}</AlertDescription>
            </Alert>
          ) : null}

          <div className={styles.field}>
            <Label htmlFor='email'>Email</Label>
            <Input
              id='email'
              type='email'
              placeholder='[email protected]'
              value={email}
              onChange={(event) => setEmail(event.target.value)}
            />
          </div>

          <div className={styles.field}>
            <Label htmlFor='password'>Password</Label>
            <Input
              id='password'
              type='password'
              value={password}
              onChange={(event) => setPassword(event.target.value)}
            />
          </div>

          <div className={styles.checkboxRow}>
            <Checkbox
              id='remember'
              checked={rememberMe}
              onCheckedChange={setRememberMe}
            />
            <Label htmlFor='remember'>Remember me</Label>
          </div>
        </CardContent>
        <CardFooter>
          <Button className={styles.submitButton}>Sign In</Button>
        </CardFooter>
      </Card>
    </div>
  );
}

Data Dashboard

import {Badge} from "@arolariu/components/badge";
import {Card, CardContent, CardHeader, CardTitle} from "@arolariu/components/card";
import {Progress} from "@arolariu/components/progress";
import styles from "./dashboard.module.css";

export function Dashboard() {
  return (
    <div className={styles.grid}>
      <Card>
        <CardHeader>
          <CardTitle className={styles.titleRow}>
            Sales <Badge variant='secondary'>+12%</Badge>
          </CardTitle>
        </CardHeader>
        <CardContent className={styles.stack}>
          <Progress value={75} />
          <p className={styles.mutedText}>75% of monthly goal</p>
        </CardContent>
      </Card>

      <Card>
        <CardHeader>
          <CardTitle>Team Health</CardTitle>
        </CardHeader>
        <CardContent className={styles.stack}>
          <p className={styles.metric}>24 active contributors</p>
          <p className={styles.mutedText}>Using `--ac-*` tokens and Base UI primitives across the app</p>
        </CardContent>
      </Card>
    </div>
  );
}

Interactive Navigation

import {NavigationMenu, NavigationMenuItem, NavigationMenuLink, NavigationMenuList} from "@arolariu/components/navigation-menu";
import {Sheet, SheetContent, SheetTrigger} from "@arolariu/components/sheet";
import {MenuIcon} from "lucide-react";
import styles from "./app-header.module.css";

export function AppHeader() {
  return (
    <header className={styles.header}>
      <div className={styles.container}>
        <h1 className={styles.brand}>My App</h1>

        <NavigationMenu className={styles.desktopNav}>
          <NavigationMenuList>
            <NavigationMenuItem>
              <NavigationMenuLink href='/'>Home</NavigationMenuLink>
            </NavigationMenuItem>
            <NavigationMenuItem>
              <NavigationMenuLink href='/about'>About</NavigationMenuLink>
            </NavigationMenuItem>
          </NavigationMenuList>
        </NavigationMenu>

        <Sheet>
          <SheetTrigger
            render={
              <button
                type='button'
                className={styles.mobileTrigger}
              />
            }>
            <MenuIcon />
          </SheetTrigger>
          <SheetContent>
            <nav className={styles.mobileNav}>
              <a href='/'>Home</a>
              <a href='/about'>About</a>
            </nav>
          </SheetContent>
        </Sheet>
      </div>
    </header>
  );
}

🛠️ Advanced Features

Tree Shaking & Bundle Optimization

@arolariu/components is built with bundle optimization in mind.

// ✅ Optimal: import only what you need
import {Button} from "@arolariu/components/button";
import {Card} from "@arolariu/components/card";

// ❌ Avoid when bundle size matters
import {Button, Card} from "@arolariu/components";

Bundle Impact

• Individual components: typically a few KB gzipped
• Full library: importable as ESM
• With tree shaking: only pay for what you use

TypeScript Integration

Full TypeScript support with intelligent autocomplete.

import {Button, type ButtonProps} from "@arolariu/components/button";
import {cn} from "@arolariu/components/utilities";
import styles from "./custom-button.module.css";

interface CustomButtonProps extends ButtonProps {
  icon?: React.ReactNode;
}

export function CustomButton({icon, children, className, ...props}: CustomButtonProps) {
  return (
    <Button
      className={cn(styles.customButton, className)}
      {...props}>
      {icon ? <span className={styles.icon}>{icon}</span> : null}
      <span>{children}</span>
    </Button>
  );
}

Server-Side Rendering (SSR)

Compatible with Next.js, Remix, and other SSR frameworks.

// app/page.tsx
import {Button} from "@arolariu/components/button";
import {Card, CardContent} from "@arolariu/components/card";

export default function HomePage() {
  return (
    <Card>
      <CardContent>
        <Button>Server-rendered Button</Button>
      </CardContent>
    </Card>
  );
}

Theming & Customization

Built around OKLCH CSS custom properties and CSS Modules.

/* theme-overrides.module.css */
.themeScope {
  --ac-primary: oklch(0.7 0.19 250);
  --ac-primary-foreground: oklch(0.99 0.01 250);
  --ac-muted: oklch(0.96 0.01 286);
  --ac-radius-md: 0.875rem;
}

import {Button} from "@arolariu/components/button";
import styles from "./theme-overrides.module.css";

export function ThemedExample() {
  return (
    <section className={styles.themeScope}>
      <Button>Custom themed button</Button>
    </section>
  );
}

🔍 Debugging & Development

Complete Source Map Support

Debug like a pro with comprehensive development tools.

• ✅ JavaScript source maps for accurate debugging
• ✅ CSS source maps for CSS Module debugging
• ✅ TypeScript declaration maps for IDE IntelliSense
• ✅ Original source access via included src/ directory

Browser DevTools Integration

import {Button} from "@arolariu/components/button";

function MyComponent() {
  return <Button onClick={() => console.log("Clicked!")}>Debug Me</Button>;
}

Inspect generated class names, Base UI data attributes, and source-mapped module styles directly in DevTools.

📖 Full Debugging Guide - Learn advanced debugging techniques.

🌐 Browser Support

Modern browsers only for optimal performance.

| Browser | Version | | ------------------ | ----------- | | 🌟 Chrome/Edge | 90+ (2021+) | | 🦊 Firefox | 88+ (2021+) | | 🧭 Safari | 14+ (2020+) |

Why modern browsers? The library uses modern ESM output, CSS custom properties, and contemporary platform APIs for smaller bundles and better performance.

🤝 Contributing

We welcome contributions. Help make @arolariu/components even better.

Quick Start for Contributors

# 1. Fork and clone the repository
git clone https://github.com/your-username/arolariu.ro.git
cd arolariu.ro/packages/components

# 2. Install dependencies
npm install

# 3. Start development environment
npm run build:components
npm run dev:components

# 4. Make your changes and test
npm run build:components

Ways to Contribute

• 🐛 Report bugs - Found an issue? Open an issue
• 💡 Suggest features - Have an idea? We'd love to hear it
• 🔧 Fix issues - Browse open issues and submit PRs
• 📖 Improve docs - Help make our documentation clearer
• 🎨 Add components - Contribute new components following our patterns

Component Development Guidelines

1. Follow accessibility standards - Use Base UI primitives when appropriate
2. Include TypeScript types - Full type definitions required
3. Add stories or demos - Document variants and use cases
4. Write tests - Ensure components work correctly
5. Follow naming conventions - Use clear, descriptive names
6. Prefer CSS Modules - Keep component styles colocated and token-driven

Read our full contributing guide →

📦 Package Details

Bundle Information

# Package size analysis
npm install @arolariu/components
npx bundlephobia @arolariu/components

Key Stats

• 📦 Version: 1.0.0
• 🌲 Tree-shakeable: import only what you need
• 📝 TypeScript: typed package with declaration output
• ♿ Accessibility: Base UI-backed primitives and patterns
• 🎭 Styling: CSS Modules + package-level design tokens
• 🌙 Theming: --ac-* tokens with .dark and [data-theme="dark"] support

Dependencies

Core runtime dependencies include:

• @base-ui/react - Accessible component primitives in a single package
• clsx - Class name composition used by cn()
• lucide-react - Icon set
• motion - Animation library
• react-hook-form and zod - Forms and validation helpers
• embla-carousel-react, recharts, react-day-picker, input-otp, react-resizable-panels, shiki - Specialized UI integrations

Removed from the 1.0.0 architecture:

• @radix-ui/*
• tailwind-merge
• class-variance-authority
• tailwindcss-animate
• vaul
• sonner
• cmdk

📄 License

MIT License - Use freely in personal and commercial projects.

MIT License

Copyright (c) 2025 Alexandru-Razvan Olariu

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

View full license →

👨‍💻 About the Author

Alexandru-Razvan Olariu

Senior Software Engineer passionate about creating beautiful, accessible user interfaces and developer tools.

• 🌐 Website: arolariu.ro
• 💻 GitHub: @arolariu
• 💼 LinkedIn: Alexandru-Razvan Olariu
• 📧 Email: [email protected]

🙏 Acknowledgments & Inspiration

This library wouldn't exist without these amazing projects.

• 🎨 Base UI - Accessible component primitives
• 💫 shadcn/ui - Component design patterns and inspiration
• 🎭 CSS Modules - Scoped styling model used throughout the library
• ⚡ Motion - Animation library for React
• 🛠️ Rslib - Fast, modern bundling with Rsbuild
• 📖 Storybook - Component development environment
• 🎪 Magic UI - Additional component inspiration
• ✨ Aceternity UI - Creative component patterns

Special thanks to the open-source community for making all of this possible. 💜

⭐ Star the Project

If @arolariu/components helps you build better UIs, please consider giving it a star on GitHub.

⭐ Star on GitHub • 📖 View Component Catalog • 🐛 Report Issues

Built with ❤️ for the React community

Making beautiful, accessible UIs easier to build, one component at a time.