Skip to content

README.md

Latest commit

 

History

History
191 lines (145 loc) · 4.05 KB

README.md

File metadata and controls

191 lines (145 loc) · 4.05 KB

@spacedrive/primitives

Primitive UI components built on Radix UI with Tailwind CSS styling.

Installation

bun add @spacedrive/primitives @spacedrive/tokens
# or
npm install @spacedrive/primitives @spacedrive/tokens

Peer dependencies:

  • react ^18.0.0 || ^19.0.0
  • react-dom ^18.0.0 || ^19.0.0
  • tailwindcss ^4.1.0

Setup

  1. Configure your CSS entrypoint

    @import '@spacedrive/tokens/theme';

  2. Import CSS

    @import '@spacedrive/tokens/css';

Usage

import { Button, Card, Dialog, Input, Badge } from '@spacedrive/primitives';

function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Welcome</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <Input placeholder="Enter your name" />
        <Button>Get Started</Button>
      </CardContent>
    </Card>
  );
}

Components

Interactive

  • Button - Multiple variants (default, subtle, outline, dotted, gray, accent, colored, bare)
  • Input - Form input with error states
  • Checkbox - Accessible checkbox with Radix
  • Switch - Toggle switch with 3 sizes
  • Slider - Range slider with marks support
  • RadioGroup - Radio button groups

Overlay

  • Dialog - Modal dialogs with animations
  • Popover - Floating content panels
  • Tooltip - Hover tooltips
  • DropdownMenu - Contextual menus
  • ContextMenu - Right-click menus

Navigation

  • Tabs - Tabbed interfaces
  • Select - Dropdown selects
  • Dropdown - Simple expanding dropdowns

Display

  • Badge - Status badges (6 variants, 2 sizes)
  • Card - Container with header/content/footer
  • Banner - Alert banners (5 variants)
  • Toast - Notification toasts
  • Loader - Loading spinners and dots
  • Divider - Horizontal/vertical dividers
  • Typography - Text components (6 heading, 3 body)
  • Shortcut - Keyboard shortcut display

Form

  • NumberStepper - Increment/decrement with min/max
  • FilterButton - Toggle buttons for filters
  • ToggleGroup - Radio-like button groups
  • SearchBar - Search inputs with icons

Progress

  • ProgressBar - Linear progress (with variants)
  • CircularProgress - Circular/spinner progress

Layout

  • Resizable - Resizable panel groups
  • Collapsible - Expand/collapse sections
  • TopBarButton - Top bar navigation buttons

Component API

All components follow consistent patterns:

Variants with CVA

Components use class-variance-authority for variants:

import { buttonVariants } from '@spacedrive/primitives';

// Use variants directly
<button className={buttonVariants({ variant: 'subtle', size: 'sm' })}>
  Small Subtle
</button>

Ref Forwarding

All interactive components support ref forwarding:

import { useRef } from 'react';
import { Button } from '@spacedrive/primitives';

function MyComponent() {
  const buttonRef = useRef<HTMLButtonElement>(null);
  return <Button ref={buttonRef}>Click me</Button>;
}

ClassName Composition

Components compose className with internal styles:

<Button className="w-full mt-4">
  {/* Classes are merged: internal + "w-full mt-4" */}
</Button>

Design Principles

  1. Accessible - Built on Radix UI primitives
  2. Composable - Small, focused components that compose
  3. Theme-agnostic - Uses semantic color classes
  4. No business logic - Purely presentational
  5. Type-safe - Full TypeScript support

Customization

Overriding Styles

Use Tailwind classes to override:

<Button 
  variant="default"
  className="bg-purple-500 hover:bg-purple-600"  {/* Override colors */}
>
  Custom Button
</Button>

Creating Variants

Extend CVA variants:

import { cva } from 'class-variance-authority';

const myButtonVariants = cva(
  'base-styles',
  {
    variants: {
      size: {
        xs: 'px-2 py-1 text-xs',
        xl: 'px-6 py-3 text-lg',
      }
    }
  }
);

Browser Support

  • Chrome/Edge 88+
  • Firefox 78+
  • Safari 14+

Requires CSS custom properties support.

License

MIT © Spacedrive