@loke/ui
Headless UI primitives, hooks, and utility functions for building accessible interfaces.
@loke/ui
@loke/ui is a comprehensive toolkit of unstyled, accessible React components and utilities that power the LOKE Design System. It provides the behavior and accessibility foundation without any visual opinions, giving you complete control over styling and design.
Use @loke/ui when you need low-level control over appearance, are building highly specialized components, or want to avoid design-system dependencies in utility libraries.
Philosophy
- Headless: Components provide behavior and accessibility; you bring the styles.
- Accessible by default: Every primitive follows WAI-ARIA patterns, includes full keyboard support, and is tested with screen readers.
- Framework-agnostic utilities: Hooks and lib utilities work anywhere React is used, not just within design-system components.
- Composable: Build complex widgets by combining simpler primitives and utilities.
- Typed: Full TypeScript support with predictable, documented APIs.
When to use @loke/ui vs @loke/design-system
| Scenario | Use @loke/design-system | Use @loke/ui |
|---|---|---|
| Building a standard button, card, or input | ✓ | — |
| Need pre-made, consistent styling | ✓ | — |
| Building a standard form | ✓ | — |
| Need complete styling control | — | ✓ |
| Building a specialized component (rich editor, custom select) | — | ✓ |
| Avoiding design-system dependencies | — | ✓ |
| Learning or prototyping interaction patterns | — | ✓ |
When in doubt, start with @loke/design-system. Use primitives when you have a specific reason to customize.
What's included
Primitives
26 unstyled, accessible headless components that form the foundation of @loke/design-system. Components like Dialog, Popover, Accordion, Tabs, and others provide complete behavior and accessibility with zero styling assumptions.
Use when: You need custom styling, building specialized components, or want to understand how the design system components work.
Hooks
Small, focused React hooks for common UI patterns: state management (controlled/uncontrolled), DOM measurement, keyboard handling, environment detection, and accessibility. Hooks can be used independently from primitives.
Use when: Building custom components, need a specific behavior pattern, or integrating with your own UI framework.
Lib
Framework-agnostic utility functions and low-level primitives for building accessible components: context creation, event composition, ref composition, DOM measurement, focus management, dismissable layers, and number utilities.
Use when: Building component libraries, need fine-grained control over interactions, or want reusable utilities for complex widgets.
Install
bun add @loke/uiImport patterns
Import from granular entry points for best tree-shaking:
// Primitives
import { Dialog, DialogTrigger, DialogContent } from '@loke/ui/dialog';
import { Accordion, AccordionItem, AccordionTrigger } from '@loke/ui/accordion';
// Hooks
import { useControllableState } from '@loke/ui/use-controllable-state';
import { useMobile } from '@loke/ui/use-mobile';
// Lib
import { createContext } from '@loke/ui/context';
import { composeRefs } from '@loke/ui/compose-refs';Never import from the package root; use specific subpaths.
Design System Components: If you want pre-styled, ready-to-use components, see @loke/design-system. Those components are built on top of these primitives and handle all the styling for you.
Where to start
- Building a custom component? Start with Primitives to understand what's available and how components compose.
- Need a specific behavior? Check Hooks for state management, keyboard handling, or environment detection.
- Building a component library? Explore Lib utilities for context, event composition, and DOM utilities.