@kala-ui/react

Standard UI components for Kala UI — the design-system vocabulary: primitives, form controls, overlays and menus, built with Radix UI and Tailwind CSS.

~90 accessible, production-ready components. App-level composites (AppShell, DataTable, charts, drag-and-drop) live in @kala-ui/react-app, which depends on this package.

Installation

npm install @kala-ui/react@beta
# optional: app-level composites
npm install @kala-ui/react-app@beta

Requires React 19.2+. The @kala-ui/react-hooks dependency installs automatically.

Import the compiled stylesheet once (no Tailwind required in your app):

@import "@kala-ui/react/styles";
/* @import "@kala-ui/react-app/styles"; */ /* after core, if used */

Usage

import { Button } from "@kala-ui/react/button";
import { Input } from "@kala-ui/react/input";
import { Dialog } from "@kala-ui/react/dialog";
import { cn } from "@kala-ui/react/lib/utils";

Every component has a subpath export (@kala-ui/react/<component>) plus the barrel (@kala-ui/react).

Component catalog

• Layout: box, flex, grid, stack, group, center, container, paper, aspect-ratio, overlay, separator, resizable, scroll-area, collapsible, collapse, accordion, tabs
• Typography: text, heading, code, kbd
• Buttons & toggles: button, button-group, copy-button, burger, toggle, toggle-group, toolbar, segmented-control
• Forms: input, textarea, number-input, input-group, input-otp, label, field, checkbox, radio-group, switch, slider, select, native-select, combobox, multi-select, calendar, date-picker, time-picker, color-input, tag-input, file-upload, password-strength-indicator, rating, command
• Display: avatar, avatar-group, badge, tag, card, indicator, spinner, skeleton, progress, ring-progress, banner, table, tree-view, list, timeline, steps, pagination, breadcrumbs
• Overlays & menus: dialog, alert-dialog, drawer, popover, hover-card, tooltip, dropdown-menu, context-menu, menubar, navigation-menu
• Feedback & utility: alert, empty-state, error-boundary, page-loader, section-loader, loading-overlay, spoiler, page-transition, skip-to-content, toast, theme-provider, kala-provider

Theming

Four built-in themes (light, dark, high-contrast-light, high-contrast-dark), class-based dark mode, and a ThemeProvider that also accepts custom themes via registration. Every component reads CSS custom properties — override tokens on :root/.dark and the whole library follows. See THEMING.md.

:root {
  --primary: oklch(0.55 0.22 264);
  --primary-foreground: white;
}

Identifying components in the DOM

Every component renders a stable data-kala-component="<name>" attribute on its root element (compound parts carry their own name: dialog-content, card-header, data-table-toolbar, …). It is a public API kept stable across releases — use it for DevTools debugging, e2e selectors, and targeted consumer CSS:

// Playwright
await page.locator("[data-kala-component='button']").first().click();

/* targeted override without fighting utility classes */
[data-kala-component='card'] {
  --kala-radius-card: 0;
}

When components compose (a Card renders a Box), the most specific component's name wins. The data-slot attributes found on some parts are shadcn-compatible styling hooks kept for ecosystem CSS snippets; prefer data-kala-component for identification.

React Server Components

All component modules ship with a "use client" banner, so they import cleanly into RSC apps (dist/lib stays server-safe for cn()).

Development

pnpm storybook        # composed dev Storybook (core + app stories)
pnpm test             # unit tests (vitest + testing-library)
pnpm type-check       # tsc --noEmit
pnpm lint             # biome
pnpm build            # tsc + postbuild + compiled CSS

Credits

• Radix UI — unstyled, accessible UI primitives
• Tailwind CSS — utility-first CSS
• Vaul, Sonner, cmdk, react-day-picker, framer-motion

See the Storybook documentation for complete interactive docs.