# Installation > Take the design layer as a package and the components from the registry. Source: https://ziiz.vercel.app/installation ziiz ships in two pieces because they change at different rates. The **theme** is one stylesheet that defines the ramp, the type roles, the materials and the prose layer. It is versioned, and an app takes updates by bumping a dependency. The **components** are source files that an app owns and edits. They come from a registry and never update on their own. ## Quick start [#quick-start] Start from a shadcn project. Skip this if `components.json` already exists. The Vega preset is the one ziiz components are built on. ```bash npx shadcn@latest init --preset vega ``` `init` writes a stock theme block into `app/globals.css`. Delete everything below the imports except `@custom-variant dark`: the next step supplies the theme, and the stock block's own font and color variables would sit on top of it. Point `components.json` at the registry. The registry is served straight from the repository, so there is no deploy between a merge and an install. ```json title="components.json" { "registries": { "@ziiz": "https://raw.githubusercontent.com/nafisazizir/ziiz/main/apps/www/public/r/{name}.json" } } ``` Add the theme. ```bash npx shadcn@latest add @ziiz/theme --overwrite ``` One item does the setup. It installs the `@nafisazizir/ziiz` package, `tw-animate-css` and `shadcn`, adds their three imports to the Tailwind entry in the right order, and replaces `lib/utils.ts` with a `cn` that understands the type roles. `--overwrite` is what lets it replace that file; without the flag the CLI stops to ask. Set the fonts. The theme reads `--font-sans` and `--font-mono` from `html` or `:root`. With next/font that is the `variable` option; ziiz uses Inter with `ss03` and Geist Mono. An app that sets neither gets Tailwind's default stacks, not a broken page. ```tsx title="app/layout.tsx" const inter = Inter({ subsets: ["latin"], variable: "--font-sans" }) const mono = Geist_Mono({ subsets: ["latin"], variable: "--font-mono" }) ``` Set up dark mode. Dark mode is the `.dark` class on `html`. With next-themes (`npm install next-themes`), that is `attribute="class"` on the provider, plus `suppressHydrationWarning` on `html` because the class is set before React hydrates. Without it, toggle the class yourself. ```tsx title="app/layout.tsx" {children} ``` Add components. Every item lists what it imports, so one command pulls in a component, the components it composes and the packages they need. ```bash npx shadcn@latest add @ziiz/button ``` After that, every Tailwind utility speaks the ramp (`bg-gray-100`, `text-gray-1000`, `border-gray-alpha-400`), the 31 type roles are single classes (`text-heading-32`, `text-copy-16`, `text-label-13`), the eight materials are too (`material-menu`, `material-modal`), and `typeset` sets prose. The stock Tailwind palette is disabled on purpose; only the ramp compiles. Type roles are single utilities, so the stock `cn` does not know that `text-label-14` and `text-copy-16` conflict. It keeps both, and stylesheet order decides which one paints, so a `className` override on a component works or fails by accident. `@nafisazizir/ziiz/cn` builds on the `cn` package with the roles as one font-size group and the materials as another. The `utils` item is a one-line re-export of it, and every component depends on it. ## Manual setup [#manual-setup] The theme item is a shortcut for four edits. Doing them by hand gives the same result. Install the packages. ```bash npm install @nafisazizir/ziiz tw-animate-css shadcn ``` `tw-animate-css` provides the enter and exit animations (`animate-in`, `fade-in-0`) that overlays use; `shadcn/tailwind.css` provides the `data-open:` and `data-closed:` variants and the accordion keyframes. Both are required, not optional. Import the stylesheets, in this order. ```css title="app/globals.css" @import "tailwindcss"; @import "tw-animate-css"; @import "shadcn/tailwind.css"; @import "@nafisazizir/ziiz/theme.css"; ``` Re-export `cn` . ```ts title="lib/utils.ts" export { cn } from "@nafisazizir/ziiz/cn" ``` Fonts and dark mode, as above. Add a fifth import, `@nafisazizir/ziiz/shadcn.css`. It maps shadcn's slot names (`bg-background`, `text-muted-foreground`, `border-input`) onto the ramp so components written against that vocabulary render on it unchanged. ziiz components speak the ramp directly and do not need it. ## Components [#components] The registry publishes every component on this site plus the documentation primitives it is written with (`callout`, `steps`, `code-block`, `code-tabs`, `component-preview`, `component-source`), which install into `components/docs/`. Search it from the CLI: ```bash npx shadcn@latest search @ziiz npx shadcn@latest view @ziiz/button ``` ## Prose [#prose] Long-form content needs no components. Add `typeset` to the container and every heading, paragraph, list, code span and table inside binds to a type role. See [Prose](/prose) for the full element set. ```tsx
{children}
``` ## Agents [#agents] The system is written down for coding agents as well as people. Three pieces: ```bash npx shadcn@latest add @ziiz/skill ``` The `skill` item installs the ziiz skill into `.agents/skills/ziiz/`: the vocabulary, the rules a component must follow, and the greps that check them. Claude Code, Codex and Cursor read that folder. ```bash npx shadcn@latest mcp init --client claude ``` The shadcn MCP reads the `@ziiz` entry from `components.json`, so an agent can search, view and add registry items as tools. `--client` also takes `cursor`, `vscode` and `codex`. Every page on this site is also markdown. [/llms.txt](/llms.txt) lists them with descriptions, [/llms-full.txt](/llms-full.txt) is the guide, the foundation and every component page in one file, and any page is at `/llms.mdx/` followed by its path, such as `/llms.mdx/components/button`. --- # Colors > Learn how to work with our color system. Source: https://ziiz.vercel.app/colors ## Scales [#scales] There are 10 color scales in the system: backgrounds, gray, gray alpha, blue, red, amber, green, teal, purple, and pink. Values are defined in oklch, so wide-gamut color renders on supported browsers and displays. Every non-background scale has the same 10 steps with the same roles. The sections below describe each role once, and it applies to every scale. The swatches use gray as the representative ramp. The scales are hand-tuned per step, not interpolated. Some steps deliberately reverse (Color 4 on the alpha scale is lighter than Color 3), so treat every step as a named role, never a point on a gradient.
## Backgrounds [#backgrounds] There are two background colors for pages and UI components. In most instances, you should use Background 1, especially when color is being placed on top of the background. Background 2 should be used sparingly when a subtle background differentiation is needed.
## Colors 1–3: Component backgrounds [#colors-13-component-backgrounds] The first three colors are component backgrounds, on every scale: Color 1 at rest, Color 2 on hover, Color 3 when pressed or selected. In practice there are two ladders. Filled components, like secondary buttons and badges, step 1 → 2 → 3 as written. If a component's default background is Background 1 (the page surface showing through, like ghost buttons, menu items and tab chips), the ladder shifts down a rung: Color 1 is the hover background and Color 2 the active background. Components that rest transparent take that shift on the alpha scale, so the state reads over any surface. Two refinements hold on both ladders. A transient open state (`aria-expanded`, `data-open`) pins to the hover step: the highlight lives in the popup, so the trigger only ever looks hovered. And hovering an already-selected control deepens one step further (`gray-alpha-300` on the alpha ladder, `gray-950` on the inverted fills) so selection never swallows the hover response.
## Colors 4–6: Borders [#colors-46-borders] These three colors are designed for UI component borders. In practice, borders default to the alpha scale; alpha hairlines hold up over any surface. Bordered controls and text fields step the hairline to Color 5 on hover. For fields, that border step is the entire hover response. Color 6's "active border" role is filled by the focus signature: solid gray-600 replaces the hairline on focus rather than stepping the alpha scale.
## Colors 7–8: High contrast backgrounds [#colors-78-high-contrast-backgrounds] These two colors are designed for high contrast UI component backgrounds.
## Colors 9–10: Text and icons [#colors-910-text-and-icons] These two colors are designed for accessible text and icons.
## shadcn mapping [#shadcn-mapping] The shadcn semantic slots are pure `var(--ds-*)` aliases onto the ramp, never values.
--- # Typography > Rules of typesetting throughout the system. Source: https://ziiz.vercel.app/typography ## Usage [#usage] Our typography styles can be consumed as Tailwind classes. The classes below pre-set a combination of `font-size`, `line-height`, `letter-spacing`, and `font-weight` for you. To make use of the **Subtle** and **Strong** modifiers, all you have to do is use the `` element nested as the descendant of a given typography class: ```tsx

Copy 16 with Strong

``` ## Headings [#headings] Used to introduce pages or sections.
## Buttons [#buttons] Only to be used within components that render buttons.
## Label [#label] Designed for single-lines, and given ample line-height for highlighting & marrying up with icons.
## Copy [#copy] Designed for multiple lines of text, having a higher line height than Label.
--- # Materials > Elevation presets combining background, border, shadow, and radius. Source: https://ziiz.vercel.app/materials ## Surface [#surface] Four levels of elevation for elements that sit in the page. Radius steps up with elevation. In-page surfaces in the component library are flat by decision: cards, sidebars, inputs and wells draw a hairline `border-gray-alpha-400` on `bg-background-100` and carry no shadow, so no `ui` component uses a Surface material today. The tiers remain available for content that genuinely needs to lift off the page (marketing sections, dashboards, previews) and for consumers whose surfaces are not flat.
## Floating [#floating] Four levels of elevation for elements that float above the page, ordered from closest to furthest off the surface.
## Best practices [#best-practices] ### When to use [#when-to-use] * Reach for a material instead of composing background, border, shadow, and radius by hand. The class encodes the elevation role, not just the look. * Pick the type from where the element sits in the layered hierarchy: `base` and `small` for resting surfaces, `medium` and `large` for raised content, `tooltip` and `menu` for popovers, `modal` and `fullscreen` for takeovers. In the component library, `menu` and `modal` do nearly all the work. * Never stack two materials on the same element. If a child needs more lift, it becomes its own material one tier up. ### Behavior [#behavior] * Keep the elevation choice in step with the element's `z-index` band, so a `tooltip`-typed surface never renders visually beneath a `base` card. * Favor the lowest tier that still reads as separated from its background; over-elevating is the most common source of visual noise. * Don't override a material's shadow or radius inline. If a surface needs different chrome, it belongs to a different tier. ### Accessibility [#accessibility] * Materials are decorative chrome. Semantics live on the role-bearing element: `role="dialog"` on a modal, `role="tooltip"` on a tooltip, never on the class. * Elevation is never the only signal: pair floating surfaces with focus management, and keep the focus ring on interactive children inside. * Check both themes. Dark shadows use higher opacities than light, yet still barely register against a black page; in dark, separation comes from the hairline ring, so verify it reads wherever the material lands. --- # Prose > The prose layer: one class that typesets long-form content onto the type roles. Source: https://ziiz.vercel.app/prose ## Usage [#usage] Add `typeset` to a container. Every heading, paragraph, list, link, code span and table inside binds to a type role with a fixed rhythm, so a docs body, a blog article or rendered markdown is plain elements with no classes. ```tsx

Title

Body copy on Copy 16, headings on the article scale.

``` Every rule is scoped with `:where()`, so a utility on the element still wins, and a subtree marked `not-typeset` opts out entirely. Rhythm is set by two custom properties, `--typeset-flow` between blocks and `--typeset-section` above a section heading. Everything below this line is one typeset body, written as bare elements. *** # Heading 1 binds to Heading 40 [#heading-1-binds-to-heading-40] The first heading level inside a body is the page-title role. This paragraph is Copy 16 on Color 9. Every block sits 24px below the one before it, headings included. A second paragraph keeps the flow gap. Inline semantics bind too: **strong is the Copy role's Strong modifier**, *emphasis stays italic*, `code` becomes a chip, ⌘ K is a key cap, mark highlights, and abbreviations carry a dotted underline. A [link](#lists) is underlined on the text color, never on the accent. ## Heading 2 binds to Heading 32 [#heading-2-binds-to-heading-32] Section headings take the section gap above, 72px by default. The role is applied as is: no weight, size or leading is overridden, so a heading here is identical to the same role anywhere in the app. A `code` span inside a heading keeps its Copy 13 Mono role too. ### Heading 3 binds to Heading 24 [#heading-3-binds-to-heading-24] Subsections take 64px above. #### Heading 4 binds to Heading 20 [#heading-4-binds-to-heading-20] Minor headings take 48px above. ##### Heading 5 binds to Heading 16, Heading 6 to 14 [#heading-5-binds-to-heading-16-heading-6-to-14] The smallest steps, 32px above, for run-in labels inside a subsection. ## Lists [#lists] Unordered lists use a disc, then a circle when nested. * The marker sits on Color 6, a step lighter than the body. * Items are 8px apart with 8px of padding after the marker, and a nested list keeps that gap. * Nested items use a circle. * They indent by the same 20px as the parent. * A block inside an item takes the item gap, whether it follows text or not. Like this paragraph. Ordered lists use decimals. 1. Read the roadmap. 2. Cut the seam. 3. Ship the layer. Definition lists set the term on Color 10 and indent the detail.
Role
A named combination of size, leading, tracking and weight.
Ramp
The ten-step scale every color in the system is drawn from.
## Quotes, rules and disclosures [#quotes-rules-and-disclosures] A blockquote is a pull quote: the text sits on Heading 24 with hanging quote marks drawn by the layer, and a trailing `footer` carries the attribution, with `cite` for the name. It takes half the section gap above and below.

{ "Minting short-lived tokens instead of keeping provider credentials in paused sandboxes has removed a whole class of security risk for us." }

{ <> Fraser Brown BuildPass }
Disclosures take the Accordion component's shape on the body role, with no hairline between rows. Adjacent ones stack; each opens on its own, since markdown cannot group them.
Is this a native details element?

{ "Yes. The summary is the trigger with the chevron at the end, and this content sits flush beneath it with 16px below, the same as the accordion panel." }

A second paragraph keeps the panel's 16px gap.

What does it not do?

{ "It does not animate open and closed, and it does not close its siblings when opened. Both need the component." }

Where does the look come from?

{ "The Accordion component is the source of truth; the prose layer mirrors it by hand." }

*** A horizontal rule is a 1px line on Color 2 with 80px above, 160px on wide screens, marking a break larger than any section. ## Code [#code] Inline code is the Copy 13 Mono chip on Color 1. Code blocks are Copy 13 Mono on Background 2 with a hairline and 16px of padding. Syntax color is a pipeline concern and lands on the tokens inside; the surface is the same everywhere. ```css @import "@nafisazizir/ziiz/theme.css"; .article { --typeset-flow: 1rem; --typeset-section: 4rem; } ``` ## Tables [#tables] Tables match the table component: Heading 14 header cells, Label 14 body cells with tabular numerals, and a hover on each row. The separator sits on the cell, so appending a row never needs a rule to change. | Element | Role | Gap above | | ------------- | ---------- | --------- | | h1 | Heading 40 | 72px | | h2 | Heading 32 | 72px | | h3 | Heading 24 | 64px | | h4 | Heading 20 | 48px | | p, ul, ol, dl | Copy 16 | 24px | | pre, table | inherits | 28px | | blockquote | Heading 24 | 36px | | figure | inherits | 40px | ## Figures [#figures]
{"image or embed"}
{ "A figure takes 40px above and below; its caption is Copy 14 on Color 9, centered, 16px below." }
## Opting out [#opting-out] A component with its own chrome sits inside a body by marking its root `not-typeset`. Nothing inside it inherits paragraph margins, link underlines or code chips. The alert below is stock; the button next to it is a plain component in a plain paragraph and needs no marker because no rule targets it. Stock alert inside a typeset body Its code and link render as the component styles them, not as prose.

## Density [#density] The two rhythm properties are the only knobs. The block below sets `--typeset-flow` to 12px and `--typeset-section` to 32px on a nested container, and everything inside tightens.

A denser body

Paragraphs sit 12px apart instead of 24px.

Section headings pull in from 72px to 32px, subsections to 28px.

Another section

--- # Accordion > A vertically stacked set of interactive headings that each reveal a section of content. Source: https://ziiz.vercel.app/components/accordion ## Installation [#installation] Command Manual ```bash npx shadcn@latest add @ziiz/accordion ``` Install the following dependencies: ```bash npm install @base-ui/react @tabler/icons-react ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage [#usage] ```tsx showLineNumbers import { Accordion, AccordionContent, AccordionItem, AccordionTrigger, } from "@/components/ui/accordion" ``` ```tsx showLineNumbers Is it accessible? Yes. It adheres to the WAI-ARIA design pattern. ``` ## Composition [#composition] Use the following composition to build an `Accordion`: ```text Accordion ├── AccordionItem │ ├── AccordionTrigger │ └── AccordionContent └── AccordionItem ├── AccordionTrigger └── AccordionContent ``` ## Basic [#basic] A basic accordion that shows one item at a time. The first item is open by default. ## Multiple [#multiple] Use the `multiple` prop to allow multiple items to be open at the same time. ## Disabled [#disabled] Use the `disabled` prop on `AccordionItem` to disable individual items. ## Borders [#borders] Add `border` to the `Accordion` and `border-b last:border-b-0` to the `AccordionItem` to add borders to the items. ## Card [#card] Wrap the `Accordion` in a `Card` component. ## API Reference [#api-reference] See the [Base UI](https://base-ui.com/react/components/accordion#api-reference) documentation for more information. --- # Alert > Displays a callout for user attention. Source: https://ziiz.vercel.app/components/alert ## Installation [#installation] Command Manual ```bash npx shadcn@latest add @ziiz/alert ``` Install the following dependencies: ```bash npm install class-variance-authority ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage [#usage] ```tsx showLineNumbers import { Alert, AlertAction, AlertDescription, AlertTitle, } from "@/components/ui/alert" ``` ```tsx showLineNumbers Heads up! You can add components and dependencies to your app using the cli. ``` ## Composition [#composition] Use the following composition to build an `Alert`: ```text Alert ├── Icon ├── AlertTitle ├── AlertDescription └── AlertAction ``` ## Basic [#basic] A basic alert with an icon, title and description. ## Destructive [#destructive] Use `variant="destructive"` to create a destructive alert. ## Action [#action] Use `AlertAction` to add a button or other action element to the alert. ## Custom Colors [#custom-colors] You can customize the alert colors by adding custom classes such as `bg-amber-50 dark:bg-amber-950` to the `Alert` component. ## API Reference [#api-reference] ### Alert [#alert] The `Alert` component displays a callout for user attention. | Prop | Type | Default | | --------- | ---------------------------- | ----------- | | `variant` | `"default" \| "destructive"` | `"default"` | ### AlertTitle [#alerttitle] The `AlertTitle` component displays the title of the alert. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | - | ### AlertDescription [#alertdescription] The `AlertDescription` component displays the description or content of the alert. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | - | ### AlertAction [#alertaction] The `AlertAction` component displays an action element (like a button) positioned absolutely in the top-right corner of the alert. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | - | --- # Alert Dialog > A modal dialog that interrupts the user with important content and expects a response. Source: https://ziiz.vercel.app/components/alert-dialog ## Installation [#installation] Command Manual ```bash npx shadcn@latest add @ziiz/alert-dialog ``` Install the following dependencies: ```bash npm install @base-ui/react ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage [#usage] ```tsx showLineNumbers import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogTrigger, } from "@/components/ui/alert-dialog" ``` ```tsx showLineNumbers }> Show Dialog Are you absolutely sure? This action cannot be undone. This will permanently delete your account from our servers. Cancel Continue ``` ## Composition [#composition] Use the following composition to build an `AlertDialog`: ```text AlertDialog ├── AlertDialogTrigger └── AlertDialogContent ├── AlertDialogHeader │ ├── AlertDialogMedia │ ├── AlertDialogTitle │ └── AlertDialogDescription └── AlertDialogFooter ├── AlertDialogCancel └── AlertDialogAction ``` ## Basic [#basic] A basic alert dialog with a title, description, and cancel and continue buttons. ## Small [#small] Use the `size="sm"` prop to make the alert dialog smaller. ## Media [#media] Use the `AlertDialogMedia` component to add a media element such as an icon or image to the alert dialog. ## Small with Media [#small-with-media] Use the `size="sm"` prop to make the alert dialog smaller and the `AlertDialogMedia` component to add a media element such as an icon or image to the alert dialog. ## Destructive [#destructive] Use the `AlertDialogAction` component to add a destructive action button to the alert dialog. ## API Reference [#api-reference] ### size [#size] Use the `size` prop on the `AlertDialogContent` component to control the size of the alert dialog. It accepts the following values: | Prop | Type | Default | | ------ | ------------------- | ----------- | | `size` | `"default" \| "sm"` | `"default"` | ### AlertDialogAction and AlertDialogCancel [#alertdialogaction-and-alertdialogcancel] Both render a [`Button`](/components/button). `AlertDialogAction` accepts all of its props; `AlertDialogCancel` accepts its `variant`, `size` and `shape`. | Prop | Type | Default | | --------- | ------------------------ | ------------------------------------------ | | `variant` | `Button["variant"]` | `"default"` (Action), `"outline"` (Cancel) | | `size` | `Button["size"]` | `"default"` | | `shape` | `"default" \| "rounded"` | `"default"` | For more information about the other components and their props, see the [Base UI documentation](https://base-ui.com/react/components/alert-dialog#api-reference). --- # Aspect Ratio > Displays content within a desired ratio. Source: https://ziiz.vercel.app/components/aspect-ratio ## Installation [#installation] Command Manual ```bash npx shadcn@latest add @ziiz/aspect-ratio ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage [#usage] ```tsx showLineNumbers import { AspectRatio } from "@/components/ui/aspect-ratio" ``` ```tsx showLineNumbers Image ``` ## Square [#square] A square aspect ratio component using the `ratio={1 / 1}` prop. This is useful for displaying images in a square format. ## Portrait [#portrait] A portrait aspect ratio component using the `ratio={9 / 16}` prop. This is useful for displaying images in a portrait format. ## API Reference [#api-reference] ### AspectRatio [#aspectratio] The `AspectRatio` component displays content within a desired ratio. | Prop | Type | Default | Required | | ----------- | -------- | ------- | -------- | | `ratio` | `number` | - | Yes | | `className` | `string` | - | No | For more information, see the [Base UI documentation](https://base-ui.com/react/components/aspect-ratio#api-reference). --- # Attachment > Displays a file or image attachment with media, metadata, upload state, and actions. Source: https://ziiz.vercel.app/components/attachment The `Attachment` component displays a file or image attachment, its media, name, and metadata, with optional actions and upload state. Use it for files and images in chat composers, message threads, and upload lists. ## Installation [#installation] Command Manual ```bash npx shadcn@latest add @ziiz/attachment ``` Install the following dependencies: ```bash npm install @base-ui/react class-variance-authority ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage [#usage] ```tsx import { Attachment, AttachmentAction, AttachmentActions, AttachmentContent, AttachmentDescription, AttachmentMedia, AttachmentTitle, } from "@/components/ui/attachment" ``` ```tsx sales-dashboard.pdf PDF · 2.4 MB ``` ## Composition [#composition] Use the following composition to build an attachment: ```text Attachment ├── AttachmentMedia ├── AttachmentContent │ ├── AttachmentTitle │ └── AttachmentDescription ├── AttachmentActions │ └── AttachmentAction └── AttachmentTrigger ``` Use `AttachmentGroup` to lay out multiple attachments in a scrollable row: ```text AttachmentGroup ├── Attachment └── Attachment ``` ## Features [#features] * Icon and image media through `AttachmentMedia` * Upload states: `idle`, `uploading`, `processing`, `error`, and `done` with built-in styling and a shimmer while in progress * Three sizes and horizontal or vertical orientation * A full-card `AttachmentTrigger` that opens a link or dialog while the actions stay independently clickable * Scrollable, snapping `AttachmentGroup` with an edge fade * Customizable styling through the `className` prop on every part ## Image [#image] Set `variant="image"` on `AttachmentMedia` and render an `` inside it. Use `orientation="vertical"` to stack the media above the content. ## States [#states] Set `state` to reflect the upload lifecycle. `uploading` and `processing` shimmer the title, and `error` switches to a destructive treatment. ## Sizes [#sizes] Use `size` to switch between `default`, `sm`, and `xs`. ## Group [#group] Wrap attachments in `AttachmentGroup` to lay them out in a horizontally scrollable, snapping row with an edge fade. ## Trigger [#trigger] Add an `AttachmentTrigger` to make the whole card open a link or dialog. It fills the card behind the actions, so the actions stay clickable. ```tsx showLineNumbers {/* media, content, actions */} } /> {/* ... */} ``` ## Accessibility [#accessibility] `AttachmentAction` renders a `Button`, and `AttachmentTrigger` renders a real ` ``` ### Interactive Bubbles [#interactive-bubbles] When a bubble is clickable, render it as a real ` ``` ## Cursor [#cursor] Tailwind v4 [switched](https://tailwindcss.com/docs/upgrade-guide#buttons-use-the-default-cursor) from `cursor: pointer` to `cursor: default` for the button component. If you want to keep the `cursor: pointer` behavior, add the following code to your CSS file: You can also enable this during project setup with `npx shadcn@latest init --pointer`. ```css showLineNumbers title="globals.css" @layer base { button:not(:disabled), [role="button"]:not(:disabled) { cursor: pointer; } } ``` ## Size [#size] Use the `size` prop to change the size of the button. ## Default [#default] ## Outline [#outline] ## Secondary [#secondary] ## Ghost [#ghost] ## Destructive [#destructive] ## Link [#link] ## Icon [#icon] ## With Icon [#with-icon] Remember to add the `data-icon="inline-start"` or `data-icon="inline-end"` attribute to the icon for the correct spacing. ## Rounded [#rounded] Use `shape="rounded"` to make the button a pill, or a circle with an icon size. Only the radius changes; a pill pads like a square button. Components built on `Button` pass `shape` through: `InputGroupButton`, `AlertDialogAction`, `AlertDialogCancel`, `PaginationLink`, the `Questionnaire` navigation buttons, `MessageScrollerButton`, `AttachmentAction` and `SidebarTrigger`. `CarouselPrevious` and `CarouselNext` are rounded by default. Inside a [Button Group](/components/button-group#rounded), rounded buttons keep the group's two ends round. ## Spinner [#spinner] Render a `` component inside the button to show a loading state. Remember to add the `data-icon="inline-start"` or `data-icon="inline-end"` attribute to the spinner for the correct spacing. ## Button Group [#button-group] To create a button group, use the `ButtonGroup` component. See the [Button Group](/components/button-group) documentation for more details. ## As Link [#as-link] You can use the `buttonVariants` helper to make a link look like a button. **Do not use ` ``` ## Composition [#composition] Use the following composition to build a `ButtonGroup`: ```text ButtonGroup ├── Button or Input ├── ButtonGroupSeparator └── ButtonGroupText ``` ## Accessibility [#accessibility] * The `ButtonGroup` component has the `role` attribute set to `group`. * Use Tab to navigate between the buttons in the group. * Use `aria-label` or `aria-labelledby` to label the button group. ```tsx showLineNumbers ``` ## ButtonGroup vs ToggleGroup [#buttongroup-vs-togglegroup] * Use the `ButtonGroup` component when you want to group buttons that perform an action. * Use the `ToggleGroup` component when you want to group buttons that toggle a state. ## Orientation [#orientation] Set the `orientation` prop to change the button group layout. ## Size [#size] Control the size of buttons using the `size` prop on individual buttons. ## Nested [#nested] Nest `` components to create button groups with spacing. ## Separator [#separator] The `ButtonGroupSeparator` component visually divides buttons within a group. Buttons with variant `outline` do not need a separator since they have a border. For other variants, a separator is recommended to improve the visual hierarchy. ## Split [#split] Create a split button group by adding two buttons separated by a `ButtonGroupSeparator`. ## Rounded [#rounded] Give the buttons `shape="rounded"`. The group squares the seams between them and leaves the two ends round, so the group reads as one pill. The ends take their shape from whatever sits there, so give whatever sits at an end `shape="rounded"` too: `Input`, `InputGroup`, `Select` and `ButtonGroupText` all take it. The seams follow the reading direction, so the round ends land on the outside in RTL as well. ## Input [#input] Wrap an `Input` component with buttons. ## Input Group [#input-group] Wrap an `InputGroup` component to create complex input layouts. ## Dropdown Menu [#dropdown-menu] Create a split button group with a `DropdownMenu` component. ## Select [#select] Pair with a `Select` component. ## Popover [#popover] Use with a `Popover` component. ## API Reference [#api-reference] ### ButtonGroup [#buttongroup] The `ButtonGroup` component is a container that groups related buttons together with consistent styling. | Prop | Type | Default | | ------------- | ---------------------------- | -------------- | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | ```tsx ``` Nest multiple button groups to create complex layouts with spacing. See the [nested](#nested) example for more details. ```tsx ``` ### ButtonGroupSeparator [#buttongroupseparator] The `ButtonGroupSeparator` component visually divides buttons within a group. | Prop | Type | Default | | ------------- | ---------------------------- | ------------ | | `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | ```tsx ``` ### ButtonGroupText [#buttongrouptext] Use this component to display text within a button group. | Prop | Type | Default | | -------- | ------------------------ | ----------- | | `shape` | `"default" \| "rounded"` | `"default"` | | `render` | `React.ReactElement` | | ```tsx Text ``` Use the `render` prop to render a custom component as the text, for example a label. ```tsx showLineNumbers import { ButtonGroupText } from "@/components/ui/button-group" import { Label } from "@/components/ui/label" export function ButtonGroupTextDemo() { return ( }>Text ) } ``` --- # Calendar > A calendar component that allows users to select a date or a range of dates. Source: https://ziiz.vercel.app/components/calendar ## Installation [#installation] Command Manual ```bash npx shadcn@latest add @ziiz/calendar ``` Install the following dependencies: ```bash npm install @tabler/icons-react react-day-picker ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage [#usage] ```tsx showLineNumbers import { Calendar } from "@/components/ui/calendar" ``` ```tsx showLineNumbers const [date, setDate] = React.useState(new Date()) return ( ) ``` See the [React DayPicker](https://react-day-picker.js.org) documentation for more information. ## About [#about] The `Calendar` component is built on top of [React DayPicker](https://react-day-picker.js.org). ## Date Picker [#date-picker] You can use the `` component to build a date picker. See the Date Picker page for more information. ## Persian / Hijri / Jalali Calendar [#persian--hijri--jalali-calendar] To use the Persian calendar, edit `components/ui/calendar.tsx` and replace `react-day-picker` with `react-day-picker/persian`. ```diff - import { DayPicker } from "react-day-picker" + import { DayPicker } from "react-day-picker/persian" ``` ## Selected Date (With TimeZone) [#selected-date-with-timezone] The Calendar component accepts a `timeZone` prop to ensure dates are displayed and selected in the user's local timezone. ```tsx showLineNumbers export function CalendarWithTimezone() { const [date, setDate] = React.useState(undefined) const [timeZone, setTimeZone] = React.useState(undefined) React.useEffect(() => { setTimeZone(Intl.DateTimeFormat().resolvedOptions().timeZone) }, []) return ( ) } ``` **Note:** If you notice a selected date offset (for example, selecting the 20th highlights the 19th), make sure the `timeZone` prop is set to the user's local timezone. **Why client-side?** The timezone is detected using `Intl.DateTimeFormat().resolvedOptions().timeZone` inside a `useEffect` to ensure compatibility with server-side rendering. Detecting the timezone during render would cause hydration mismatches, as the server and client may be in different timezones. ## Basic [#basic] A basic calendar component. We used `className="rounded-lg border"` to style the calendar. ## Range Calendar [#range-calendar] Use the `mode="range"` prop to enable range selection. ## Month and Year Selector [#month-and-year-selector] Use `captionLayout="dropdown"` to show month and year dropdowns. ## Presets [#presets] ## Date and Time Picker [#date-and-time-picker] ## Booked dates [#booked-dates] ## Custom Cell Size [#custom-cell-size] You can customize the size of calendar cells using the `--cell-size` CSS variable. You can also make it responsive by using breakpoint-specific values: ```tsx showLineNumbers ``` Or use fixed values: ```tsx showLineNumbers ``` ## Week Numbers [#week-numbers] Use `showWeekNumber` to show week numbers. ## API Reference [#api-reference] See the [React DayPicker](https://react-day-picker.js.org) documentation for more information on the `Calendar` component. ## Changelog [#changelog] ### RTL Support [#rtl-support] If you're upgrading from a previous version of the `Calendar` component, you'll need to apply the following updates to add locale support: Import the `Locale` type. Add `Locale` to your imports from `react-day-picker`: ```diff import { DayPicker, getDefaultClassNames, type DayButton, + type Locale, } from "react-day-picker" ``` Add `locale` prop to the Calendar component. Add the `locale` prop to the component's props: ```diff function Calendar({ className, classNames, showOutsideDays = true, captionLayout = "label", buttonVariant = "ghost", + locale, formatters, components, ...props }: React.ComponentProps & { buttonVariant?: React.ComponentProps["variant"] }) { ``` Pass `locale` to DayPicker. Pass the `locale` prop to the `DayPicker` component: ```diff - date.toLocaleString("default", { month: "short" }), + date.toLocaleString(locale?.code, { month: "short" }), ...formatters, }} ``` Update CalendarDayButton to accept locale. Update the `CalendarDayButton` component signature and pass `locale`: ```diff function CalendarDayButton({ className, day, modifiers, + locale, ...props - }: React.ComponentProps) { + }: React.ComponentProps & { locale?: Partial }) { ``` Update date formatting in CalendarDayButton. Use `locale?.code` in the date formatting: ```diff }>Cancel ``` ## Composition [#composition] Use the following composition to build a `Drawer`: ```text Drawer ├── DrawerTrigger └── DrawerContent ├── DrawerHeader │ ├── DrawerTitle │ └── DrawerDescription └── DrawerFooter ``` `DrawerContent` composes the portal, overlay, viewport, and popup from Base UI. For lower-level control, `DrawerPortal`, `DrawerOverlay`, and `DrawerSwipeHandle` are also exported. ## Custom Sizes [#custom-sizes] A vertical drawer sizes itself to its content and is capped at `calc(100dvh - 6rem)` by default. A side drawer spans `75%` of the viewport width, or `24rem` on larger screens. To customize the height of a vertical drawer, use the `h-*` and `max-h-*` utilities on `DrawerContent`. ```tsx ``` To customize the width of a side drawer, use the `w-*` and `max-w-*` utilities on `DrawerContent`. ```tsx ``` When the same component renders in multiple directions, scope an override to one axis using the `data-[swipe-axis=*]` variants. ```tsx ``` To make a region of the drawer scrollable, make the scroll container a flex item. Avoid `h-full`, which does not resolve inside a content-sized drawer. ```tsx ...
{/* Scrollable content */}
...
``` ## Styling [#styling] The drawer exposes CSS variables for style-level customization. Set the sizing variables on `DrawerContent`. Set the overlay variable on `[data-slot=drawer-overlay]` in your CSS. | Variable | Default | Description | | ------------------------------ | ---------------------- | ----------------------------------------------------------------------- | | `--drawer-inset` | `0px` | Floats the drawer from the viewport edges. | | `--drawer-bleed-background` | `var(--color-popover)` | Fills the gap behind the drawer on swipe overshoot. | | `--drawer-overlay-min-opacity` | `0` | Minimum overlay opacity. Defaults to `0.5` when snap points are active. | The drawer also sets data attributes you can target with variants such as `data-[swipe-direction=down]:` on `DrawerContent`, or `group-data-[swipe-axis=y]/drawer-popup:` on its descendants. | Attribute | Values | Set when | | ------------------------- | ----------------------------- | ------------------------------------- | | `data-swipe-direction` | `up`, `right`, `down`, `left` | Always. | | `data-swipe-axis` | `x`, `y` | Always. | | `data-snap-points` | Present | The drawer has snap points. | | `data-expanded` | Present | The drawer is at the full snap point. | | `data-swiping` | Present | A swipe is in progress. | | `data-nested-drawer-open` | Present | A nested drawer is open on top. | ## Position [#position] Use the `swipeDirection` prop to set the side of the drawer. Available options are `up`, `right`, `down`, and `left`. ## Swipe Handle [#swipe-handle] Use `showSwipeHandle` on `Drawer` to render a swipe handle. ## Nested [#nested] Open drawers from inside another drawer. Parent drawers stay mounted and stack behind the frontmost drawer. ## Non Modal [#non-modal] Set `modal={false}` to allow interaction with the rest of the page while the drawer is open. Combine with `disablePointerDismissal` to prevent the drawer from closing on outside presses. Use `modal="trap-focus"` to keep focus inside the drawer while leaving scroll and pointer interaction unrestricted. ## Snap Points [#snap-points] Use `snapPoints` to snap a drawer to preset heights. Numbers between `0` and `1` represent fractions of the viewport. Numbers greater than `1` are treated as pixel values. String values support `px` and `rem` units. Snap points apply to vertical drawers. Track the active snap point with the controlled `snapPoint` and `onSnapPointChange` props. At the full snap point, the drawer gets a `data-expanded` attribute you can style with the `data-expanded:` variant. ## Responsive [#responsive] You can combine the `Dialog` and `Drawer` components to create a responsive dialog. This renders a `Dialog` component on desktop and a `Drawer` on mobile. ## Migrating from Vaul [#migrating-from-vaul] The base drawer now uses [Base UI](https://base-ui.com/react/components/drawer) instead of Vaul. If you installed the previous base drawer, update your usage to the Base UI API. Update the dependency. ```diff - npm install vaul + npm install @base-ui/react ``` Replace `direction` with `swipeDirection` . Use `down` instead of `bottom`, and `up` instead of `top`. `left` and `right` stay the same. ```diff - + ``` Replace `asChild` with `render` . For `DrawerTrigger`, pass the trigger element to the `render` prop. ```diff - - - + }> + Open + ``` For `DrawerClose`, pass the close element to the `render` prop. ```diff - - - + }> + Cancel + ``` Update snap point props. If you use snap points, rename the controlled snap point props and the sequential snap point prop. ```diff ``` Update animation and focus props. ```diff - setDone(open)}> + setDone(open)}> ``` ```diff - event.preventDefault()}> + ``` Review Vaul-only props. Vaul props like `handleOnly`, `repositionInputs`, and `shouldScaleBackground` do not have one-to-one replacements in the base drawer API. Use Base UI props such as `disablePointerDismissal`, `modal`, `snapPoints`, or controlled `open` state for the behavior you need. ```diff - + ``` ```diff - + ``` Update custom data attribute selectors. Replace Vaul's `data-vaul-drawer-direction` selectors with Base UI's `data-swipe-direction` selectors. ```diff - + ``` Base UI also exposes attributes like `data-swiping`, `data-starting-style`, and `data-ending-style` for swipe and transition states. Descendants inside `DrawerContent` can use `group-data-[swipe-axis=x]/drawer-popup` and `group-data-[swipe-axis=y]/drawer-popup` for axis-specific styling. ## API Reference [#api-reference] See the [Base UI documentation](https://base-ui.com/react/components/drawer) for the full API reference. --- # Dropdown Menu > Displays a menu to the user, such as a set of actions or functions, triggered by a button. Source: https://ziiz.vercel.app/components/dropdown-menu ## Installation [#installation] Command Manual ```bash npx shadcn@latest add @ziiz/dropdown-menu ``` Install the following dependencies: ```bash npm install @base-ui/react @tabler/icons-react ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage [#usage] ```tsx showLineNumbers import { Button } from "@/components/ui/button" import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, } from "@/components/ui/dropdown-menu" ``` ```tsx showLineNumbers }> Open My Account Profile Billing Team Subscription ``` ## Composition [#composition] Use the following composition to build a `DropdownMenu`: ```text DropdownMenu ├── DropdownMenuTrigger └── DropdownMenuContent ├── DropdownMenuGroup │ ├── DropdownMenuLabel │ ├── DropdownMenuItem │ └── DropdownMenuItem ├── DropdownMenuSeparator ├── DropdownMenuGroup │ ├── DropdownMenuLabel │ ├── DropdownMenuCheckboxItem │ └── DropdownMenuCheckboxItem ├── DropdownMenuSeparator ├── DropdownMenuGroup │ ├── DropdownMenuLabel │ └── DropdownMenuRadioGroup │ ├── DropdownMenuRadioItem │ └── DropdownMenuRadioItem └── DropdownMenuSub ├── DropdownMenuSubTrigger └── DropdownMenuSubContent └── DropdownMenuGroup ├── DropdownMenuLabel ├── DropdownMenuItem └── DropdownMenuItem ``` ## Basic [#basic] A basic dropdown menu with labels and separators. ## Submenu [#submenu] Use `DropdownMenuSub` to nest secondary actions. ## Shortcuts [#shortcuts] Add `DropdownMenuShortcut` to show keyboard hints. ## Icons [#icons] Combine icons with labels for quick scanning. ## Checkboxes [#checkboxes] Use `DropdownMenuCheckboxItem` for toggles. ## Checkboxes Icons [#checkboxes-icons] Add icons to checkbox items. ## Radio Group [#radio-group] Use `DropdownMenuRadioGroup` for exclusive choices. ## Radio Icons [#radio-icons] Show radio options with icons. ## Destructive [#destructive] Use `variant="destructive"` for irreversible actions. ## Avatar [#avatar] An account switcher dropdown triggered by an avatar. ## Complex [#complex] A richer example combining groups, icons, and submenus. ## Size [#size] A `size="lg"` menu pads its items for a 40px trigger, so item text lines up with a `size="lg"` button's label. Give the trigger button the same size. ## API Reference [#api-reference] See the [Base UI documentation](https://base-ui.com/react/components/menu) for the full API reference. --- # Empty > Use the Empty component to display an empty state. Source: https://ziiz.vercel.app/components/empty ## Installation [#installation] Command Manual ```bash npx shadcn@latest add @ziiz/empty ``` Install the following dependencies: ```bash npm install class-variance-authority ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage [#usage] ```tsx import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from "@/components/ui/empty" ``` ```tsx No data No data found ``` ## Composition [#composition] Use the following composition to build an `Empty` state: ```text Empty ├── EmptyHeader │ ├── EmptyMedia │ ├── EmptyTitle │ └── EmptyDescription └── EmptyContent ``` ## Outline [#outline] Use the `border` utility class to create an outline empty state. ## Background [#background] Use the `bg-*` and `bg-gradient-*` utilities to add a background to the empty state. ## Avatar [#avatar] Use the `EmptyMedia` component to display an avatar in the empty state. ## Avatar Group [#avatar-group] Use the `EmptyMedia` component to display an avatar group in the empty state. ## InputGroup [#inputgroup] You can add an `InputGroup` component to the `EmptyContent` component. ## API Reference [#api-reference] ### Empty [#empty] The main component of the empty state. Wraps the `EmptyHeader` and `EmptyContent` components. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | ```tsx ``` ### EmptyHeader [#emptyheader] The `EmptyHeader` component wraps the empty media, title, and description. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | ```tsx ``` ### EmptyMedia [#emptymedia] Use the `EmptyMedia` component to display the media of the empty state such as an icon or an image. You can also use it to display other components such as an avatar. | Prop | Type | Default | | ----------- | --------------------- | --------- | | `variant` | `"default" \| "icon"` | `default` | | `className` | `string` | | ```tsx ``` ```tsx CN ``` ### EmptyTitle [#emptytitle] Use the `EmptyTitle` component to display the title of the empty state. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | ```tsx No data ``` ### EmptyDescription [#emptydescription] Use the `EmptyDescription` component to display the description of the empty state. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | ```tsx You do not have any notifications. ``` ### EmptyContent [#emptycontent] Use the `EmptyContent` component to display the content of the empty state such as a button, input or a link. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | ```tsx ``` --- # Field > Combine labels, controls, and help text to compose accessible form fields and grouped inputs. Source: https://ziiz.vercel.app/components/field ## Installation [#installation] Command Manual ```bash npx shadcn@latest add @ziiz/field ``` Install the following dependencies: ```bash npm install class-variance-authority ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage [#usage] ```tsx showLineNumbers import { Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle, } from "@/components/ui/field" ``` ```tsx showLineNumbers
Profile This appears on invoices and emails. Full name This appears on invoices and emails. Username Choose another username. Subscribe to the newsletter
``` ## Composition [#composition] ### Field [#field] A single control with label, helper text, and validation. ```text Field ├── FieldLabel ├── Input / Textarea / Switch / Select ├── FieldDescription └── FieldError ``` ### FieldGroup [#fieldgroup] Related fields in one group. Use `FieldSeparator` between sections when needed. ```text FieldGroup ├── Field │ ├── FieldLabel │ ├── Input / Textarea / Switch / Select │ ├── FieldDescription │ └── FieldError ├── FieldSeparator └── Field ├── FieldLabel └── Input / Textarea / Switch / Select ``` ### FieldSet [#fieldset] Semantic grouping with a legend and description, usually containing a `FieldGroup`. ```text FieldSet ├── FieldLegend ├── FieldDescription └── FieldGroup ├── Field │ ├── FieldLabel │ ├── Input / Textarea / Switch / Select │ ├── FieldDescription │ └── FieldError └── Field ├── FieldLabel └── Input / Textarea / Switch / Select ``` ## Anatomy [#anatomy] The `Field` family is designed for composing accessible forms. A typical field is structured as follows: ```tsx showLineNumbers Label {/* Input, Select, Switch, etc. */} Optional helper text. Validation message. ``` * `Field` is the core wrapper for a single field. * `FieldContent` is a flex column that groups label and description. Not required if you have no description. * Wrap related fields with `FieldGroup`, and use `FieldSet` with `FieldLegend` for semantic grouping. ## Form [#form] See the Form documentation for building forms with the `Field` component and React Hook Form, Tanstack Form, or Formisch. ## Input [#input] ## Textarea [#textarea] ## Select [#select] ## Slider [#slider] ## Fieldset [#fieldset-1] ## Checkbox [#checkbox] ## Radio [#radio] ## Switch [#switch] ## Choice Card [#choice-card] Wrap `Field` components inside `FieldLabel` to create selectable field groups. This works with `RadioItem`, `Checkbox` and `Switch` components. ## Field Group [#field-group] Stack `Field` components with `FieldGroup`. Add `FieldSeparator` to divide them. ## Responsive Layout [#responsive-layout] * **Vertical fields:** Default orientation stacks label, control, and helper text, ideal for mobile-first layouts. * **Horizontal fields:** Set `orientation="horizontal"` on `Field` to align the label and control side-by-side. Pair with `FieldContent` to keep descriptions aligned. * **Responsive fields:** Set `orientation="responsive"` for automatic column layouts inside container-aware parents. Apply `@container/field-group` classes on `FieldGroup` to switch orientations at specific breakpoints. ## Validation and Errors [#validation-and-errors] * Add `data-invalid` to `Field` to switch the entire block into an error state. * Add `aria-invalid` on the input itself for assistive technologies. * Render `FieldError` immediately after the control or inside `FieldContent` to keep error messages aligned with the field. ```tsx showLineNumbers /data-invalid/ /aria-invalid/ Email Enter a valid email address. ``` ## Accessibility [#accessibility] * `FieldSet` and `FieldLegend` keep related controls grouped for keyboard and assistive tech users. * `Field` outputs `role="group"` so nested controls inherit labeling from `FieldLabel` and `FieldLegend` when combined. * Apply `FieldSeparator` sparingly to ensure screen readers encounter clear section boundaries. ## API Reference [#api-reference] ### FieldSet [#fieldset-2] Container that renders a semantic `fieldset` with spacing presets. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | ```tsx
Delivery {/* Fields */}
``` ### FieldLegend [#fieldlegend] Legend element for a `FieldSet`. Switch to the `label` variant to align with label sizing. | Prop | Type | Default | | ----------- | --------------------- | ---------- | | `variant` | `"legend" \| "label"` | `"legend"` | | `className` | `string` | | ```tsx Notification Preferences ``` The `FieldLegend` has two variants: `legend` and `label`. The `label` variant applies label sizing and alignment. Handy if you have nested `FieldSet`. ### FieldGroup [#fieldgroup-1] Layout wrapper that stacks `Field` components and enables container queries for responsive orientations. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | ```tsx {/* ... */} {/* ... */} ``` ### Field [#field-1] The core wrapper for a single field. Provides orientation control, invalid state styling, and spacing. | Prop | Type | Default | | -------------- | -------------------------------------------- | ------------ | | `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` | | `className` | `string` | | | `data-invalid` | `boolean` | | ```tsx Remember me ``` ### FieldContent [#fieldcontent] Flex column that groups control and descriptions when the label sits beside the control. Not required if you have no description. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | ```tsx Notifications Email, SMS, and push options. ``` ### FieldLabel [#fieldlabel] Label styled for both direct inputs and nested `Field` children. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | ```tsx Email ``` ### FieldTitle [#fieldtitle] Renders a title with label styling inside `FieldContent`. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | ```tsx Enable Touch ID Unlock your device faster. ``` ### FieldDescription [#fielddescription] Helper text slot that automatically balances long lines in horizontal layouts. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | ```tsx We never share your email with anyone. ``` ### FieldSeparator [#fieldseparator] Visual divider to separate sections inside a `FieldGroup`. Accepts optional inline content. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | ```tsx Or continue with ``` ### FieldError [#fielderror] Accessible error container that accepts children or an `errors` array (e.g., from `react-hook-form`). | Prop | Type | Default | | ----------- | ------------------------------------------ | ------- | | `errors` | `Array<{ message?: string } \| undefined>` | | | `className` | `string` | | ```tsx ``` When the `errors` array contains multiple messages, the component renders a list automatically. `FieldError` also accepts issues produced by any validator that implements [Standard Schema](https://standardschema.dev/), including Zod, Valibot, and ArkType. Pass the `issues` array from the schema result directly to render a unified error list across libraries. --- # Hover Card > For sighted users to preview content available behind a link. Source: https://ziiz.vercel.app/components/hover-card ## Installation [#installation] Command Manual ```bash npx shadcn@latest add @ziiz/hover-card ``` Install the following dependencies: ```bash npm install @base-ui/react ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage [#usage] ```tsx showLineNumbers import { HoverCard, HoverCardContent, HoverCardTrigger, } from "@/components/ui/hover-card" ``` ```tsx showLineNumbers Hover The React Framework, created and maintained by @vercel. ``` ## Composition [#composition] Use the following composition to build a `HoverCard`: ```text HoverCard ├── HoverCardTrigger └── HoverCardContent ``` ## Trigger Delays [#trigger-delays] Use `delay` and `closeDelay` on the trigger to control when the card opens and closes. ```tsx showLineNumbers Hover Content ``` ## Positioning [#positioning] Use the `side` and `align` props on `HoverCardContent` to control placement. ```tsx showLineNumbers Hover Content ``` ## Basic [#basic] ## Sides [#sides] ## API Reference [#api-reference] See the [Base UI](https://base-ui.com/react/components/hover-card#api-reference) documentation for more information. --- # Input > A text input component for forms and user data entry with built-in styling and accessibility features. Source: https://ziiz.vercel.app/components/input ## Installation [#installation] Command Manual ```bash npx shadcn@latest add @ziiz/input ``` Install the following dependencies: ```bash npm install @base-ui/react ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage [#usage] ```tsx import { Input } from "@/components/ui/input" ``` ```tsx ``` ## Basic [#basic] ## Size [#size] Use the `size` prop for a 32, 36 or 40px field. The text inset follows: 12px at `sm` and `default`, 16px at `lg`, the same as a button of that size. ## Variant [#variant] Use the `variant` prop to change the field's look. `default` is the outlined field, `secondary` a gray fill that darkens on hover, and `ghost` is transparent with no hover, for a field on a toolbar or a surface of its own. They match the `outline`, `secondary` and `ghost` button. Focus darkens the default border; secondary and ghost stay as they rest and the caret shows focus. ## Rounded [#rounded] Use `shape="rounded"` for a pill. Only the radius changes, so the text inset is the same as a square field's. ## Field [#field] Use `Field`, `FieldLabel`, and `FieldDescription` to create an input with a label and description. ## Field Group [#field-group] Use `FieldGroup` to show multiple `Field` blocks and to build forms. ## Disabled [#disabled] Use the `disabled` prop to disable the input. To style the disabled state, add the `data-disabled` attribute to the `Field` component. ## Invalid [#invalid] Use the `aria-invalid` prop to mark the input as invalid. To style the invalid state, add the `data-invalid` attribute to the `Field` component. ## File [#file] Use the `type="file"` prop to create a file input. ## Inline [#inline] Use `Field` with `orientation="horizontal"` to create an inline input. Pair with `Button` to create a search input with a button. ## Grid [#grid] Use a grid layout to place multiple inputs side by side. ## Required [#required] Use the `required` attribute to indicate required inputs. ## Badge [#badge] Use `Badge` in the label to highlight a recommended field. ## Input Group [#input-group] To add icons, text, or buttons inside an input, use the `InputGroup` component. See the [Input Group](/components/input-group) component for more examples. ## Button Group [#button-group] To add buttons to an input, use the `ButtonGroup` component. See the [Button Group](/components/button-group) component for more examples. ## Form [#form] A full form example with multiple inputs, a select, and a button. --- # Input Group > Add addons, buttons, and helper content to inputs. Source: https://ziiz.vercel.app/components/input-group ## Installation [#installation] Command Manual ```bash npx shadcn@latest add @ziiz/input-group ``` Install the following dependencies: ```bash npm install class-variance-authority ``` Copy and paste the following code into your project. Update the import paths to match your project setup. ## Usage [#usage] ```tsx showLineNumbers import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, } from "@/components/ui/input-group" ``` ```tsx showLineNumbers ``` ## Composition [#composition] Use the following composition to build an `InputGroup`: ```text InputGroup ├── InputGroupInput or InputGroupTextarea ├── InputGroupAddon ├── InputGroupButton └── InputGroupText ``` ## Align [#align] Use the `align` prop on `InputGroupAddon` to position the addon relative to the input. For proper focus management, `InputGroupAddon` should always be placed after `InputGroupInput` or `InputGroupTextarea` in the DOM. Use the `align` prop to visually position the addon. ### inline-start [#inline-start] Use `align="inline-start"` to position the addon at the start of the input. This is the default. ### inline-end [#inline-end] Use `align="inline-end"` to position the addon at the end of the input. ### block-start [#block-start] Use `align="block-start"` to position the addon above the input. ### block-end [#block-end] Use `align="block-end"` to position the addon below the input. ## Icon [#icon] ## Text [#text] ## Button [#button] `InputGroupButton` takes `shape="rounded"` for a pill, or a circle at `icon-xs` and `icon-sm`. Set `shape="rounded"` on `InputGroup` for a pill field and its buttons follow; a group with a textarea or block addon keeps its radius while its buttons go round. ## Kbd [#kbd] ## Dropdown [#dropdown] ## Spinner [#spinner] ## Textarea [#textarea] ## Custom Input [#custom-input] Add the `data-slot="input-group-control"` attribute to your custom input for automatic focus state handling. Here's an example of a custom resizable textarea from a third-party library. ## API Reference [#api-reference] ### InputGroup [#inputgroup] The main component that wraps inputs and addons. | Prop | Type | Default | | ----------- | --------------------------- | ----------- | | `size` | `"sm" \| "default" \| "lg"` | `"default"` | | `className` | `string` | | The group's input, textarea and addons take the size together. ```tsx ``` ### InputGroupAddon [#inputgroupaddon] Displays icons, text, buttons, or other content alongside inputs. For proper focus navigation, the `InputGroupAddon` component should be placed after the input. Set the `align` prop to position the addon. | Prop | Type | Default | | ----------- | ---------------------------------------------------------------- | ---------------- | | `align` | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | `"inline-start"` | | `className` | `string` | | ```tsx ``` **For ``, use the `inline-start` or `inline-end` alignment. For ``, use the `block-start` or `block-end` alignment.** The `InputGroupAddon` component can have multiple `InputGroupButton` components and icons. ```tsx Button Button ``` ### InputGroupButton [#inputgroupbutton] Displays buttons within input groups. | Prop | Type | Default | | ----------- | ----------------------------------------------------------------------------- | ----------- | | `size` | `"xs" \| "icon-xs" \| "sm" \| "icon-sm"` | `"xs"` | | `variant` | `"default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| "link"` | `"ghost"` | | `shape` | `"default" \| "rounded"` | `"default"` | | `className` | `string` | | ```tsx Button ``` ### InputGroupInput [#inputgroupinput] Replacement for `` when building input groups. This component has the input group styles pre-applied and uses the unified `data-slot="input-group-control"` for focus state handling. | Prop | Type | Default | | ----------- | -------- | ------- | | `className` | `string` | | All other props are passed through to the underlying `` component. ```tsx ``` ### InputGroupTextarea [#inputgrouptextarea] Replacement for `