@brightlocal/ui-components

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

Installation

``bash
npm install @brightlocal/ui-components
`

Peer Dependencies

This package requires React 17+ or 18+ or 19+:

`bash
npm install react react-dom
`

Components

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

$3

- 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

$3

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

$3

- 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

$3

- 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

$3

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

$3

- 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

$3

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

function MyComponent() {
return (


Submit

);
}
`

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

Hooks

$3

A React hook to detect mobile breakpoints.

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

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

return

;
}
`

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

$3

A utility function for conditionally joining class names.

`tsx
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

$3

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

$3

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:

`css
: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%;
}
`

$3

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

$3

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

`tsx
// Using className prop

Custom Button


// Creating a wrapper component
export function PrimaryButton(props) {
return ;
}
`

Accessibility

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

$3

- 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

$3

- 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

$3

- 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

$3

- 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)

$3

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

$3

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

`tsx
// Good accessibility example

Email Address
dataHook="email-input"
id="email"
type="email"
aria-describedby="email-error"
error={hasError}
/>
{hasError && (

Please enter a valid email address

)}

`

Available Exports

- @brightlocal/ui-components/collapsible - Collapsible components
- @brightlocal/ui-components/scroll-area - ScrollArea components
- @brightlocal/ui-components/hooks/use-mobile - Mobile detection hook
- @brightlocal/ui-components/lib/utils - Utility functions

Dependencies

This package builds on:

- @radix-ui/react-collapsible - Collapsible primitive
- @radix-ui/react-scroll-area - ScrollArea primitive

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.

$3

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

Check bundle sizes:

`bash


From ui-components directory

pnpm size

From monorepo root

pnpm --filter @brightlocal/ui-components size
`

Analyze bundle composition:

`bash


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