Skip to main content

Overview

The @brainbox/ui package provides a comprehensive React component library for building Brainbox interfaces. Built on Radix UI primitives and styled with TailwindCSS v4, it offers accessible, customizable components.

Installation

npm install @brainbox/ui

Dependencies

  • React 19
  • Radix UI primitives
  • TailwindCSS v4
  • Framer Motion (animations)
  • TipTap (rich text editing)
  • Lucide React (icons)

Core Components

Buttons

Button

Primary button component with variants and sizes.
variant
'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'
default:"'default'"
Visual style variant
size
'default' | 'sm' | 'lg' | 'icon' | 'icon-sm' | 'icon-lg'
default:"'default'"
Button size
asChild
boolean
default:"false"
Render as child component (Slot pattern)
import { Button } from '@brainbox/ui';

<Button variant="default">Save</Button>
<Button variant="destructive">Delete</Button>
<Button variant="outline" size="sm">Cancel</Button>
<Button variant="ghost" size="icon"><SearchIcon /></Button>

Dialogs

Dialog

Modal dialog with overlay and animations.
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogFooter,
} from '@brainbox/ui';

<Dialog>
  <DialogTrigger asChild>
    <Button>Open Dialog</Button>
  </DialogTrigger>
  <DialogContent size="md">
    <DialogHeader>
      <DialogTitle>Delete Page</DialogTitle>
      <DialogDescription>
        This action cannot be undone.
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <Button variant="outline">Cancel</Button>
      <Button variant="destructive">Delete</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
size
'sm' | 'md' | 'lg'
default:"'md'"
Dialog width (480px / 640px / 800px)
showCloseButton
boolean
default:"true"
Show close button in top-right

AlertDialog

Dialog for confirming destructive actions.
import {
  AlertDialog,
  AlertDialogTrigger,
  AlertDialogContent,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogCancel,
  AlertDialogAction,
} from '@brainbox/ui';

<AlertDialog>
  <AlertDialogTrigger asChild>
    <Button variant="destructive">Delete</Button>
  </AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This will permanently delete the page.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction>Continue</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

Forms

Input

Text input with validation states.
import { Input } from '@brainbox/ui';

<Input
  type="text"
  placeholder="Page name"
  aria-invalid={errors.name ? true : undefined}
/>

Textarea

Multi-line text input.
import { Textarea } from '@brainbox/ui';

<Textarea
  placeholder="Description"
  rows={4}
/>

Checkbox

Checkbox with label support.
import { Checkbox } from '@brainbox/ui';

<Checkbox
  checked={isChecked}
  onCheckedChange={setIsChecked}
/>

Form

Form components with react-hook-form integration.
import {
  Form,
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@brainbox/ui';
import { useForm } from 'react-hook-form';

const form = useForm();

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <FormField
      control={form.control}
      name="name"
      render={({ field }) => (
        <FormItem>
          <FormLabel>Name</FormLabel>
          <FormControl>
            <Input {...field} />
          </FormControl>
          <FormDescription>Display name for the page</FormDescription>
          <FormMessage />
        </FormItem>
      )}
    />
  </form>
</Form>
Contextual menu triggered by button.
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuLabel,
} from '@brainbox/ui';

<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="ghost" size="icon"><MoreIcon /></Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="end">
    <DropdownMenuLabel>Actions</DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuItem>Edit</DropdownMenuItem>
    <DropdownMenuItem>Duplicate</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem className="text-destructive">
      Delete
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

ContextMenu

Right-click context menu.
import {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuItem,
} from '@brainbox/ui';

<ContextMenu>
  <ContextMenuTrigger>
    <div>Right-click me</div>
  </ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem>Copy</ContextMenuItem>
    <ContextMenuItem>Paste</ContextMenuItem>
    <ContextMenuItem>Delete</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>

Overlays

Popover

Floating content overlay.
import {
  Popover,
  PopoverTrigger,
  PopoverContent,
} from '@brainbox/ui';

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">Open</Button>
  </PopoverTrigger>
  <PopoverContent>
    <div className="space-y-2">
      <h4 className="font-medium">Settings</h4>
      <p className="text-sm text-muted">Configure options</p>
    </div>
  </PopoverContent>
</Popover>

Tooltip

Hover tooltip with delay.
import {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  TooltipProvider,
} from '@brainbox/ui';

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <Button variant="ghost" size="icon"><InfoIcon /></Button>
    </TooltipTrigger>
    <TooltipContent>
      <p>Additional information</p>
    </TooltipContent>
  </Tooltip>
</TooltipProvider>

HoverCard

Rich hover preview card.
import {
  HoverCard,
  HoverCardTrigger,
  HoverCardContent,
} from '@brainbox/ui';

<HoverCard>
  <HoverCardTrigger asChild>
    <a href="#">@username</a>
  </HoverCardTrigger>
  <HoverCardContent>
    <div className="space-y-1">
      <h4 className="font-semibold">John Doe</h4>
      <p className="text-sm">Product Designer</p>
    </div>
  </HoverCardContent>
</HoverCard>

Layout

Tabs

Tabbed interface.
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@brainbox/ui';

<Tabs defaultValue="general">
  <TabsList>
    <TabsTrigger value="general">General</TabsTrigger>
    <TabsTrigger value="members">Members</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  <TabsContent value="general">
    General content
  </TabsContent>
  <TabsContent value="members">
    Members content
  </TabsContent>
</Tabs>

Separator

Visual divider.
import { Separator } from '@brainbox/ui';

<Separator orientation="horizontal" />
<Separator orientation="vertical" className="h-4" />

ScrollArea

Custom scrollbar container.
import { ScrollArea } from '@brainbox/ui';

<ScrollArea className="h-72">
  <div className="p-4">
    {/* Long content */}
  </div>
</ScrollArea>

Collapsible

Expandable/collapsible section.
import {
  Collapsible,
  CollapsibleTrigger,
  CollapsibleContent,
} from '@brainbox/ui';

<Collapsible>
  <CollapsibleTrigger asChild>
    <Button variant="ghost">Toggle</Button>
  </CollapsibleTrigger>
  <CollapsibleContent>
    <div className="p-4">
      Hidden content
    </div>
  </CollapsibleContent>
</Collapsible>

Feedback

Progress

Progress bar indicator.
import { Progress } from '@brainbox/ui';

<Progress value={65} />

Spinner

Loading spinner.
import { Spinner } from '@brainbox/ui';

<Spinner size="md" />

Badge

Status badge.
import { Badge } from '@brainbox/ui';

<Badge variant="default">New</Badge>
<Badge variant="secondary">Beta</Badge>
<Badge variant="destructive">Error</Badge>

Skeleton

Loading skeleton.
import { Skeleton } from '@brainbox/ui';

<Skeleton className="h-4 w-full" />
<Skeleton className="h-8 w-32 rounded-full" />

Animation Components

Motion Components

MotionDiv

Animated div with presets.
preset
'fadeIn' | 'slideIn' | 'scaleIn' | 'slideUp'
Animation preset
import { MotionDiv } from '@brainbox/ui';

<MotionDiv preset="fadeIn">
  Content
</MotionDiv>

AnimatePresence

Animate components on mount/unmount.
import { AnimatePresence, MotionDiv } from '@brainbox/ui';

<AnimatePresence>
  {isVisible && (
    <MotionDiv preset="fadeIn">
      Content
    </MotionDiv>
  )}
</AnimatePresence>

AnimatedList

Stagger animation for lists.
import { AnimatedList } from '@brainbox/ui';

<AnimatedList>
  {items.map((item) => (
    <div key={item.id}>{item.name}</div>
  ))}
</AnimatedList>

Motion Utilities

Pre-configured animation variants and transitions.
import { variants, transition } from '@brainbox/ui/lib/motion';

// Available variants
variants.fadeIn
variants.slideIn
variants.scaleIn
variants.slideUp

// Available transitions
transition.fast
transition.normal
transition.slow

Hooks

useReducedMotion

Detect user’s motion preference.
import { useReducedMotion } from '@brainbox/ui';

const Component = () => {
  const prefersReducedMotion = useReducedMotion();
  
  return (
    <MotionDiv
      animate={prefersReducedMotion ? {} : { opacity: 1 }}
    />
  );
};

Theme

ThemeProvider

Provides theme context (light/dark mode).
import { ThemeProvider } from '@brainbox/ui';

<ThemeProvider defaultTheme="system">
  <App />
</ThemeProvider>

ThemeToggle

Toggle between light/dark themes.
import { ThemeToggle } from '@brainbox/ui';

<ThemeToggle />

Utilities

cn

Merge Tailwind classes.
import { cn } from '@brainbox/ui/lib/utils';

const className = cn(
  'base-class',
  condition && 'conditional-class',
  'override-class'
);

Spacing

Standardized spacing values.
import { spacing } from '@brainbox/ui/lib/spacing';

spacing.xs  // 0.25rem
spacing.sm  // 0.5rem
spacing.md  // 1rem
spacing.lg  // 1.5rem
spacing.xl  // 2rem

Accessibility

All components follow WAI-ARIA best practices:
  • Full keyboard navigation support
  • Screen reader friendly
  • Focus management
  • ARIA attributes
  • Semantic HTML

Styling

Components use TailwindCSS v4 with design tokens:
/* Colors */
bg-bg-base          /* Base background */
bg-bg-elevated      /* Elevated surfaces */
bg-bg-muted         /* Muted backgrounds */

text-fg-default     /* Default text */
text-fg-muted       /* Muted text */
text-fg-on-accent   /* Text on accent */

border-border-default  /* Default borders */

/* Semantic colors */
bg-accent-default
bg-error
bg-success
bg-warning

Build docs developers (and LLMs) love