@tale-ui/react
v1.3.48
Published
Styled React component library built on React Aria Components, themed with @tale-ui/core design tokens.
Downloads
989
Maintainers
ndrewtranReadme
@tale-ui/react
An accessible React component library built on React Aria Components, with BEM class names applied automatically. Styles and design tokens are included — one package, one style import.
Installation
npm install @tale-ui/reactThis single install pulls in @tale-ui/react-styles (component CSS) and @tale-ui/core (design tokens) automatically.
Peer dependencies: react and react-dom (^17, ^18, or ^19).
AI agent setup (optional)
If you use Claude Code or other AI coding agents, run this once to add component documentation instructions to your project:
npx tale-ui-setupThis creates or updates your CLAUDE.md with instructions that tell the agent how to use Tale UI components correctly.
Quick Start
/* app root CSS */
html {
font-size: 62.5%; /* Required — design tokens assume 1rem = 10px */
}
body {
background-color: var(--neutral-5); /* Required — base page background */
}import '@tale-ui/react/styles'; // tokens + all component CSS — import once
import { Button } from '@tale-ui/react/button';
export default function App() {
return <Button variant="primary" size="md">Click me</Button>;
}
// Renders: <button class="tale-button tale-button--primary tale-button--md">Click me</button>Critical Setup Details
Base font size — The design system requires html { font-size: 62.5%; } so that 1rem = 10px. Without this, all spacing and sizing will be wrong.
Page background — Set body { background-color: var(--neutral-5); }. This is the standard base surface colour and inverts automatically in dark mode.
Dark mode — Set data-color-mode="dark" on <html>. All --neutral-* and --color-* tokens invert automatically. Always toggle between "dark" and "light" — never remove the attribute. Removing it falls back to OS preference via prefers-color-scheme, which may not be what the user chose.
<html class="tale-ui" data-color-mode="dark">Token rule — Always use --color-* (not --brand-*) in component and app CSS. --brand-* is palette-only and does NOT invert in dark mode.
/* Correct */
.my-card { background: var(--color-60); color: var(--color-60-fg); }
/* Wrong — will break in dark mode */
.my-card { background: var(--brand-60); }Components
All components are imported from @tale-ui/react/{name}:
import { Button } from '@tale-ui/react/button';
import { Input } from '@tale-ui/react/input';
import { Dialog } from '@tale-ui/react/dialog';
import { Select } from '@tale-ui/react/select';
import { Checkbox } from '@tale-ui/react/checkbox';Form Controls
Autocomplete · Button · Checkbox · Checkbox Group · Combobox · Input · Input Group · Input Tags · Multi Select · Number Field · Payment Input · Pin Input · Radio · Radio Group · Search Field · Select · Select Native · Slider · Switch · Tag Select · Text Area · Text Field · Toggle Button · Toggle Button Group
Date & Time
Calendar · Date Field · Date Picker · Date Range Picker · Range Calendar · Time Field
Color
Color Area · Color Field · Color Picker · Color Slider · Color Swatch · Color Swatch Picker · Color Wheel
Overlay
Alert Dialog · Dialog · Drawer · Popover · Preview Card · Tooltip
Navigation
Breadcrumbs · Context Menu · Header Nav · Link · Menu · Menubar · Navigation Menu · Pagination · Pagination Dot · Pagination Line · Sidebar
Layout
Accordion · Card · Carousel · Column · Disclosure · Row · Scroll Area · Separator · Tabs · Toolbar
Feedback
Banner · Meter · Progress Bar · Progress Circle · Spinner
Display
Avatar (with Group, Count, Indicator, and LabelGroup) · Badge · Dot Icon · Empty State · Featured Icon · Grid List · Image · List · QR Code · Rating Badge · Rating Stars · Table · Tag Group · Tree · Video Player
Form Structure
Field · Fieldset · Form
Interaction
Drop Zone · File Trigger · File Upload · Image Cropper · Text Editor
Marketing
App Store Button · Social Button · Social Button Group · Badge Group · Section Divider · Background Pattern · Illustration · Iphone Mockup · Credit Card
Typography
Text
Utilities
Color Mode Toggle · Container · CSP Provider · I18n Provider · Icon · IconButton · mergeProps
Styling
Components apply BEM base class names automatically. Variant and size props map to BEM modifiers:
<Button variant="primary" size="sm">Save</Button>
// → class="tale-button tale-button--primary tale-button--sm"State is exposed via data attributes (data-disabled, data-open, data-selected, data-pressed, data-focus-visible, data-focused, data-hovered, data-entering, data-exiting, data-placement) for CSS selectors.
Custom Theme
Create a tale-ui-overrides.css file in your project (next to your app entry):
/* tale-ui-overrides.css
*
* Paste your generated theme from https://tale-ui.github.io/core/scale
* This file overrides the default --brand-* palette tokens.
* Import AFTER @tale-ui/react/styles so overrides take effect.
*/Import it after the Tale UI styles:
import '@tale-ui/react/styles';
import './tale-ui-overrides.css'; // your custom theme — must come afterTo generate a theme, visit https://tale-ui.github.io/core/scale, configure your colour scale, and paste the generated CSS into tale-ui-overrides.css. Dark mode inversion works automatically — you only define the light-mode palette.
If the generated CSS includes foreground pivot overrides (.tale-ui selectors), add class="tale-ui" to your <html> element:
<html class="tale-ui" data-color-mode="light">Per-component CSS Imports
For smaller bundles, import individual component styles instead of the all-in-one:
import '@tale-ui/core'; // tokens — required when using per-component imports
import '@tale-ui/react-styles/button';
import '@tale-ui/react-styles/dialog';Documentation
For the complete guides on typography, colour system, dark mode, component composition patterns, accessibility, and framework integration:
- React setup guide — full consumer walkthrough
- Design tokens reference — every CSS class, token, and valid value
- Design philosophy — architectural decisions
- Component authoring — contributor guide
Per-component documentation
Each component has a detailed usage guide with imports, sub-parts, props, and examples. Fetch the doc for any component by name:
https://raw.githubusercontent.com/Tale-UI/core/main/docs/components/{name}.mdFor example: button.md, dialog.md, select.md, checkbox.md, tabs.md, table.md, date-picker.md.
License
MIT