# Zen
> React components in dark glass: translucent surfaces, hairline borders that catch a pointer light, one accent colour. Tailwind v4, no runtime dependencies.
## Installation
```sh
pnpm add @rinzai/zen
```
React 19 is the only peer dependency.
**Using Tailwind CSS v4?** Add Zen's theme after Tailwind in your stylesheet. Your one Tailwind build then generates everything Zen's components use:
```css
@import 'tailwindcss';
@import '@rinzai/zen/tailwind.css';
```
**Not using Tailwind?** Import the complete stylesheet once, near the root of your app. It includes the default theme:
```js
import '@rinzai/zen/css';
```
Zen never styles your own elements. For its page setup (the background showing through), heading scale, inline code and quiet scrollbars, also add the optional base:
```css
@import '@rinzai/zen/base.css';
```
The look is set in [Geist](https://vercel.com/font); load it however you like.
## Usage
```tsx
import { Backdrop, Button, Card, CardHeader, CardTitle } from '@rinzai/zen';
export default function App() {
return (
<>
Budget
);
}
```
## Props
Every component takes `className`, and a class you pass always overrides the component's default. Other props (`id`, `aria-*`, `data-*`, handlers) and `ref` reach its element, and parts that render a link or button take `asChild` to use your own (a router's Link, say).
Zen exports no icons. Use any icon set (the examples use [Heroicons](https://heroicons.com)) and pass icons in as elements, such as `icon={}`.
## Values and forms
Controls report changes with `onValueChange` (`onCheckedChange` for Checkbox and Toggle). Pass `value` to control one, or `defaultValue` to let it keep its own. Give a control a `name` and it's submitted with its form, the custom ones (Combobox, the date pickers, MoneyInput, ColorPicker, TagInput…) included, and goes back to its first value when the form is reset.
## Languages and right to left
```tsx
import { LocaleProvider } from '@rinzai/zen';
;
```
The locale formats dates, numbers and money, and sets the week's first day. `messages` replaces any of the words Zen shows or announces (`ENGLISH` lists them all); the rest stay English. With `dir="rtl"` on the page or any element above, layout, arrow keys and chevrons mirror.
## Theming
Dark is the default. Add the `light` class (or `data-theme="light"`) for the light palette. Colours are OKLCH `L C H` triplets; override any token in your own CSS:
```css
:root {
--primary: 0.72 0.13 200; /* teal instead of violet */
--glow: 0.7 0.13 200;
}
```
Or generate a whole theme at runtime:
```ts
import { applyPreset, applyTheme, DEFAULT_THEME } from '@rinzai/zen';
applyTheme(applyPreset(DEFAULT_THEME, 'ocean'));
```
## Overlays
For a page composited over something else, such as an OBS browser source, which never gets a pointer:
```html
```
`data-zen-glow="ambient"` sends the edge light round each glowing border by itself (on any element, it does so for what's inside). `data-zen-page="transparent"` paints nothing behind the content; it needs the base stylesheet.
## Browser support
Chrome and Edge 114+, Safari 17+ and Firefox 128+: the versions with the native Popover API that popups, menus and toasts are built on, and with what Tailwind v4 needs.
- **Popups** are placed with CSS anchor positioning where the browser has it (Chrome 129+, Safari 26+, recent Firefox). Elsewhere Zen places them itself, the same way.
- **Glass** is blurred live where there's a GPU and a mouse. On touch screens, without hardware acceleration, and with the OS's "reduce transparency", surfaces are solid instead.
- **Motion** such as entry animations is left out where a browser lacks it, and for anyone who prefers reduced motion.
In a project with Zen installed, the same pages are in node_modules/@rinzai/zen/dist/docs, for the installed version. All of them in one file: https://zen.rinzai.dev/llms-full.txt. Showcase apps: a budget app at https://zen.rinzai.dev/showcase/ and a music player at https://zen.rinzai.dev/showcase/music/.
## Components
- [Accordion](https://zen.rinzai.dev/docs/accordion.md): Sections under headings that open one at a time, or several: questions and answers, or groups of settings.
- [Alert](https://zen.rinzai.dev/docs/alert.md): A notice, warning or failure beside what it is about: a tinted box, or a plain line in a form or card.
- [Animated Number](https://zen.rinzai.dev/docs/animated-number.md): Numbers and amounts that count smoothly to each new value.
- [Avatar](https://zen.rinzai.dev/docs/avatar.md): A round picture, or the name's initial on the glowing accent. With an in-browser crop for uploads.
- [Backdrop](https://zen.rinzai.dev/docs/backdrop.md): The page background: aurora glows over contours or dots, and a light that follows the pointer and catches card edges, or drifts round them by itself on pages with no pointer.
- [Badge](https://zen.rinzai.dev/docs/badge.md): A small label for status, counts and tags.
- [Breadcrumbs](https://zen.rinzai.dev/docs/breadcrumbs.md): Where a page sits: its parents as links, then the page itself. Works with any router.
- [Button](https://zen.rinzai.dev/docs/button.md): Actions, from the one glowing primary action to quiet ghost buttons.
- [Button Group](https://zen.rinzai.dev/docs/button-group.md): Buttons joined into one, rounded only at the ends: a split button, or Previous, Today and Next.
- [Calendar](https://zen.rinzai.dev/docs/calendar.md): A month grid to pick a date or a range, fully keyboard-driven, with limits, blocked days and a year view to jump far.
- [Calendar Heatmap](https://zen.rinzai.dev/docs/calendar-heatmap.md): A month of days shaded by their value, like spending per day.
- [Canvas](https://zen.rinzai.dev/docs/canvas.md): A fixed-size surface where items sit anywhere, like the cards of a stream overlay: drag, resize and select several, by pointer, touch or keyboard, with snapping, a grid, undo and a fit-to-width scale.
- [Card](https://zen.rinzai.dev/docs/card.md): Glass panels for grouping content, and stats for single figures.
- [Carousel](https://zen.rinzai.dev/docs/carousel.md): Slides in a row that snap as you swipe or scroll, with glass buttons and dots that light the current one beneath, and the arrow keys. Native scrolling, so it follows the finger exactly.
- [Chart](https://zen.rinzai.dev/docs/chart.md): Areas, lines and bars on one axis, a donut and an allocation bar: plain SVG that draws itself in, with a crosshair tooltip, keyboard reading, a legend and a table for screen readers.
- [Checkbox](https://zen.rinzai.dev/docs/checkbox.md): A native checkbox whose tick draws itself in, with a label, a description and a mixed state.
- [Chip](https://zen.rinzai.dev/docs/chip.md): Small pressable buttons for quick picks beside a field, like common tenures.
- [Code Block](https://zen.rinzai.dev/docs/code-block.md): Code with a copy button; bring your own highlighter for colours. The copy button runs on useCopyToClipboard, which you can use for copy buttons anywhere.
- [Code Input](https://zen.rinzai.dev/docs/code-input.md): A one-time code, a box per character, that types, pastes and autofills from a text message like any field.
- [Collapse](https://zen.rinzai.dev/docs/collapse.md): Shows as many items as fit on one line, and the rest behind "+N".
- [Color Picker](https://zen.rinzai.dev/docs/color-picker.md): Pick a colour by eye or by hex: a saturation and brightness area, hue and opacity, and your own swatches. With hexToOklch to give a colour to the theme engine.
- [Combobox](https://zen.rinzai.dev/docs/combobox.md): Search and pick one or several items of any shape, composed from parts: field, panel, search, a virtualized list, empty and create rows.
- [Command Palette](https://zen.rinzai.dev/docs/command-palette.md): Search everything and act on it from the keyboard: a field over a list that narrows as you type, opened with ⌘K.
- [Date Picker](https://zen.rinzai.dev/docs/date-picker.md): A field that opens a calendar: one date, or a range previewed as you point. Dates are "YYYY-MM-DD" strings, so they never shift with time zones.
- [Dialog](https://zen.rinzai.dev/docs/dialog.md): Modal dialogs on the native