@novahelm/ui

Component library for NovaHelm — built on shadcn/ui, Radix primitives, Tailwind CSS 4, and class-variance-authority. Ships 70+ components covering forms, data display, feedback, navigation, layout, and dashboard patterns.

Quick Start

pnpm add @novahelm/ui

import { Button, Card, CardHeader, CardTitle, CardContent } from "@novahelm/ui";

export function Dashboard() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Welcome</CardTitle>
      </CardHeader>
      <CardContent>
        <Button variant="default" size="md">
          Get Started
        </Button>
      </CardContent>
    </Card>
  );
}

Subpath Exports

| Import path | Purpose | |-------------|---------| | @novahelm/ui | All components, hooks, and utilities | | @novahelm/ui/theme | Theme system (ThemeProvider, presets, tokens, defineTheme) | | @novahelm/ui/theme/tailwind-preset | Tailwind CSS 4 preset for consumer projects | | @novahelm/ui/registry | Dynamic component registry (registerComponent, getComponent) | | @novahelm/ui/meta | Component metadata system (defineComponentMeta) | | @novahelm/ui/contracts | Component prop contracts / interfaces |

Component Inventory

Form Components

| Component | Description | |-----------|-------------| | Button | Primary action button with variants, sizes, loading state, and icon slots | | Input | Text input field | | Textarea | Multi-line text input | | Label | Form label | | Select | Single-value dropdown select | | Checkbox | Boolean checkbox | | Switch | Toggle switch | | RadioGroup | Radio button group | | Slider | Range slider | | FormField | Labeled field wrapper with description and error display | | Form | TanStack Form integration wrapper | | Combobox | Searchable select with autocomplete | | TagInput | Multi-value tag input | | MultiSelect | Multi-value dropdown select | | FileUpload | Drag-and-drop file upload area | | ColorPicker | Color selection input | | DatePicker | Single date picker | | DateRangePicker | Date range selection | | Calendar | Calendar date picker primitive | | InputOTP | One-time password input | | SearchInput | Search input with icon and clear button |

Data Display

| Component | Description | |-----------|-------------| | Card | Content container with header, content, and footer sections | | Badge | Status or label badge with variant and size props | | Avatar | User avatar with image, initials fallback, and size variants | | AvatarGroup | Stacked avatar group with overflow indicator | | Table | HTML table primitives (Header, Body, Row, Head, Cell, Caption) | | DataTable | Full-featured data table (TanStack Table + Virtual) with sorting, filtering, pagination, row selection, and virtualization | | Tabs | Tabbed content panels | | Accordion | Collapsible content sections | | Separator | Horizontal or vertical divider | | Skeleton | Loading placeholder | | Progress | Progress bar | | Spinner | Loading spinner | | Timeline | Vertical timeline with variant-styled items | | ActivityFeed | Chronological activity list | | CodeBlock | Syntax-highlighted code display | | Kbd | Keyboard shortcut display | | AspectRatio | Constrained aspect ratio container | | Carousel | Image/content carousel | | RatingsIndicator | Star/score rating display |

Feedback & Overlay

| Component | Description | |-----------|-------------| | Dialog | Modal dialog with portal, overlay, header, footer | | AlertDialog | Confirmation dialog with action/cancel buttons | | Sheet | Slide-out side panel | | Drawer | Bottom/side drawer panel | | Alert | Inline alert banner (info, warning, error) | | Popover | Floating content popover | | Tooltip | Hover tooltip | | HoverCard | Rich hover preview card | | toast / Toaster | Toast notification system (Sonner) | | EmptyState | Empty content placeholder with icon, title, action | | ErrorBoundary | React error boundary with fallback UI | | Command | Command menu / palette primitive (cmdk) |

Navigation

| Component | Description | |-----------|-------------| | DropdownMenu | Dropdown menu with items, checkboxes, radios, submenus | | ContextMenu | Right-click context menu | | Menubar | Horizontal menu bar | | NavigationMenu | Site navigation menu with content panels | | Breadcrumb | Breadcrumb navigation trail | | Pagination | Page navigation controls | | Stepper | Multi-step progress indicator | | ScrollArea | Custom scrollbar container | | Collapsible | Expandable/collapsible section | | Toggle / ToggleGroup | Toggle button and grouped toggles | | SegmentedControl | Segmented option switcher | | ResizablePanels | Resizable split panel layout |

Layout

| Component | Description | |-----------|-------------| | Sidebar | Full sidebar system (Provider, Header, Footer, Content, Menu, Groups) | | SettingsLayout | Settings page shell with sidebar navigation |

Dashboard & Admin

| Component | Description | |-----------|-------------| | StatCard | Metric card with trend indicator | | StatsGrid | Grid of stat cards | | KPIIndicator | Key performance indicator display | | ChartCard | Chart container card | | StatusBadge | Semantic status badge (success, warning, error, info) | | ActivitySidebar | Activity feed sidebar panel | | QuickActions | Quick action button grid | | NotificationBell | Notification icon with badge and dropdown | | NotificationPreferences | Notification channel settings form | | CommandPalette | Full command palette with groups and keyboard shortcut | | OnboardingWizard | Multi-step onboarding flow | | CopyButton | Copy-to-clipboard button |

Dock Primitives (NovaPulse design language)

The components/dock/ subpath ships 10 primitives for the signature NovaPulse UI — used in mobile and the dev-console shells. Source of truth: the mockup at docs/mockups/novapulse-redesign.html.

import {
  FloatingDock, TabPill, FAB,
  ActionSheet, ActionRow, ActionTile,
  BreadcrumbChip, L3Strip,
  GlassSurface, PulseDot,
} from "@novahelm/ui";

| Primitive | Purpose | | --- | --- | | GlassSurface | Translucent glass-blur surface (pill / chip / glass radii) | | PulseDot | Animated live indicator | | FAB | Circular floating action button with hold-affordance ring + holdHint label | | TabPill | Single tab in a floating dock (active-state indicator) | | FloatingDock | Dock container: tab row + separate FAB | | ActionSheet | Bottom glass sheet (grabber + title + content) | | ActionRow | Sheet row (icon + label + sub + trailing slot) | | ActionTile | Compact grid tile (icon above label) | | BreadcrumbChip | Scope switcher chip (gradient dot + path + chevron) | | L3Strip | Horizontal scroller of sub-tab pills for module sections |

Pair with the novapulse-dark or novapulse-light preset (see Theme System below) for the full visual language. Utility Tailwind classes (bg-brand, bg-destructive, etc.) continue to work through the --nova-* alias layer emitted by every preset.

Theme System

NovaHelm UI generates its themes from @novahelm/design-tokens (one canonical source for both web and native). Six presets ship: default, slate, neon, warm, novapulse-dark, and novapulse-light. Each preset emits both semantic CSS variables (--color-brand-pulse, --color-bg-canvas, ...) and legacy --nova-* aliases so existing Tailwind utility classes (bg-primary, bg-destructive, ...) keep working across theme switches.

Theme Provider

Wrap your app with ThemeProvider to enable dark/light mode and theme presets:

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

export function App({ children }) {
  return (
    <ThemeProvider defaultTheme="system" storageKey="nova-theme">
      {children}
    </ThemeProvider>
  );
}

Built-in Presets

| Preset | Description | |--------|-------------| | defaultPreset | Standard NovaHelm theme | | slatePreset | Cool slate tones | | neonPreset | Vibrant neon accents | | warmPreset | Warm earth tones | | cyberPreset | Cyberpunk-inspired | | oceanPreset | Ocean blue palette | | forestPreset | Forest green palette | | midnightPreset | Deep midnight tones | | lavenderPreset | Soft lavender palette | | sunsetPreset | Warm sunset gradient | | sandstonePreset | Neutral sandstone | | arcticPreset | Cool arctic blues | | rosePreset | Rose pink palette | | emeraldPreset | Rich emerald greens |

Custom Themes

Create a custom theme with defineTheme():

import { defineTheme } from "@novahelm/ui";

const myTheme = defineTheme({
  name: "my-brand",
  colors: {
    primary: { light: "#0066ff", dark: "#3388ff" },
    background: { light: "#ffffff", dark: "#0a0a0a" },
  },
});

Tailwind CSS 4 Integration

Use createNovaPreset() in your Tailwind config to get all NovaHelm design tokens:

import { createNovaPreset } from "@novahelm/ui/theme/tailwind-preset";

export default {
  presets: [createNovaPreset()],
  content: ["./src/**/*.{ts,tsx}", "./node_modules/@novahelm/ui/dist/**/*.mjs"],
};

Usage Examples

Button

import { Button } from "@novahelm/ui";
import { Plus, ArrowRight } from "lucide-react";

// Variants: default, destructive, outline, ghost, link
// Sizes: sm, md, lg, icon
<Button variant="default" size="md" loading={isSubmitting}>
  Save Changes
</Button>

<Button variant="outline" leftIcon={<Plus className="h-4 w-4" />}>
  Add Item
</Button>

<Button variant="ghost" rightIcon={<ArrowRight className="h-4 w-4" />}>
  Continue
</Button>

DataTable

import { DataTable, type DataTableColumn } from "@novahelm/ui";

interface User {
  id: string;
  name: string;
  email: string;
  role: string;
}

const columns: DataTableColumn<User>[] = [
  { accessorKey: "name", header: "Name", enableSorting: true },
  { accessorKey: "email", header: "Email" },
  {
    accessorKey: "role",
    header: "Role",
    cell: (value) => <Badge variant={value === "admin" ? "default" : "outline"}>{value}</Badge>,
  },
];

<DataTable
  columns={columns}
  data={users}
  sorting
  pagination
  pageSize={25}
  selectable
  onRowClick={(user) => router.push(`/users/${user.id}`)}
  virtualizeRows
  emptyMessage="No users found"
/>

Dialog

import {
  Dialog, DialogTrigger, DialogContent,
  DialogHeader, DialogTitle, DialogDescription, DialogFooter,
  Button,
} from "@novahelm/ui";

<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Edit Profile</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Edit Profile</DialogTitle>
      <DialogDescription>Update your account details.</DialogDescription>
    </DialogHeader>
    {/* form fields */}
    <DialogFooter>
      <Button type="submit">Save</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

Toast Notifications

import { toast, Toaster } from "@novahelm/ui";

// Add <Toaster /> once at your app root
<Toaster />

// Trigger toasts anywhere
toast("Item saved successfully");
toast.error("Something went wrong");
toast.promise(saveData(), {
  loading: "Saving...",
  success: "Saved!",
  error: "Failed to save",
});

Hooks

| Hook | Description | |------|-------------| | useTheme() | Access current theme and toggle dark/light mode | | useSidebar() | Control sidebar open/collapsed state | | useControllableState() | Controlled/uncontrolled state helper | | useMediaQuery() | Responsive breakpoint detection | | useMounted() | SSR-safe mounted check | | useCallbackRef() | Stable callback reference | | useToasts() | Programmatic toast access |

Component Registry

Register and resolve components dynamically at runtime:

import { registerComponent, getComponent, hasComponent } from "@novahelm/ui";

// Register a custom component
registerComponent("my-widget", MyWidgetComponent);

// Resolve at runtime
const Widget = getComponent("my-widget");
if (Widget) {
  return <Widget {...props} />;
}

Utilities

import { cn } from "@novahelm/ui";

// Merge Tailwind classes with conflict resolution (clsx + tailwind-merge)
const className = cn("px-4 py-2 bg-primary", isActive && "bg-primary/90", className);

API Reference

| Export | Description | |--------|-------------| | cn(...inputs) | Tailwind class merge utility | | ThemeProvider | Theme context provider | | useTheme() | Theme hook (theme, setTheme, resolvedTheme) | | defineTheme(config) | Create a custom theme | | createNovaPreset() | Tailwind CSS 4 preset | | presets | All built-in theme presets | | defineComponentMeta(meta) | Register component metadata | | componentRegistry | Component metadata registry | | registerComponent(name, component) | Register a runtime component | | getComponent(name) | Resolve a registered component | | buttonVariants(props) | Button CVA variant helper | | alertVariants(props) | Alert CVA variant helper | | toggleVariants(props) | Toggle CVA variant helper | | segmentedControlVariants(props) | SegmentedControl CVA variant helper |