@brightlocal/ui-components

BrightLocal Design System UI Components package containing low-level React components and utilities built on top of Radix UI primitives.

Installation

pnpm add @brightlocal/ui-components

Peer Dependencies

This package requires React 18 or 19 and Tailwind CSS v4:

pnpm add react react-dom tailwindcss @tailwindcss/vite

You also need the BrightLocal design tokens for theming:

pnpm add @brightlocal/tokens

Components

This package includes 62 components and 3 blocks built on Radix UI primitives and other React libraries. All components are fully typed with TypeScript and follow BrightLocal's design system patterns.

Layout Components

• AspectRatio - Maintains consistent aspect ratios for content
• Card - Container for content with consistent styling
• CentredLayout - Centers content horizontally
• GlobalLayout - Full-page layout wrapper
• ResizablePanel - Panels that can be resized by users
• ScrollArea - Custom scrollable areas with styled scrollbars
• Separator - Visual dividers between content
• Skeleton - Loading placeholder components
• SplitLayout - Split-pane layouts

Navigation Components

• Breadcrumb - Hierarchical navigation trail
• Link - Styled anchor links
• NavigationMenu - Complex navigation menus
• Menubar - Application menu bars
• Pagination - Page navigation controls
• Tabs - Tabbed interface components

Form Components

• Button - Interactive buttons with variants
• Calendar - Date selection calendar
• Checkbox - Checkbox inputs
• Combobox - Searchable select inputs
• DatePicker - Date picker with calendar
• Field - Form field wrapper with label and error handling
• Input - Text input fields
• InputBase - Base input component
• InputGroup - Grouped input components
• InputOTP - One-time password inputs
• Label - Form labels
• InputPassword - Password input with visibility toggle
• RadioGroup - Radio button groups
• Rating - Star rating input
• Select - Dropdown select inputs
• Slider - Range slider inputs
• Switch - Toggle switches
• Textarea - Multi-line text inputs
• Toggle - Toggle buttons
• ToggleGroup - Groups of toggle buttons

Overlay Components

• AlertDialog - Modal dialogs for confirmations
• ContextMenu - Right-click context menus
• Dialog - Modal dialogs
• Drawer - Side drawer panels
• DropdownMenu - Dropdown menus
• HoverCard - Popover cards on hover
• Popover - Floating popovers
• Sheet - Slide-in panels
• Tooltip - Tooltips on hover

Feedback Components

• Alert - Alert messages
• Badge - Status badges and labels
• Progress - Progress indicators
• Sonner - Toast notifications

Block Components

• DataTable - Complex data table with sorting, filtering, and pagination
• InputList - Editable list of text items with add/remove, paste support, and validation
• Sidebar - Complex sidebar navigation with collapsible support

Display Components

• Accordion - Expandable/collapsible sections
• Avatar - User avatar images
• Carousel - Image/content carousels
• Chart - Data visualization charts
• Collapsible - Collapsible content sections
• Command - Command palette/search
• Logo - BrightLocal logo component
• Table - Data tables
• Typography - Text styling components (headings, paragraphs, blockquotes, lists)

Example Usage

import { Button } from "@brightlocal/ui-components/button";
import { Input } from "@brightlocal/ui-components/input";
import { Card } from "@brightlocal/ui-components/card";

function MyComponent() {
  return (
    <Card dataHook="example-card">
      <Input dataHook="name-input" placeholder="Enter your name" />
      <Button dataHook="submit-button">Submit</Button>
    </Card>
  );
}

For detailed component APIs and props, refer to the TypeScript definitions included with this package.

Hooks

useIsMobile

A React hook to detect mobile breakpoints.

import { useIsMobile } from "@brightlocal/ui-components/hooks/use-mobile";

function MyComponent() {
  const isMobile = useIsMobile();

  return <div>{isMobile ? "Mobile View" : "Desktop View"}</div>;
}

Features:

• Uses 768px as the mobile breakpoint
• Returns boolean | undefined (undefined during hydration)
• Automatically updates on window resize
• Uses window.matchMedia for efficient media query listening

Utilities

cn (Class Name Utility)

A utility function for conditionally joining class names.

import { cn } from "@brightlocal/ui-components/lib/utils";

// Usage
const className = cn(
  "base-class",
  condition && "conditional-class",
  { "object-class": someCondition },
  ["array", "of", "classes"]
);

TypeScript Support

This package is written in TypeScript and provides full type definitions. All components include proper typing for props and data hooks with template literal types for better type safety.

Data Hooks

All components in this package follow the BrightLocal data hook pattern:

• Components require dataHook props for testing and automation
• Data hooks follow specific naming patterns (e.g., ${string}-collapsibleTrigger)
• Template literal types ensure correct data hook formatting

Styling & Theming

Styling Approach

Components use a modern, flexible styling system:

• Tailwind CSS - Utility-first CSS classes for rapid styling
• CSS Custom Properties - For dynamic theming and customization
• Data Attributes - data-slot attributes for component part identification
• Class Variance Authority - For component variants and states

Tailwind CSS v4 Setup

This package uses Tailwind CSS utility classes internally. In Tailwind CSS v4, node_modules are not scanned by default, so you need to import the package's source declaration in your main CSS file:

@import "tailwindcss";
@import "@brightlocal/ui-components";

This tells Tailwind to scan the package's compiled output for utility classes, ensuring all component styles are generated correctly.

Note: If you're using Tailwind CSS v3, configure the content array in your tailwind.config.js instead:

module.exports = {
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@brightlocal/ui-components/dist/**/*.js",
  ],
};

Theming & Customization

All components are built to be themeable using CSS custom properties. You can customize the look and feel by overriding CSS variables in your application:

:root {
  /* Customize colors, spacing, borders, etc. */
  --radius: 0.5rem;
  --primary: 210 100% 50%;
  --foreground: 222.2 84% 4.9%;
}

.dark {
  /* Dark mode overrides */
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
}

Dark Mode Support

Components support dark mode through CSS custom properties and the dark class. Implement dark mode in your application by:

1. Adding the dark class to your root element
2. Defining dark mode color values in your CSS
3. Using the Tailwind dark: modifier for custom styles

Custom Styling

You can customize individual components using:

• className prop - Pass additional Tailwind classes
• CSS modules - Target data-slot attributes
• Wrapper components - Create your own component variants

// Using className prop
<Button className="bg-blue-600 hover:bg-blue-700">
  Custom Button
</Button>

// Creating a wrapper component
export function PrimaryButton(props) {
  return <Button className="bg-primary text-primary-foreground" {...props} />;
}

Accessibility

All components in this package are built with accessibility in mind, following WAI-ARIA best practices:

Keyboard Navigation

• All interactive components support full keyboard navigation
• Tab order follows logical flow through the interface
• Arrow keys navigate through menus, tabs, and other grouped elements
• Escape key closes overlays and dismisses dialogs
• Enter/Space activate buttons and toggles

Screen Reader Support

• Components use proper ARIA roles, labels, and attributes
• State changes are announced to screen readers
• Error messages and validation feedback are associated with form inputs
• Loading states and progress indicators are announced

Focus Management

• Focus indicators are clearly visible using :focus-visible patterns
• Focus is trapped in modal dialogs and drawers
• Focus returns to the trigger element when closing overlays
• Skip links and focus management for complex widgets

Color Contrast

• All text meets WCAG AA contrast requirements (4.5:1 for normal text)
• Interactive elements have sufficient contrast in all states
• Error states use multiple indicators (not just color)

Responsive Design

• Components work across all viewport sizes
• Touch targets meet minimum size requirements (44x44px)
• Mobile-specific patterns (like bottom sheets) for better mobile UX

Best Practices

When using these components:

1. Always provide labels - Use the Label component or aria-label
2. Include error messages - Associate errors with form fields using aria-describedby
3. Test with keyboard only - Ensure all functionality is accessible via keyboard
4. Test with screen readers - Verify announcements are meaningful
5. Maintain focus order - Keep tab order logical and predictable

// Good accessibility example
<Field>
  <Label htmlFor="email">Email Address</Label>
  <Input
    dataHook="email-input"
    id="email"
    type="email"
    aria-describedby="email-error"
    error={hasError}
  />
  {hasError && (
    <span id="email-error" role="alert">
      Please enter a valid email address
    </span>
  )}
</Field>

Available Exports

Components are exported per-file (not barrel imports). Use the component name in kebab-case:

import { Button } from "@brightlocal/ui-components/button";
import { Dialog, DialogContent, DialogTrigger } from "@brightlocal/ui-components/dialog";
import { DataTable } from "@brightlocal/ui-components/blocks/data-table";
import { useIsMobile } from "@brightlocal/ui-components/hooks/use-mobile";
import { cn } from "@brightlocal/ui-components/lib/utils";

| Path pattern | Example | |---|---| | @brightlocal/ui-components/{component} | /button, /input, /dialog, /select | | @brightlocal/ui-components/blocks/{block} | /blocks/data-table, /blocks/sidebar | | @brightlocal/ui-components/hooks/{hook} | /hooks/use-mobile | | @brightlocal/ui-components/lib/{util} | /lib/utils |

Dependencies

This package builds on:

• Radix UI - Accessible primitives (Dialog, Select, Tabs, Tooltip, etc.)
• Class Variance Authority - Component variant management
• Tailwind Merge - Intelligent class merging via cn() utility
• Framer Motion - Animation and transitions
• TanStack Table - Headless table utilities (DataTable block)
• Recharts - Chart visualizations (Chart component)
• react-day-picker - Calendar and date picking
• Embla Carousel - Carousel functionality
• Sonner - Toast notifications
• Vaul - Drawer component

AI Integration

This package ships with AI-friendly documentation:

• AI_USAGE.md — Rules, patterns, do's/don'ts, and composition examples for AI code generation
• component-meta.json — Machine-readable registry of all components with categories, variants, props, and relationships

These files help AI assistants generate code that follows BrightLocal Design System conventions out of the box.

Development

This package is part of the BrightLocal Design System monorepo. It publishes source files directly (no build step required) for maximum compatibility with consuming applications.

Bundle Size Monitoring

This package uses size-limit to monitor and prevent bundle size regressions.

Check bundle sizes:

# From ui-components directory
pnpm size

# From monorepo root
pnpm --filter @brightlocal/ui-components size

Analyze bundle composition:

# From ui-components directory
pnpm analyze

# From monorepo root
pnpm analyze

Bundle size limits:

• Main Bundle (ESM): 50 KB
• Main Bundle (CJS): 50 KB
• Total Dist Size: 500 KB

These limits are enforced to prevent performance regressions. If you need to increase the limits, update the size-limit configuration in package.json.

Repository

GitHub Repository

License

MIT