@matheusrizzati/ui

A premium React UI component library built for modern SaaS applications. Features a dual light/dark theme (Obsidian), 45 production-ready components, and a flexible token-based design system.

✨ Features

• 🎨 Dual Theme — Light mode + Obsidian dark mode with seamless toggle
• 📦 45 Components — Forms, data display, overlays, navigation, feedback, and layout
• 🔧 Token-Based — Fully customizable via CSS variables
• ♿ Accessible — Built on Radix UI primitives where it matters
• 📐 TypeScript — Full type safety and IntelliSense
• 🪶 Lightweight — Tree-shakeable ESM + CJS output

📥 Installation

npm install @matheusrizzati/ui

Peer dependencies:

npm install react react-dom

🚀 Setup

1. Import the CSS

In your app's entry file (e.g., main.tsx or layout.tsx):

import "@matheusrizzati/ui/tokens.css";

2. Add the ThemeProvider

import { ThemeProvider } from "@matheusrizzati/ui";

function App() {
  return (
    <ThemeProvider defaultTheme="system">
      {/* your app */}
    </ThemeProvider>
  );
}

The ThemeProvider supports three modes:

• "light" — Light theme
• "dark" — Obsidian dark theme
• "system" — Follows OS preference (default)

3. Toggle themes

import { useTheme } from "@matheusrizzati/ui";

function ThemeToggle() {
  const { resolvedTheme, toggleTheme } = useTheme();
  return (
    <button onClick={toggleTheme}>
      {resolvedTheme === "dark" ? "☀️" : "🌙"}
    </button>
  );
}

4. Tailwind CSS (if using)

Add darkMode: "class" to your tailwind.config.ts and include the library in content:

export default {
  darkMode: "class",
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@matheusrizzati/ui/dist/**/*.{js,cjs}",
  ],
};

📚 Component Catalog

Forms & Inputs

| Component | Description | Key Features | |-----------|-------------|--------------| | Button | Primary action trigger | 5 variants, 3 sizes, loading state, icon support | | Input | Text input field | Start/end icons, clearable (onClear), error state | | Textarea | Multi-line text input | Auto-resize, character count | | Select | Custom dropdown select | Searchable, clearable, groups, icons, descriptions, keyboard nav | | Combobox | Autocomplete/typeahead | Multi-select, creatable, groups, loading state | | Checkbox | Boolean toggle box | Indeterminate state | | Radio | Single selection group | RadioGroup + Radio | | Switch | Toggle switch | Labels, sizes | | Slider | Range input | Pointer drag, keyboard, step snapping, value display | | Toggle | Pressed/unpressed button | Toolbar toggles, view modes | | ToggleGroup | Group of toggles | Single/multiple selection | | DatePicker | Date input with calendar | Popover calendar, clearable, min/max dates |

Data Display

| Component | Description | Key Features | |-----------|-------------|--------------| | Table | Basic table primitives | Thead, Tbody, Tr, Th, Td | | DataTable | Feature-rich data table | Sorting, pagination, row selection | | Badge | Status/category label | 6 variants, 3 sizes | | Avatar | User/entity image | Sizes, shapes, status indicator | | AvatarGroup | Stacked avatars | max prop, +N overflow counter | | Card | Content container | Elevated, outlined, ghost variants | | StatCard | KPI metric card | Change indicator, icon slot | | Skeleton | Loading placeholder | Pulse animation | | Progress | Progress bar | Variants, sizes, label | | Calendar | Date grid | Month nav, min/max, locale support |

Navigation

| Component | Description | Key Features | |-----------|-------------|--------------| | Tabs | Tab switcher | Segmented style | | Breadcrumb | Path navigation | Separator, active state | | Pagination | Page navigation | Page numbers, ellipsis | | Sidebar | App sidebar | Collapsible, sections, active items | | Navbar | Top navigation bar | — | | Steps | Step indicator | Completed/active/upcoming states |

Overlays

| Component | Description | Key Features | |-----------|-------------|--------------| | Modal | Dialog window | Radix Dialog, title/description/footer | | Drawer | Slide-out panel | 4 sides, 5 sizes, header/body/footer | | Dropdown | Context/action menu | Radix DropdownMenu, labels, groups, separators | | Tooltip | Hover info | Radix Tooltip | | Popover | Click popover | Radix Popover | | HoverCard | Rich hover preview | Radix HoverCard, configurable delays | | ConfirmDialog | Destructive action confirm | Danger/primary variants, loading state |

Feedback

| Component | Description | Key Features | |-----------|-------------|--------------| | Alert | Inline message | Info, success, warning, danger | | Toast | Notification popup | Provider + useToast() hook | | EmptyState | No-data placeholder | Icon, title, description, action | | Spinner | Loading spinner | 5 sizes, primary color |

Layout

| Component | Description | Key Features | |-----------|-------------|--------------| | AppShell | Full page layout | Sidebar + content areas | | PageHeader | Page title section | Title, description, action slot | | Separator | Visual divider | Horizontal/vertical | | Accordion | Collapsible sections | Single/multiple mode, smooth animation | | Collapsible | Simple expand/collapse | Controlled/uncontrolled, Trigger + Content |

Utilities

| Export | Description | |--------|-------------| | ThemeProvider | Light/dark/system toggle + persistence | | useTheme() | Access theme state and controls | | cn() | Class merging utility (clsx + tailwind-merge) | | CommandPalette | ⌘K search palette |

🎯 Quick Start Example

import {
  ThemeProvider,
  AppShell,
  Sidebar,
  SidebarHeader,
  SidebarContent,
  SidebarSection,
  SidebarItem,
  Navbar,
  PageHeader,
  Button,
  Card,
  CardHeader,
  CardBody,
  StatCard,
  Input,
  Select,
  DataTable,
  useTheme,
} from "@matheusrizzati/ui";

function Dashboard() {
  const { toggleTheme, resolvedTheme } = useTheme();

  return (
    <AppShell>
      <Sidebar>
        <SidebarHeader>My App</SidebarHeader>
        <SidebarContent>
          <SidebarSection label="Menu">
            <SidebarItem active>Dashboard</SidebarItem>
            <SidebarItem>Users</SidebarItem>
            <SidebarItem>Settings</SidebarItem>
          </SidebarSection>
        </SidebarContent>
      </Sidebar>

      <main>
        <Navbar>
          <Button variant="ghost" onClick={toggleTheme}>
            {resolvedTheme === "dark" ? "☀️" : "🌙"}
          </Button>
        </Navbar>

        <div className="p-6">
          <PageHeader
            title="Dashboard"
            description="Overview of your metrics"
          />

          <div className="grid grid-cols-3 gap-4 mb-6">
            <StatCard title="Revenue" value="$12,345" change="+12%" />
            <StatCard title="Users" value="1,234" change="+5%" />
            <StatCard title="Orders" value="567" change="-2%" />
          </div>

          <Card>
            <CardHeader>Recent Orders</CardHeader>
            <CardBody>
              <DataTable
                columns={[
                  { key: "id", header: "ID" },
                  { key: "customer", header: "Customer" },
                  { key: "total", header: "Total" },
                ]}
                data={[
                  { id: "#001", customer: "John Doe", total: "$99.00" },
                  { id: "#002", customer: "Jane Smith", total: "$149.00" },
                ]}
              />
            </CardBody>
          </Card>
        </div>
      </main>
    </AppShell>
  );
}

🎨 Customizing Tokens

Override CSS variables in your own stylesheet to customize the theme:

:root {
  /* Change the primary color to emerald */
  --color-primary-500: #10b981;
  --color-primary-600: #059669;
  --color-primary-700: #047857;
  --color-primary: var(--color-primary-600);
  --color-primary-hover: var(--color-primary-700);

  /* Change the font */
  --font-sans: "Inter", sans-serif;

  /* Adjust border radius */
  --radius: 0.75rem;
}

🛠️ Tech Stack

• React 18+ with TypeScript
• Tailwind CSS for utility classes
• Radix UI for accessible primitives (Dialog, Dropdown, Tooltip, Popover, AlertDialog)
• CVA (class-variance-authority) for variant management
• tsup for building ESM + CJS bundles

📦 Exports

dist/
├── index.js        # ESM
├── index.cjs       # CommonJS
├── index.d.ts      # TypeScript declarations
├── index.d.cts     # CTS declarations  
├── styles.css      # Compiled styles
└── tokens.css      # Design tokens (import this!)

📄 License

MIT