| name | reablocks |
| description | Use when building UI in React with the reablocks component library (Button, Dialog, Drawer, Select, Calendar, CommandPalette, Tabs, Tree, Tooltip, etc.). Covers ThemeProvider setup, extendTheme, custom variants, mergeThemeClasses, useComponentTheme/useTheme hooks, and the 50+ component index. |
Reablocks
Reablocks is a React UI component library with 50+ components built on Tailwind CSS and Framer Motion. It provides a comprehensive theming system, accessible components, and consistent design patterns.
Installation
npm install reablocks
ThemeProvider Setup
Every app using reablocks must be wrapped in a ThemeProvider:
import { ThemeProvider, theme } from 'reablocks';
function App() {
return (
<ThemeProvider theme={theme}>
<YourApp />
</ThemeProvider>
);
}
ThemeProvider Props
| Prop | Type | Required | Description |
|---|
theme | ReablocksTheme | Yes | The theme to apply |
Built-in Themes
Reablocks ships two theme options:
theme — standard theme using Tailwind utility classes. The default. Use this unless the user asks for Unify.
- Unify Theme — design-system theme built on a three-level token architecture (primitives → semantic → Tailwind), synced with the Unify Figma library. Available in two flavors:
- Quick-start:
themeUnify export + reablocks/unify.css import (one-line setup, fixed tokens).
- Production / Figma-synced: the single-file
themeUnify.ts download (every component theme + composed ReablocksTheme) plus CSS layers (root.css / dark.css / light.css / tw.css) generated by the Reablocks Figma Plugin. This is what powers per-component detail tokens like --buttons-details-height-core-icon-lg.
import { ThemeProvider, theme } from 'reablocks';
<ThemeProvider theme={theme}>...</ThemeProvider>
import { ThemeProvider, themeUnify } from 'reablocks';
import 'reablocks/unify.css';
<ThemeProvider theme={themeUnify}>...</ThemeProvider>
When to use Unify instead of the default theme
Switch to Unify when any of these apply:
- The user mentions Figma, the Unify Figma library, or the Reablocks Figma Plugin.
- The user wants tokens synced end-to-end from Figma to production.
- The user wants to re-skin components at fine granularity (per-component dimensions, radii, padding) without writing Tailwind overrides or per-component TypeScript.
- The user references
themeUnify.ts, root.css / dark.css / light.css / tw.css, or per-component detail tokens like --buttons-details-*, --inputs-details-*, --tabs-details-*.
For the quick-start path (single import, no Figma): use themeUnify as shown above. No further setup required.
For the production / Figma-synced path (single-file themeUnify.ts + Figma-generated CSS layers, customization via CSS, designer ↔ engineer sync): see the dedicated skill at unify-theme/SKILL.md. It covers:
- Prerequisites (Tailwind v4+, postcss plugins)
- File layout (
root.css / dark.css / light.css / tw.css / common.css)
- Three-tier token architecture and how it cascades
- Re-branding via the primitive color scale
- Per-component tuning without TypeScript changes
- Adding new semantic roles
- Troubleshooting (purge issues, token override order, palette leaks)
Do not offer Unify when the user only wants minor color/variant tweaks — extendTheme(theme, …) against the default theme is simpler. Do not offer Unify when the user is not on Tailwind v4+ or reablocks v10+.
Theme Customization
extendTheme
Use extendTheme() to deep-merge partial overrides into a base theme. Only specify the properties you want to change:
import { ThemeProvider, theme, extendTheme, PartialReablocksTheme } from 'reablocks';
const customTheme: PartialReablocksTheme = {
components: {
button: {
colors: {
primary: {
filled: 'bg-blue-500 hover:bg-blue-600 text-white'
}
}
}
}
};
<ThemeProvider theme={extendTheme(theme, customTheme)}>
<App />
</ThemeProvider>
Adding a Custom Variant
You can extend any component with new variants and colors. Only provide the keys you want to add — existing values remain intact:
import { ThemeProvider, theme, extendTheme, PartialReablocksTheme } from 'reablocks';
const customTheme: PartialReablocksTheme = {
components: {
button: {
variants: {
gradient: 'border rounded-lg'
},
colors: {
primary: {
gradient: 'bg-linear-to-r from-blue-500 to-purple-500 border-blue-500 text-white'
},
secondary: {
gradient: 'bg-linear-to-r from-pink-500 to-purple-500 border-pink-500 text-white'
}
}
}
}
};
<ThemeProvider theme={extendTheme(theme, customTheme)}>
{/* Use the new variant just like built-in ones */}
<Button variant="gradient" color="primary">Gradient Primary</Button>
<Button variant="gradient" color="secondary">Gradient Secondary</Button>
</ThemeProvider>
The same pattern works for adding custom colors, sizes, or entirely new theme keys to any component.
mergeThemeClasses
By default, extendTheme replaces theme string values. To merge Tailwind classes (append instead of replace), pass mergeThemeClasses as the third argument:
import { extendTheme, mergeThemeClasses, theme } from 'reablocks';
const merged = extendTheme(theme, customTheme, mergeThemeClasses);
extendComponentTheme
Extend a single component's theme:
import { extendComponentTheme, defaultButtonTheme } from 'reablocks';
const myButtonTheme = extendComponentTheme(defaultButtonTheme, {
sizes: { xlarge: 'text-xl px-6 py-3' }
});
Theme Types
Reablocks exports several utility types for typing partial themes:
PartialReablocksTheme — DeepPartial<ReablocksTheme>, ideal for extendTheme(theme, ...) overrides
DeepPartial<T> — recursive Partial<T>, useful for typing custom component theme fragments
import type { DeepPartial, PartialReablocksTheme } from 'reablocks';
import type { ButtonTheme } from 'reablocks';
const myButton: DeepPartial<ButtonTheme> = {
sizes: { xlarge: 'text-xl px-6 py-3' }
};
Theme Hooks
useComponentTheme
Get a specific component's theme from context. Pass an optional custom theme to override:
import { useComponentTheme } from 'reablocks';
function MyComponent({ theme: customTheme }) {
const theme = useComponentTheme('button', customTheme);
return <button className={theme.base}>...</button>;
}
useTheme
Access the full theme context including CSS tokens and runtime updates:
import { useTheme } from 'reablocks';
function MyComponent() {
const { theme, tokens, updateTheme, updateTokens } = useTheme();
}
Common Component Patterns
When working with reablocks components, follow these conventions:
- Import from barrel: Always
import { Component } from 'reablocks'
- forwardRef: All components use
forwardRef and accept a ref prop
- className: Components accept
className which is merged last (highest priority) via cn() (tailwind-merge)
- theme prop: Components accept a
theme prop for per-instance theme override
- cn() utility: Use
cn() for Tailwind class merging — combines classnames + tailwind-merge to deduplicate/resolve conflicts
- Animations: Framer Motion powers animations; use
animated prop (boolean) to toggle
- Controlled/Uncontrolled: Form components support both patterns
ReablocksTheme Component Keys
The theme.components object contains theme configs for every component:
avatar, avatarGroup, badge, button, chip, checkbox, contextMenu,
dateFormat, dialog, divider, dotsLoader, drawer, ellipsis, field,
select, list, menu, sort, card, kbd, notification, input, dateInput,
calendar, calendarRange, commandPalette, collapse, textarea, radio,
range, redact, toggle, tooltip, tree, jsonTree, popover, pager,
tabs, breadcrumbs, stepper, callout, backdrop, navigation, skeleton,
typography
Component Index
Elements
Avatar, AvatarGroup, Badge, Button, Chip, CommandPalette, IconButton, Kbd, Loader, Navigation, Skeleton
Form
Calendar, Checkbox, DateInput, Input (DebouncedInput, InlineInput), Radio, Range, Select (SingleSelect, MultiSelect), Textarea, Toggle
Layout
Breadcrumbs, Card, Collapse, Divider, Field, List, Motion, Stepper, Tabs, Tree
Layers
Backdrop, Callout, ConfirmDialog, ContextMenu, Dialog, Drawer, Menu, Notification, Popover, Tooltip
Typography
H1, H2, H3, H4, H5, H6, P, BlockQuote, Lead, Large, Small, Muted
Data
DataSize, DateFormat, Duration, Ellipsis, InfinityList, Pager, Pluralize, Redact, Sort