# VaneUI Documentation

> Complete documentation for the VaneUI React component library (`@vaneui/ui` 1.5.0),
> every doc page concatenated into one file. Each page starts with `# <page name>`, its URL and
> one import line for the `@vaneui/ui` exports its examples use. Component pages end with
> their props, grouped by category with defaults marked, generated from the installed package.

- Repository: https://github.com/vaneui/vaneui
- Documentation: https://vaneui.com
- Package: `@vaneui/ui` 1.5.0
- Index: https://vaneui.com/llms.txt
- Contact: hello@vaneui.com

Pages follow the site navigation: Getting Started, Basic Components, Form Components, Typography Components, Layout Components, Overlay Components, Customization, Reference.
Each page is also available on its own as Markdown at its URL plus `.md`.

# Installation

> Install @vaneui/ui with npm, yarn or pnpm, add its CSS through Tailwind CSS v4 or the prebuilt bundle, and wrap your React app in ThemeProvider.

Source: https://vaneui.com/docs/getting-started/installation

Import: `import { Button, Card, Stack, ThemeProvider, useTheme } from "@vaneui/ui"`

Install VaneUI, a React component library built with TypeScript and Tailwind CSS, using your preferred package manager:

```bash
npm install @vaneui/ui
```

```bash
yarn add @vaneui/ui
```

```bash
pnpm add @vaneui/ui
```

## CSS setup

VaneUI supports two CSS setup options depending on your project configuration.

### Option 1: with Tailwind CSS (recommended)

If your project uses Tailwind CSS v4, VaneUI plugs in directly. Tailwind scans VaneUI components and generates only the CSS classes you use.

Install Tailwind CSS if you haven't already:

```bash
npm install -D tailwindcss @tailwindcss/postcss
```

Add the following to your main CSS file:

```css
@import "tailwindcss";
@import "@vaneui/ui/tokens";
@import "@vaneui/ui/vars";
@source "../node_modules/@vaneui/ui";
```

This setup:
- Imports Tailwind CSS base styles
- Imports VaneUI theme tokens (registers custom breakpoints and design tokens with Tailwind)
- Imports VaneUI CSS variables and component rules
- Tells Tailwind to scan VaneUI components for class generation

> The `@vaneui/ui/tokens` import is required for responsive props like `mobileStack`, `tabletHide`, and responsive typography to work. It registers VaneUI's custom breakpoints (`mobile`, `tablet`, `desktop`) with your project's Tailwind CSS instance.

### Option 2: without Tailwind CSS

If your project doesn't use Tailwind CSS, you can import VaneUI's pre-built CSS bundle which includes all component styles.

Add the following to your main CSS file:

```css
@import "@vaneui/ui/css";
```

This setup:
- Imports the complete pre-built VaneUI stylesheet (component styles and CSS variables in one file)
- Works without any Tailwind configuration

The pre-built stylesheet is compiled for VaneUI's own components; it does not contain Tailwind's full utility set. A Tailwind class passed through `className` or `extraClasses` has no effect unless it happens to be in the bundle, and most (`max-w-md`, `p-6`, `size-8`, `ms-auto`, `z-40`) are not. For arbitrary utilities, use Option 1 or the `style` prop.

## ThemeProvider setup

Wrap your application in `ThemeProvider`. Without it, each component falls back to its own built-in default theme, but `themeDefaults`, `extraClasses`, and `themeOverride` only apply inside a provider. Place it once at the root, above every VaneUI component.

```tsx
import { ThemeProvider } from '@vaneui/ui';

function Root() {
  return (
    <ThemeProvider>
      <App />
    </ThemeProvider>
  );
}
```

`ThemeProvider` needs no props to apply the built-in defaults. To set application-wide defaults, extra classes, or theme overrides, see [Using ThemeProvider](/docs/customization/using-theme-provider).

For a Next.js App Router project, see [Next.js](/docs/getting-started/nextjs); to connect an AI coding assistant through the MCP server, llms.txt or the Markdown copy of each page, see [AI Assistants](/docs/getting-started/ai-assistants).

## Usage

Start using VaneUI components in your React application:

```tsx
import { Button, Stack } from '@vaneui/ui';

function App() {
  return (
    <Stack>
      <Button primary>Get Started</Button>
    </Stack>
  );
}
```

## Per-component imports

For better tree-shaking, you can import components directly:

```tsx
import { Button } from '@vaneui/ui/button';
import { Card } from '@vaneui/ui/card';
import { useTheme } from '@vaneui/ui/theme';
```

This is optional. Importing from `@vaneui/ui` works the same way. Per-component imports can reduce bundle size when using only a few components with bundlers that don't fully tree-shake barrel exports.

Available subpath imports include: `@vaneui/ui/button`, `@vaneui/ui/iconButton`, `@vaneui/ui/icon`, `@vaneui/ui/badge`, `@vaneui/ui/card`, `@vaneui/ui/checkbox`, `@vaneui/ui/chip`, `@vaneui/ui/code`, `@vaneui/ui/divider`, `@vaneui/ui/img`, `@vaneui/ui/input`, `@vaneui/ui/kbd`, `@vaneui/ui/label`, `@vaneui/ui/mark`, `@vaneui/ui/menu`, `@vaneui/ui/modal`, `@vaneui/ui/navLink`, `@vaneui/ui/overlay`, `@vaneui/ui/popup`, `@vaneui/ui/section`, `@vaneui/ui/container`, `@vaneui/ui/row`, `@vaneui/ui/col`, `@vaneui/ui/stack`, `@vaneui/ui/grid`, `@vaneui/ui/typography`, `@vaneui/ui/layout`, `@vaneui/ui/theme`, `@vaneui/ui/props`.

# Core Concepts

> How VaneUI's boolean props API works in React: one prop per category, how props become Tailwind CSS classes and CSS variables, and where custom classes fit.

Source: https://vaneui.com/docs/getting-started/core-concepts

Import: `import { Button, Card, Stack, ThemeProvider } from "@vaneui/ui"`

VaneUI turns common design decisions into boolean props. Instead of memorizing property names and values, you compose intent: `primary`, `lg`, `outline`, `rounded`. This page covers the boolean props API, the three-layer component architecture, prop extraction priority, and the three-tier CSS variable system.

## Boolean props API

At its core, VaneUI uses **boolean props** instead of string enums for cleaner JSX:

```tsx
// VaneUI approach
<Button primary lg filled>Submit</Button>

// Instead of traditional
<Button appearance="primary" size="lg" variant="filled">Submit</Button>
```

Props are organized into **categories**:
- **size**: `xs`, `sm`, `md`, `lg`, `xl`
- **appearance**: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- **variant**: `filled`, `outline`, `ghost` (`ghost`: transparent background, no border, appearance-colored text, tinted hover background)
- **shape**: `rounded`, `pill`, `sharp`
- **typography**: `fontSans`, `fontSerif`, `fontMono`, `fontSemibold`, `fontBold`, etc.
- **layout**: `flex`, `column`, `itemsCenter`, `justifyBetween`, etc.
- **inheritance**: `inheritSize`, `inheritColor`, `inheritBg`, `inheritBorder` (and `noInherit*` toggles)

Text, Title, SectionTitle, PageTitle, Blockquote, Label, List, Divider, and Spinner default to `inheritAppearance`, which means they [inherit colors from their parent element](/docs/customization/variant-inheritance) via CSS variable cascade rather than setting their own color. Link and Mark default to `inheritSize`, so they inherit font-size from their parent while keeping their own appearance color; Code and Kbd achieve the same effect through em-relative geometry.

## Three-layer component architecture

VaneUI components follow a three-layer architecture:

### Layer 1: React component
Each component gets its theme from `ThemeContext` via `useTheme()` and passes props to `ThemedComponent`, which computes the final CSS classes.

### Layer 2: theme system
The `ComponentTheme` class orchestrates class generation. It walks a tree of `BaseClassMapper` subclasses (like `FontSizeClassMapper`, `RadiusClassMapper`) that each generate specific CSS classes based on the active props.

### Layer 3: CSS variables
Components output **data attributes** (`data-size`, `data-appearance`, `data-variant`) that CSS rules in `rules.css` use to set CSS variables. These variables are then consumed by Tailwind utility classes.

## Prop extraction

When you pass props, VaneUI selects ONE value per category based on priority:

```tsx
// Button defaults: { sm: true, primary: true, outline: true, ... }
// User props:     { lg: true, filled: true }

<Button lg filled>Submit</Button>
// Result: size='lg' (prop overrides default sm),
//         appearance='primary' (default kept),
//         variant='filled' (prop overrides default outline)
```

**Priority order**:
1. Props explicitly set to `true`
2. Defaults set to `true` (unless explicitly set to `false` in props)

## Prop combinations

Boolean props can be combined naturally to create the exact styling you need:

```tsx
<Button primary lg pill shadow>
  Large primary pill button with shadow
</Button>

<Card secondary filled>
  Filled secondary card
</Card>

<Stack itemsCenter>
  Stack with centered items (column, gap, padding, and flexWrap are defaults)
</Stack>
```

## CSS variable system

VaneUI uses a [three-tier CSS variable system](/docs/customization/css-variables):

### Tier 1: unit variables
Set by component class based on `data-size`:
```css
.vane-button[data-size="md"] {
  --fs-unit: 8;   /* Font size unit */
  --py-unit: 2;   /* Padding Y unit */
}
```

### Tier 2: computed variables
Calculated from unit variables using base multipliers:
```css
[data-size] {
  --fs: calc(var(--fs-unit) * var(--fs-base));  /* --fs-base = 0.125rem */
  --py: calc(var(--py-unit) * var(--spacing));  /* --spacing = 0.25rem */
  --px: calc(var(--aspect-ratio) * var(--py-unit) * var(--spacing));
  --br: calc(var(--br-unit) * var(--br-base));  /* --br-base = 0.25rem */
  --gap: calc(var(--gap-unit) * var(--spacing));
}
```

### Tier 3: semantic color variables
Set by `data-variant` + `data-appearance` attributes:
```css
[data-variant="outline"][data-appearance="primary"] {
  --text-color: var(--color-text-primary);
  --bg-color: var(--color-bg-primary);
  --border-color: var(--color-border-primary);
}
```

## Mixing custom classes

You can always [add your own Tailwind classes](/docs/customization/customizing-styles) via `className` to fine-tune any edge case:
```tsx demo
<Button primary lg filled className="hover:opacity-80 shadow-xl">
  Get started
</Button>
```

User-provided `className` takes precedence over theme classes for the same properties (via `twMerge`).

## Customization options

### CSS variables
Override colors globally or for any subtree:
```css
:root {
  --color-text-primary: #8b5cf6;
  --color-bg-primary: #f3e8ff;
  --color-border-primary: #c4b5fd;
}
```

### ThemeProvider defaults
[Set default prop values](/docs/customization/theme-defaults) for all components, including overlay components (Overlay, Modal, Popup):
```tsx demo
<ThemeProvider themeDefaults={{
  button: { main: { pill: true, lg: true } }, // button is compound; defaults nest under `main`
  card: { main: { primary: true } }            // card is compound too
}}>
  <Button>Large pill button by default</Button>
</ThemeProvider>
```

### Extra classes
Add additional CSS classes based on active props:
```tsx demo
<ThemeProvider extraClasses={{
  button: { main: { primary: 'shadow-lg hover:shadow-xl' } }
}}>
  <Button primary>Button with extra shadow</Button>
</ThemeProvider>
```

### Theme override function
A function that receives the resolved theme and returns it modified. Unlike `themeDefaults` (which sets default props) and `extraClasses` (which adds classes keyed by active prop), it has direct access to the whole theme tree, including each component's always-on base classes:
```tsx
<ThemeProvider themeOverride={(theme) => {
  // Modify base classes
  theme.button.main.base += ' uppercase tracking-wide';
  return theme;
}}>
  <App />
</ThemeProvider>
```

# Usage Basics

> Core VaneUI patterns in React: boolean size and appearance props, layout components, responsive visibility, typography, icons, images and overlays.

Source: https://vaneui.com/docs/getting-started/usage-basics

Import: `import { Badge, Button, Card, Col, Container, Icon, Img, List, ListItem, Modal, ModalBody, ModalCloseButton, ModalFooter, ModalHeader, PageTitle, Popup, PopupTrigger, Row, Section, SectionTitle, Stack, Text, Title } from "@vaneui/ui"`

VaneUI components share a boolean props API for size, appearance, variant, and layout. This page covers the core usage patterns: size and appearance props, layout components, responsive breakpoints, typography, icons, images, overlays, and when to prefer props over Tailwind classes.

## Component props

VaneUI components use boolean props for styling. Most components support size, appearance, and layout props.

### Size props

Components support five sizes:

```tsx
import { Button, Stack } from '@vaneui/ui';

function SizeExample() {
  return (
    <Stack>
      <Button xs>Extra Small</Button>
      <Button sm>Small (Button default)</Button>
      <Button md>Medium</Button>
      <Button lg>Large</Button>
      <Button xl>Extra Large</Button>
    </Stack>
  );
}
```

> Most components default to `md`. Button, IconButton, NavLink, MenuItem, MenuLabel, Label, and Tooltip default to `sm`.

### Appearance props

Control visual appearance with semantic props:

```tsx
import { Button, Row } from '@vaneui/ui';

function AppearanceExample() {
  return (
    <Row>
      <Button primary>Primary</Button>
      <Button accent>Accent</Button>
      <Button secondary>Secondary</Button>
      <Button tertiary>Tertiary</Button>
      <Button success>Success</Button>
      <Button danger>Danger</Button>
      <Button warning>Warning</Button>
      <Button info>Info</Button>
    </Row>
  );
}
```

### Filled and outline variants

All components support `filled`, `outline`, and `ghost` variants. `outline` is the default for most components. `ghost` renders a transparent background with no border and appearance-colored text, plus a tinted hover background:

```tsx
import { Button, Card, Stack, Container, Row } from '@vaneui/ui';

function FilledOutlineExample() {
  return (
    <Stack lg>
      {/* Buttons */}
      <Row>
        <Button filled>Filled Button</Button>
        <Button>Outline Button (default)</Button>
        <Button ghost>Ghost Button</Button>
      </Row>

      {/* Cards */}
      <Row>
        <Card filled success lg>Filled Card</Card>
        <Card danger lg>Outline Card (default)</Card>
      </Row>

      {/* Layout Components */}
      <Container filled secondary>
        <Stack lg>Filled Container</Stack>
      </Container>
      <Container warning>
        <Stack lg>Outline Container (default)</Stack>
      </Container>
    </Stack>
  );
}
```

### Shape props

Control border radius:

```tsx
import { Button, Row } from '@vaneui/ui';

function ShapeExample() {
  return (
    <Row>
      <Button sharp>Sharp (no radius)</Button>
      <Button>Rounded (default)</Button>
      <Button pill>Pill (fully rounded)</Button>
    </Row>
  );
}
```

## Layout components

### Stack

Arrange children vertically with consistent spacing:

```tsx
import { Stack, Text } from '@vaneui/ui';

function StackExample() {
  return (
    <Stack lg>
      <Text>Item 1</Text>
      <Text>Item 2</Text>
      <Text>Item 3</Text>
    </Stack>
  );
}
```

### Row and Col

Compose layouts:

```tsx
import { Row, Col, Card } from '@vaneui/ui';

function GridExample() {
  return (
    <Row>
      <Col>
        <Card>Column 1</Card>
      </Col>
      <Col>
        <Card>Column 2</Card>
      </Col>
    </Row>
  );
}
```

### Responsive breakpoints

Use breakpoint props to change layout on different screen sizes:

```tsx
import { Row, Card } from '@vaneui/ui';

function ResponsiveLayout() {
  return (
    // Row on desktop, column on tablet and below
    <Row tabletStack>
      <Card>Left</Card>
      <Card>Right</Card>
    </Row>
  );
}
```

Available breakpoint props:
- `mobileStack`: Column on mobile and below (below 48rem)
- `tabletStack`: Column on tablet and below (below 64rem)
- `desktopStack`: Column on desktop and below (below 80rem)

## Typography

VaneUI provides typography components with consistent hierarchy:

```tsx
import { PageTitle, SectionTitle, Title, Text, Stack } from '@vaneui/ui';

function TypographyExample() {
  return (
    <Stack>
      <PageTitle>Page Title (h1)</PageTitle>
      <SectionTitle>Section Title (h2)</SectionTitle>
      <Title>Title (h3)</Title>
      <Text>Body text (p)</Text>
    </Stack>
  );
}
```

### Automatic responsive typography

Typography components (`PageTitle`, `SectionTitle`, `Title`) and layout components (`Section`) automatically scale across breakpoints: no props needed:

```tsx
import { PageTitle, SectionTitle, Title, Section } from '@vaneui/ui';

function ResponsiveTypography() {
  return (
    <Section>
      {/* Font size automatically reduces on smaller screens */}
      <PageTitle>Welcome to My App</PageTitle>
      <SectionTitle>Section Heading</SectionTitle>
      <Title>Content Title</Title>
    </Section>
  );
}
```

- `PageTitle` scales: e.g., 24 units on desktop, 21 on tablet, 18 on mobile
- `SectionTitle` scales: e.g., 18 units on desktop, 16 on tablet, 14 on mobile
- `Title` scales: e.g., 12 units on desktop, 11 on tablet, 10 on mobile
- `Section` padding/gap scales automatically across breakpoints

### Typography color inheritance

List items inherit appearance from their parent List component via CSS variables:

```tsx
import { List, ListItem, Stack } from '@vaneui/ui';

function ListInheritance() {
  return (
    <Stack lg>
      <List success>
        <ListItem>Inherits success color</ListItem>
        <ListItem>Also inherits success color</ListItem>
      </List>
      
      <List danger>
        <ListItem>Inherits danger color</ListItem>
        <ListItem>Also inherits danger color</ListItem>
      </List>
    </Stack>
  );
}
```

## Images

Display images with VaneUI styling using the `Img` component:

```tsx
import { Img, Row } from '@vaneui/ui';

function ImageExample() {
  return (
    <Row>
      <Img src="/photo.jpg" alt="Photo" rounded border shadow />
      <Img src="/avatar.jpg" alt="Avatar" pill />
      <Img src="/banner.jpg" alt="Banner" sharp objectCover />
    </Row>
  );
}
```

`Img` supports shape props (`rounded`, `pill`, `sharp`), `border`, `shadow`, size props, and object-fit props (`objectCover`, `objectContain`, `objectFill`).

## Icons

Wrap any SVG with the `Icon` component to inherit the parent's font color and scale with the size system:

```tsx
import { Icon, Row, Text } from '@vaneui/ui';
import { Star, AlertCircle } from 'react-feather';

function IconExample() {
  return (
    <Row>
      <Icon sm><Star /></Icon>
      <Icon><Star /></Icon>
      <Icon lg success><Star /></Icon>
      <Text danger><Icon><AlertCircle /></Icon> Inline with text</Text>
    </Row>
  );
}
```

### Icon container mode

By default `Icon` renders as a bare glyph that inherits color from its parent. Adding any of `padding`, `border`, `insetRing`, `shadow`, or `filled` switches it into *container mode*: the icon gains a sized box that shape props (`rounded`, `pill`, `sharp`) can act on:

```tsx
import { Icon, Row } from '@vaneui/ui';
import { Check, Heart, AlertCircle } from 'react-feather';

function IconContainerExample() {
  return (
    <Row>
      <Icon padding pill primary filled><Heart /></Icon>
      <Icon padding pill success border><Check /></Icon>
      <Icon padding danger filled insetRing><AlertCircle /></Icon>
    </Row>
  );
}
```

Padding and radius scale with the size prop, so the same composition works across `xs` through `xl`.

## Overlays and modals

Use `Modal` for dialogs that require user attention. Modals include focus trapping, scroll lock, and ARIA attributes by default. Modal provides sub-components for structured layout: `ModalHeader`, `ModalBody`, `ModalFooter`, and `ModalCloseButton`.

```tsx
import { Modal, ModalHeader, ModalBody, ModalFooter, ModalCloseButton, Button, Text } from '@vaneui/ui';
import { useState } from 'react';

function ModalExample() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open Modal</Button>
      <Modal open={open} onClose={() => setOpen(false)}>
        <ModalHeader>
          <Text fontBold>Dialog Title</Text>
          <ModalCloseButton />
        </ModalHeader>
        <ModalBody>
          <Text>Dialog content goes here.</Text>
        </ModalBody>
        <ModalFooter>
          <Button primary filled onClick={() => setOpen(false)}>Close</Button>
        </ModalFooter>
      </Modal>
    </>
  );
}
```

### PopupTrigger

Use `PopupTrigger` as a convenience wrapper that manages open/close state for `Popup` automatically. Pass the popup content via the `popup` prop and the trigger element as children:

```tsx
import { PopupTrigger, Button, Card, Text } from '@vaneui/ui';

function PopupExample() {
  return (
    <PopupTrigger popup={<Card sm shadow><Text sm>Popup content</Text></Card>}>
      <Button>Toggle Popup</Button>
    </PopupTrigger>
  );
}
```

`PopupTrigger` selects its trigger mode with three boolean props: `triggerOnClick` (the default when none is set), `triggerOnHover`, and `triggerOnFocus`.

`Popup` positions itself relative to its anchor through a placement prop: `placeTop`, `placeTopStart`, `placeTopEnd`, `placeBottom`, `placeBottomStart`, `placeBottomEnd`, `placeLeft`, `placeLeftStart`, `placeLeftEnd`, `placeRight`, `placeRightStart`, and `placeRightEnd`.

```tsx
<Popup placeBottomStart>Anchored below, aligned to the start edge</Popup>
```

See the [Overlay Components](/docs/overlay-components/overlay) section for `Overlay`, `Modal`, and `Popup` documentation.

## Responsive visibility

Hide components below a breakpoint, or show them only below one:

```tsx
import { Text, Stack } from '@vaneui/ui';

function ResponsiveVisibility() {
  return (
    <Stack>
      <Text>Always visible</Text>
      <Text mobileHide>Hidden on mobile (below 48rem)</Text>
      <Text tabletHide>Hidden on tablet (below 64rem)</Text>
      <Text desktopHide>Hidden on desktop (below 80rem)</Text>
      <Text mobileShow>Shown only on mobile (below 48rem)</Text>
      <Text tabletShow>Shown only below tablet width (64rem)</Text>
    </Stack>
  );
}
```

Make a component full width below a breakpoint while it keeps its own width above it:

```tsx
<Row mobileStack>
  <Button mobileWFull>Full width on mobile</Button>
  <Button mobileWFull>Fit width from 48rem</Button>
</Row>
```

## Custom HTML tags

Use the `tag` prop to render different HTML elements:

```tsx
import { Text, Button } from '@vaneui/ui';

function TagExample() {
  return (
    <div>
      <Text tag="h1">Heading rendered as h1</Text>
      <Text tag="span">Text rendered as span</Text>
      <Button tag="a" href="/link">Button rendered as anchor</Button>
    </div>
  );
}
```

## Combining with custom classes

Add custom Tailwind classes via `className`:

```tsx
import { Button, Card } from '@vaneui/ui';

function CustomStyling() {
  return (
    <Card className="shadow-2xl">
      <Button wFull className="hover:scale-105">
        Full width with hover effect
      </Button>
    </Card>
  );
}
```

User-provided `className` takes precedence over theme classes (via `twMerge`).

## Prefer props over Tailwind classes

VaneUI provides boolean props for most common styling needs. Use these instead of Tailwind classes to ensure consistent theming and proper integration with the size system.

### Common props vs Tailwind classes

| Instead of Tailwind | Use VaneUI prop |
|---------------------|-----------------|
| `className="uppercase"` | `uppercase` |
| `className="font-bold"` | `fontBold` |
| `className="font-semibold"` | `fontSemibold` |
| `className="font-mono"` | `fontMono` |
| `className="italic"` | `italic` |
| `className="text-center"` | `textCenter` |
| `className="sticky"` | `sticky` |
| `className="items-center"` | `itemsCenter` |
| `className="justify-between"` | `justifyBetween` |
| `className="border-b"` | `borderB` |
| `className="rounded-full"` | `pill` |
| `className="shadow"` | `shadow` |

```tsx
// Good: Using VaneUI props
<Text uppercase fontSemibold>IMPORTANT</Text>
<Card borderB>Card with bottom border</Card>
<Row itemsCenter justifyBetween>Spaced content</Row>

// Avoid: Tailwind classes that duplicate props
<Text className="uppercase font-semibold">IMPORTANT</Text>
<Card className="border-b">Card with bottom border</Card>
<Row className="items-center justify-between">Spaced content</Row>
```

### Gap is controlled by size props

Don't use Tailwind gap classes. Gap is controlled by the size prop system (`xs`, `sm`, `md`, `lg`, `xl`) and is enabled by default on layout components.

```tsx
// Good: Size prop controls gap
<Row lg>Large gap between items</Row>
<Stack sm>Small gap between items</Stack>
<Col>Default gap (md)</Col>

// Avoid: Tailwind gap classes
<Row className="gap-10">Don't override gap this way</Row>
```

### Background colors via appearance props

Background colors are controlled by appearance + variant props. Only use `bg-*` classes for edge cases not covered by the theme (like gradients).

```tsx
// Good: Appearance controls color
<Card primary filled>Primary background</Card>
<Button success filled>Success button</Button>

// Avoid: Tailwind bg classes when appearance works
<Card className="bg-blue-500">Don't fight the theme</Card>

// OK: Tailwind for custom colors not in theme
<div className="bg-gradient-to-r from-purple-500 to-pink-500">
  Custom gradient
</div>
```

### Typography styling is built-in

Typography components have built-in letter spacing, line height, and other typographic properties. Avoid overriding these with Tailwind classes.

```tsx
// Good: Built-in typography styling
<Badge uppercase>STATUS</Badge>
<Title>Properly styled heading</Title>

// Avoid: Manual typography overrides
<Badge className="tracking-wider">STATUS</Badge>
<Title className="leading-tight">Overridden heading</Title>
```

# Next.js

> Set up VaneUI in a Next.js App Router project: add the Tailwind CSS v4 imports, render ThemeProvider in the root layout, and add dark mode without a flash.

Source: https://vaneui.com/docs/getting-started/nextjs

Import: `import { Button, ThemeProvider } from "@vaneui/ui"`

This guide sets up VaneUI in a Next.js project that uses the App Router and Tailwind CSS v4. It covers four pieces: the CSS entry, the root layout, an optional client wrapper for theme functions, and an inline dark-mode script.

## Create a Next.js app with Tailwind CSS

Start from a Next.js app with Tailwind CSS, then add VaneUI:

```bash
npx create-next-app@latest my-app --typescript --tailwind --app
cd my-app
npm install @vaneui/ui
```

For an existing app without Tailwind CSS, install it with `npm install -D tailwindcss @tailwindcss/postcss` and add `"@tailwindcss/postcss": {}` to the plugins in `postcss.config.mjs`.

## Import the VaneUI styles

Replace the contents of `app/globals.css`:

```css
@import "tailwindcss";
@import "@vaneui/ui/tokens";
@import "@vaneui/ui/vars";
@source "../node_modules/@vaneui/ui";
```

The `@source` line lets Tailwind find the classes VaneUI components use. See [Installation](/docs/getting-started/installation) for the prebuilt stylesheet if you don't use Tailwind CSS.

## Wrap the root layout in ThemeProvider

VaneUI components ship with the `'use client'` directive, so a Server Component such as the root layout can render them directly:

```tsx
// app/layout.tsx
import { ThemeProvider } from '@vaneui/ui';
import './globals.css';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}
```

`themeDefaults` and `extraClasses` take plain objects, so the layout can pass them too. `themeOverride` takes a function, and a Server Component can't pass a function to a client component. Put it in a client wrapper, then render `AppThemeProvider` in the layout instead of `ThemeProvider`:

```tsx
// app/theme-provider.tsx
'use client';

import { ThemeProvider, type ThemeProps } from '@vaneui/ui';

const override = (theme: ThemeProps) => theme;

export function AppThemeProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return <ThemeProvider themeOverride={override}>{children}</ThemeProvider>;
}
```

## Dark mode without a flash

VaneUI switches to dark colors when `<html>` has `data-theme="dark"`. Set it before the page paints with a script in the root layout's `<head>`, so a dark-mode visitor never sees a white flash:

```tsx
<head>
  <script
    dangerouslySetInnerHTML={{
      __html: `try{var t=localStorage.getItem('theme')||(matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light');document.documentElement.dataset.theme=t}catch(e){}`,
    }}
  />
</head>
```

`suppressHydrationWarning` on `<html>` stops React from warning about the attribute the script adds. To switch themes, a toggle sets `document.documentElement.dataset.theme` and saves the choice to `localStorage` under `theme`, the key the script reads. [Dark Mode](/docs/customization/dark-mode) covers the color tokens.

## Client-side links with `next/link`

Button, Card, NavLink and Badge render an `<a>` when you pass `href`. Pass `tag={Link}` to route them through Next.js:

```tsx
import Link from 'next/link';
import { Button } from '@vaneui/ui';

<Button href="/docs" tag={Link}>Documentation</Button>
```

# AI Assistants

> Connect Claude Code, Cursor or VS Code to the VaneUI MCP server, or point any AI assistant at llms.txt and Markdown docs, so it writes correct React props.

Source: https://vaneui.com/docs/getting-started/ai-assistants

VaneUI styles components with boolean props. An AI assistant that guesses from other libraries writes `variant="filled"` or `size="lg"` instead, and VaneUI ignores both. Giving the assistant VaneUI's own docs prevents this. The MCP server is the most direct way; llms.txt and the Markdown copy of each page work with any tool that can read a URL.

## Connect the `@vaneui/mcp` server

`@vaneui/mcp` is the official [Model Context Protocol](https://modelcontextprotocol.io) server for VaneUI. It exposes every docs page as a resource and provides two tools: `search_docs` searches the docs, and `get_component_props` returns a component's boolean props with their defaults. It is listed in the official MCP Registry as `io.github.vaneui/mcp` and needs Node.js 24.

### Claude Code

```bash
claude mcp add vaneui -- npx -y @vaneui/mcp
```

### Cursor

Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project:

```json
{
  "mcpServers": {
    "vaneui": { "command": "npx", "args": ["-y", "@vaneui/mcp"] }
  }
}
```

### VS Code

Add the server to `.vscode/mcp.json` in your project. VS Code uses a `servers` key instead of `mcpServers`:

```json
{
  "servers": {
    "vaneui": { "command": "npx", "args": ["-y", "@vaneui/mcp"] }
  }
}
```

### Claude Desktop

Add the same `mcpServers` entry as Cursor to `claude_desktop_config.json`, then restart Claude Desktop.

## llms.txt and Markdown pages

For assistants without MCP support, point them at the plain-text docs:

- [llms.txt](/llms.txt) lists every docs page with a one-line summary and a link to its Markdown copy.
- [llms-full.txt](/llms-full.txt) contains every docs page, including props tables, in one file.
- Every docs page has a Markdown copy at its URL with `.md` appended, for example [/docs/basic-components/button.md](/docs/basic-components/button.md). A request to the normal URL with an `Accept: text/markdown` header also returns Markdown.
- The **Copy as Markdown** button under each page title copies the page for pasting into a chat.

## VaneUI rules for agent instruction files

Add these lines to your project's agent instructions, such as `CLAUDE.md`, `AGENTS.md` or `.cursor/rules`:

```text
- Style VaneUI components with boolean props: <Button danger lg filled>. Never pass variant, size or appearance strings.
- Pass at most one value per category: one size, one appearance, one variant, one shape.
- Leave out props that are already defaults. Button is already sm, primary, outline and rounded.
- Wrap the app once in <ThemeProvider> at the root.
- Prefer VaneUI props to Tailwind classes: fontBold, not className="font-bold".
- Check prop names and defaults on vaneui.com/docs or with the @vaneui/mcp server before guessing.
```

The [Core Concepts](/docs/getting-started/core-concepts) page explains why the props work this way, and [Common Props](/docs/reference/common-props) lists the layout props every component shares.

# Button

> Button triggers an action or event when clicked. It can contain text, an icon, or both, and is a primary way for users to interact with the app.

Source: https://vaneui.com/docs/basic-components/button

Import: `import { Button, Col, Row, ThemeProvider } from "@vaneui/ui"`

Use Button for actions, [Link](/docs/typography-components/link) for an in-prose hyperlink, and [NavLink](/docs/basic-components/navlink) for a sidebar or navigation item. An action shown only as an icon goes in an [IconButton](/docs/basic-components/icon-button). Button renders a native `<button>`, or an `<a>` when `href` is set. A `disabled` or `loading` Button with an `href` drops the `href` but stays focusable, marked with `aria-disabled`.

## Basic usage

Button triggers an action when the user clicks it; each `appearance` prop maps to a semantic color from the active theme.

```tsx demo
<Row flexWrap>
  <Button primary>primary</Button>
  <Button accent>accent</Button>
  <Button secondary>secondary</Button>
  <Button tertiary>tertiary</Button>
  <Button success>success</Button>
  <Button danger>danger</Button>
  <Button warning>warning</Button>
  <Button info>info</Button>
  <Button inheritAppearance>inheritAppearance</Button>
</Row>
```

## Sizes

Buttons come in five sizes: `xs`, `sm` (default), `md`, `lg`, `xl`. Size drives font-size, padding, gap, and border-radius simultaneously via CSS variables.

```tsx demo
<Row flexWrap>
  <Button xs>xs</Button>
  <Button sm>sm</Button>
  <Button md>md</Button>
  <Button lg>lg</Button>
  <Button xl>xl</Button>
</Row>
```

## Variants

Buttons can be styled as `filled`, `outline` (default), or `ghost`.

```tsx demo
<Col>
  <Row flexWrap>
    <Button filled primary>primary</Button>
    <Button filled accent>accent</Button>
    <Button filled secondary>secondary</Button>
  </Row>
  <Row flexWrap>
    <Button primary>primary</Button>
    <Button accent>accent</Button>
    <Button secondary>secondary</Button>
  </Row>
  <Row flexWrap>
    <Button ghost primary>primary</Button>
    <Button ghost accent>accent</Button>
    <Button ghost secondary>secondary</Button>
  </Row>
</Col>
```

## Shapes

Button supports three border-radius styles: `rounded` (default), `pill`, and `sharp`.

```tsx demo
<Row flexWrap>
  <Button pill>Subscribe</Button>
  <Button sharp>Subscribe</Button>
  <Button rounded>Subscribe</Button>
</Row>
```

## With icon

Drop an icon directly inside the button. `gap` is on by default, so spacing is automatic.

```tsx demo
<Row flexWrap>
  <Button><Download/> Download</Button>
  <Button success filled><Check/> Saved</Button>
  <Button danger><Trash2/> Delete</Button>
  <Button secondary>Next <ArrowRight/></Button>
</Row>
```

## Sizes with icon

The same size matrix paired with an inline icon.

```tsx demo
<Row flexWrap>
  <Button xs><Star/> Extra Small</Button>
  <Button sm><Star/> Small</Button>
  <Button md><Star/> Medium</Button>
  <Button lg><Star/> Large</Button>
  <Button xl><Star/> Extra Large</Button>
</Row>
```

## Font weights

Buttons default to `fontSemibold`. Use any of the standard weight props to override.

```tsx demo
<Row flexWrap>
  <Button fontThin>Submit</Button>
  <Button fontExtralight>Submit</Button>
  <Button fontLight>Submit</Button>
  <Button fontNormal>Submit</Button>
  <Button fontMedium>Submit</Button>
  <Button fontSemibold>Submit</Button>
  <Button fontBold>Submit</Button>
  <Button fontExtrabold>Submit</Button>
  <Button fontBlack>Submit</Button>
</Row>
```

## As Link and disabled

Pass `href` to render the button as an `<a>` for navigation. Use `disabled` to prevent interaction.

```tsx demo
<Row flexWrap>
  <Button href="#">Link Button</Button>
  <Button success filled href="#">Success Link</Button>
  <Button disabled>Disabled</Button>
  <Button danger filled disabled>Disabled Danger</Button>
</Row>
```

## Loading state

Set `loading` to swap the label for a spinner and auto-disable the button. The width is kept, so the layout does not jump when the state flips.

```tsx demo
<Row flexWrap itemsCenter>
  <Button loading>Saving</Button>
  <Button loading filled danger>Deleting</Button>
  <Button loading lg>Large</Button>
</Row>
```

The ring is the `Spinner` component, so there is one spinner in the library and restyling `theme.spinner` restyles both. The button forwards its own size, and the ring inherits the button's text colour: a filled button gets a light ring, an outline button a dark one.

It is decorative here rather than a live region. The button already carries `aria-busy`, so the Spinner's `role="status"` is suppressed and the accessible name stays the button's own.

```tsx demo
const [loading, setLoading] = useState(false);

return (
  <Button loading={loading} onClick={() => setLoading(true)}>
    Submit
  </Button>
);
```

## Next.js Link integration

Use the `tag` prop to render the button as a Next.js `Link` for client-side navigation.

```tsx
import Link from 'next/link';
import { Button } from '@vaneui/ui';

<Button href="/docs" tag={Link}>Documentation</Button>
```

## Customizing

Set app-wide Button defaults with `ThemeProvider`'s `themeDefaults`:

```tsx demo
<ThemeProvider themeDefaults={{
  button: { main: { primary: true, lg: true, filled: true } },
}}>
  <Button>Submit</Button>
</ThemeProvider>
```

Add prop-conditional classes with `extraClasses`, applied whenever the matching boolean prop is active. For compound themes like Button, nest the prop-class map under the sub-theme name (`main` for Button's primary surface):

```tsx demo
<ThemeProvider extraClasses={{
  button: {
    main: {
      primary: 'shadow-lg hover:shadow-xl transition-shadow',
      danger: 'animate-pulse',
    },
  },
}}>
  <Button primary>Glowing Primary</Button>
</ThemeProvider>
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold` (default), `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Size: `inheritSize`, `noInheritSize`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm` (default), `md`, `lg`, `xl`
- Text Align: `textLeft`, `textCenter` (default), `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# IconButton

> A square icon-only button with customizable appearance, size, and shape. Supports loading state and renders as anchor when href is provided.

Source: https://vaneui.com/docs/basic-components/icon-button

Import: `import { IconButton, Col, Row, Text, ThemeProvider } from "@vaneui/ui"`

IconButton is for a toolbar action or a dismiss control that has no room for a text label. It renders a `<button>` with the same `sm` default size as [Button](/docs/basic-components/button), so it lines up with a Button placed beside it. When the action needs visible text, use Button; for a glyph that does nothing on click, use [Icon](/docs/basic-components/icon).

## Basic usage

Drop an icon directly inside the `IconButton`. Each `appearance` prop maps to a semantic color from the active theme.

```tsx demo
<Row flexWrap>
  <IconButton aria-label="Favorite"><Star /></IconButton>
  <IconButton secondary aria-label="Like"><Heart /></IconButton>
  <IconButton success aria-label="Confirm"><Check /></IconButton>
  <IconButton danger aria-label="Delete"><Trash2 /></IconButton>
  <IconButton warning aria-label="Notifications"><Bell /></IconButton>
  <IconButton info aria-label="Show info"><Info /></IconButton>
</Row>
```

## Accessibility

An icon-only button has no visible text, so assistive technology has nothing to announce. Give every `IconButton` an accessible name with `aria-label`.

```tsx demo
<Row flexWrap>
  <IconButton aria-label="Add to favorites"><Star /></IconButton>
  <IconButton secondary aria-label="Like"><Heart /></IconButton>
  <IconButton danger aria-label="Delete"><Trash2 /></IconButton>
</Row>
```

## Sizes

IconButton supports five sizes: `xs`, `sm` (default), `md`, `lg`, `xl`. Size drives the button's dimensions, padding, and border-radius; the aspect ratio stays square at every size.

```tsx demo
<Row flexWrap itemsEnd>
  <Col itemsCenter>
    <IconButton xs><Star /></IconButton>
    <Text sm secondary>xs</Text>
  </Col>
  <Col itemsCenter>
    <IconButton sm><Star /></IconButton>
    <Text sm secondary>sm</Text>
  </Col>
  <Col itemsCenter>
    <IconButton md><Star /></IconButton>
    <Text sm secondary>md</Text>
  </Col>
  <Col itemsCenter>
    <IconButton lg><Star /></IconButton>
    <Text sm secondary>lg</Text>
  </Col>
  <Col itemsCenter>
    <IconButton xl><Star /></IconButton>
    <Text sm secondary>xl</Text>
  </Col>
</Row>
```

## Variants

IconButton renders as `outline` (default) or `filled`.

```tsx demo
<Col>
  <Row flexWrap>
    <IconButton><Star /></IconButton>
    <IconButton secondary><Heart /></IconButton>
    <IconButton success><Check /></IconButton>
    <IconButton danger><Trash2 /></IconButton>
    <IconButton warning><Bell /></IconButton>
    <IconButton info><Info /></IconButton>
  </Row>
  <Row flexWrap>
    <IconButton filled><Star /></IconButton>
    <IconButton filled secondary><Heart /></IconButton>
    <IconButton filled success><Check /></IconButton>
    <IconButton filled danger><Trash2 /></IconButton>
    <IconButton filled warning><Bell /></IconButton>
    <IconButton filled info><Info /></IconButton>
  </Row>
</Col>
```

## Shapes

IconButton supports `rounded` (default), `pill`, and `sharp`. `pill` is especially well suited to icon-only buttons.

```tsx demo
<Row flexWrap>
  <Col itemsCenter>
    <IconButton filled><Star /></IconButton>
    <Text sm secondary>rounded</Text>
  </Col>
  <Col itemsCenter>
    <IconButton pill filled><Star /></IconButton>
    <Text sm secondary>pill</Text>
  </Col>
  <Col itemsCenter>
    <IconButton sharp filled><Star /></IconButton>
    <Text sm secondary>sharp</Text>
  </Col>
</Row>
```

## As Link and disabled

Pass `href` to render the IconButton as an `<a>` for navigation. Use `disabled` to prevent interaction.

```tsx demo
<Row flexWrap>
  <IconButton href="https://github.com" target="_blank"><ExternalLink /></IconButton>
  <IconButton filled success href="#"><ExternalLink /></IconButton>
  <IconButton disabled><Star /></IconButton>
  <IconButton filled danger disabled><Trash2 /></IconButton>
</Row>
```

## Next.js Link integration

Use the `tag` prop to render the IconButton as a Next.js `Link` for client-side navigation.

```tsx
import Link from 'next/link';
import { IconButton } from '@vaneui/ui';
import { Settings } from 'react-feather';

<IconButton href="/settings" tag={Link}><Settings /></IconButton>
```

## Loading state

Set `loading` to replace the icon with a spinner and auto-disable the button.

```tsx demo
<Row flexWrap itemsCenter>
  <IconButton loading aria-label="Refreshing"><RefreshCw /></IconButton>
  <IconButton loading filled danger aria-label="Deleting"><Trash2 /></IconButton>
  <IconButton loading lg aria-label="Saving"><Star /></IconButton>
</Row>
```

The ring is the `Spinner` component, sized from the button and coloured by the button's own text colour, so it reads correctly on every variant. Keep the `aria-label` describing the action: the button carries `aria-busy` while it spins, and the Spinner itself is decorative here.

```tsx demo
const [loading, setLoading] = useState(false);

return (
  <IconButton loading={loading} onClick={() => setLoading(true)} aria-label="Favorite">
    <Star />
  </IconButton>
);
```

## Customizing

Set app-wide IconButton defaults with `ThemeProvider`'s `themeDefaults`:

```tsx demo
<ThemeProvider themeDefaults={{
  iconButton: { secondary: true, pill: true, lg: true },
}}>
  <IconButton><Star /></IconButton>
</ThemeProvider>
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans`, `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Size: `inheritSize`, `noInheritSize`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm` (default), `md`, `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# NavLink

> A navigation link for sidebars, nav menus and tab bars. Supports active state, icons, start and bottom indicator lines, and renders as anchor or button.

Source: https://vaneui.com/docs/basic-components/navlink

Import: `import { NavLink, Badge, Card, Col, Divider, Row, Text, ThemeProvider } from "@vaneui/ui"`

NavLink is one entry in a sidebar or a tab bar and points at one destination. For a link inside a sentence, use [Link](/docs/typography-components/link); for a list of actions that opens from a trigger, use [Menu](/docs/overlay-components/menu). In its `<button>` form (no `href`), NavLink defaults to `type="button"`, so a click inside a `<form>` does not submit the form.

## Basic usage

NavLink renders as an `<a>` when `href` is provided. Defaults to `sm` size, `primary` appearance, `outline` variant, `wFull` and `textLeft` layout, ideal for stacking inside a sidebar `Col`.

```tsx demo
<Col className="w-64">
  <NavLink href="#">Home</NavLink>
  <NavLink href="#">Dashboard</NavLink>
  <NavLink href="#">Settings</NavLink>
</Col>
```

## Sizes

NavLink supports five sizes: `xs`, `sm` (default), `md`, `lg`, `xl`. Size drives font-size, padding, gap, and border-radius simultaneously via CSS variables.

```tsx demo
<Col className="w-72">
  <NavLink xs href="#"><Home size={12} /> XS NavLink</NavLink>
  <NavLink href="#"><Home size={14} /> SM NavLink</NavLink>
  <NavLink md href="#"><Home size={16} /> MD NavLink</NavLink>
  <NavLink lg href="#"><Home size={18} /> LG NavLink</NavLink>
  <NavLink xl href="#"><Home size={20} /> XL NavLink</NavLink>
</Col>
```

## Active state

Use the `active` prop to indicate the current page. Active NavLinks get a `data-active` attribute for styling; the `href` (anchor) form also gets `aria-current="page"` (the no-href button form omits it).

```tsx demo
<Col className="w-64">
  <NavLink href="#">Home</NavLink>
  <NavLink href="#" active>Dashboard</NavLink>
  <NavLink href="#">Settings</NavLink>
  <NavLink href="#">Profile</NavLink>
</Col>
```

## With icon

Drop an icon directly inside the NavLink. `gap` is on by default, so spacing is automatic. React elements rendered before any text become the leading icon; text is auto-wrapped in a label span with truncation; elements after text become trailing accessories.

```tsx demo
<Col className="w-64">
  <NavLink href="#"><Home size={16} /> Home</NavLink>
  <NavLink href="#" active><FileText size={16} /> Documents</NavLink>
  <NavLink href="#"><Users size={16} /> Team</NavLink>
  <NavLink href="#"><Settings size={16} /> Settings</NavLink>
</Col>
```

## Appearances and variants

NavLinks default to `primary outline`. Use `filled` for solid backgrounds. Active state works with all appearances.

```tsx demo
<Row flexWrap>
  <Col className="w-48">
    <Text sm fontSemibold secondary>Outline (default)</Text>
    <NavLink href="#" active>Primary</NavLink>
    <NavLink href="#" success active>Success</NavLink>
    <NavLink href="#" danger active>Danger</NavLink>
    <NavLink href="#" secondary active>Secondary</NavLink>
  </Col>
  <Col className="w-48">
    <Text sm fontSemibold secondary>Filled</Text>
    <NavLink href="#" filled active>Primary</NavLink>
    <NavLink href="#" success filled active>Success</NavLink>
    <NavLink href="#" danger filled active>Danger</NavLink>
    <NavLink href="#" secondary filled active>Secondary</NavLink>
  </Col>
</Row>
```

## Shapes

NavLink is `rounded` by default. `sharp` fits a full-bleed sidebar where the item runs to the panel edge; `pill` suits a horizontal nav.

```tsx demo
<Col className="w-72">
  <NavLink href="#">Rounded, the default</NavLink>
  <NavLink sharp href="#">Sharp</NavLink>
  <NavLink pill href="#">Pill</NavLink>
</Col>
```

## Disabled state

Use `disabled` to prevent interaction. When `disabled` is combined with `href`, the `href` is dropped and it renders as a non-navigable anchor (`role="link"`, `aria-disabled="true"`) that stays focusable but cannot be followed.

```tsx demo
<Col className="w-64">
  <NavLink href="#"><Home size={16} /> Active Link</NavLink>
  <NavLink href="#" disabled><Lock size={16} /> Disabled Link</NavLink>
  <NavLink href="#" active><Settings size={16} /> Current Page</NavLink>
  <NavLink href="#" disabled><Users size={16} /> Restricted</NavLink>
</Col>
```

## As Button (no href)

Without `href`, NavLink renders as a `<button>`, useful for menu items that trigger actions instead of navigating.

```tsx demo
<Col className="w-64">
  <NavLink onClick={() => alert('Profile')}><User size={16} /> Profile</NavLink>
  <NavLink onClick={() => alert('Sign out')}><LogOut size={16} /> Sign out</NavLink>
</Col>
```

## Sidebar navigation

A real-world sidebar pattern with icons, active state, dividers, and trailing badges. The active item is semibold on a tinted background, the label takes the free space so a trailing `Badge` sits at the row's end, and icons take the NavLink's size.

```tsx demo
<Card className="w-64" noGap>
  <Text sm fontSemibold secondary>Navigation</Text>
  <Divider />
  <NavLink href="#"><Home /> Home</NavLink>
  <NavLink href="#" active><FileText /> Documents</NavLink>
  <NavLink href="#"><Mail /> Messages <Badge xs info>3</Badge></NavLink>
  <NavLink href="#"><Bell /> Notifications <Badge xs danger>12</Badge></NavLink>
  <NavLink href="#"><Star /> Favorites</NavLink>
  <Divider />
  <NavLink href="#"><Users /> Team</NavLink>
  <NavLink href="#"><Settings /> Settings</NavLink>
</Card>
```

## Horizontal navigation

NavLink is `wFull` so sidebar items fill the column. In a horizontal nav or a tab bar, add `wFit` so each item keeps its own width.

```tsx demo
<Row>
  <NavLink href="#" active wFit>Description</NavLink>
  <NavLink href="#" wFit>Reviews</NavLink>
  <NavLink href="#" wFit>Shipping</NavLink>
</Row>
```

## Indicator lines with indicatorStart and indicatorBottom

To mark the current item with a line as well as a tint, add `indicatorStart` or `indicatorBottom`. `indicatorStart` draws a 1px rail on the start edge of every link, and on the `active` link it turns into a 2px mark in the accent color. Stacked links join their rails into one line down the sidebar.

```tsx demo
<Col noGap className="w-56">
  <NavLink href="#" indicatorStart ghost sharp secondary>Installation</NavLink>
  <NavLink href="#" indicatorStart ghost sharp active>Core concepts</NavLink>
  <NavLink href="#" indicatorStart ghost sharp secondary>Theming</NavLink>
</Col>
```

`indicatorBottom` draws an accent bar under the active link, or under a link with `aria-selected="true"` such as a `role="tab"` tab, for a tab bar. Put the tabs in a [Row](/docs/layout-components/row) with `noGap` and `borderB`, so the bar sits on the row's bottom border.

```tsx demo
<Row noGap borderB>
  <NavLink href="#" indicatorBottom ghost sharp active wFit>Docs</NavLink>
  <NavLink href="#" indicatorBottom ghost sharp secondary wFit>Playground</NavLink>
  <NavLink href="#" indicatorBottom ghost sharp secondary wFit>Changelog</NavLink>
</Row>
```

Both indicators are inset shadows, so the text does not move when the active item changes. Inside a `dir="rtl"` container, the start rail moves to the right edge. The examples pair the indicators with `ghost` and `sharp`, so the lines meet square corners, and with `secondary` on the inactive links. The indicator props need `@vaneui/ui` 1.4.5 or later, and the `aria-selected` bar on `indicatorBottom` needs 1.5.0.

## Selected options in a listbox

A NavLink with `aria-selected="true"` takes the hover fill, so the highlighted option in a listbox, such as a search result picked with the arrow keys, stays visible while the pointer is elsewhere. Give the container `role="listbox"` and each NavLink `role="option"`. With `indicatorStart`, the selected option also gets the accent mark.

```tsx demo
<Col noGap role="listbox" aria-label="Search results" className="w-56">
  <NavLink role="option" aria-selected="true" indicatorStart ghost sharp>Button</NavLink>
  <NavLink role="option" aria-selected="false" indicatorStart ghost sharp secondary>Badge</NavLink>
  <NavLink role="option" aria-selected="false" indicatorStart ghost sharp secondary>Card</NavLink>
</Col>
```

In a search box built as a combobox, keyboard focus stays in the input, and `aria-activedescendant` on the input names the selected option's `id`. `MenuItem` takes the same fill for `aria-selected="true"`, but its default `role="menuitem"` has no selected state, so use NavLink for options.

## Keyboard focus

NavLink renders a keyboard focus-visible outline by default so keyboard users can see where they are. Opt out with `noFocusVisible`.

## Next.js Link integration

Use the `tag` prop to render NavLink as a Next.js `Link` for client-side navigation.

```tsx
import Link from 'next/link';
import { NavLink } from '@vaneui/ui';

<NavLink href="/docs" tag={Link} active={pathname === '/docs'}>
  Documentation
</NavLink>
```

## Customizing

Set app-wide NavLink defaults with `ThemeProvider`'s `themeDefaults`. Style the active state by targeting the emitted `data-active` attribute in your own CSS: `extraClasses` keys apply only to category props, so an `active` key there has no effect.

```tsx demo
<ThemeProvider themeDefaults={{ navLink: { root: { md: true } } }}>
  <NavLink href="/docs" active>Docs</NavLink>
</ThemeProvider>
```

```css
.vane-nav-link[data-active] {
  background: #eff6ff;
  color: #1d4ed8;
  font-weight: 600;
}
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Indicator: `indicatorStart`, `indicatorBottom`
- Inherit Size: `inheritSize`, `noInheritSize`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm` (default), `md`, `lg`, `xl`
- Text Align: `textLeft` (default), `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Badge

> Badge highlights information such as notifications or counts in a non-intrusive way. Often paired with other elements like icons or navigation links.

Source: https://vaneui.com/docs/basic-components/badge

Import: `import { Badge, Card, Col, Row, Text, ThemeProvider, Title } from "@vaneui/ui"`

Badge adds a short label, such as an unread count, "Live" or "Pro", next to a title or inside a [NavLink](/docs/basic-components/navlink). It renders a `<span>` whose text stays on one line, and switches to `<a>` when `href` is set. For a tag or filter token, use a [Chip](/docs/basic-components/chip), and when clicking the label should run an action, use a [Button](/docs/basic-components/button).

## Basic usage

Badge highlights a short piece of information such as a count or status, and each `appearance` prop maps to a semantic color from the active theme. Badge defaults to `md`, `secondary`, `outline`, `pill`, and `fontSemibold` in normal case. Add `uppercase` for a status-chip look.

```tsx demo
<Row flexWrap>
  <Badge primary>primary</Badge>
  <Badge accent>accent</Badge>
  <Badge secondary>secondary</Badge>
  <Badge tertiary>tertiary</Badge>
  <Badge success>success</Badge>
  <Badge danger>danger</Badge>
  <Badge warning>warning</Badge>
  <Badge info>info</Badge>
  <Badge inheritAppearance>inheritAppearance</Badge>
</Row>
```

## Sizes

Badges come in different sizes such as `xs`, `sm`, `md` (default), `lg`, `xl`.

```tsx demo
<Row flexWrap>
  <Badge xs>xs</Badge>
  <Badge sm>sm</Badge>
  <Badge md>md</Badge>
  <Badge lg>lg</Badge>
  <Badge xl>xl</Badge>
</Row>
```

## Variants

Badges can be styled as `filled`, `outline` (default), or `ghost`.

```tsx demo
<Col>
  <Row flexWrap>
    <Badge filled primary>primary</Badge>
    <Badge filled accent>accent</Badge>
    <Badge filled secondary>secondary</Badge>
  </Row>
  <Row flexWrap>
    <Badge outline primary>primary</Badge>
    <Badge outline accent>accent</Badge>
    <Badge outline secondary>secondary</Badge>
  </Row>
  <Row flexWrap>
    <Badge ghost primary>primary</Badge>
    <Badge ghost accent>accent</Badge>
    <Badge ghost secondary>secondary</Badge>
  </Row>
</Col>
```

## Shapes

Badges support different border radius styles: `rounded`, `pill` (default), and `sharp`.

```tsx demo
<Row flexWrap>
  <Badge pill>Pro</Badge>
  <Badge sharp>Pro</Badge>
  <Badge rounded>Pro</Badge>
</Row>
```

## Font weights

Badges support different font weights.

```tsx demo
<Row flexWrap>
  <Badge fontNormal>Premium</Badge>
  <Badge fontMedium>Premium</Badge>
  <Badge fontSemibold>Premium</Badge>
  <Badge fontBold>Premium</Badge>
</Row>
```

## As Link

Pass `href` to render the badge as an `<a>`, useful for clickable status labels. When `href` is set, the badge gains a keyboard focus-visible outline by default (opt out with `noFocusVisible`).

```tsx demo
<Row flexWrap>
  <Badge href="#">Status</Badge>
  <Badge href="#" success filled>Live</Badge>
  <Badge href="#" warning>Pending</Badge>
</Row>
```

## Status badges in context

Badges work well as status indicators inside cards and other layout components.

```tsx demo
<Card>
  <Row justifyBetween>
    <Title>Production deploy</Title>
    <Badge success filled>Live</Badge>
  </Row>
  <Text>Build #1284 promoted to production 2 minutes ago.</Text>
</Card>
```

## Customizing

Set app-wide Badge defaults with `ThemeProvider`'s `themeDefaults`:

```tsx demo
<ThemeProvider themeDefaults={{
  badge: { success: true, uppercase: true },
}}>
  <Badge>Live</Badge>
</ThemeProvider>
```

## Props

- Appearance: `primary`, `accent`, `secondary` (default), `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold` (default), `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Size: `inheritSize`, `noInheritSize`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Shape: `pill` (default), `sharp`, `rounded`
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Chip

> Compact token for tags, attributes, or other discrete entities inline with text. Defaults to secondary appearance, outline variant, and rounded shape.

Source: https://vaneui.com/docs/basic-components/chip

Import: `import { Chip, Card, Col, IconButton, Row, Text, ThemeProvider, Title } from "@vaneui/ui"`

Chip is for values a reader scans as a group, such as the tags on an article or the filters applied to a list. It renders a `<span>`, or an `<a>` when `href` is set, and its label does not wrap. For a count or status indicator, use a [Badge](/docs/basic-components/badge). When clicking the token should run an action rather than follow a link, use a [Button](/docs/basic-components/button), which renders a native `<button>`.

## Basic usage

Chip is a compact token for tags or attributes, and each `appearance` prop maps to a semantic color from the active theme.

```tsx demo
<Row flexWrap>
  <Chip primary>primary</Chip>
  <Chip accent>accent</Chip>
  <Chip>secondary</Chip>
  <Chip tertiary>tertiary</Chip>
  <Chip success>success</Chip>
  <Chip danger>danger</Chip>
  <Chip warning>warning</Chip>
  <Chip info>info</Chip>
  <Chip inheritAppearance>inheritAppearance</Chip>
</Row>
```

## Sizes

Chips come in five sizes: `xs`, `sm`, `md` (default), `lg`, `xl`. Size drives font-size, padding, gap, and border-radius simultaneously via CSS variables.

```tsx demo
<Row flexWrap>
  <Chip xs>xs</Chip>
  <Chip sm>sm</Chip>
  <Chip>md</Chip>
  <Chip lg>lg</Chip>
  <Chip xl>xl</Chip>
</Row>
```

## Variants

Chips can be styled as `filled`, `outline` (default), or `ghost`.

```tsx demo
<Col>
  <Row flexWrap>
    <Chip filled primary>primary</Chip>
    <Chip filled accent>accent</Chip>
    <Chip filled>secondary</Chip>
  </Row>
  <Row flexWrap>
    <Chip primary>primary</Chip>
    <Chip accent>accent</Chip>
    <Chip>secondary</Chip>
  </Row>
  <Row flexWrap>
    <Chip ghost primary>primary</Chip>
    <Chip ghost accent>accent</Chip>
    <Chip ghost>secondary</Chip>
  </Row>
</Col>
```

## Shapes

Chips support three border-radius styles: `rounded` (default), `pill`, and `sharp`.

```tsx demo
<Row flexWrap>
  <Chip>rounded</Chip>
  <Chip pill>pill</Chip>
  <Chip sharp>sharp</Chip>
</Row>
```

## Font family

Chips default to `fontSans`. Override with `fontMono` for code-adjacent tokens or `fontSerif` when the surrounding copy calls for it.

```tsx demo
<Row flexWrap>
  <Chip fontMono>v1.4.2</Chip>
  <Chip>Active user</Chip>
  <Chip fontSerif>Editorial</Chip>
</Row>
```

## With icon

Drop an icon directly inside the chip. `gap` is on by default, so spacing is automatic.

```tsx demo
<Row flexWrap>
  <Chip info><Heart/> Favorite</Chip>
  <Chip success><CheckSquare/> Verified</Chip>
  <Chip danger><X/> Blocked</Chip>
</Row>
```

## Tag lists

The canonical chip pattern: a wrapping row of tokens that label or categorize content. Chip is presentational, so for clickable tags give it an `href` (see As Link) or wire your own `onClick` (see Clickable chips).

```tsx demo
<Card>
  <Title>Article tags</Title>
  <Row flexWrap>
    <Chip>typescript</Chip>
    <Chip>react</Chip>
    <Chip>tailwind</Chip>
    <Chip>design-systems</Chip>
    <Chip>accessibility</Chip>
  </Row>
</Card>
```

## Removable chips

Chip is presentational, so wire removal yourself: compose an `IconButton` as the close control and drop the tag from your own state. The trailing `IconButton` owns the click target and carries an accessible label, and adds no height to the chip.

```tsx demo
const [tags, setTags] = React.useState(['typescript', 'react', 'tailwind']);
return (
  <Row flexWrap>
    {tags.map(tag => (
      <Chip key={tag}>
        {tag}
        <IconButton xs ghost aria-label={`Remove ${tag}`} onClick={() => setTags(tags.filter(t => t !== tag))}>
          <X/>
        </IconButton>
      </Chip>
    ))}
    {tags.length === 0 && <Text secondary>All tags removed.</Text>}
  </Row>
);
```

## As Link

Pass `href` to render the chip as an `<a>`, useful for clickable tag listings. When `href` is set, the chip gains a keyboard focus-visible outline by default, and so does a chip with `onClick` or `tag="button"`. Opt out with `noFocusVisible`. A linked chip tints on hover.

```tsx demo
<Row flexWrap>
  <Chip href="#">typescript</Chip>
  <Chip href="#" info>react</Chip>
  <Chip href="#" accent>tailwind</Chip>
</Row>
```

## Clickable chips

A Chip with `onClick` and no `href` stays a `<span>` but gets `role="button"`, a tab stop, and activation with Enter and Space. A `disabled` one stays focusable with `aria-disabled` and does nothing when activated. A `role` or `tabIndex` you pass wins. This needs `@vaneui/ui` 1.5.0 or later.

```tsx demo
const [selected, setSelected] = useState(['react']);
const toggle = (tag: string) =>
  setSelected(selected.includes(tag) ? selected.filter(t => t !== tag) : [...selected, tag]);

return (
  <Row flexWrap>
    {['typescript', 'react', 'tailwind'].map(tag => (
      <Chip
        key={tag}
        filled={selected.includes(tag)}
        aria-pressed={selected.includes(tag)}
        onClick={() => toggle(tag)}
      >
        {tag}
      </Chip>
    ))}
    <Chip disabled onClick={() => {}}>archived</Chip>
  </Row>
);
```

## Customizing

Set app-wide Chip defaults with `ThemeProvider`'s `themeDefaults`:

```tsx demo
<ThemeProvider themeDefaults={{
  chip: { info: true, filled: true, pill: true },
}}>
  <Chip>v2.0</Chip>
</ThemeProvider>
```

Add prop-conditional classes with `extraClasses`, applied whenever the matching boolean prop is active:

```tsx demo
<ThemeProvider extraClasses={{
  chip: {
    danger: 'animate-pulse',
    success: 'shadow-sm',
  },
}}>
  <Chip danger>blocked</Chip>
</ThemeProvider>
```

## Props

- Appearance: `primary`, `accent`, `secondary` (default), `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal` (default), `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Size: `inheritSize`, `noInheritSize`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Code

> Renders inline code snippets in a themed monospace surface. Use for commands, file paths, or technical terms in prose; renders as an anchor when given href.

Source: https://vaneui.com/docs/basic-components/code

Import: `import { Code, Button, Col, PageTitle, Row, SectionTitle, Text, Title } from "@vaneui/ui"`

Code sets apart the parts of a sentence that a reader would type or copy, such as a package name, a hook or a prop value. It renders a native `<code>` whose text does not wrap, so it suits short snippets rather than multi-line listings. For keys the reader presses, use [Kbd](/docs/basic-components/kbd), and for a phrase that only needs emphasis, a [Mark](/docs/basic-components/mark) highlight.

## Basic usage

Inline code snippets with default styling. `Code` aligns to the surrounding text's baseline, so it lines up with the text it's inlined in. Pass `href` to render `Code` as `<a>` instead of `<code>`. A focus-visible outline auto-enables when `href` is set.

```tsx demo
<Col>
  <Text>Run <Code>npm install</Code> to install packages.</Text>
  <Text>Declare a constant with <Code>{"const x = 'value'"}</Code>.</Text>
</Col>
```

## Sizes

Code elements in different sizes: `xs`, `sm`, `md`, `lg`, `xl`.

```tsx demo
<Col>
  <Text>Size xs: <Code xs>{"console.log('Hello')"}</Code></Text>
  <Text>Size sm: <Code sm>{"console.log('Hello')"}</Code></Text>
  <Text>Size md: <Code md>{"console.log('Hello')"}</Code></Text>
  <Text>Size lg: <Code lg>{"console.log('Hello')"}</Code></Text>
  <Text>Size xl: <Code xl>{"console.log('Hello')"}</Code></Text>
</Col>
```

## Appearances

Different appearance colors for inline code.

```tsx demo
<Row flexWrap>
  <Code primary>primary code</Code>
  <Code accent>accent code</Code>
  <Code secondary>secondary code</Code>
  <Code tertiary>tertiary code</Code>
  <Code success>success code</Code>
  <Code danger>danger code</Code>
  <Code warning>warning code</Code>
  <Code info>info code</Code>
  <Code inheritAppearance>inheritAppearance code</Code>
</Row>
```

## Variants

Code defaults to `outline` variant. Use `filled` for stronger visual emphasis.

```tsx demo
<Col>
  <Text>Default outline: <Code>npm install</Code> then <Code>npm run build</Code></Text>
  <Text>Filled: <Code filled>git commit</Code> then <Code filled>git push</Code></Text>
  <Text>Colored filled: <Code success filled>200 OK</Code> <Code danger filled>500 Error</Code> <Code warning filled>deprecated</Code></Text>
</Col>
```

## Shapes

Code supports `rounded` (default), `pill`, and `sharp` border-radius styles.

```tsx demo
<Row flexWrap>
  <Code rounded>rounded</Code>
  <Code pill>pill</Code>
  <Code sharp>sharp</Code>
</Row>
```

## Code in context

Code elements used within text content.

```tsx demo
<Col>
  <Text>
    To create a new React component, use <Code>{"function Component() {}"}</Code> or
    the arrow function syntax <Code>{"const Component = () => {}"}</Code>.
  </Text>
  <p>
    Install the package with <Code primary>npm i @vaneui/ui</Code> and then
    import it using <Code secondary>{'import { Button } from "@vaneui/ui"'}</Code>.
  </p>
  <Text>
    The <Code info>useState</Code> hook returns an array with two elements:
    the current state value and a setter function like <Code info>[state, setState]</Code>.
  </Text>
</Col>
```

## In heading context

Code uses an em-based geometry pipeline: at the default `md` size it renders at ~87.5% of the surrounding text's font-size, with padding and border-radius scaling proportionally. The same `<Code>` looks right inside body copy, a subheading, a section heading, or a page title.

```tsx demo
<Col>
  <Text>Body text with <Code>npm install</Code> inline.</Text>
  <Title>Subheading: run <Code>npm run build</Code> first.</Title>
  <SectionTitle>Section: <Code>useState</Code> hook</SectionTitle>
  <PageTitle><Code>@vaneui/ui</Code></PageTitle>
</Col>
```

## As Link

Add `href` to render the `Code` element as an `<a>` tag. A keyboard focus-visible outline auto-renders so the link is reachable via Tab; opt out with `noFocusVisible`.

```tsx demo
<Col>
  <Text>Install <Code href="https://npmjs.com/package/@vaneui/ui" target="_blank" rel="noopener noreferrer">@vaneui/ui</Code> from npm.</Text>
  <Text>The <Code href="https://react.dev/reference/react/useState" target="_blank" rel="noopener noreferrer" info>useState</Code> hook returns a value and a setter.</Text>
  <Text>See the <Code href="/docs/getting-started/installation" filled success>install guide</Code> for setup steps.</Text>
</Col>
```

## Next.js Link integration

Use the `tag` prop to render `Code` as a Next.js `Link` for client-side navigation.

```tsx
import Link from 'next/link';
import { Code, Text } from '@vaneui/ui';

<Text>
  Read the <Code href="/docs/getting-started" tag={Link}>getting started guide</Code> for setup steps.
</Text>
```

## Props

- Appearance: `primary`, `accent`, `secondary` (default), `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans`, `fontSerif`, `fontMono` (default), `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal` (default), `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Size: `inheritSize`, `noInheritSize`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Kbd

> Displays keyboard keys and shortcuts with monospace font, border, and a raised 3D effect. Ideal for documenting keyboard shortcuts.

Source: https://vaneui.com/docs/basic-components/kbd

Import: `import { Kbd, Col, PageTitle, Row, SectionTitle, Text, Title } from "@vaneui/ui"`

Use Kbd for the keys a reader presses and [Code](/docs/basic-components/code) for inline source or literal values. Kbd renders the native `<kbd>` element, with a font one step smaller than Code at the same size. Its keycap edge comes from a bottom border twice as thick as the other three sides.

## Basic usage

Display keyboard keys with the `Kbd` component. Kbd defaults to a monospace font, a border, and `md` size.

```tsx demo
<Row flexWrap>
  <Kbd>Ctrl</Kbd>
  <Kbd>Shift</Kbd>
  <Kbd>Enter</Kbd>
  <Kbd>Esc</Kbd>
  <Kbd>Tab</Kbd>
</Row>
```

## Sizes

Kbd elements in different sizes: `xs`, `sm`, `md` (default), `lg`, `xl`.

```tsx demo
<Row flexWrap itemsEnd>
  <Col itemsCenter>
    <Kbd xs>Ctrl</Kbd>
    <Text sm secondary>xs</Text>
  </Col>
  <Col itemsCenter>
    <Kbd sm>Ctrl</Kbd>
    <Text sm secondary>sm</Text>
  </Col>
  <Col itemsCenter>
    <Kbd>Ctrl</Kbd>
    <Text sm secondary>md</Text>
  </Col>
  <Col itemsCenter>
    <Kbd lg>Ctrl</Kbd>
    <Text sm secondary>lg</Text>
  </Col>
  <Col itemsCenter>
    <Kbd xl>Ctrl</Kbd>
    <Text sm secondary>xl</Text>
  </Col>
</Row>
```

## Appearances

Different color appearances for keyboard keys.

```tsx demo
<Row flexWrap>
  <Kbd primary>Ctrl</Kbd>
  <Kbd accent>Alt</Kbd>
  <Kbd secondary>Tab</Kbd>
  <Kbd tertiary>Esc</Kbd>
  <Kbd success>Enter</Kbd>
  <Kbd danger>Del</Kbd>
  <Kbd warning>Fn</Kbd>
  <Kbd info>F5</Kbd>
</Row>
```

## Shapes

```tsx demo
<Row itemsCenter flexWrap>
  <Kbd>rounded, the default</Kbd>
  <Kbd sharp>sharp</Kbd>
  <Kbd pill>pill</Kbd>
</Row>
```

## Variants

Kbd is `outline` by default, which is what gives it the raised key edge. `filled` trades that for a solid block.

```tsx demo
<Row itemsCenter flexWrap>
  <Kbd>outline, the default</Kbd>
  <Kbd filled>filled</Kbd>
  <Kbd ghost>ghost</Kbd>
</Row>
```

## Key combinations

Combine multiple `Kbd` elements to show keyboard shortcuts.

```tsx demo
<Col>
  <Text><Kbd>Ctrl</Kbd> + <Kbd>C</Kbd> to copy</Text>
  <Text><Kbd>Ctrl</Kbd> + <Kbd>V</Kbd> to paste</Text>
  <Text><Kbd>Ctrl</Kbd> + <Kbd>Shift</Kbd> + <Kbd>P</Kbd> for the command palette</Text>
  <Text><Kbd>Alt</Kbd> + <Kbd>Tab</Kbd> to switch windows</Text>
</Col>
```

## In text context

Kbd elements blend naturally within text content.

```tsx demo
<Col>
  <Text>Press <Kbd>Ctrl</Kbd> + <Kbd>S</Kbd> to save your work.</Text>
  <Text>Use <Kbd sm>Esc</Kbd> to close the dialog.</Text>
  <Text>Hit <Kbd info>F5</Kbd> to refresh the page.</Text>
</Col>
```

## In heading context

Kbd uses an em-based geometry pipeline: its font-size, padding, and border-radius all scale proportionally to the surrounding text. The same `<Kbd>` keeps its keycap look at body, subheading, section heading, and page title sizes.

```tsx demo
<Col>
  <Text>Press <Kbd>Ctrl</Kbd> + <Kbd>S</Kbd> to save.</Text>
  <Title>Subheading: hit <Kbd>Esc</Kbd> to close.</Title>
  <SectionTitle>Section: use <Kbd>Tab</Kbd> to focus</SectionTitle>
  <PageTitle><Kbd>⌘</Kbd> + <Kbd>K</Kbd></PageTitle>
</Col>
```

## Shortcut table

Display a set of keyboard shortcuts in a structured layout.

```tsx demo
<Col>
  <Row justifyBetween><Text>Undo</Text><Text><Kbd>Ctrl</Kbd> + <Kbd>Z</Kbd></Text></Row>
  <Row justifyBetween><Text>Redo</Text><Text><Kbd>Ctrl</Kbd> + <Kbd>Shift</Kbd> + <Kbd>Z</Kbd></Text></Row>
  <Row justifyBetween><Text>Find</Text><Text><Kbd>Ctrl</Kbd> + <Kbd>F</Kbd></Text></Row>
  <Row justifyBetween><Text>Save</Text><Text><Kbd>Ctrl</Kbd> + <Kbd>S</Kbd></Text></Row>
  <Row justifyBetween><Text>Select all</Text><Text><Kbd>Ctrl</Kbd> + <Kbd>A</Kbd></Text></Row>
</Col>
```

## Props

- Appearance: `primary`, `accent`, `secondary` (default), `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans`, `fontSerif`, `fontMono` (default), `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold` (default), `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Size: `inheritSize`, `noInheritSize`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Mark

> Highlights text with a background color for emphasis. Defaults to warning (yellow) appearance for a natural highlighter effect.

Source: https://vaneui.com/docs/basic-components/mark

Import: `import { Mark, Col, PageTitle, Row, SectionTitle, Text, Title } from "@vaneui/ui"`

Mark picks out a search match or a changed value in running text. It renders the native `<mark>` element with no padding and `sharp` corners, so the tint sits flush around the glyphs. In the default `outline` variant, the text keeps the body text color whatever the appearance. For literal values and identifiers, use [Code](/docs/basic-components/code); for a short standalone status label, use a [Badge](/docs/basic-components/badge).

## Basic usage

Highlight text with the `Mark` component. Defaults to `warning` (yellow) appearance for a natural highlighter effect.

```tsx demo
<Row flexWrap>
  <Mark>Highlighted text</Mark>
  <Mark>Important</Mark>
  <Mark>Key term</Mark>
</Row>
```

## Appearances

Different color appearances for highlights. `warning` is the default.

```tsx demo
<Row flexWrap>
  <Mark primary>Primary</Mark>
  <Mark accent>Accent</Mark>
  <Mark secondary>Secondary</Mark>
  <Mark tertiary>Tertiary</Mark>
  <Mark success>Success</Mark>
  <Mark danger>Danger</Mark>
  <Mark warning>Warning</Mark>
  <Mark info>Info</Mark>
</Row>
```

## Variants

Mark supports `outline` (default) and `filled` variants.

```tsx demo
<Col>
  <Row flexWrap>
    <Mark>outline (default)</Mark>
    <Mark primary>primary outline</Mark>
    <Mark success>success outline</Mark>
    <Mark danger>danger outline</Mark>
  </Row>
  <Row flexWrap>
    <Mark filled>filled</Mark>
    <Mark primary filled>primary filled</Mark>
    <Mark success filled>success filled</Mark>
    <Mark danger filled>danger filled</Mark>
  </Row>
</Col>
```

## Shapes

```tsx demo
<Text>
  A <Mark>sharp</Mark> default, a <Mark rounded>rounded</Mark> highlight, and a <Mark pill>pill</Mark> one.
</Text>
```

## Highlight matches context

Mark defaults to `inheritSize: true` so a highlight always renders at the same size as the surrounding text (body copy, subheading, section heading, or page title) without passing any size prop.

```tsx demo
<Col>
  <Text>Body text with a <Mark>highlighted phrase</Mark> inline.</Text>
  <Title>Subheading with <Mark>highlighted text</Mark> inside.</Title>
  <SectionTitle>Section heading with <Mark>a highlight</Mark>.</SectionTitle>
  <PageTitle>Page title <Mark>highlight</Mark></PageTitle>
</Col>
```

## Opting out with noInheritSize

Pass `noInheritSize` together with a size prop to render Mark at a fixed size regardless of the parent.

```tsx demo
<Title>
  Subheading with a <Mark sm noInheritSize>fixed-small highlight</Mark> inside.
</Title>
```

## In text context

Mark elements blend naturally within body text for inline highlights.

```tsx demo
<Col>
  <Text>VaneUI uses a <Mark>boolean props API</Mark> for styling components.</Text>
  <Text>Always wrap your app in <Mark primary>ThemeProvider</Mark> for theming to work.</Text>
  <Text>Components marked with <Mark danger>danger</Mark> indicate destructive actions.</Text>
</Col>
```

## Search highlight pattern

Use Mark to highlight search matches within text content.

```tsx demo
<Col>
  <Text sm secondary>Search results for &quot;React&quot;:</Text>
  <Text>VaneUI is a <Mark>React</Mark> component library built with TypeScript.</Text>
  <Text>All components are <Mark>React</Mark> 19 compatible with server component support.</Text>
  <Text>Use <Mark>React</Mark> hooks like useState with VaneUI form components.</Text>
</Col>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning` (default), `info`, `inheritAppearance`
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans`, `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Size: `inheritSize` (default), `noInheritSize`
- Padding: `padding`, `paddingX`, `paddingY`, `noPadding` (default)
- Shape: `pill`, `sharp` (default), `rounded`
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Icon

> A lightweight SVG wrapper that provides consistent sizing, color inheritance, and themed appearances for icons.

Source: https://vaneui.com/docs/basic-components/icon

Import: `import { Icon, Button, Card, Col, Row, Text } from "@vaneui/ui"`

Icon displays an SVG glyph that is not itself clickable; an icon the user clicks belongs in an [IconButton](/docs/basic-components/icon-button), or inside a [Button](/docs/basic-components/button) next to its label. It wraps the SVG in an inline-flex `<span>` that centers the glyph and keeps it from shrinking in a flex row. Without an accessible name the wrapper gets `aria-hidden`, so screen readers skip it; with `aria-label`, `aria-labelledby` or `title` it gets `role="img"` and is announced.

## Basic usage

Wrap any SVG inside `Icon` to apply consistent sizing and color inheritance.

```tsx demo
<Row flexWrap>
  <Icon><Star /></Icon>
  <Icon><Heart /></Icon>
  <Icon><AlertCircle /></Icon>
  <Icon><Check /></Icon>
  <Icon><Info /></Icon>
</Row>
```

## Sizes

Icons support five sizes: `xs`, `sm`, `md` (default), `lg`, `xl`.

```tsx demo
<Row flexWrap itemsEnd>
  <Col itemsCenter>
    <Icon xs><Star /></Icon>
    <Text sm secondary>xs</Text>
  </Col>
  <Col itemsCenter>
    <Icon sm><Star /></Icon>
    <Text sm secondary>sm</Text>
  </Col>
  <Col itemsCenter>
    <Icon md><Star /></Icon>
    <Text sm secondary>md</Text>
  </Col>
  <Col itemsCenter>
    <Icon lg><Star /></Icon>
    <Text sm secondary>lg</Text>
  </Col>
  <Col itemsCenter>
    <Icon xl><Star /></Icon>
    <Text sm secondary>xl</Text>
  </Col>
</Row>
```

## Appearances

By default, Icon inherits `currentColor` from the parent. Use appearance props to apply themed colors.

```tsx demo
<Row flexWrap>
  <Col itemsCenter>
    <Icon primary><Star /></Icon>
    <Text xs secondary>primary</Text>
  </Col>
  <Col itemsCenter>
    <Icon accent><Star /></Icon>
    <Text xs secondary>accent</Text>
  </Col>
  <Col itemsCenter>
    <Icon secondary><Star /></Icon>
    <Text xs secondary>secondary</Text>
  </Col>
  <Col itemsCenter>
    <Icon tertiary><Star /></Icon>
    <Text xs secondary>tertiary</Text>
  </Col>
  <Col itemsCenter>
    <Icon success><Star /></Icon>
    <Text xs secondary>success</Text>
  </Col>
  <Col itemsCenter>
    <Icon danger><Star /></Icon>
    <Text xs secondary>danger</Text>
  </Col>
  <Col itemsCenter>
    <Icon warning><Star /></Icon>
    <Text xs secondary>warning</Text>
  </Col>
  <Col itemsCenter>
    <Icon info><Star /></Icon>
    <Text xs secondary>info</Text>
  </Col>
</Row>
```

## Variants

Icons support `outline` (default, text color only) and `filled` (background fill) variants.

```tsx demo
<Row flexWrap>
  <Col itemsCenter>
    <Icon primary><Star /></Icon>
    <Text xs secondary>outline</Text>
  </Col>
  <Col itemsCenter>
    <Icon primary filled><Star /></Icon>
    <Text xs secondary>filled</Text>
  </Col>
  <Col itemsCenter>
    <Icon danger><AlertCircle /></Icon>
    <Text xs secondary>outline</Text>
  </Col>
  <Col itemsCenter>
    <Icon danger filled><AlertCircle /></Icon>
    <Text xs secondary>filled</Text>
  </Col>
</Row>
```

## Shapes

Shape props apply once the icon enters container mode (any of `padding`, `border`, `insetRing`, `shadow`, `filled`). Without a container, the SVG has no visible box for the radius to act on.

```tsx demo
<Row flexWrap>
  <Col itemsCenter>
    <Icon padding primary filled sharp><Star /></Icon>
    <Text xs secondary>sharp</Text>
  </Col>
  <Col itemsCenter>
    <Icon padding primary filled><Star /></Icon>
    <Text xs secondary>rounded</Text>
  </Col>
  <Col itemsCenter>
    <Icon padding primary filled pill><Star /></Icon>
    <Text xs secondary>pill</Text>
  </Col>
</Row>
```

## Container mode

Add `padding` to give the icon a sized box, then combine `filled`, `border`, `insetRing`, or `shadow` to style the container. Padding and radius scale with the size prop.

```tsx demo
<Row flexWrap itemsCenter>
  <Col itemsCenter>
    <Icon padding pill primary filled><Heart /></Icon>
    <Text xs secondary>filled</Text>
  </Col>
  <Col itemsCenter>
    <Icon padding pill primary border><Heart /></Icon>
    <Text xs secondary>border</Text>
  </Col>
  <Col itemsCenter>
    <Icon padding pill primary insetRing><Heart /></Icon>
    <Text xs secondary>ring</Text>
  </Col>
  <Col itemsCenter>
    <Icon padding pill primary filled shadow><Heart /></Icon>
    <Text xs secondary>filled + shadow</Text>
  </Col>
  <Col itemsCenter>
    <Icon padding pill success filled insetRing><Check /></Icon>
    <Text xs secondary>filled + ring</Text>
  </Col>
  <Col itemsCenter>
    <Icon lg padding pill danger filled><AlertCircle /></Icon>
    <Text xs secondary>lg</Text>
  </Col>
</Row>
```

## Transparent

`transparent` drops the container's background and changes nothing else. It only has an effect on `filled`, since every other variant is already background-less.

That leaves the glyph in the "on this fill" colour with no fill of its own, so it belongs on a filled surface of the same appearance, where that colour is the readable one. On a plain surface, use the default `outline` variant instead.

```tsx demo
<Row flexWrap itemsCenter>
  <Col itemsCenter>
    <Icon padding pill danger filled><AlertCircle /></Icon>
    <Text xs secondary>filled: paints its own surface</Text>
  </Col>
  <Card danger filled wFit>
    <Col itemsCenter>
      <Icon padding pill danger filled transparent><AlertCircle /></Icon>
      <Text xs>transparent: blends into a matching fill</Text>
    </Col>
  </Card>
</Row>
```

Note that `border` and `insetRing` have nothing to show on a `filled` icon: the filled variant resolves both to transparent so the edge disappears into the fill. Pair them with `outline` instead.

## In context

Icons work naturally alongside text and inside buttons.

```tsx demo
<Col>
  <Row>
    <Button><Search /> Search</Button>
    <Button success filled><Check /> Saved</Button>
    <Button danger><AlertCircle /> Delete</Button>
  </Row>
  <Text><Icon xs info><Info /></Icon> Icon sizes are fixed per size prop; in body text use `xs` so the line keeps its height.</Text>
  <Row itemsCenter>
    <Icon padding pill primary filled><Star /></Icon>
    <Col gap noPadding>
      <Text fontBold>Container-mode icons</Text>
      <Text sm secondary>Pair a padded icon with adjacent text for compact summaries.</Text>
    </Col>
  </Row>
</Col>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Padding: `padding`, `paddingX`, `paddingY`, `noPadding` (default)
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink` (default)
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Display, Height, Hide, Items, Justify, Position, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Alert

> Alert is a live region for messages that follow a user action. It announces itself when it appears, assertively by default or politely on request.

Source: https://vaneui.com/docs/basic-components/alert

Import: `import { Alert, Button, Col, Text } from "@vaneui/ui"`

Alert shows messages such as a save confirmation, a failed payment or an upload error. It renders a full-width `<div>` laid out as a flex row, in the `info` appearance unless another is set. A note that is part of the page from the first render fits a [Card](/docs/layout-components/card), and an error about one input fits the `error` prop of [Field](/docs/form-components/field). A message the user must answer before continuing belongs in a [Modal](/docs/overlay-components/modal).

## Basic usage

Alert is a live region: assistive technology announces its content when it appears, without the user having to find it. Use it for messages that result from something the user just did.

```tsx demo
<Alert>Scheduled maintenance starts at 02:00 UTC.</Alert>
```

By default it renders `role="alert"`, which interrupts. For a message that can wait for a natural pause, use `polite`, which renders `role="status"`.

```tsx demo
<Alert polite success>Your changes were saved.</Alert>
```

Render an Alert only when the message appears. An Alert present on first paint is not announced, because a live region announces changes, not initial content.

## Appearances

```tsx demo
<Col>
  <Alert info>A new version is available.</Alert>
  <Alert success polite>Your changes were saved.</Alert>
  <Alert warning>Your trial ends in three days.</Alert>
  <Alert danger>Payment failed. Update your card to continue.</Alert>
</Col>
```

## Variants

```tsx demo
<Col>
  <Alert danger>Outline, the default.</Alert>
  <Alert danger filled>Filled, for the loudest messages.</Alert>
</Col>
```

## With a title and actions

Alert is a flex row, so compose whatever the message needs.

```tsx demo
<Alert warning>
  <Col noGap>
    <Text fontSemibold>Your trial ends in three days</Text>
    <Text sm>Add a payment method to keep your projects running.</Text>
  </Col>
  <Button sm warning filled>Add card</Button>
</Alert>
```

## With an icon

A leading icon spans one text line, so it centres on the first line of the message.

```tsx demo
<Alert info>
  <Info />
  A new version is available. Reload to update.
</Alert>
```

## Font family

Alert text renders in the sans font (`fontSans`, the default) with body line-height, even when the page uses another font. Pass `fontMono` for a machine-style message.

```tsx demo
<Alert danger fontMono>Error 503: upstream connect error</Alert>
```

## Shapes

Alert is `rounded` by default. `sharp` suits an alert pinned to the edge of a panel, where a radius would leave a gap against the edge.

```tsx demo
<Col>
  <Alert>Rounded, the default</Alert>
  <Alert sharp>Sharp</Alert>
  <Alert pill>Pill</Alert>
</Col>
```

## Sizes

```tsx demo
<Col>
  <Alert xs>Extra small</Alert>
  <Alert sm>Small</Alert>
  <Alert>Medium, the default</Alert>
  <Alert lg>Large</Alert>
  <Alert xl>Extra large</Alert>
</Col>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info` (default), `inheritAppearance`
- Breakpoint: `desktopStack`, `tabletStack`, `mobileStack`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Display, Flex Direction, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transparent, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Spinner

> Spinner indicates that something is in progress. The ring is sized in em, so it scales with the size prop and lines up with text.

Source: https://vaneui.com/docs/basic-components/spinner

Import: `import { Spinner, Badge, Card, Col, Row, Text } from "@vaneui/ui"`

Spinner stands in for content that is not there yet, while data loads or a job runs. It renders an inline-block `<span>` and takes no padding, border or shape props. For a button waiting on its own action, set `loading` on [Button](/docs/basic-components/button) instead of placing a Spinner inside it by hand. For a full-screen loading state, place the Spinner on an [Overlay](/docs/overlay-components/overlay).

## Basic usage

Spinner indicates that something is in progress. Give it an `aria-label` so the busy state has a name, since the ring itself carries no text.

```tsx demo
<Spinner aria-label="Loading"/>
```

It renders `role="status"`, so assistive technology announces the label when the spinner appears.

## Sizes

The ring is one em square, so it scales with the size prop and lines up with text of the same size.

```tsx demo
<Row itemsCenter flexWrap>
  <Spinner xs aria-label="Loading"/>
  <Spinner sm aria-label="Loading"/>
  <Spinner aria-label="Loading"/>
  <Spinner lg aria-label="Loading"/>
  <Spinner xl aria-label="Loading"/>
</Row>
```

## Appearances

The ring is drawn in the current text colour, so an appearance prop colours it directly.

```tsx demo
<Row itemsCenter flexWrap>
  <Spinner primary aria-label="Loading"/>
  <Spinner accent aria-label="Loading"/>
  <Spinner secondary aria-label="Loading"/>
  <Spinner tertiary aria-label="Loading"/>
  <Spinner success aria-label="Loading"/>
  <Spinner danger aria-label="Loading"/>
  <Spinner warning aria-label="Loading"/>
  <Spinner info aria-label="Loading"/>
</Row>
```

## Variants

An appearance only becomes a colour through a variant, so Spinner carries the same `outline` / `filled` / `ghost` axis as everything else. It has no background of its own, so the variant does one thing here: it picks which colour of the appearance the ring paints in.

`outline`, the default, uses the appearance's own colour, for a spinner on a plain surface. `filled` uses the "on this fill" colour, for a spinner sitting on a filled surface of the same appearance.

```tsx demo
<Col>
  <Row itemsCenter flexWrap>
    <Spinner danger aria-label="Loading"/>
    <Spinner success aria-label="Loading"/>
    <Spinner info aria-label="Loading"/>
  </Row>
  <Row flexWrap>
    <Card danger filled wFit><Spinner danger filled aria-label="Loading"/></Card>
    <Card success filled wFit><Spinner success filled aria-label="Loading"/></Card>
    <Card info filled wFit><Spinner info filled aria-label="Loading"/></Card>
  </Row>
</Col>
```

Most of the time you do not need either. With no appearance prop the Spinner inherits the colour of whatever it sits in, which is what makes it readable inside a filled Badge, Card or Button without being told anything.

```tsx demo
<Row itemsCenter flexWrap>
  <Badge info filled><Spinner xs aria-label="Loading"/> Syncing</Badge>
  <Card sm filled secondary wFit>
    <Row itemsCenter>
      <Spinner sm aria-label="Loading"/>
      <Text sm>Rebuilding index</Text>
    </Row>
  </Card>
</Row>
```

Setting an appearance that matches the surface you are on is the one thing to avoid: `<Spinner secondary>` inside a `secondary filled` Card resolves to the outline colour, which is the surface's own colour, so the ring disappears.

`Button` and `IconButton` render this same component for their `loading` prop, so there is one spinner in the library and restyling `theme.spinner` restyles both. That state is documented where it is used, on [Button](/docs/basic-components/button) and [IconButton](/docs/basic-components/icon-button).

Spinner honours `prefers-reduced-motion`: the animation stops for users who ask for less motion.

## Inline with text

Because the ring is sized in em, it matches the surrounding text without any manual tuning.

```tsx demo
<Row itemsCenter>
  <Spinner sm aria-label="Loading"/>
  <Text sm secondary>Checking availability…</Text>
</Row>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance` (default)
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin` (default)
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Display, Hide, Show) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Progress

> Progress is a determinate bar for a task with a known size, such as an upload or a setup step. A role="progressbar" track whose fill grows with value.

Source: https://vaneui.com/docs/basic-components/progress

Import: `import { Progress, Button, Card, Col, Row, Text, ThemeProvider } from "@vaneui/ui"`

Progress is a determinate bar: it shows how much of a task with a known size is done, such as a file upload, an import or step 3 of 8 in a setup flow. It renders a `role="progressbar"` track with `aria-valuenow`, `aria-valuemin` and `aria-valuemax`, and a fill that grows with `value`. It takes no children, so a label or a percentage goes beside it. When the end of the wait is unknown, use [Spinner](/docs/basic-components/spinner) instead. Progress needs `@vaneui/ui` 1.4.5 or later.

## Basic usage

`value` is required and fills the bar against `max`, which is 100 by default. Give the bar an `aria-label`, since the track itself carries no text.

```tsx demo
<Progress value={40} aria-label="Upload"/>
```

`md`, `primary`, `pill`, `transition` and `wFull` are defaults, so a bare `<Progress value={40}/>` is an 8px pill bar across the full width of its parent.

## Setting the range with max

Set `max` when the value counts something other than percent, such as steps or megabytes. `value` is clamped to the range 0 to `max`: a value above `max` shows a full bar and reports `max` in `aria-valuenow`, and a negative value shows an empty one.

```tsx demo
<Col>
  <Progress value={3} max={8} aria-label="Setup, step 3 of 8"/>
  <Progress value={8} max={8} aria-label="Setup, step 8 of 8"/>
</Col>
```

## Sizes

Size sets the bar height: 2, 4, 8, 12 and 16px from `xs` to `xl`, with `md` (8px) as the default. In a [Row](/docs/layout-components/row), `flex1` lets the bar take the space its label leaves.

```tsx demo
<Col>
  <Row>
    <Text sm secondary className="w-8">xs</Text>
    <Progress xs flex1 value={60} aria-label="Progress xs"/>
  </Row>
  <Row>
    <Text sm secondary className="w-8">sm</Text>
    <Progress sm flex1 value={60} aria-label="Progress sm"/>
  </Row>
  <Row>
    <Text sm secondary className="w-8">md</Text>
    <Progress flex1 value={60} aria-label="Progress md"/>
  </Row>
  <Row>
    <Text sm secondary className="w-8">lg</Text>
    <Progress lg flex1 value={60} aria-label="Progress lg"/>
  </Row>
  <Row>
    <Text sm secondary className="w-8">xl</Text>
    <Progress xl flex1 value={60} aria-label="Progress xl"/>
  </Row>
</Col>
```

## Appearances

The fill is a filled bar in the appearance color, and the track stays neutral whatever the appearance. With the default `primary`, the fill is near-black in light mode and near-white in dark mode.

```tsx demo
<Col>
  <Progress value={70} aria-label="Primary"/>
  <Progress accent value={70} aria-label="Accent"/>
  <Progress secondary value={70} aria-label="Secondary"/>
  <Progress tertiary value={70} aria-label="Tertiary"/>
  <Progress success value={70} aria-label="Success"/>
  <Progress danger value={70} aria-label="Danger"/>
  <Progress warning value={70} aria-label="Warning"/>
  <Progress info value={70} aria-label="Info"/>
</Col>
```

## Shapes

`pill` is the default. `rounded` and `sharp` square the ends off, and the fill follows the shape of the track.

```tsx demo
<Col>
  <Progress lg value={45} aria-label="Pill progress"/>
  <Progress lg rounded value={45} aria-label="Rounded progress"/>
  <Progress lg sharp value={45} aria-label="Sharp progress"/>
</Col>
```

## Animating the progress bar to a new value

With the default `transition`, the fill eases to each new value over `--transition-duration` (200ms); `noTransition` makes it jump. Under `prefers-reduced-motion` the fill moves without the animation. Each click below sends another megabyte, and the bar turns `success` once the upload completes.

```tsx demo
const total = 6;
const [sent, setSent] = useState(2);
const done = sent >= total;

return (
  <Card sm className="max-w-md">
    <Row justifyBetween>
      <Text sm fontSemibold>quarterly-report.pdf</Text>
      <Text sm secondary>{sent} of {total}MB</Text>
    </Row>
    <Progress sm success={done} value={sent} max={total} aria-label="Uploading quarterly-report.pdf"/>
    <Row justifyBetween>
      <Text xs secondary>{done ? 'Upload complete' : 'Uploading to the shared drive'}</Text>
      <Button xs secondary onClick={() => setSent(done ? 0 : sent + 1)}>
        {done ? 'Restart' : 'Send 1MB'}
      </Button>
    </Row>
  </Card>
);
```

## Visible labels and value text

When a visible label names the bar, point `aria-labelledby` at it instead of repeating the text in `aria-label`. Screen readers announce a progressbar's value as a percentage of the range; for a count, `aria-valuetext` gives the wording to read instead.

```tsx demo
<Col>
  <Row justifyBetween>
    <Text sm id="import-label">Importing contacts</Text>
    <Text sm secondary>3 of 8 files</Text>
  </Row>
  <Progress value={3} max={8} aria-labelledby="import-label" aria-valuetext="3 of 8 files"/>
</Col>
```

## Customizing

Progress has two theme nodes for [themeDefaults](/docs/customization/theme-defaults): `progress.main` for the track and `progress.fill` for the bar inside it. The fill follows the track's appearance, shape and transition whenever they differ from the library defaults, so most changes go on `main`. A `fill` default, such as `success` below, applies while the track keeps its default appearance.

```tsx demo
<ThemeProvider themeDefaults={{
  progress: { main: { sm: true }, fill: { success: true } },
}}>
  <Progress value={65} aria-label="Storage used"/>
</ThemeProvider>
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin` (default)
- Shape: `pill` (default), `sharp`, `rounded`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`

Layout and utility props (Hide, Overflow, Responsive Width, Show, Transition, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Input

> Input lets users enter text, numbers, and other data. A form element with support for various types, validation states, and styling options.

Source: https://vaneui.com/docs/form-components/input

Import: `import { Input, Button, Col, Label, Row, ThemeProvider } from "@vaneui/ui"`

Input takes a single-line value, such as a name, an email address or a search query, and renders a native `<input>`. With `invalid` set, it adds `aria-invalid="true"` and a trailing alert icon that screen readers skip. Text that runs over several lines needs a [Textarea](/docs/form-components/textarea), and a [Field](/docs/form-components/field) around an Input links its label, help text and error message.

## Basic usage

Input renders a styled text field for entering text, numbers, and other data. It defaults to `md`, `primary`, `outline`, and `rounded`, with `insetRing` and `focusVisible`. Input is `wFull` by default, so it spans its container. Constrain the width with a sized parent or `className="w-64"`.

```tsx demo
<Input placeholder="Enter text..." />
```

## Sizes

Inputs come in different sizes: `xs`, `sm`, `md` (default), `lg`, `xl`. At the same size an Input is as tall as a `Button` and has the same corner radius. Button defaults to `sm` and Input to `md`, so give a button beside a field the field's size.

```tsx demo
<Row>
  <Input placeholder="you@company.com" />
  <Button md filled>Subscribe</Button>
</Row>
```

```tsx demo
<Col>
  <Input xs placeholder="Extra small" />
  <Input sm placeholder="Small" />
  <Input placeholder="Medium (default)" />
  <Input lg placeholder="Large" />
  <Input xl placeholder="Extra large" />
</Col>
```

## Variants

Inputs are `outline` by default. Use `filled` for solid backgrounds.

```tsx demo
<Col>
  <Row flexWrap>
    <Input placeholder="Outline (default)" />
    <Input success placeholder="Outline success" />
    <Input danger placeholder="Outline danger" />
  </Row>
  <Row flexWrap>
    <Input filled placeholder="Filled" />
    <Input filled success placeholder="Filled success" />
    <Input filled danger placeholder="Filled danger" />
  </Row>
</Col>
```

## Shapes

Inputs support border radius styles: `rounded` (default), `pill`, and `sharp`.

```tsx demo
<Row flexWrap>
  <Input placeholder="Rounded (default)" />
  <Input pill placeholder="Pill shape" />
  <Input sharp placeholder="Sharp corners" />
</Row>
```

## Types

The `type` HTML attribute passes through to the underlying `<input>` element.

```tsx demo
<Col>
  <Input type="text" placeholder="Text input" />
  <Input type="email" placeholder="Email input" />
  <Input type="password" placeholder="Password input" />
  <Input type="number" placeholder="Number input" />
  <Input type="search" placeholder="Search input" />
</Col>
```

## With labels

Pair inputs with labels for accessibility and better UX. When the `Input` is nested inside a `Label`, it inherits the Label's size. Set it once on the Label.

```tsx demo
<Col>
  <Label>
    Full Name
    <Input type="text" placeholder="Enter your full name" />
  </Label>
  <Label lg>
    Email Address (large)
    <Input type="email" placeholder="Enter your email" />
  </Label>
</Col>
```

## States

Different input states: disabled, readonly, and validation feedback. Use appearance props (`success`, `danger`) for visual feedback, or the `invalid` validity prop for form validation state. `invalid` layers a danger border and ring over the current appearance.

```tsx
<Input placeholder="Normal input" />
<Input disabled placeholder="Disabled input" />
<Input success placeholder="Success state" />
<Input danger placeholder="Error state" />
<Input invalid placeholder="Validation error" />
```

```tsx demo
<Col>
  <Input placeholder="Normal input" />
  <Input disabled placeholder="Disabled input" />
  <Input success placeholder="Success state" />
  <Input danger placeholder="Error state" />
  <Input invalid placeholder="Validation error (validity)" />
</Col>
```

## Customizing

Set app-wide Input defaults with `ThemeProvider`'s `themeDefaults` and add a focus-ring colour with `extraClasses`:

```tsx demo
<ThemeProvider
  themeDefaults={{ input: { lg: true, filled: true } }}
  extraClasses={{ input: { primary: 'focus:ring-2 focus:ring-blue-500/40' } }}
>
  <Input placeholder="Email" />
</ThemeProvider>
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal` (default), `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Read Only: `readOnly`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Validity: `invalid`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Checkbox

> Allows users to select one or more options from a set. Checkboxes are ideal for binary choices and multiple selections within forms.

Source: https://vaneui.com/docs/form-components/checkbox

Import: `import { Checkbox, Col, Label, Link, Row, Text, ThemeProvider } from "@vaneui/ui"`

Checkbox is for a value that waits for the form to be submitted. For a setting that applies the moment it flips, use [Switch](/docs/form-components/switch); to pick exactly one option from a set, use [Radio](/docs/form-components/radio). Checkbox renders a native `<input type="checkbox">` under a styled box, so the checked state, keyboard focus and form submission come from the browser. The check mark and the indeterminate dash are overlays hidden from screen readers.

## Basic usage

Checkbox should be used inside a Label with matching `id`/`htmlFor`. `Label` defaults to a stacked column layout, so add `row itemsCenter` to place the checkbox inline with its text. The checkbox takes its size from the Label, so match the Label's size to its text (here `md`) to keep the box centered on the first line of a multi-line label.

```tsx demo
<Col>
  <Label row itemsCenter htmlFor="terms">
    <Checkbox id="terms"/>
    <span>I agree to the <Link href="#">Terms of Service</Link> and <Link href="#">Privacy Policy</Link>.</span>
  </Label>

  <Label md row itemsCenter htmlFor="emails">
    <Checkbox defaultChecked id="emails"/>
    <Col noGap tag="span">
      <Text>Receive product updates</Text>
      <Text xs secondary>Occasional emails about new features</Text>
    </Col>
  </Label>
</Col>
```

## Sizes

Checkboxes in different sizes: `xs`, `sm`, `md` (default), `lg`, `xl`. A `Checkbox` nested inside a `Label` inherits the Label's size automatically. Set it once on the Label and both scale together.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter xs htmlFor="size-xs">
    <Checkbox id="size-xs" defaultChecked/>
    Size: xs
  </Label>
  <Label row itemsCenter sm htmlFor="size-sm">
    <Checkbox id="size-sm" defaultChecked/>
    Size: sm
  </Label>
  <Label row itemsCenter md htmlFor="size-md">
    <Checkbox id="size-md" defaultChecked/>
    Size: md
  </Label>
  <Label row itemsCenter lg htmlFor="size-lg">
    <Checkbox id="size-lg" defaultChecked/>
    Size: lg
  </Label>
  <Label row itemsCenter xl htmlFor="size-xl">
    <Checkbox id="size-xl" defaultChecked/>
    Size: xl
  </Label>
</Row>
```

## Explicit size on the control

Setting the size on the Label is the usual route, but the Checkbox takes its own size prop, which wins over the inherited one.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter lg><Checkbox xs defaultChecked/> xs box, lg label</Label>
  <Label row itemsCenter lg><Checkbox defaultChecked/> inherited lg box</Label>
  <Label row itemsCenter lg><Checkbox xl defaultChecked/> xl box, lg label</Label>
</Row>
```

## Appearances

Different color appearances applied to the Checkbox; always place inside a Label.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter htmlFor="appearance-primary">
    <Checkbox id="appearance-primary" defaultChecked/>
    Enable primary style
  </Label>
  <Label row itemsCenter accent htmlFor="appearance-accent">
    <Checkbox accent id="appearance-accent" defaultChecked/>
    Enable accent style
  </Label>
  <Label row itemsCenter secondary htmlFor="appearance-secondary">
    <Checkbox secondary id="appearance-secondary" defaultChecked/>
    Enable secondary style
  </Label>
  <Label row itemsCenter tertiary htmlFor="appearance-tertiary">
    <Checkbox tertiary id="appearance-tertiary" defaultChecked/>
    Enable tertiary style
  </Label>
  <Label row itemsCenter success htmlFor="appearance-success">
    <Checkbox success id="appearance-success" defaultChecked/>
    Enable success style
  </Label>
  <Label row itemsCenter danger htmlFor="appearance-danger">
    <Checkbox danger id="appearance-danger" defaultChecked/>
    Enable danger style
  </Label>
  <Label row itemsCenter warning htmlFor="appearance-warning">
    <Checkbox warning id="appearance-warning" defaultChecked/>
    Enable warning style
  </Label>
  <Label row itemsCenter info htmlFor="appearance-info">
    <Checkbox info id="appearance-info" defaultChecked/>
    Enable info style
  </Label>
  <Label row itemsCenter inheritAppearance htmlFor="appearance-inherit">
    <Checkbox inheritAppearance id="appearance-inherit" defaultChecked/>
    Enable inheritAppearance style
  </Label>
</Row>
```

## Shapes

Checkboxes support border radius styles: `rounded` (default), `pill`, and `sharp`.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter htmlFor="shape-rounded">
    <Checkbox id="shape-rounded" defaultChecked/>
    Rounded (default)
  </Label>
  <Label row itemsCenter htmlFor="shape-pill">
    <Checkbox pill id="shape-pill" defaultChecked/>
    Pill
  </Label>
  <Label row itemsCenter htmlFor="shape-sharp">
    <Checkbox sharp id="shape-sharp" defaultChecked/>
    Sharp
  </Label>
</Row>
```

## Variants

Checkbox is `filled` by default: the box fills with the appearance colour when checked. `outline` keeps the box transparent and marks the check itself.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter><Checkbox defaultChecked/> filled, the default</Label>
  <Label row itemsCenter><Checkbox outline defaultChecked/> outline</Label>
  <Label row itemsCenter><Checkbox ghost defaultChecked/> ghost</Label>
</Row>
```

## Disabled

Use the `disabled` HTML attribute to prevent interaction.

```tsx demo
<Col>
  <Label row itemsCenter htmlFor="disabled-unchecked">
    <Checkbox disabled id="disabled-unchecked"/>
    Disabled (unchecked)
  </Label>
  <Label row itemsCenter htmlFor="disabled-checked">
    <Checkbox disabled defaultChecked id="disabled-checked"/>
    Disabled (checked)
  </Label>
</Col>
```

## Controlled vs uncontrolled

Checkbox forwards every HTML input attribute, so use `defaultChecked` for uncontrolled state and `checked` + `onChange` for controlled state.

Uncontrolled: initial value only, the input manages its own state.

```tsx demo
<Label row itemsCenter htmlFor="uncontrolled">
  <Checkbox defaultChecked id="uncontrolled"/>
  Uncontrolled (defaultChecked)
</Label>
```

Controlled: parent owns the value via `useState`.

```tsx demo
const [checked, setChecked] = useState(false);

return (
  <Label row itemsCenter htmlFor="controlled">
    <Checkbox
      id="controlled"
      checked={checked}
      onChange={(e) => setChecked(e.target.checked)}
    />
    Controlled ({checked ? 'on' : 'off'})
  </Label>
);
```

## Indeterminate state

Use the `indeterminate` prop for "select all" checkboxes that represent a partially selected group. It is visual only: it renders a dash (the box fills like a checked one) and does not change the `checked` value, so you set it from your own state and manage the real values yourself.

```tsx demo
<Label row itemsCenter>
  <Checkbox indeterminate />
  Indeterminate
</Label>
```

Wire it to a group so "Select all" reflects and controls the children: `checked` when all are on, `indeterminate` when some are on, and clicking it toggles them all.

```tsx demo
const [items, setItems] = React.useState([true, true, false, false]);
const allChecked = items.every(Boolean);
const anyChecked = items.some(Boolean);
const labels = ['Item one', 'Item two', 'Item three', 'Item four'];
return (
  <Col>
    <Label row itemsCenter>
      <Checkbox
        checked={allChecked}
        indeterminate={anyChecked && !allChecked}
        onChange={() => setItems(items.map(() => !allChecked))}
      />
      Select all ({items.filter(Boolean).length} of {items.length} selected)
    </Label>
    <Col className="pl-6">
      {labels.map((label, i) => (
        <Label row itemsCenter key={label}>
          <Checkbox
            checked={items[i]}
            onChange={() => setItems(items.map((v, idx) => (idx === i ? !v : v)))}
          />
          {label}
        </Label>
      ))}
    </Col>
  </Col>
);
```

## Checkbox group

Multiple labeled checkboxes working together.

```tsx demo
<Col>
  <Label row itemsCenter htmlFor="opt-1">
    <Checkbox id="opt-1" defaultChecked/>
    Email notifications
  </Label>
  <Label row itemsCenter htmlFor="opt-2">
    <Checkbox id="opt-2"/>
    SMS alerts
  </Label>
  <Label row itemsCenter htmlFor="opt-3">
    <Checkbox id="opt-3"/>
    Push notifications
  </Label>
</Col>
```

## Customizing

Set app-wide Checkbox defaults with `ThemeProvider`'s `themeDefaults` and tune the checked-state visuals with `extraClasses`:

```tsx demo
<ThemeProvider
  themeDefaults={{ checkbox: { input: { lg: true } } }}
  extraClasses={{ checkbox: { input: { primary: 'checked:bg-blue-600 checked:border-blue-600' } } }}
>
  <Label row itemsCenter htmlFor="terms">
    <Checkbox id="terms"/>
    I agree to the terms
  </Label>
</ThemeProvider>
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Read Only: `readOnly`
- Shape: `pill`, `sharp`, `rounded` (default)
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Validity: `invalid`
- Variant: `filled` (default), `outline`, `ghost`

Layout and utility props (Align Self, Border, Cursor, Display, Focus Visible, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Label

> Label associates text with a form control. Wrap an Input or Checkbox to make the label clickable, or use htmlFor when the control sits outside.

Source: https://vaneui.com/docs/form-components/label

Import: `import { Label, Card, Checkbox, Code, Col, Field, Input, Row, Text } from "@vaneui/ui"`

Label gives a form control its visible name and renders a native `<label>` element. It links no help text or error message to the control; [Field](/docs/form-components/field) adds both. Text that names no control, such as a hint under a heading, belongs in [Text](/docs/typography-components/text).

## Basic usage

A `Label` defaults to `sm` size and `inheritAppearance` appearance, so it picks up text color from its surroundings.

```tsx demo
<Label>Email address</Label>
```

## Sizes

Labels come in five sizes: `xs`, `sm` (default), `md`, `lg`, `xl`. Nested `Input` and `Checkbox` controls inherit the size.

```tsx demo
<Col>
  <Label xs>xs label <Input placeholder="xs input" /></Label>
  <Label>sm label (default) <Input placeholder="sm input" /></Label>
  <Label md>md label <Input placeholder="md input" /></Label>
  <Label lg>lg label <Input placeholder="lg input" /></Label>
  <Label xl>xl label <Input placeholder="xl input" /></Label>
</Col>
```

## Appearances

Labels default to `inheritAppearance`: they take their color from the surrounding text. Set an explicit appearance to override.

```tsx demo
<Row flexWrap>
  <Label>inheritAppearance label (default)</Label>
  <Label primary>primary label</Label>
  <Label accent>accent label</Label>
  <Label secondary>secondary label</Label>
  <Label tertiary>tertiary label</Label>
  <Label success>success label</Label>
  <Label danger>danger label</Label>
  <Label warning>warning label</Label>
  <Label info>info label</Label>
</Row>
```

## Variants

Label never paints a surface, so the variant only picks which colour of the appearance the text is painted in. `outline`, the default, uses the appearance's own colour. `filled` uses the "on this fill" colour, for a label sitting on a filled surface of the same appearance. For a filled pill beside a field, reach for `Badge` or `Chip` instead.

```tsx demo
<Col>
  <Row flexWrap>
    <Label success>outline success</Label>
    <Label danger>outline danger</Label>
  </Row>
  <Card success filled wFit>
    <Label success filled>filled success, on a matching filled Card</Label>
  </Card>
</Col>
```

## Disabled

`disabled` dims the label, and a Label containing a disabled control dims with it, so you only have to disable the field itself.

```tsx demo
<Col>
  <Label disabled>Explicitly disabled label</Label>
  <Label>
    Email
    <Input disabled placeholder="you@example.com" />
  </Label>
  <Label row itemsCenter>
    <Checkbox disabled />
    Subscribe to product updates
  </Label>
</Col>
```

The dimming applies once: a disabled control inside a dimmed Label is not faded a second time.

## With Input

Wrap an `Input` inside a `Label` to make the label clickable and associate them implicitly. No `htmlFor`/`id` wiring required.

```tsx demo
<Col noGap>
  <Label>
    Email
    <Input placeholder="you@example.com" />
  </Label>
</Col>
```

## With Checkbox

Place a `Checkbox` inside a `Label` so the label text expands the toggle's hit area. `Label` defaults to a stacked column layout, so add `row itemsCenter` to sit the checkbox inline with its text.

```tsx demo
<Label row itemsCenter>
  <Checkbox />
  Subscribe to product updates
</Label>
```

## htmlFor association

When the control lives outside the label, use the standard `htmlFor` attribute pointing at the input's `id`.

```tsx demo
<Col noGap>
  <Label htmlFor="username">Username</Label>
  <Input id="username" placeholder="Choose a username" />
</Col>
```

## Font weights

The default weight is `fontMedium`. Override with any weight prop from `fontThin` to `fontBlack`.

```tsx demo
<Col>
  <Label fontThin>thin weight</Label>
  <Label fontExtralight>extralight weight</Label>
  <Label fontLight>light weight</Label>
  <Label fontNormal>normal weight</Label>
  <Label>medium weight (default)</Label>
  <Label fontSemibold>semibold weight</Label>
  <Label fontBold>bold weight</Label>
  <Label fontExtrabold>extrabold weight</Label>
  <Label fontBlack>black weight</Label>
</Col>
```

## Text decorations

Apply text decorations as needed.

```tsx demo
<Row flexWrap>
  <Label underline>underline text</Label>
  <Label lineThrough>lineThrough text</Label>
  <Label overline>overline text</Label>
</Row>
```

## Size propagation

When an `Input` or `Checkbox` is nested inside a `Label`, it automatically picks up the label's size. Set it once and everything scales together. Pass a size on the child to opt out for that one element.

```tsx demo
<Col>
  <Label xl row itemsCenter>
    <Checkbox />
    Extra-large checkbox option
  </Label>
  <Label lg row itemsCenter>
    <Checkbox xs />
    Explicit <Code>xs</Code> checkbox overrides the <Code>lg</Code> label
  </Label>
</Col>
```

## Required and status

Use appearances to indicate field status: `danger` for errors, `success` for valid, `secondary` for hints.

```tsx demo
<Col>
  <Field label={<>Username <Text tag="span" danger inheritSize>*</Text></>}>
    <Input placeholder="Choose a username" required />
  </Field>
  <Label success fontSemibold>
    Email verified
    <Input placeholder="verified@example.com" />
  </Label>
  <Text sm secondary>All fields marked with * are required.</Text>
</Col>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance` (default)
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium` (default), `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Shrink: `noShrink`
- Size: `xs`, `sm` (default), `md`, `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Cursor, Display, Flex Direction, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Field

> Field wires a control to its label, help text and error message. It owns the id, points the label at the control, and links both messages with aria-describedby.

Source: https://vaneui.com/docs/form-components/field

Import: `import { Field, Card, Col, Input, Label, Radio, RadioGroup, Row, Select, Text, Textarea } from "@vaneui/ui"`

Use Field when a control has help text or an error message. A bare [Label](/docs/form-components/label) associates text with a control but links neither message to it, so a screen reader announces that the control is invalid and never says why. For a control that needs a visible name and nothing else, a Label is enough. Field renders a `<div>` that holds a `<label>`, the control, and the help and error text as `<p>` elements.

## Basic usage

Field wires a control to its label, help text and error message. It generates one id, points the label at the control with `htmlFor`, and links the description and error with `aria-describedby`. Pass any control as the child. `disabled`, `required` and `readOnly` set on the Field reach the child control (and every `Radio` of a child `RadioGroup`); a prop set on the child itself wins. A disabled Field, or a disabled child control, also dims the label.

```tsx demo
<Field label="Email" description="We will never share it.">
  <Input type="email" placeholder="you@company.com"/>
</Field>
```

## Rendering the control

Field can render the control itself instead of wrapping one passed as a child. Pass `type` (a control kind such as `select`, or a native input type such as `email` or `date`) or one of six booleans: `textInput`, `textarea`, `select`, `checkbox`, `switch`, `radiogroup`. Naming none of them keeps the children mode above unchanged.

```tsx demo
<Col>
  <Field type="email" label="Email" description="We never share it." placeholder="you@company.com"/>
  <Field select label="Region" description="Sets your default currency.">
    <option>Cyprus</option>
    <option>Estonia</option>
    <option>Portugal</option>
  </Field>
</Col>
```

Children still reach the rendered control, so an `<option>` works with `select` and a `<Radio>` works with `radiogroup`, the same way they do when passed to a standalone `Select` or `RadioGroup`.

In this self-rendering mode, surface props (`appearance`, `variant`, `shape`, `border`, `ring`, `shadow`, `transparent`) route to the control rather than the wrapper, and native attributes such as `placeholder` or `defaultValue` go to the control too. Layout props and `className` stay on the wrapper, and `ref` points at the control. Field's own size still becomes the control's default, the same as in children mode.

```tsx demo
<Field type="text" filled secondary label="Name" description="Filled and secondary route to the input, not the wrapper."/>
```

Three details are worth knowing before you reach for them.

`onChange` is typed for whichever control Field might render, so its event target is the union of an input, a select and a textarea. Reading a property that only one of them has needs a cast:

```tsx
<Field checkbox label="Subscribe"
  onChange={(e) => setSubscribed((e.target as HTMLInputElement).checked)}/>
```

`ref` points at the rendered control for every kind except `checkbox`, where it lands on the element wrapping the box. A form library that reads `.checked` straight off the ref will not find it there; pass the control as a child and put the ref on it instead.

`className` stays on the wrapper, but `style` goes to the control, since only `className` and `tag` are treated as wrapper props. Use `className` to size or place the whole field block.

## Checkbox and switch

`checkbox` and `switch` lay out inline: the control first, the label beside it, with the description and error below the row. Any explicit direction prop (`row`, `column`, `rowReverse` or `columnReverse`) drops the inline row and falls back to the plain stacked layout used by every other control.

```tsx demo
<Col>
  <Field checkbox label="Subscribe to the newsletter" description="One email a month."/>
  <Field switch label="Beta features"/>
</Col>
```

## Error state

Passing `error` renders the message and marks the control invalid, so the danger cue and the message can never disagree. With a message you do not set `invalid` yourself.

```tsx demo
<Col>
  <Field label="Display name" error="This name is already taken.">
    <Input defaultValue="alex.rivera"/>
  </Field>

  <Field
    label="Password"
    description="At least 12 characters."
    error="Too short."
  >
    <Input type="password" defaultValue="short"/>
  </Field>
</Col>
```

When both `description` and `error` are present, the control is described by both, in that order.

An invalid control gets a danger border and ring plus `aria-invalid="true"`, and on `Input` a trailing alert icon, so the state is never signalled by colour alone.

## Invalid without a message

Set `invalid` on the Field when the control is invalid but the reason is reported elsewhere, such as a cross-field check or a server error shown in a banner. The control gets the same danger cue and `aria-invalid` as with an `error`, and no message element is rendered. `error={true}` does the same. The `invalid` prop needs `@vaneui/ui` 1.5.0 or later.

```tsx demo
<Col>
  <Text sm danger>The end date is before the start date.</Text>
  <Row mobileStack>
    <Field label="Start" invalid>
      <Input type="date" defaultValue="2026-11-20"/>
    </Field>
    <Field label="End" invalid>
      <Input type="date" defaultValue="2026-11-10"/>
    </Field>
  </Row>
</Col>
```

## Any control

Every form control reads the Field it sits in: `Input`, `Textarea`, `Select`, `Checkbox`, `Radio` and `Switch`.

```tsx demo
<Col>
  <Field label="Region" description="Sets your default currency.">
    <Select>
      <option>Cyprus</option>
      <option>Estonia</option>
      <option>Portugal</option>
    </Select>
  </Field>

  <Field label="Release notes" description="Markdown is supported.">
    <Textarea placeholder="What changed?"/>
  </Field>
</Col>
```

## Radio groups

A `radiogroup` is not a labelable element, so Field labels it by reference with `aria-labelledby` instead of `htmlFor`, and leaves the individual radios alone.

```tsx demo
<Field label="Billing period" description="Change it any time.">
  <RadioGroup name="billing" defaultValue="yearly">
    <Label row itemsCenter><Radio value="monthly"/> Monthly</Label>
    <Label row itemsCenter><Radio value="yearly"/> Yearly</Label>
  </RadioGroup>
</Field>
```

State set on the Field reaches every radio in the group, whether the group is a child or rendered with `radiogroup`: `disabled`, `readOnly` and `required` pass through, and an `error` or `invalid` marks each radio invalid. `RadioGroup` takes the same props itself (see [Radio](/docs/form-components/radio)).

```tsx demo
<Field disabled label="Billing period" description="Locked by your plan.">
  <RadioGroup name="billing-locked" defaultValue="yearly">
    <Label row itemsCenter><Radio value="monthly"/> Monthly</Label>
    <Label row itemsCenter><Radio value="yearly"/> Yearly</Label>
  </RadioGroup>
</Field>
```

## Sizes

Field's size sets the whole block: the label and the control both take it, and the help and error text sit one step below so they stay subordinate. You set it once, and an explicit size on the control still wins.

```tsx demo
<Col>
  <Field xs label="Extra small">
    <Input placeholder="xs"/>
  </Field>
  <Field sm label="Small">
    <Input placeholder="sm"/>
  </Field>
  <Field label="Medium (default)">
    <Input placeholder="md"/>
  </Field>
  <Field lg label="Large">
    <Input placeholder="lg"/>
  </Field>
  <Field xl label="Extra large">
    <Input placeholder="xl"/>
  </Field>
</Col>
```

## Shape, variant and appearance

Field is a layout wrapper, so it takes the same surface props as `Col`: it paints nothing by default (`sharp`, `outline`, no padding), and an appearance only shows once you give it a surface with `filled` or `border`. Useful for marking a field block that needs attention without touching the control inside it.

```tsx demo
<Col>
  <Field label="Default" description="No surface of its own.">
    <Input placeholder="you@company.com"/>
  </Field>
  <Field rounded border danger padding label="Bordered danger" description="A border plus an appearance.">
    <Input placeholder="you@company.com"/>
  </Field>
  <Field rounded filled secondary padding label="Filled secondary" description="A surface plus an appearance.">
    <Input placeholder="you@company.com"/>
  </Field>
</Col>
```

### On a dark surface

A field's label, help text and error read off the surface they sit on, so putting the block on a filled `Card` or `Row` carries all three with it instead of leaving them in the colours they pin for a light page. `filled` on a self-rendering Field routes to the control, as every surface prop does.

```tsx demo
<Card filled>
  <Field label="Display name" description="Visible to your team.">
    <Input defaultValue="alex.rivera"/>
  </Field>
  <Field textInput filled secondary label="Recovery email" error="Enter a valid address." defaultValue="alex@"/>
</Card>
```

Only the message text follows the surface. The control keeps its danger border, ring and alert icon, so the error is still marked where it happened. The pinned danger red is tuned for a light page and loses contrast on a dark one.

## Bringing your own id

If the control already carries an `id`, Field adopts it rather than generating one, so the label still points at the right element. Useful with form libraries that own the id.

```tsx demo
<Field label="Coupon code" description="Case sensitive.">
  <Input id="coupon" defaultValue="LAUNCH25"/>
</Field>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Breakpoint: `desktopStack`, `tabletStack`, `mobileStack`
- Control: `textInput`, `textarea`, `select`, `checkbox`, `switch`, `radiogroup`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Padding: `padding`, `paddingX`, `paddingY`, `noPadding` (default)
- Shape: `pill`, `sharp` (default), `rounded`
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Display, Flex Direction, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transparent, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Textarea

> Textarea captures multi-line input. It shares the Input size ramp and appearance props, resizes vertically, and never collapses below three lines.

Source: https://vaneui.com/docs/form-components/textarea

Import: `import { Textarea, Col, Field, Row } from "@vaneui/ui"`

Textarea is for comments, descriptions and other free-form text; a name, an email address or a number belongs in a single-line [Input](/docs/form-components/input). A Textarea inside a [Label](/docs/form-components/label) or a [Field](/docs/form-components/field) takes its size from that parent unless it sets its own.

## Basic usage

Textarea is an Input that wraps lines. It shares the Input size ramp and appearance props, and renders a real `<textarea>`, so every native attribute works.

```tsx demo
<Textarea placeholder="What changed in this release?" rows={4}/>
```

It resizes vertically by default and has a minimum height of three lines, so an empty textarea never collapses to a single row.

## Sizes

```tsx demo
<Col>
  <Textarea xs placeholder="xs"/>
  <Textarea sm placeholder="sm"/>
  <Textarea placeholder="md (default)"/>
  <Textarea lg placeholder="lg"/>
  <Textarea xl placeholder="xl"/>
</Col>
```

## Variants

Textarea is `outline` by default. Use `filled` for a solid background, and the appearance props for status colour.

```tsx demo
<Col>
  <Row flexWrap itemsStretch>
    <Textarea className="w-56" placeholder="Outline (default)"/>
    <Textarea className="w-56" success placeholder="Outline success"/>
    <Textarea className="w-56" danger placeholder="Outline danger"/>
  </Row>
  <Row flexWrap itemsStretch>
    <Textarea className="w-56" filled placeholder="Filled"/>
    <Textarea className="w-56" filled success placeholder="Filled success"/>
    <Textarea className="w-56" filled danger placeholder="Filled danger"/>
  </Row>
</Col>
```

## Shapes

```tsx demo
<Col>
  <Textarea rows={2} placeholder="Rounded, the default"/>
  <Textarea sharp rows={2} placeholder="Sharp"/>
  <Textarea pill rows={2} placeholder="Pill"/>
</Col>
```

## States

`invalid` paints a danger border and ring and emits `aria-invalid="true"`. Unlike `Input`, a Textarea shows no overlaid alert icon: a single-line field has one obvious place to put one, a box that grows does not. The border is therefore the only *visual* cue on its own, so pair `invalid` with a `Field` and let the `error` message carry the reason. It renders in danger text below the box and is linked with `aria-describedby`.

Note that the value itself never turns red. Colouring what the user typed hurts readability and says nothing about what is wrong.

```tsx demo
<Col>
  <Textarea placeholder="Default"/>
  <Field error="Tell us at least a sentence about what changed.">
    <Textarea defaultValue="Too short"/>
  </Field>
  <Textarea disabled defaultValue="Disabled"/>
  <Textarea readOnly defaultValue="Read only"/>
</Col>
```

## With a label and help text

```tsx demo
<Field label="Release notes" description="Markdown is supported.">
  <Textarea rows={3} placeholder="What changed?"/>
</Field>
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal` (default), `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Read Only: `readOnly`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Validity: `invalid`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Select

> Select presents a list of options using the native dropdown, so it stays keyboard and screen-reader correct and behaves as expected on mobile.

Source: https://vaneui.com/docs/form-components/select

Import: `import { Select, Col, Field, Row } from "@vaneui/ui"`

Use Select to pick a value such as a country or a currency from a long list, with the options passed as `<option>` and `<optgroup>` children. A handful of options that should all stay visible reads better as a [Radio](/docs/form-components/radio) group, and commands belong in a [Menu](/docs/overlay-components/menu). Inside a [Field](/docs/form-components/field) set to `readOnly`, Select stays read-only even though a native select has no such attribute: opening and keyboard changes are blocked, while Tab still moves focus.

## Basic usage

Select renders a real `<select>`, so keyboard support, screen-reader semantics, form submission and constraint validation all come from the platform rather than from re-implemented JavaScript.

```tsx demo
<Select>
  <option>Cyprus</option>
  <option>Estonia</option>
  <option>Portugal</option>
</Select>
```

The native arrow is replaced with a themed chevron that scales with the size prop. The field reserves room for it, so a long option never runs underneath. The selected value stays on one line, and at the same size a Select is as tall as an `Input` or a `Button`. In a `Row`, `noShrink` keeps the Select at its natural width.

## The dropdown list

Historically a native `<select>` hands its option list to the operating system, which draws a flat, square, unpadded menu that no page CSS can reach. Only the option's text and background colour land, because the options get no layout box at all.

On engines that support `appearance: base-select` the list becomes real DOM instead, and VaneUI styles it to match a `Menu`: themed surface, border, radius, shadow, padded rows, a hover state, and a checkmark on the selected option. Everywhere else the OS picker still appears, with `option` and `optgroup` carrying the field's surface and text colours so the list at least stays on your palette in both light and dark mode.

The list opens below the field and flips above it only when it genuinely does not fit. Browsers default to whichever side has more room, which sends the list upward for any field past the middle of the window even when there is space below it.

Options are children of the field, so they inherit its colours: the list follows the appearance and variant you set rather than staying pinned to the light surface. A disabled option, typically a placeholder, fades toward the list's own background instead of a fixed grey, so it stays readable on a filled list too.

Nothing is required to opt in, and nothing breaks on engines without it: the enhancement sits behind an `@supports` rule and the control is the same `<select>` either way.

## Sizes

Selects come in five sizes: `xs`, `sm`, `md` (default), `lg`, `xl`. The chevron and the room reserved for it scale with the field.

```tsx demo
<Col>
  <Select xs defaultValue="sm">
    <option value="xs">Extra small</option>
    <option value="sm">Small</option>
    <option value="md">Medium</option>
    <option value="lg">Large</option>
  </Select>
  <Select sm defaultValue="sm">
    <option value="xs">Extra small</option>
    <option value="sm">Small</option>
    <option value="md">Medium</option>
    <option value="lg">Large</option>
  </Select>
  <Select defaultValue="sm">
    <option value="xs">Extra small</option>
    <option value="sm">Small</option>
    <option value="md">Medium</option>
    <option value="lg">Large</option>
  </Select>
  <Select lg defaultValue="sm">
    <option value="xs">Extra small</option>
    <option value="sm">Small</option>
    <option value="md">Medium</option>
    <option value="lg">Large</option>
  </Select>
  <Select xl defaultValue="sm">
    <option value="xs">Extra small</option>
    <option value="sm">Small</option>
    <option value="md">Medium</option>
    <option value="lg">Large</option>
  </Select>
</Col>
```

## States

`invalid` adds a danger border and ring, turns the chevron danger, and emits `aria-invalid`. Pair it with `Field` to attach the message.

```tsx demo
<Col>
  <Select defaultValue="eur">
    <option value="eur">Euro</option>
    <option value="usd">US dollar</option>
    <option value="gbp">Pound sterling</option>
  </Select>
  <Select invalid placeholder="Select a currency">
    <option value="eur">Euro</option>
    <option value="usd">US dollar</option>
    <option value="gbp">Pound sterling</option>
  </Select>
  <Select disabled defaultValue="eur">
    <option value="eur">Euro</option>
    <option value="usd">US dollar</option>
    <option value="gbp">Pound sterling</option>
  </Select>
</Col>
```

## Appearances

Selects are `primary` by default and take the same appearance props as `Input`.

```tsx demo
<Row flexWrap>
  <Select className="w-40" defaultValue="eur">
    <option value="eur">Primary</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select success className="w-40" defaultValue="eur">
    <option value="eur">Success</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select warning className="w-40" defaultValue="eur">
    <option value="eur">Warning</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select danger className="w-40" defaultValue="eur">
    <option value="eur">Danger</option>
    <option value="usd">US dollar</option>
  </Select>
</Row>
```

## Variants

`outline` is the default. The dropdown list takes its colours from the field, so a `filled` Select opens a filled list rather than a light one on a dark control. `ghost` drops the field's own surface but keeps the list opaque, since a see-through popup would render the options unreadable.

```tsx demo
<Row flexWrap>
  <Select className="w-40" defaultValue="eur">
    <option value="eur">Outline</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select filled className="w-40" defaultValue="eur">
    <option value="eur">Filled</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select ghost className="w-40" defaultValue="eur">
    <option value="eur">Ghost</option>
    <option value="usd">US dollar</option>
  </Select>
</Row>
```

## Shapes

`rounded` is the default, and the shape carries through to the dropdown: a `sharp` Select opens a sharp list rather than a rounded one on a square field.

`pill` is the exception. It reshapes the field only, because a pill radius is effectively infinite and a tall list box given that radius swallows its own first and last rows.

```tsx demo
<Row flexWrap>
  <Select rounded className="w-40" defaultValue="eur">
    <option value="eur">Rounded</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select pill className="w-40" defaultValue="eur">
    <option value="eur">Pill</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select sharp className="w-40" defaultValue="eur">
    <option value="eur">Sharp</option>
    <option value="usd">US dollar</option>
  </Select>
</Row>
```

## Placeholder

`placeholder` adds a muted first option that prompts for a choice. It is disabled and hidden from the list, so it can't be picked again, and an uncontrolled Select starts on it; with `required`, the empty value fails validation. `multiple` ignores it, and `<Field select placeholder="...">` passes it through. The prop needs `@vaneui/ui` 1.5.0 or later.

```tsx demo
<Col>
  <Select placeholder="Choose a currency">
    <option value="eur">Euro</option>
    <option value="usd">US dollar</option>
    <option value="gbp">Pound sterling</option>
  </Select>
  <Field select required placeholder="Choose a region" label="Region" description="Required.">
    <option>Cyprus</option>
    <option>Estonia</option>
    <option>Portugal</option>
  </Field>
</Col>
```

## Groups and placeholders

An `optgroup` labels a run of related options, and the placeholder stays above the groups.

```tsx demo
<Field label="Region" description="Sets your default currency.">
  <Select placeholder="Choose a region">
    <optgroup label="Europe">
      <option>Cyprus</option>
      <option>Estonia</option>
    </optgroup>
    <optgroup label="Americas">
      <option>Canada</option>
    </optgroup>
  </Select>
</Field>
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal` (default), `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Read Only: `readOnly`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Validity: `invalid`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Radio

> Radio selects exactly one option from a set. RadioGroup shares a name across its options and exposes them as a single labelled group.

Source: https://vaneui.com/docs/form-components/radio

Import: `import { Radio, RadioGroup, Col, Field, Label, Row, Text } from "@vaneui/ui"`

Radio fits a short set of choices that should all stay visible. Each one is a native `<input type="radio">`, so the browser moves the selection with the arrow keys inside a group. RadioGroup takes `value`, `defaultValue` and `onChange` for the whole set and matches each option by its `value` prop. For a long list, use a [Select](/docs/form-components/select); when more than one option can be on, use [Checkbox](/docs/form-components/checkbox).

## Basic usage

Radio selects exactly one option from a set. Wrap the options in a `RadioGroup` so they share a name and behave as one control.

```tsx demo
<RadioGroup name="plan" defaultValue="pro">
  <Label row itemsCenter><Radio value="free"/> Free</Label>
  <Label row itemsCenter><Radio value="pro"/> Pro</Label>
  <Label row itemsCenter><Radio value="team"/> Team</Label>
</RadioGroup>
```

`RadioGroup` renders `role="radiogroup"` and generates a shared `name` when you do not pass one, so radios are mutually exclusive without extra wiring.

## With a group label

Inside a `Field`, the group is labelled by reference with `aria-labelledby`, because a radiogroup cannot be the target of `htmlFor`.

```tsx demo
<Field label="Billing period" description="Change it any time.">
  <RadioGroup name="billing" defaultValue="yearly">
    <Label row itemsCenter><Radio value="monthly"/> Monthly</Label>
    <Label row itemsCenter><Radio value="yearly"/> Yearly, two months free</Label>
  </RadioGroup>
</Field>
```

## Sizes

```tsx demo
<Col>
  <Label row itemsCenter xs><Radio name="s-xs" defaultChecked/> Extra small</Label>
  <Label row itemsCenter sm><Radio name="s-sm" defaultChecked/> Small</Label>
  <Label row itemsCenter md><Radio name="s-md" defaultChecked/> Medium</Label>
  <Label row itemsCenter lg><Radio name="s-lg" defaultChecked/> Large</Label>
  <Label row itemsCenter xl><Radio name="s-xl" defaultChecked/> Extra large</Label>
</Col>
```

## Appearances

Radio takes the same appearance props as Checkbox: the appearance colours the box border, the selected fill and the focus ring. Set it on the `Label` too when you want the text to match.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter><Radio name="a-primary" defaultChecked/> primary (default)</Label>
  <Label row itemsCenter accent><Radio accent name="a-accent" defaultChecked/> accent</Label>
  <Label row itemsCenter secondary><Radio secondary name="a-secondary" defaultChecked/> secondary</Label>
  <Label row itemsCenter tertiary><Radio tertiary name="a-tertiary" defaultChecked/> tertiary</Label>
  <Label row itemsCenter success><Radio success name="a-success" defaultChecked/> success</Label>
  <Label row itemsCenter danger><Radio danger name="a-danger" defaultChecked/> danger</Label>
  <Label row itemsCenter warning><Radio warning name="a-warning" defaultChecked/> warning</Label>
  <Label row itemsCenter info><Radio info name="a-info" defaultChecked/> info</Label>
</Row>
```

## Shapes

Radio is `pill` by default, which is what distinguishes it from a Checkbox at a glance. `rounded` and `sharp` are available, but a square radio reads as a checkbox, so reach for them only when the surrounding design demands it.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter><Radio name="sh-pill" defaultChecked/> pill, the default</Label>
  <Label row itemsCenter><Radio rounded name="sh-rounded" defaultChecked/> rounded</Label>
  <Label row itemsCenter><Radio sharp name="sh-sharp" defaultChecked/> sharp</Label>
</Row>
```

## Variants

Radio is `filled` by default: the box fills with the appearance colour when selected. `outline` keeps the box transparent and colours the dot instead.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter><Radio name="v-filled" defaultChecked/> filled, the default</Label>
  <Label row itemsCenter><Radio outline name="v-outline" defaultChecked/> outline</Label>
  <Label row itemsCenter><Radio ghost name="v-ghost" defaultChecked/> ghost</Label>
</Row>
```

## Explicit size on the control

The Radio takes its own size prop, which wins over the size inherited from the Label.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter lg><Radio xs name="sz-a" defaultChecked/> xs dot, lg label</Label>
  <Label row itemsCenter lg><Radio name="sz-b" defaultChecked/> inherited lg</Label>
  <Label row itemsCenter lg><Radio xl name="sz-c" defaultChecked/> xl dot, lg label</Label>
</Row>
```

## States

```tsx demo
<RadioGroup name="states" defaultValue="on">
  <Label row itemsCenter><Radio value="off"/> Unselected</Label>
  <Label row itemsCenter><Radio value="on"/> Selected</Label>
  <Label row itemsCenter><Radio value="no" disabled/> Disabled</Label>
</RadioGroup>
```

## Group state props

`RadioGroup` takes `disabled`, `readOnly`, `required` and `invalid`. Each one reaches every `Radio` in the group, and a `Radio`'s own prop wins. The group element also gets the matching `aria-disabled`, `aria-readonly`, `aria-required` and `aria-invalid` attributes. These props need `@vaneui/ui` 1.5.0 or later.

```tsx demo
<Row flexWrap itemsStart>
  <Col>
    <Text sm secondary>disabled</Text>
    <RadioGroup name="group-disabled" disabled defaultValue="free">
      <Label row itemsCenter><Radio value="free"/> Free</Label>
      <Label row itemsCenter><Radio value="pro"/> Pro</Label>
      <Label row itemsCenter><Radio value="team" disabled={false}/> Team, enabled</Label>
    </RadioGroup>
  </Col>
  <Col>
    <Text sm secondary>readOnly</Text>
    <RadioGroup name="group-readonly" readOnly defaultValue="pro">
      <Label row itemsCenter><Radio value="free"/> Free</Label>
      <Label row itemsCenter><Radio value="pro"/> Pro</Label>
    </RadioGroup>
  </Col>
  <Col>
    <Text sm secondary>invalid</Text>
    <RadioGroup name="group-invalid" invalid>
      <Label row itemsCenter><Radio value="free"/> Free</Label>
      <Label row itemsCenter><Radio value="pro"/> Pro</Label>
    </RadioGroup>
  </Col>
</Row>
```

Inside a [Field](/docs/form-components/field), the Field's own `disabled`, `readOnly`, `required` and `error` reach the group the same way.

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Read Only: `readOnly`
- Shape: `pill` (default), `sharp`, `rounded`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Validity: `invalid`
- Variant: `filled` (default), `outline`, `ghost`

Layout and utility props (Align Self, Border, Cursor, Display, Focus Visible, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Switch

> Switch toggles a setting that takes effect immediately. Use Checkbox instead when the value is submitted with a form.

Source: https://vaneui.com/docs/form-components/switch

Import: `import { Switch, Col, Label, Row } from "@vaneui/ui"`

Switch takes the same `checked`, `defaultChecked`, `onChange`, `name` and `readOnly` props as [Checkbox](/docs/form-components/checkbox), so choosing between the two comes down to when the change applies. Its knob is decorative markup marked `aria-hidden`. Pass `switch` to a [Field](/docs/form-components/field) to render a Switch with its label beside it.

## Basic usage

Switch toggles a setting that takes effect immediately. It renders a real checkbox input with `role="switch"`, so it is operable with the keyboard and announced correctly.

```tsx demo
<Label row itemsCenter>
  <Switch defaultChecked/>
  Email notifications
</Label>
```

## Sizes

A Switch inside a Label inherits the Label's size, so set it once.

```tsx demo
<Col>
  <Label row itemsCenter xs><Switch defaultChecked/> Extra small</Label>
  <Label row itemsCenter sm><Switch defaultChecked/> Small</Label>
  <Label row itemsCenter md><Switch defaultChecked/> Medium</Label>
  <Label row itemsCenter lg><Switch defaultChecked/> Large</Label>
  <Label row itemsCenter xl><Switch defaultChecked/> Extra large</Label>
</Col>
```

## Appearances

The appearance colours the track when the switch is on, and the focus ring.

```tsx demo
<Row flexWrap>
  <Label row itemsCenter><Switch defaultChecked/> primary (default)</Label>
  <Label row itemsCenter accent><Switch accent defaultChecked/> accent</Label>
  <Label row itemsCenter secondary><Switch secondary defaultChecked/> secondary</Label>
  <Label row itemsCenter tertiary><Switch tertiary defaultChecked/> tertiary</Label>
  <Label row itemsCenter success><Switch success defaultChecked/> success</Label>
  <Label row itemsCenter danger><Switch danger defaultChecked/> danger</Label>
  <Label row itemsCenter warning><Switch warning defaultChecked/> warning</Label>
  <Label row itemsCenter info><Switch info defaultChecked/> info</Label>
</Row>
```

## Shapes

Switch is `pill` by default. The shape applies to the track and the knob together: the knob's corner radius insets from the track's by the track padding, so the two stay concentric instead of a round knob sitting in a square track.

```tsx demo
<Col>
  <Label row itemsCenter><Switch defaultChecked/> pill, the default</Label>
  <Label row itemsCenter><Switch rounded defaultChecked/> rounded</Label>
  <Label row itemsCenter><Switch sharp defaultChecked/> sharp</Label>
</Col>
```

## Variants

Switch is `filled` by default: the track fills with the appearance colour when on. `outline` keeps the track transparent and colours its border instead.

```tsx demo
<Col>
  <Label row itemsCenter><Switch defaultChecked/> filled, the default</Label>
  <Label row itemsCenter><Switch outline defaultChecked/> outline</Label>
  <Label row itemsCenter><Switch ghost defaultChecked/> ghost</Label>
</Col>
```

## Explicit size on the control

The Switch takes its own size prop, which wins over the size inherited from the Label.

```tsx demo
<Col>
  <Label row itemsCenter lg><Switch xs defaultChecked/> xs track, lg label</Label>
  <Label row itemsCenter lg><Switch defaultChecked/> inherited lg</Label>
  <Label row itemsCenter lg><Switch xl defaultChecked/> xl track, lg label</Label>
</Col>
```

## States

A `readOnly` switch keeps its value when clicked and dims like a read-only text field; `Checkbox` and `Radio` behave the same way.

```tsx demo
<Col>
  <Label row itemsCenter><Switch/> Off</Label>
  <Label row itemsCenter><Switch defaultChecked/> On</Label>
  <Label row itemsCenter><Switch disabled/> Disabled</Label>
  <Label row itemsCenter><Switch disabled defaultChecked/> Disabled and on</Label>
  <Label row itemsCenter><Switch readOnly defaultChecked/> Read-only</Label>
</Col>
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Read Only: `readOnly`
- Shape: `pill` (default), `sharp`, `rounded`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Validity: `invalid`
- Variant: `filled` (default), `outline`, `ghost`

Layout and utility props (Align Self, Border, Cursor, Display, Focus Visible, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Text

> The primary component for rendering all text content. It provides props to control typographic properties like size, weight, color, and alignment.

Source: https://vaneui.com/docs/typography-components/text

Import: `import { Text, Card, Col, Row } from "@vaneui/ui"`

Use Text for paragraphs, captions and helper copy. It renders a `<p>` element, or an `<a>` when `href` is set. Headings belong in [Title](/docs/typography-components/title) and its siblings, which render `<h1>` to `<h3>` elements. For a link inside a sentence, nest a [Link](/docs/typography-components/link) in the Text: it keeps the link color and matches the size of the text around it.

## Basic usage

Text renders paragraph text with default styling.

```tsx demo
<Text>Compose interfaces with VaneUI components. Text provides consistent typography across your application.</Text>
```

## Sizes

Text comes in different sizes: `xs`, `sm`, `md` (default), `lg`, `xl`.

```tsx demo
<Col>
  <Text xs>Extra small text</Text>
  <Text sm>Small text for captions</Text>
  <Text>Medium text (default)</Text>
  <Text lg>Large text for emphasis</Text>
  <Text xl>Extra large text</Text>
</Col>
```

## Appearances

Text supports explicit color appearances: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`. Use these to override the default `inheritAppearance` behavior.

```tsx demo
<Col>
  <Text primary>Primary text for important content</Text>
  <Text accent>Accent text for highlights</Text>
  <Text secondary>Secondary text for supporting content</Text>
  <Text tertiary>Tertiary text for muted content</Text>
  <Text success>Success text for positive feedback</Text>
  <Text danger>Danger text for errors or warnings</Text>
  <Text warning>Warning text for cautionary messages</Text>
  <Text info>Info text for informational content</Text>
</Col>
```

## Variants

Text never paints a background, so the variant does one thing here: it picks which colour of the appearance the text is painted in. `outline`, the default, uses the appearance's own colour, for text on a plain surface. `filled` uses the "on this fill" colour, for text sitting on a filled surface of the same appearance.

```tsx demo
<Col>
  <Text info>outline info, on the page surface</Text>
  <Text danger>outline danger, on the page surface</Text>
  <Card info filled>
    <Text info filled>filled info, on a matching filled Card</Text>
  </Card>
  <Card danger filled>
    <Text danger filled>filled danger, on a matching filled Card</Text>
  </Card>
</Col>
```

Use `filled` on a plain page and the text takes the colour meant to sit on the fill, which is close to the page itself. Wrap it in a matching surface, or leave the default `inheritAppearance` on and let it take the colour from whatever it sits in.

## Inherit appearance (default)

Text defaults to the `inheritAppearance` appearance: it picks up its color from the parent via CSS cascade instead of applying its own. Set an explicit appearance to override.

```tsx demo
<Row flexWrap itemsStretch>
  <Card primary filled>
    <Text fontBold>Inherited Primary</Text>
    <Text>This text inherits primary from the Card.</Text>
  </Card>
  <Card success filled>
    <Text fontBold>Inherited Success</Text>
    <Text>Inherits success color automatically.</Text>
  </Card>
  <Card border secondary>
    <Text fontBold>On a plain surface</Text>
    <Text>Inherits the Card's own colour.</Text>
    <Text danger>Explicit danger overrides inherit.</Text>
  </Card>
</Row>
```

An explicit appearance stops inheriting, so it has to read on the surface it lands on. Inside a filled Card, `<Text danger>` resolves to the outline danger colour, which is close in weight to the filled surface behind it.

## Font weights

Control weight with `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`.

```tsx demo
<Col>
  <Text fontThin>Thin weight</Text>
  <Text fontLight>Light weight</Text>
  <Text fontNormal>Normal weight</Text>
  <Text fontMedium>Medium weight</Text>
  <Text fontSemibold>Semibold weight</Text>
  <Text fontBold>Bold weight</Text>
  <Text fontExtrabold>Extra bold weight</Text>
  <Text fontBlack>Black weight</Text>
</Col>
```

## Font families

Switch font family with `fontSans` (default), `fontSerif`, `fontMono`.

```tsx demo
<Col>
  <Text fontSans>Sans-serif font (default)</Text>
  <Text fontSerif>Serif font for editorial content</Text>
  <Text fontMono>Monospace for code or technical content</Text>
</Col>
```

## Italic, underline, line-through

```tsx demo
<Col>
  <Text italic>Italic text for quotes or terms</Text>
  <Text underline>Underlined text for emphasis</Text>
  <Text lineThrough>Line-through for deleted content</Text>
</Col>
```

## Text transform

Use `uppercase`, `lowercase`, `capitalize`.

```tsx demo
<Col>
  <Text uppercase>Uppercase for labels</Text>
  <Text lowercase>LOWERCASE NORMALIZED</Text>
  <Text capitalize>capitalized words example</Text>
</Col>
```

## Text alignment

Align text with `textLeft` (default), `textCenter`, `textRight`, `textJustify`. Text defaults to `wFit`, so set `wFull` to see alignment effects across the container.

```tsx demo
<Col>
  <Text wFull>Left aligned (default)</Text>
  <Text wFull textCenter>Center aligned</Text>
  <Text wFull textRight>Right aligned</Text>
  <Text wFull textJustify>Justified text spreads to fill the line, distributing extra space between words across the full container width.</Text>
</Col>
```

## Truncate and line clamp

Use `truncate` for single-line ellipsis, or `lineClamp2`/`lineClamp3`/`lineClamp4`/`lineClamp5` for multi-line clamping.

```tsx demo
<Col>
  <Text wFull truncate>Truncated single line of text that will be cut off with an ellipsis when it exceeds the container width.</Text>
  <Text wFull lineClamp2>Clamped to two lines. This release note covers the new size props, the revised default appearances, and the spacing changes that now scale with the size prop across every typography component in the library.</Text>
  <Text wFull lineClamp3>Clamped to three lines. The migration guide walks through each change in detail, from the renamed appearance props to the updated default margins, and explains how to update your existing components step by step so nothing renders differently after you upgrade to the latest version.</Text>
</Col>
```

## Word break

Control how long unbreakable strings behave when they would overflow the container. `breakWords` wraps a long word onto the next line (`overflow-wrap: break-word`), `breakAll` breaks between any two characters, `breakKeep` prevents breaks in CJK text, and `breakNormal` sets `overflow-wrap: normal` so the string overflows. By default Text already wraps long strings (`overflow-wrap: anywhere`). This is the opposite of `truncate`: instead of hiding the overflow, the text wraps to fit.

```tsx demo
<Col>
  <Text breakNormal className="w-48 border border-gray-300 p-2">
    breakNormal: https://vaneui.com/docs/typography-components/text overflows.
  </Text>
  <Text breakWords className="w-48 border border-gray-300 p-2">
    breakWords: https://vaneui.com/docs/typography-components/text wraps.
  </Text>
  <Text breakAll className="w-48 border border-gray-300 p-2">
    breakAll: https://vaneui.com/docs/typography-components/text wraps.
  </Text>
</Col>
```

## Letter spacing

Control letter spacing with `trackingTighter`, `trackingTight`, `trackingNormal`, `trackingWide`, `trackingWider`, `trackingWidest`. Text defaults to a compact `-0.011em` tracking; `trackingNormal` resets it to `0`.

```tsx demo
<Col>
  <Text trackingTighter>Tighter letter spacing</Text>
  <Text trackingTight>Tight letter spacing</Text>
  <Text trackingNormal>Normal letter spacing</Text>
  <Text trackingWide>Wide letter spacing</Text>
  <Text trackingWider>Wider letter spacing</Text>
  <Text trackingWidest>Widest letter spacing</Text>
</Col>
```

## Margins

Block typography (`Text`, `Title`, `SectionTitle`, `PageTitle`, `Blockquote`) accepts size-driven margin props: `margin` (all sides), `marginX`, `marginY`, `marginT`, and `marginB`. `Text` defaults to `noMargin`, so opt in where you need vertical rhythm outside a gap-based layout. The margin scales with the size prop. Side props compose: `marginT marginB` applies both. `noMargin` resets and wins.

```tsx demo
<Col noGap>
  <Text>No margin (default), sits flush.</Text>
  <Text marginT marginB>Margin above and below, scales with size.</Text>
  <Text>Another flush line.</Text>
</Col>
```

## Text in context

Combining text properties for real-world use cases.

```tsx demo
<Col>
  <Card>
    <Text lg fontBold>Product Title</Text>
    <Text secondary>Category • 4.5 ★ (128 reviews)</Text>
    <Text>High-quality component library for building modern web applications with React and TypeScript.</Text>
    <Text sm primary fontSemibold>$99.00</Text>
  </Card>
</Col>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance` (default)
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Color: `inheritColor`, `noInheritColor`
- Inherit Size: `inheritSize`, `noInheritSize`
- Letter Spacing: `trackingTighter`, `trackingTight`, `trackingNormal`, `trackingWide`, `trackingWider`, `trackingWidest`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin` (default)
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft` (default), `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Cursor, Display, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Show, Whitespace, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# PageTitle

> A specialized component for the primary heading of a page. It ensures consistent styling for top-level titles across your application.

Source: https://vaneui.com/docs/typography-components/page-title

Import: `import { PageTitle, Button, Card, Col, Divider, Row, SectionTitle, Stack, Text, Title } from "@vaneui/ui"`

PageTitle is the heading that names the whole screen, such as an article title, a dashboard name or a hero headline. Long titles wrap into lines of similar length (`text-wrap: balance`), and the font size steps down at tablet and mobile widths. Headings below it belong in [SectionTitle](/docs/typography-components/section-title), which renders `<h2>`, and [Title](/docs/typography-components/title), which renders `<h3>`.

## Basic usage

PageTitle renders a large `<h1>` heading for page titles. It defaults to `fontSemibold` weight, `fontHeading` font family, `trackingTight` letter spacing, and `inheritAppearance` appearance.

```tsx demo
<PageTitle>Welcome to VaneUI</PageTitle>
```

## Sizes

Page titles come in five sizes: `xs`, `sm`, `md` (default), `lg`, `xl`.

```tsx demo
<Col>
  <PageTitle xs>Extra Small Page Title</PageTitle>
  <PageTitle sm>Small Page Title</PageTitle>
  <PageTitle>Medium Page Title (default)</PageTitle>
  <PageTitle lg>Large Page Title</PageTitle>
  <PageTitle xl>Extra Large Page Title</PageTitle>
</Col>
```

## Appearances

By default, PageTitle uses the `inheritAppearance` appearance: it inherits color from its parent. Use explicit appearances like `primary`, `secondary`, `success`, `warning`, `danger`, `info` to override.

```tsx demo
<Col>
  <PageTitle primary>Primary Page Title</PageTitle>
  <PageTitle secondary>Secondary Page Title</PageTitle>
  <PageTitle success>Success Page Title</PageTitle>
  <PageTitle warning>Warning Page Title</PageTitle>
  <PageTitle danger>Danger Page Title</PageTitle>
  <PageTitle info>Info Page Title</PageTitle>
</Col>
```

## Variants

Headings never paint a background, so the variant only picks which colour of the appearance the heading is painted in. `outline`, the default, uses the appearance's own colour. `filled` uses the "on this fill" colour, for a heading sitting on a filled surface of the same appearance.

```tsx demo
<Col>
  <PageTitle info>outline info, on the page surface</PageTitle>
  <PageTitle danger>outline danger, on the page surface</PageTitle>
  <Card info filled>
    <PageTitle info filled>filled info, on a matching filled Card</PageTitle>
  </Card>
  <Card danger filled>
    <PageTitle danger filled>filled danger, on a matching filled Card</PageTitle>
  </Card>
</Col>
```

## PageTitle vs SectionTitle vs Title

Three heading components for a clean semantic hierarchy. Use them together so the document outline matches the visual hierarchy.

```tsx demo
<Col>
  <PageTitle>Page Heading (h1)</PageTitle>
  <SectionTitle>Section Heading (h2)</SectionTitle>
  <Title>Subsection Heading (h3)</Title>
</Col>
```

## Font weights

PageTitle is `fontSemibold` by default. Override with any weight prop: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`.

```tsx demo
<Col>
  <PageTitle fontLight>Light Page Title</PageTitle>
  <PageTitle fontNormal>Normal Page Title</PageTitle>
  <PageTitle fontMedium>Medium Page Title</PageTitle>
  <PageTitle>Semibold Page Title (default)</PageTitle>
  <PageTitle fontBold>Bold Page Title</PageTitle>
  <PageTitle fontBlack>Black Page Title</PageTitle>
</Col>
```

## Font families

Switch between `fontSans`, `fontSerif`, and `fontMono` font families.

```tsx demo
<Col>
  <PageTitle fontSans>Sans-serif Page Title</PageTitle>
  <PageTitle fontSerif>Serif Page Title</PageTitle>
  <PageTitle fontMono>Monospace Page Title</PageTitle>
</Col>
```

## Italic

Use the `italic` prop for italic emphasis.

```tsx demo
<PageTitle italic>Italic Page Title</PageTitle>
```

## Text alignment

PageTitle is left-aligned by default. Use `textCenter`, `textRight`, or `textJustify` to change alignment.

```tsx demo
<Card>
  <PageTitle wFull>Left Aligned (default)</PageTitle>
  <PageTitle wFull textCenter>Center Aligned</PageTitle>
  <PageTitle wFull textRight>Right Aligned</PageTitle>
</Card>
```

## Custom HTML tag

Override the rendered tag with the `tag` prop when the visual style of PageTitle is wanted but a different semantic level is required.

```tsx demo
<Col>
  <PageTitle>Rendered as h1 (default)</PageTitle>
  <PageTitle tag="h2">Rendered as h2</PageTitle>
  <PageTitle tag="h3">Rendered as h3</PageTitle>
  <PageTitle tag="div">Rendered as div</PageTitle>
</Col>
```

## PageTitle in context

Page titles work well as the main heading of a page, paired with a subtitle.

```tsx demo
<Card>
  <PageTitle lg primary>Product Documentation</PageTitle>
  <Text secondary>Learn how to use VaneUI components in your projects.</Text>
  <Text>Get started with our comprehensive guides and examples.</Text>
</Card>
```

## Page header pattern

Combine PageTitle with Text and Divider for a complete page header.

```tsx demo
<Col>
  <PageTitle xl>Dashboard</PageTitle>
  <Text lg secondary>Welcome back. Here is an overview of your projects.</Text>
  <Divider />
  <Text>Content goes here...</Text>
</Col>
```

## Hero page header

Combine an `xl` PageTitle with a large subtitle and a call to action for a marketing-style hero.

```tsx demo
<Stack itemsCenter>
  <PageTitle xl textCenter>Build Faster with VaneUI</PageTitle>
  <Text lg secondary textCenter>A boolean-props React component library powered by Tailwind CSS v4.</Text>
  <Row>
    <Button filled>Get Started</Button>
    <Button>View on GitHub</Button>
  </Row>
</Stack>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance` (default)
- Font Family: `fontSans`, `fontSerif`, `fontMono`, `fontHeading` (default)
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold` (default), `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Color: `inheritColor`, `noInheritColor`
- Inherit Size: `inheritSize`, `noInheritSize`
- Letter Spacing: `trackingTighter`, `trackingTight` (default), `trackingNormal`, `trackingWide`, `trackingWider`, `trackingWidest`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft` (default), `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Cursor, Display, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Show, Whitespace, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# SectionTitle

> A component for rendering headings of major sections within a page. It helps to create a clear and accessible document structure.

Source: https://vaneui.com/docs/typography-components/section-title

Import: `import { SectionTitle, Card, Col, Divider, PageTitle, Section, Text, Title } from "@vaneui/ui"`

SectionTitle opens each major part of a page, such as features, pricing or FAQ. Like the other heading components, its font size steps down at tablet and mobile widths, and passing `href` renders an `<a>` in place of the `<h2>`. Keep [PageTitle](/docs/typography-components/page-title) for the `<h1>` that names the page, and use [Title](/docs/typography-components/title) for headings inside a section, such as card titles.

## Basic usage

SectionTitle renders an `<h2>` heading for major section headings. It defaults to `fontSemibold` weight, `fontHeading` font family, `inheritAppearance` appearance, and left-aligned text.

```tsx demo
<SectionTitle>Getting Started</SectionTitle>
```

## Sizes

Section titles come in five sizes: `xs`, `sm`, `md` (default), `lg`, `xl`.

```tsx demo
<Col>
  <SectionTitle xs>Extra Small Section Title</SectionTitle>
  <SectionTitle sm>Small Section Title</SectionTitle>
  <SectionTitle>Medium Section Title (default)</SectionTitle>
  <SectionTitle lg>Large Section Title</SectionTitle>
  <SectionTitle xl>Extra Large Section Title</SectionTitle>
</Col>
```

## Appearances

By default, SectionTitle uses the `inheritAppearance` appearance: it inherits color from its parent. Use explicit appearances like `primary`, `secondary`, `success`, `warning`, `danger`, `info` to override.

```tsx demo
<Col>
  <SectionTitle primary>Primary Section Title</SectionTitle>
  <SectionTitle secondary>Secondary Section Title</SectionTitle>
  <SectionTitle success>Success Section Title</SectionTitle>
  <SectionTitle warning>Warning Section Title</SectionTitle>
  <SectionTitle danger>Danger Section Title</SectionTitle>
  <SectionTitle info>Info Section Title</SectionTitle>
</Col>
```

## Variants

Headings never paint a background, so the variant only picks which colour of the appearance the heading is painted in. `outline`, the default, uses the appearance's own colour. `filled` uses the "on this fill" colour, for a heading sitting on a filled surface of the same appearance.

```tsx demo
<Col>
  <SectionTitle info>outline info, on the page surface</SectionTitle>
  <SectionTitle danger>outline danger, on the page surface</SectionTitle>
  <Card info filled>
    <SectionTitle info filled>filled info, on a matching filled Card</SectionTitle>
  </Card>
  <Card danger filled>
    <SectionTitle danger filled>filled danger, on a matching filled Card</SectionTitle>
  </Card>
</Col>
```

## PageTitle vs SectionTitle vs Title

Three heading components for a clean semantic hierarchy.

```tsx demo
<Col>
  <PageTitle>Page Heading (h1)</PageTitle>
  <SectionTitle>Section Heading (h2)</SectionTitle>
  <Title>Subsection Heading (h3)</Title>
</Col>
```

## Font weights

SectionTitle is `fontSemibold` by default. Override with any weight prop: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`.

```tsx demo
<Col>
  <SectionTitle fontLight>Light Section Title</SectionTitle>
  <SectionTitle fontNormal>Normal Section Title</SectionTitle>
  <SectionTitle fontMedium>Medium Section Title</SectionTitle>
  <SectionTitle>Semibold Section Title (default)</SectionTitle>
  <SectionTitle fontBold>Bold Section Title</SectionTitle>
  <SectionTitle fontBlack>Black Section Title</SectionTitle>
</Col>
```

## Font families

Switch between `fontSans`, `fontSerif`, and `fontMono` font families.

```tsx demo
<Col>
  <SectionTitle fontSans>Sans-serif Section Title</SectionTitle>
  <SectionTitle fontSerif>Serif Section Title</SectionTitle>
  <SectionTitle fontMono>Monospace Section Title</SectionTitle>
</Col>
```

## Italic

Use the `italic` prop for italic emphasis.

```tsx demo
<SectionTitle italic>Italic Section Title</SectionTitle>
```

## Uppercase

Use the `uppercase` prop to render the title in all caps.

```tsx demo
<SectionTitle uppercase>Uppercase Section Title</SectionTitle>
```

## Text alignment

SectionTitle is left-aligned by default. Use `textCenter`, `textRight`, or `textJustify` to change alignment.

```tsx demo
<Col>
  <SectionTitle wFull>Left Aligned (default)</SectionTitle>
  <SectionTitle wFull textCenter>Center Aligned</SectionTitle>
  <SectionTitle wFull textRight>Right Aligned</SectionTitle>
</Col>
```

## Custom HTML tag

Override the rendered tag with the `tag` prop when the visual style of SectionTitle is wanted but a different semantic level is required.

```tsx demo
<Col>
  <SectionTitle tag="h1">Rendered as h1</SectionTitle>
  <SectionTitle>Rendered as h2 (default)</SectionTitle>
  <SectionTitle tag="h3">Rendered as h3</SectionTitle>
  <SectionTitle tag="h4">Rendered as h4</SectionTitle>
</Col>
```

## SectionTitle in a Section

`SectionTitle` is designed to head a `<Section>`. Use them together so the visual structure matches the semantic outline.

```tsx demo
<Col>
  <Section>
    <SectionTitle>Installation</SectionTitle>
    <Text>Install VaneUI using npm or yarn.</Text>
  </Section>
  <Section>
    <SectionTitle>Usage</SectionTitle>
    <Text>Import components and start building.</Text>
  </Section>
</Col>
```

## SectionTitle in context

Section titles work well with other typography components in cards.

```tsx demo
<Card>
  <SectionTitle lg primary>Product Features</SectionTitle>
  <Text secondary>Everything you need to build modern applications.</Text>
  <SectionTitle sm>Performance</SectionTitle>
  <Text>Optimized for speed and efficiency.</Text>
  <SectionTitle sm>Accessibility</SectionTitle>
  <Text>Built with ARIA best practices.</Text>
</Card>
```

## Section header pattern

Combine SectionTitle with Divider and content for a structured section.

```tsx demo
<Col>
  <SectionTitle primary>Getting Started</SectionTitle>
  <Divider />
  <Text>Follow the steps below to set up your project.</Text>
  <SectionTitle primary>Configuration</SectionTitle>
  <Divider />
  <Text>Customize the settings to match your requirements.</Text>
</Col>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance` (default)
- Font Family: `fontSans`, `fontSerif`, `fontMono`, `fontHeading` (default)
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold` (default), `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Color: `inheritColor`, `noInheritColor`
- Inherit Size: `inheritSize`, `noInheritSize`
- Letter Spacing: `trackingTighter`, `trackingTight`, `trackingNormal`, `trackingWide`, `trackingWider`, `trackingWidest`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft` (default), `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Cursor, Display, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Show, Whitespace, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Title

> React Title component for Tailwind CSS v4: an h3 heading for cards, dialogs and subsections, one level below SectionTitle, with size, color and weight props.

Source: https://vaneui.com/docs/typography-components/title

Import: `import { Title, Badge, Card, Col, PageTitle, Row, SectionTitle, Text } from "@vaneui/ui"`

Title is the third level of the heading set, used for card headings, dialog titles and subsection headings. A [Modal](/docs/overlay-components/modal) given a plain-text `title` renders it as a Title. Passing `href` swaps the `<h3>` for an `<a>` and drops the heading semantics, so to link a heading, nest a Link inside it instead. The levels above are [SectionTitle](/docs/typography-components/section-title) (`<h2>`) and [PageTitle](/docs/typography-components/page-title) (`<h1>`).

## Basic usage

Title renders an `<h3>` heading for subsection headings. It defaults to `fontSemibold` weight, `fontHeading` font family, and left-aligned text.

```tsx demo
<Title>Subsection Heading</Title>
```

## Sizes

Titles come in five sizes: `xs`, `sm`, `md` (default), `lg`, `xl`.

```tsx demo
<Col>
  <Title xs>Extra Small Title</Title>
  <Title sm>Small Title</Title>
  <Title>Medium Title (default)</Title>
  <Title lg>Large Title</Title>
  <Title xl>Extra Large Title</Title>
</Col>
```

## Appearances

By default, Title uses the `inheritAppearance` appearance: it inherits color from its parent. Use explicit appearances like `primary`, `secondary`, `success`, `danger`, `warning`, `info` to override.

```tsx demo
<Col>
  <Title primary>Primary Title</Title>
  <Title secondary>Secondary Title</Title>
  <Title success>Success Title</Title>
  <Title warning>Warning Title</Title>
  <Title danger>Danger Title</Title>
  <Title info>Info Title</Title>
</Col>
```

## Variants

Headings never paint a background, so the variant only picks which colour of the appearance the heading is painted in. `outline`, the default, uses the appearance's own colour. `filled` uses the "on this fill" colour, for a heading sitting on a filled surface of the same appearance.

```tsx demo
<Col>
  <Title info>outline info, on the page surface</Title>
  <Title danger>outline danger, on the page surface</Title>
  <Card info filled>
    <Title info filled>filled info, on a matching filled Card</Title>
  </Card>
  <Card danger filled>
    <Title danger filled>filled danger, on a matching filled Card</Title>
  </Card>
</Col>
```

## Title vs PageTitle vs SectionTitle

Three heading components for a clean semantic hierarchy. Use them together so the document outline matches the visual hierarchy.

```tsx demo
<Col>
  <PageTitle>Page Heading (h1)</PageTitle>
  <SectionTitle>Section Heading (h2)</SectionTitle>
  <Title>Subsection Heading (h3)</Title>
</Col>
```

## Font weights

Title is `fontSemibold` by default. Override with any weight prop: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`.

```tsx demo
<Col>
  <Title fontLight>Light Title</Title>
  <Title fontNormal>Normal Title</Title>
  <Title fontMedium>Medium Title</Title>
  <Title>Semibold Title (default)</Title>
  <Title fontBold>Bold Title</Title>
  <Title fontBlack>Black Title</Title>
</Col>
```

## Font families

Switch between `fontSans`, `fontSerif`, and `fontMono` font families.

```tsx demo
<Col>
  <Title fontSans>Sans-serif Title</Title>
  <Title fontSerif>Serif Title</Title>
  <Title fontMono>Monospace Title</Title>
</Col>
```

## Italic

Use the `italic` prop for italic emphasis.

```tsx demo
<Title italic>Italic Title</Title>
```

## Uppercase

Use the `uppercase` prop to render the title in all caps.

```tsx demo
<Title uppercase>Uppercase Title</Title>
```

## Text alignment

Title is left-aligned by default. Use `textCenter`, `textRight`, or `textJustify` to change alignment.

```tsx demo
<Card>
  <Title wFull>Left Aligned (default)</Title>
  <Title wFull textCenter>Center Aligned</Title>
  <Title wFull textRight>Right Aligned</Title>
</Card>
```

## Custom HTML tag

Override the rendered tag with the `tag` prop when the visual style of Title is wanted but a different semantic level is required.

```tsx demo
<Col>
  <Title tag="h1">Rendered as h1</Title>
  <Title tag="h2">Rendered as h2</Title>
  <Title>Rendered as h3 (default)</Title>
  <Title tag="h4">Rendered as h4</Title>
</Col>
```

## Title with Badge context

Titles pair naturally with badges, chips, and other inline components.

```tsx demo
<Col>
  <Row>
    <Title>Release Notes</Title>
    <Badge sm success>New</Badge>
  </Row>
  <Row>
    <Title>Deprecated API</Title>
    <Badge sm danger>Removed</Badge>
  </Row>
</Col>
```

## Title in context

Titles work well with other typography components in cards and sections.

```tsx demo
<Card>
  <Title lg primary fontBold>Product Features</Title>
  <Text secondary>Everything you need to build modern applications.</Text>
  <Title sm>Performance</Title>
  <Text>Optimized for speed and efficiency.</Text>
  <Title sm>Accessibility</Title>
  <Text>Built with ARIA best practices.</Text>
</Card>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance` (default)
- Font Family: `fontSans`, `fontSerif`, `fontMono`, `fontHeading` (default)
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold` (default), `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Color: `inheritColor`, `noInheritColor`
- Inherit Size: `inheritSize`, `noInheritSize`
- Letter Spacing: `trackingTighter`, `trackingTight`, `trackingNormal`, `trackingWide`, `trackingWider`, `trackingWidest`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft` (default), `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Cursor, Display, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Show, Whitespace, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Link

> Renders an accessible and themeable anchor link for navigation. Use this to direct users to other pages or external websites.

Source: https://vaneui.com/docs/typography-components/link

Import: `import { Link, Col, PageTitle, Row, SectionTitle, Text, ThemeProvider, Title } from "@vaneui/ui"`

Use Link for inline links in running text, footers and help copy. When it opens a new tab through `external` or `target="_blank"`, it appends a visually hidden "(opens in new window)" note for screen readers, unless an `aria-label` is set. For navigation in a sidebar or header, use [NavLink](/docs/basic-components/navlink); for a call to action styled as a button, use [Button](/docs/basic-components/button), which also renders `<a>` when given `href`.

## Basic usage

Link renders a styled anchor element for navigation. Unlike other typography components which default to `inheritAppearance`, Link renders its blue link color by default (no explicit appearance) with `underline`, and ships with `focusVisible` on for a keyboard focus outline.

```tsx demo
<Link href="#">Click here to learn more</Link>
```

## Appearances

Links render their blue link color by default. Set an explicit appearance to override: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`.

```tsx demo
<Row flexWrap>
  <Link primary href="#">Primary</Link>
  <Link accent href="#">Accent</Link>
  <Link secondary href="#">Secondary</Link>
  <Link success href="#">Success</Link>
  <Link danger href="#">Danger</Link>
  <Link warning href="#">Warning</Link>
  <Link info href="#">Info</Link>
</Row>
```

## Variants

Link renders its own link colour rather than an appearance by default. Like all typography, Link is background-less: `filled` paints no surface behind it, and with an explicit appearance the text colour matches `outline`.

```tsx demo
<Row flexWrap itemsCenter>
  <Link href="#">outline, the default</Link>
  <Link filled info href="#">filled info</Link>
  <Link filled success href="#">filled success</Link>
</Row>
```

## Size inherits from context

Link defaults to `inheritSize: true` so a link inside a heading renders at the heading's font-size automatically. No `size` prop needed. The link keeps its own blue colour.

```tsx demo
<Col>
  <Text>Body text with a <Link href="#">link inline</Link>.</Text>
  <Title>Subheading with a <Link href="#">link</Link> inside.</Title>
  <SectionTitle>Section heading with a <Link href="#">link</Link>.</SectionTitle>
  <PageTitle>Page title <Link href="#">link</Link></PageTitle>
</Col>
```

## Fixed size with noInheritSize

Pass `noInheritSize` to render the Link at its own size instead of the parent's, useful when a link inside a heading should stay at body-text size.

```tsx demo
<Title>
  Subheading with <Link href="#" noInheritSize>a fixed-size link</Link> mid-sentence.
</Title>
```

## Explicit sizes

An explicit size, `xs`, `sm`, `md` (default), `lg` or `xl`, renders the Link at that size instead of the parent's. Pass `inheritSize` alongside it to keep following the parent.

```tsx demo
<Col>
  <Link href="#" xs>Extra small link</Link>
  <Link href="#" sm>Small link</Link>
  <Link href="#" md>Medium link</Link>
  <Link href="#" lg>Large link</Link>
  <Link href="#" xl>Extra large link</Link>
</Col>
```

## Styling

Use `fontBold`, `fontSemibold`, or `italic` for emphasis, or `noUnderline` to remove the default underline.

```tsx demo
<Col>
  <Link fontBold href="#">Bold link</Link>
  <Link fontSemibold href="#">Semibold link</Link>
  <Link italic href="#">Italic link</Link>
  <Link noUnderline href="#">Link without underline</Link>
</Col>
```

## Hover state

Links keep an underline at rest. With `noUnderline`, the underline appears on hover for affordance. Links also render a keyboard focus-visible outline by default for keyboard users (opt out with `noFocusVisible`).

```tsx demo
<Col>
  <Link href="#">Underlined at rest, stays underlined on hover</Link>
  <Link noUnderline href="#">No underline at rest, hover to reveal it</Link>
</Col>
```

## External links

Pass the `external` prop and Link auto-applies `target="_blank"` and `rel="noopener noreferrer"` for safe cross-origin navigation.

```tsx demo
<Link href="https://github.com/vaneui/vaneui" external>VaneUI on GitHub</Link>
```

## Manual target="_blank"

Setting `target="_blank"` directly also auto-applies `rel="noopener noreferrer"`. No need to spell it out.

```tsx demo
<Link href="https://github.com/vaneui/vaneui" target="_blank">Open in a new tab</Link>
```

## Inline in Text

Links integrate naturally with surrounding prose. Drop them inline inside `Text` and they inherit the parent size.

```tsx demo
<Text>
  Check out our <Link href="#">documentation</Link> to learn more about the features.
  You can also visit the <Link href="#">GitHub repository</Link> for source code.
</Text>
```

Link is inline, so `marginT`, `marginB`, and `marginY` have no visual effect. Use `marginX` for inline-side spacing, or `className` for an exact value.

## Inherits parent Text size

Links inside body text inherit the surrounding `Text` size. Set the size on the parent and the Link follows along.

```tsx demo
<Col>
  <Text sm>Read the <Link href="#">terms and conditions</Link> before proceeding.</Text>
  <Text>Visit our <Link href="#">help center</Link> for more information.</Text>
  <Text lg>Check out the <Link href="#">getting started guide</Link> to begin.</Text>
</Col>
```

## With icons

Combine links with icons using Row for visual navigation cues.

```tsx demo
<Col>
  <Row itemsCenter>
    <ExternalLink size={14} />
    <Link href="#">Open in new window</Link>
  </Row>
  <Row itemsCenter>
    <FileText size={14} />
    <Link href="#">View documentation</Link>
  </Row>
  <Row itemsCenter>
    <GitHub size={14} />
    <Link href="#">Source on GitHub</Link>
  </Row>
</Col>
```

## Next.js Link integration

Use the `tag` prop to render the VaneUI Link as a Next.js `Link` for client-side navigation. Alias the Next.js import so it doesn't shadow `Link` from `@vaneui/ui`.

```tsx
import NextLink from 'next/link';
import { Link } from '@vaneui/ui';

<Link href="/docs" tag={NextLink}>Documentation</Link>
```

## Customizing

Set app-wide Link defaults with `ThemeProvider`'s `themeDefaults`:

```tsx demo
<ThemeProvider themeDefaults={{
  link: { info: true, noUnderline: true },
}}>
  <Link href="/docs">Read more</Link>
</ThemeProvider>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Color: `inheritColor`, `noInheritColor`
- Inherit Size: `inheritSize` (default), `noInheritSize`
- Letter Spacing: `trackingTighter`, `trackingTight`, `trackingNormal`, `trackingWide`, `trackingWider`, `trackingWidest`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline` (default), `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Variant: `filled`, `outline`, `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Cursor, Display, Focus Visible, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Show, Whitespace, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# List

> A container for displaying a series of related items in an ordered or unordered fashion. Documents both List and its ListItem entries.

Source: https://vaneui.com/docs/typography-components/list

Import: `import { List, Card, Col, ListItem, Text } from "@vaneui/ui"`

Use List for sibling items that read as one group, such as a feature list, the steps in a procedure or a checklist. Rows that compare several values belong in a [Table](/docs/layout-components/table), and a dropdown of actions in a [Menu](/docs/overlay-components/menu), whose items get `role="menuitem"` and arrow-key navigation.

## Basic usage

List renders an unordered list with bullet points by default. Each entry is a `ListItem`, which renders an `<li>` and carries the core typography props (appearance, size, weight, alignment) minus the margin, letter-spacing, and cursor props that `Text` has. Always render `ListItem` inside a `List`, which supplies the marker style and size.

```tsx demo
<List>
  <ListItem>First item in the list</ListItem>
  <ListItem>Second item in the list</ListItem>
  <ListItem>Third item in the list</ListItem>
</List>
```

## Sizes

Lists come in different sizes: `xs`, `sm`, `md` (default), `lg`, `xl`. Font size, line height, padding, and the gap between items all scale together via the CSS-variable pipeline. `ListItem` has no size default of its own. It inherits from the parent `List`, so `<List xl>` propagates to every item without repeating the prop.

```tsx demo
<Col>
  <List xs>
    <ListItem>Extra small item</ListItem>
    <ListItem>Extra small item two</ListItem>
  </List>
  <List sm>
    <ListItem>Small list item</ListItem>
    <ListItem>Another small item</ListItem>
  </List>
  <List lg>
    <ListItem>Large list item</ListItem>
    <ListItem>Another large item</ListItem>
  </List>
  <List xl>
    <ListItem>Extra large item</ListItem>
    <ListItem>Another extra large item</ListItem>
  </List>
</Col>
```

## Appearances

Lists use `inheritAppearance` appearance by default: they inherit color from their parent and stay `transparent` with no background of their own. Use explicit appearances like `primary`, `success`, `danger` to override the text color. Because a List has no background of its own, place it inside a filled container like `Card` when you want a surface behind it.

```tsx demo
<Col>
  <List primary>
    <ListItem>Primary colored item</ListItem>
    <ListItem>Another primary item</ListItem>
  </List>
  <List success>
    <ListItem>Success colored item</ListItem>
    <ListItem>Another success item</ListItem>
  </List>
  <List danger>
    <ListItem>Danger colored item</ListItem>
    <ListItem>Another danger item</ListItem>
  </List>
  <Card secondary filled>
    <List>
      <ListItem>List on a filled Card surface</ListItem>
      <ListItem>The Card provides the background</ListItem>
    </List>
  </Card>
</Col>
```

## Variants

List is `outline` and transparent by default, so an appearance colours the text and the list paints nothing behind it. List (like `ListItem`) is a typography component that still wires a background mapper, so clearing `transparent` lets `filled` paint the appearance's surface behind the whole list. Left alone, `filled` only switches the text to the "on this fill" colour, for a list sitting on a filled surface of the same appearance.

```tsx demo
<Col>
  <List info>
    <ListItem>outline info, on the page surface</ListItem>
  </List>
  <List danger filled transparent={false}>
    <ListItem>filled danger, with the surface switched on</ListItem>
  </List>
  <Card info filled>
    <List info filled>
      <ListItem>filled info, on a matching filled Card</ListItem>
    </List>
  </Card>
</Col>
```

## List style types

List supports six marker types: `listDisc` (default for unordered), `listDecimal` (default for ordered), `listCircle`, `listSquare`, `listLowerAlpha`, and `listLowerRoman`. Setting `listDecimal`, `listLowerAlpha`, or `listLowerRoman` switches the element from `<ul>` to `<ol>`.

```tsx demo
<Col>
  <div>
    <Text fontSemibold>Unordered (disc)</Text>
    <List listDisc>
      <ListItem>Bullet point one</ListItem>
      <ListItem>Bullet point two</ListItem>
    </List>
  </div>
  <div>
    <Text fontSemibold>circle</Text>
    <List listCircle>
      <ListItem>Hollow circle marker</ListItem>
      <ListItem>Second item</ListItem>
    </List>
  </div>
  <div>
    <Text fontSemibold>square</Text>
    <List listSquare>
      <ListItem>Filled square marker</ListItem>
      <ListItem>Second item</ListItem>
    </List>
  </div>
  <div>
    <Text fontSemibold>Ordered (decimal)</Text>
    <List listDecimal>
      <ListItem>Step one</ListItem>
      <ListItem>Step two</ListItem>
    </List>
  </div>
  <div>
    <Text fontSemibold>lowerAlpha</Text>
    <List listLowerAlpha>
      <ListItem>Lowercase letters</ListItem>
      <ListItem>Second item</ListItem>
    </List>
  </div>
  <div>
    <Text fontSemibold>lowerRoman</Text>
    <List listLowerRoman>
      <ListItem>Lowercase roman</ListItem>
      <ListItem>Second item</ListItem>
    </List>
  </div>
</Col>
```

## Marker position (inside vs outside)

Use `listOutside` (the default) to hang markers outside the content box so multi-line items align under the first character. Use `listInside` to place markers inline with text. Compact, but wrapped lines flow under the marker.

```tsx demo
<Col>
  <div>
    <Text fontSemibold>outside (default)</Text>
    <List listOutside className="w-64">
      <ListItem>A short item.</ListItem>
      <ListItem>A much longer item that wraps onto a second line so you can see the hanging marker behaviour.</ListItem>
    </List>
  </div>
  <div>
    <Text fontSemibold>inside</Text>
    <List listInside className="w-64">
      <ListItem>A short item.</ListItem>
      <ListItem>A much longer item that wraps onto a second line, markers flow inline with the text.</ListItem>
    </List>
  </div>
</Col>
```

## Nested lists: automatic marker progression

Nested unordered lists automatically progress `listDisc` → `listCircle` → `listSquare`. Nested ordered lists progress `listDecimal` → `listLowerAlpha` → `listLowerRoman`. Override a specific nested list by forcing the marker with an important utility like `list-[square]!`. The parent's descendant selector outranks a plain child utility on specificity, so the trailing `!` is what makes the override win.

```tsx demo
<Col>
  <div>
    <Text fontSemibold>Unordered (ul)</Text>
    <List>
      <ListItem>Level 0: disc</ListItem>
      <ListItem>
        Parent
        <List>
          <ListItem>Level 1: circle</ListItem>
          <ListItem>
            Parent
            <List>
              <ListItem>Level 2: square</ListItem>
            </List>
          </ListItem>
        </List>
      </ListItem>
    </List>
  </div>
  <div>
    <Text fontSemibold>Ordered (ol)</Text>
    <List listDecimal>
      <ListItem>Level 0: decimal</ListItem>
      <ListItem>
        Parent
        <List listDecimal>
          <ListItem>Level 1: lowerAlpha</ListItem>
          <ListItem>
            Parent
            <List listDecimal>
              <ListItem>Level 2: lowerRoman</ListItem>
            </List>
          </ListItem>
        </List>
      </ListItem>
    </List>
  </div>
</Col>
```

## Item spacing (gap vs noGap)

Lists apply a size-driven `gap` by default: a sibling margin between items that scales with the list's size prop. Use `noGap` to remove it entirely for a compact layout (useful for checklists or dense content).

```tsx demo
<Col>
  <div>
    <Text fontSemibold>Default gap</Text>
    <List>
      <ListItem>Item one</ListItem>
      <ListItem>Item two</ListItem>
      <ListItem>Item three</ListItem>
    </List>
  </div>
  <div>
    <Text fontSemibold>noGap</Text>
    <List noGap>
      <ListItem>Item one</ListItem>
      <ListItem>Item two</ListItem>
      <ListItem>Item three</ListItem>
    </List>
  </div>
</Col>
```

## Custom item icons

Pass an `icon` node to a `ListItem` to replace the native marker on that item only. The icon wrapper is sized to match the text font size (1em) and scales with the list size, so checkmarks, arrows, or any custom SVG align cleanly with the text. The icon sits in the marker gutter, so icon items and plain items share one text column. For decorative glyphs, include `aria-hidden="true"` on the icon node.

```tsx demo
<List>
  <ListItem icon={<span aria-hidden="true">✓</span>}>Ship the feature</ListItem>
  <ListItem icon={<span aria-hidden="true">✓</span>}>Write the tests</ListItem>
  <ListItem icon={<span aria-hidden="true">→</span>}>Update the docs</ListItem>
  <ListItem>Plain item keeps the native marker</ListItem>
</List>
```

## Overriding size and color per item

`ListItem` has no size or appearance default of its own, so both cascade from the parent `List`: `<List xl success>` propagates to every item. Set an explicit size or appearance on one item to opt out of just that row while its siblings keep the inherited values.

```tsx demo
<List xl success>
  <ListItem>Inherits xl size and success color</ListItem>
  <ListItem sm>Opts out of size: small, still inherits color</ListItem>
  <ListItem primary>Opts out of color: primary</ListItem>
</List>
```

## Styling

Combine font properties like `fontBold`, `italic`, `fontMono` with lists.

```tsx demo
<Col>
  <List fontSemibold>
    <ListItem>Bold list items</ListItem>
    <ListItem>Another bold item</ListItem>
  </List>
  <List fontMono>
    <ListItem>code --install extension</ListItem>
    <ListItem>npm run build</ListItem>
  </List>
</Col>
```

The same toggles apply per item, so one entry can stand out without affecting the rest of the list.

```tsx demo
<List>
  <ListItem fontBold>Bold item</ListItem>
  <ListItem italic>Italic item</ListItem>
  <ListItem fontMono>monospace-item</ListItem>
  <ListItem>Default item</ListItem>
</List>
```

## Truncating long items

Use `truncate` for a single clipped line, or `lineClamp2` through `lineClamp5` to cap an item at a fixed number of lines.

```tsx demo
<List className="w-72">
  <ListItem truncate>This item is clipped to one line with an ellipsis when it runs past the width.</ListItem>
  <ListItem lineClamp2>This item is clamped to two lines, so longer content wraps once and then cuts off with an ellipsis at the end of the second line.</ListItem>
  <ListItem>A short item.</ListItem>
</List>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance` (default)
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal` (default), `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Bg: `inheritBg`, `noInheritBg`
- Inherit Color: `inheritColor`, `noInheritColor`
- Inherit Size: `inheritSize`, `noInheritSize`
- List Position: `listInside`, `listOutside` (default)
- List Style: `listDisc` (default), `listDecimal`, `listCircle`, `listSquare`, `listLowerAlpha`, `listLowerRoman`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Display, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Show, Transparent, Whitespace, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

## ListItem props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Color: `inheritColor`, `noInheritColor`
- Inherit Size: `inheritSize`, `noInheritSize`
- Size: `xs`, `sm`, `md`, `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Display, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Show, Whitespace, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Blockquote

> Displays quoted content with a left border accent. Inherits appearance from the parent by default, so it blends into themed containers.

Source: https://vaneui.com/docs/typography-components/blockquote

Import: `import { Blockquote, Card, Col, Row, Text } from "@vaneui/ui"`

Blockquote is for pull quotes, testimonials and excerpts from another source. A status message that follows a user action, such as an error or a saved confirmation, belongs in an [Alert](/docs/basic-components/alert) instead, and a highlighted phrase inside a sentence in a [Mark](/docs/basic-components/mark).

## Basic usage

Blockquote displays quoted content, shown here with an attribution line. The element renders as `<blockquote>` and inherits color from its surroundings.

```tsx demo
<Blockquote>
  <Text italic>The only way to do great work is to love what you do.</Text>
  <Text sm secondary> - Steve Jobs</Text>
</Blockquote>
```

## Sizes

Blockquote supports five sizes: `xs`, `sm`, `md` (default), `lg`, `xl`.

```tsx demo
<Col>
  <Blockquote xs primary>Size xs: The best way to predict the future is to create it.</Blockquote>
  <Blockquote sm primary>Size sm: The best way to predict the future is to create it.</Blockquote>
  <Blockquote primary>Size md: The best way to predict the future is to create it.</Blockquote>
  <Blockquote lg primary>Size lg: The best way to predict the future is to create it.</Blockquote>
  <Blockquote xl primary>Size xl: The best way to predict the future is to create it.</Blockquote>
</Col>
```

## Appearances

Apply appearance props to color the blockquote. The default is `inheritAppearance`, which picks up the parent color.

```tsx demo
<Col>
  <Blockquote primary>Primary appearance blockquote.</Blockquote>
  <Blockquote accent>Accent appearance blockquote.</Blockquote>
  <Blockquote secondary>Secondary appearance blockquote.</Blockquote>
  <Blockquote success>Success appearance blockquote.</Blockquote>
  <Blockquote danger>Danger appearance blockquote.</Blockquote>
  <Blockquote warning>Warning appearance blockquote.</Blockquote>
  <Blockquote info>Info appearance blockquote.</Blockquote>
</Col>
```

## Variants

Blockquote is `outline` by default: an accent border in the appearance's colour, and no background of its own. `filled` paints no surface either. It switches the quote to the "on this fill" colour and drops the accent border, for a quote sitting on a filled surface of the same appearance.

```tsx demo
<Col>
  <Blockquote info>outline info, on the page surface</Blockquote>
  <Blockquote danger>outline danger, on the page surface</Blockquote>
  <Card info filled>
    <Blockquote info filled>filled info, on a matching filled Card</Blockquote>
  </Card>
</Col>
```

To put a surface behind a quote, nest it in a filled `Card` rather than reaching for `filled` on the Blockquote itself.

## Italic

Italic is not a default. Opt in with the `italic` prop for traditional quotation styling.

```tsx demo
<Col>
  <Blockquote primary>Upright (default), no italic styling.</Blockquote>
  <Blockquote primary italic>Italic, traditional quotation styling.</Blockquote>
</Col>
```

## Source attribution

Pass `cite` to set the native `<blockquote cite>` attribute and render a visible source line below the quote. `Blockquote` has a single visual style, the reading-direction-start accent border (the `outline` default); it does not paint a background, so wrap it in a `Card` or `Section` to place a quote on a colored surface.

```tsx demo
<Col>
  <Blockquote primary cite="Ada Lovelace">
    That brain of mine is something more than merely mortal, as time will show.
  </Blockquote>
  <Blockquote info cite="Alan Turing">
    We can only see a short distance ahead, but we can see plenty there that needs to be done.
  </Blockquote>
</Col>
```

## Inside a Card

Blockquote inherits the parent appearance, so it blends into themed containers.

```tsx demo
<Row flexWrap>
  <Card primary>
    <Blockquote>Inherits primary from the card.</Blockquote>
  </Card>
  <Card success>
    <Blockquote>Inherits success from the card.</Blockquote>
  </Card>
  <Card danger>
    <Blockquote>Inherits danger from the card.</Blockquote>
  </Card>
</Row>
```

## With rich content

Blockquotes can contain multiple paragraphs and nested components.

```tsx demo
<Blockquote primary>
  <Text fontBold>Steve Jobs</Text>
  <Text>Innovation distinguishes between a leader and a follower. Stay hungry, stay foolish.</Text>
</Blockquote>
```

## Testimonial pattern

Use blockquotes with attribution for testimonials and customer quotes.

```tsx demo
<Col>
  <Card info>
    <Blockquote>
      <Text italic>VaneUI cut our migration time in half. The boolean props API is concise and the theming covers our cases.</Text>
      <Text sm fontBold> - Sarah Chen, Lead Engineer</Text>
    </Blockquote>
  </Card>
  <Card success>
    <Blockquote>
      <Text italic>We shipped our new dashboard in half the time thanks to VaneUI components.</Text>
      <Text sm fontBold> - Alex Rivera, Product Manager</Text>
    </Blockquote>
  </Card>
</Col>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance` (default)
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Color: `inheritColor`, `noInheritColor`
- Inherit Size: `inheritSize`, `noInheritSize`
- Letter Spacing: `trackingTighter`, `trackingTight`, `trackingNormal`, `trackingWide`, `trackingWider`, `trackingWidest`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin` (default)
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart` (default), `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Cursor, Display, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Show, Whitespace, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Container

> Manages the main content area by centering it and applying a max-width. It ensures a consistent and readable layout across different screen sizes.

Source: https://vaneui.com/docs/layout-components/container

Import: `import { Container, Col, PageTitle, Section, Text, Title } from "@vaneui/ui"`

Container sets the width of a page's content column: it renders a `<div>` that fills its parent's width until it reaches the max-width set by its size. The full-width background behind it and the vertical spacing around it belong to a [Section](/docs/layout-components/section) wrapped around the Container. For a bordered box around a single piece of content, use [Card](/docs/layout-components/card).

## Basic usage

A centered, full-width wrapper that caps content at a readable max-width. `md`, `wFull`, `flex`, `column`, `itemsCenter`, `gap`, `noPadding`, `outline`, and `sharp` are defaults.

```tsx demo
<Container border>
  <Title>Page Content</Title>
  <Text>Container centers content and constrains width for optimal readability.</Text>
</Container>
```

## Sizes

Sizes (`xs`, `sm`, `md` default, `lg`, `xl`) control the max-width: `max-w-3xl` through `max-w-7xl`. Resize the viewport to see narrower containers stop growing before wider ones do.

```tsx demo
<Col>
  <Container xs border>
    <Text fontSemibold>xs: max-w-3xl</Text>
  </Container>
  <Container sm border>
    <Text fontSemibold>sm: max-w-4xl</Text>
  </Container>
  <Container border>
    <Text fontSemibold>md (default): max-w-5xl</Text>
  </Container>
  <Container lg border>
    <Text fontSemibold>lg: max-w-6xl</Text>
  </Container>
  <Container xl border>
    <Text fontSemibold>xl: max-w-7xl</Text>
  </Container>
</Col>
```

## Padding

Container defaults to `noPadding`: the parent Section usually owns vertical rhythm. Pass `padding` to opt in to size-driven internal padding.

```tsx demo
<Col>
  <Container border>
    <Text fontSemibold>noPadding (default)</Text>
    <Text>Edges sit flush with the container box.</Text>
  </Container>
  <Container padding border>
    <Text fontSemibold>padding</Text>
    <Text>Internal padding scales with the size prop.</Text>
  </Container>
</Col>
```

## Appearances

Containers support color appearances: `primary`, `secondary`, `success`, `danger`, etc.

```tsx demo
<Col>
  <Container primary border>
    <Text fontSemibold>Primary Container</Text>
    <Text>Highlighted content area</Text>
  </Container>
  <Container success border>
    <Text fontSemibold>Success Container</Text>
    <Text>Positive feedback area</Text>
  </Container>
</Col>
```

## Variants

Use `filled` for solid backgrounds. `outline` is the default. Add `shadow` for elevation.

```tsx demo
<Col>
  <Container filled primary padding>
    <Title filled primary>Filled Container</Title>
    <Text filled primary>Solid background with primary color</Text>
  </Container>
  <Container secondary border padding>
    <Title secondary>Outline Container (default)</Title>
    <Text secondary>Border only styling</Text>
  </Container>
  <Container shadow padding>
    <Title>Shadow Container</Title>
    <Text>Elevated with drop shadow</Text>
  </Container>
</Col>
```

## Shapes

Containers support different border radius styles. `sharp` is the default (no radius).

```tsx demo
<Col>
  <Container border>
    <Text fontSemibold>Sharp (default)</Text>
  </Container>
  <Container rounded border>
    <Text fontSemibold>Rounded corners</Text>
  </Container>
  <Container pill border padding>
    <Text fontSemibold>Pill shape</Text>
  </Container>
</Col>
```

## Responsive breakpoints

Container is a flex column by default. Use `row` to flow horizontally on desktop and `mobileStack` / `tabletStack` to stack on smaller screens.

```tsx demo
<Container row tabletStack border padding>
  <Col>
    <Title>Left Content</Title>
    <Text>Switches to stacked layout on tablets and below.</Text>
  </Col>
  <Col>
    <Title>Right Content</Title>
    <Text>Resize your browser to see the responsive behavior.</Text>
  </Col>
</Container>
```

## Page layout pattern

The canonical page layout: a Section owns vertical padding and full-width background, the Container nested inside caps reading width and centers the content.

```tsx demo
<Section secondary>
  <Container>
    <PageTitle>Getting Started</PageTitle>
    <Text>The Section handles the full-bleed background and outer padding. The Container constrains the inner content to a comfortable reading width.</Text>
  </Container>
</Section>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Breakpoint: `desktopStack`, `tabletStack`, `mobileStack`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Padding: `padding`, `paddingX`, `paddingY`, `noPadding` (default)
- Shape: `pill`, `sharp` (default), `rounded`
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Strong Border: `strongBorder`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Display, Flex Direction, Gap, Height, Hide, Items, Justify, Overflow, Pointer Events, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Section

> Groups related content and owns the outer padding and background of a page band. Renders as a plain wrapper by default; pass tag="section" for a landmark.

Source: https://vaneui.com/docs/layout-components/section

Import: `import { Section, Col, Container, PageTitle, Text, Title } from "@vaneui/ui"`

Use one Section for each band of a page, such as a hero, a feature list or a footer. A [Container](/docs/layout-components/container) nested inside a Section keeps its content at a readable width. For a bordered panel that sits within the content instead of spanning the page, use [Card](/docs/layout-components/card).

## Basic usage

`md`, `wFull`, `flex`, `column`, `itemsStart`, `gap`, `padding`, `outline`, `sharp`, and `responsiveSizing` are defaults. Padding and gap automatically scale at tablet and mobile breakpoints because `responsiveSizing` is on.

```tsx demo
<Section border>
  <Title>Welcome Section</Title>
  <Text>Sections provide consistent vertical rhythm and full-width backgrounds.</Text>
</Section>
```

## Sizes

Sizes (`xs`, `sm`, `md` default, `lg`, `xl`) control padding and gap.

```tsx demo
<Col>
  <Section xs border>
    <Text fontSemibold>Extra Small Section</Text>
    <Text>Tightest padding</Text>
  </Section>
  <Section sm border>
    <Text fontSemibold>Small Section</Text>
    <Text>Compact padding</Text>
  </Section>
  <Section border>
    <Text fontSemibold>Medium Section (default)</Text>
    <Text>Standard padding</Text>
  </Section>
  <Section lg border>
    <Text fontSemibold>Large Section</Text>
    <Text>Generous padding</Text>
  </Section>
  <Section xl border>
    <Text fontSemibold>Extra Large Section</Text>
    <Text>Widest padding</Text>
  </Section>
</Col>
```

## Appearances

Sections support color appearances: `primary`, `secondary`, `success`, `danger`, etc. Use `secondary` filled bands to create visual rhythm between regular sections.

```tsx demo
<Col>
  <Section secondary filled>
    <Text fontSemibold>Secondary band</Text>
    <Text>Subtle background to break up a long page.</Text>
  </Section>
  <Section primary>
    <Text fontSemibold>Primary Section</Text>
    <Text>Highlighted content area</Text>
  </Section>
  <Section success>
    <Text fontSemibold>Success Section</Text>
    <Text>Positive feedback area</Text>
  </Section>
  <Section danger>
    <Text fontSemibold>Danger Section</Text>
    <Text>Warning or error area</Text>
  </Section>
</Col>
```

## Variants

Use `filled` for solid backgrounds (`outline` is the default), and `shadow` for elevation.

```tsx demo
<Col>
  <Section filled primary>
    <Title filled primary>Filled Section</Title>
    <Text filled primary>Solid background with primary color</Text>
  </Section>
  <Section secondary border>
    <Title secondary>Outline Section (default)</Title>
    <Text secondary>Border-only styling</Text>
  </Section>
  <Section shadow>
    <Title>Shadow Section</Title>
    <Text>Elevated with drop shadow</Text>
  </Section>
</Col>
```

## Shapes

Section is `sharp` by default, since a full-bleed band should meet the viewport edge without a radius. `rounded` suits a section used as an inset panel.

```tsx demo
<Col>
  <Section border>Sharp, the default</Section>
  <Section rounded border>Rounded</Section>
  <Section pill border>Pill</Section>
</Col>
```

## Layout

Use `row` for horizontal layout. `gap` is already on by default; pair with `noPadding` only when a wrapper owns spacing.

```tsx demo
<Col>
  <Section row border>
    <Text fontSemibold>Row Layout</Text>
    <Text>Content flows horizontally</Text>
    <Text>With gap between items</Text>
  </Section>
  <Section border>
    <Text fontSemibold>Column Layout (default)</Text>
    <Text>Content flows vertically</Text>
    <Text>With gap between items</Text>
  </Section>
</Col>
```

## Responsive breakpoints

Use `mobileStack` or `tabletStack` to switch from row to column layout on smaller screens.

```tsx demo
<Section row tabletStack border>
  <Col>
    <Title>Left Content</Title>
    <Text>Switches to stacked layout on tablets and below.</Text>
  </Col>
  <Col>
    <Title>Right Content</Title>
    <Text>Resize your browser to see the responsive behavior.</Text>
  </Col>
</Section>
```

## Responsive sizing

`responsiveSizing` (default) scales padding and gap at tablet and mobile breakpoints using `--py-tablet`, `--gap-mobile`, etc. Pass `responsiveSizing={false}` to lock a single size across all viewports.

```tsx demo
<Col>
  <Section lg border>
    <Text fontSemibold>responsiveSizing (default)</Text>
    <Text>Padding shrinks at tablet and mobile.</Text>
  </Section>
  <Section lg responsiveSizing={false} border>
    <Text fontSemibold>responsiveSizing=&#123;false&#125;</Text>
    <Text>Padding stays fixed at the lg size on every viewport.</Text>
  </Section>
</Col>
```

## Semantic tag

Section renders as `<div>` by default. Pass `tag="section"` for a semantic `<section>` element, or `tag="header"` / `tag="footer"` / `tag="aside"` for other landmarks.

```tsx demo
<Col>
  <Section tag="section" border>
    <Title>Semantic section</Title>
    <Text>Renders as &lt;section&gt; in the DOM.</Text>
  </Section>
  <Section tag="header" secondary filled>
    <Title>Page header</Title>
    <Text>Renders as &lt;header&gt;.</Text>
  </Section>
</Col>
```

## Page layout pattern

The canonical full-bleed page band: a Section owns the outer padding and background, with a nested `Container` capping the inner reading width.

```tsx demo
<Section secondary filled>
  <Container>
    <PageTitle>Getting Started</PageTitle>
    <Text>The Section handles the full-bleed background and outer padding. The Container constrains the inner content to a comfortable reading width.</Text>
  </Container>
</Section>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Breakpoint: `desktopStack`, `tabletStack`, `mobileStack`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Shape: `pill`, `sharp` (default), `rounded`
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Strong Border: `strongBorder`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Display, Flex Direction, Gap, Height, Hide, Items, Justify, Overflow, Pointer Events, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Row

> A fundamental layout component that arranges its children in a horizontal line. It is built on the flexbox model and is used to create columns.

Source: https://vaneui.com/docs/layout-components/row

Import: `import { Row, Badge, Button, Card, Col, Text, Title } from "@vaneui/ui"`

Row suits content that sits side by side at its natural width: a toolbar, a set of tags, an icon beside its label. When the children should share equal column widths instead, a [Grid](/docs/layout-components/grid) component such as Grid3 sizes them. For a vertical group, use [Col](/docs/layout-components/col), or [Stack](/docs/layout-components/stack) when the group also needs its own padding.

## Basic usage

A horizontal flex container. `Row` defaults to `gap`, `itemsCenter`, `noPadding`, `noBorder`, `noInsetRing`, `outline`, and `sharp`: you don't need to pass these explicitly. Pass `href` to render `Row` as `<a>` instead of `<div>`. A focus-visible outline auto-enables when `href` is set.

```tsx demo
<Row>
  <div className="p-4 bg-gray-100 rounded">Item 1</div>
  <div className="p-4 bg-gray-100 rounded">Item 2</div>
  <div className="p-4 bg-gray-100 rounded">Item 3</div>
</Row>
```

## Spacing

Use size props (`xs`, `sm`, `md`, `lg`, `xl`) to control the gap amount, or `noGap` to disable.

```tsx demo
<Col>
  <Text fontSemibold>xs</Text>
  <Row xs>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
  </Row>
  <Text fontSemibold>sm</Text>
  <Row sm>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
  </Row>
  <Text fontSemibold>md (default)</Text>
  <Row>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
  </Row>
  <Text fontSemibold>lg</Text>
  <Row lg>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
  </Row>
  <Text fontSemibold>xl</Text>
  <Row xl>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
  </Row>
  <Text fontSemibold>noGap</Text>
  <Row noGap>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
  </Row>
</Col>
```

## Justify (main axis)

Control horizontal distribution with `justifyStart`, `justifyEnd`, `justifyCenter`, `justifyBetween`, `justifyAround`, or `justifyEvenly`.

```tsx demo
<Col>
  <Text fontSemibold>justifyStart</Text>
  <Row justifyStart className="border-2 border-dashed border-gray-300 p-2">
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
    <div className="p-2 bg-gray-100 rounded">C</div>
  </Row>
  <Text fontSemibold>justifyEnd</Text>
  <Row justifyEnd className="border-2 border-dashed border-gray-300 p-2">
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
    <div className="p-2 bg-gray-100 rounded">C</div>
  </Row>
  <Text fontSemibold>justifyCenter</Text>
  <Row justifyCenter className="border-2 border-dashed border-gray-300 p-2">
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
    <div className="p-2 bg-gray-100 rounded">C</div>
  </Row>
  <Text fontSemibold>justifyBetween</Text>
  <Row justifyBetween className="border-2 border-dashed border-gray-300 p-2">
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
    <div className="p-2 bg-gray-100 rounded">C</div>
  </Row>
  <Text fontSemibold>justifyAround</Text>
  <Row justifyAround className="border-2 border-dashed border-gray-300 p-2">
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
    <div className="p-2 bg-gray-100 rounded">C</div>
  </Row>
  <Text fontSemibold>justifyEvenly</Text>
  <Row justifyEvenly className="border-2 border-dashed border-gray-300 p-2">
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
    <div className="p-2 bg-gray-100 rounded">C</div>
  </Row>
</Col>
```

## Items (cross axis)

Control vertical alignment with `itemsStart`, `itemsEnd`, `itemsCenter` (default), `itemsBaseline`, or `itemsStretch`.

```tsx demo
<Col>
  <Text fontSemibold>itemsStart</Text>
  <Row itemsStart className="border-2 border-dashed border-gray-300 p-2 h-24">
    <div className="p-2 bg-gray-100 rounded">Small</div>
    <div className="p-6 bg-gray-100 rounded">Tall</div>
    <div className="p-2 bg-gray-100 rounded">Small</div>
  </Row>
  <Text fontSemibold>itemsEnd</Text>
  <Row itemsEnd className="border-2 border-dashed border-gray-300 p-2 h-24">
    <div className="p-2 bg-gray-100 rounded">Small</div>
    <div className="p-6 bg-gray-100 rounded">Tall</div>
    <div className="p-2 bg-gray-100 rounded">Small</div>
  </Row>
  <Text fontSemibold>itemsCenter (default)</Text>
  <Row className="border-2 border-dashed border-gray-300 p-2 h-24">
    <div className="p-2 bg-gray-100 rounded">Small</div>
    <div className="p-6 bg-gray-100 rounded">Tall</div>
    <div className="p-2 bg-gray-100 rounded">Small</div>
  </Row>
  <Text fontSemibold>itemsBaseline</Text>
  <Row itemsBaseline className="border-2 border-dashed border-gray-300 p-2 h-24">
    <Text sm>Small text</Text>
    <Text xl>Large text</Text>
    <Text>Default</Text>
  </Row>
  <Text fontSemibold>itemsStretch</Text>
  <Row itemsStretch className="border-2 border-dashed border-gray-300 p-2 h-24">
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
    <div className="p-2 bg-gray-100 rounded">C</div>
  </Row>
</Col>
```

## Wrap

Use `flexWrap` to allow items to wrap to the next line when they overflow.

```tsx demo
<Row flexWrap className="max-w-md border-2 border-dashed border-gray-300 p-2">
  <div className="p-4 bg-gray-100 rounded">Item 1</div>
  <div className="p-4 bg-gray-100 rounded">Item 2</div>
  <div className="p-4 bg-gray-100 rounded">Item 3</div>
  <div className="p-4 bg-gray-100 rounded">Item 4</div>
  <div className="p-4 bg-gray-100 rounded">Item 5</div>
</Row>
```

## Reverse order

Use `rowReverse` to reverse the visual order of children.

```tsx demo
<Row rowReverse className="border-2 border-dashed border-gray-300 p-2">
  <div className="p-4 bg-gray-100 rounded">First in DOM</div>
  <div className="p-4 bg-gray-100 rounded">Second</div>
  <div className="p-4 bg-gray-100 rounded">Last in DOM</div>
</Row>
```

## Responsive layout

Use `mobileStack` to stack on mobile, or `tabletStack` to stack on tablet and below.

```tsx demo
<Col>
  <Text fontSemibold>tabletStack (stacks below 1024px)</Text>
  <Row tabletStack>
    <Col flex1 className="p-4 bg-primary-100 rounded">
      <Text fontSemibold>Column 1</Text>
      <Text>Horizontal on desktop, stacked on tablet and below.</Text>
    </Col>
    <Col flex1 className="p-4 bg-primary-100 rounded">
      <Text fontSemibold>Column 2</Text>
      <Text>Resize to see the responsive behavior.</Text>
    </Col>
  </Row>
  <Text fontSemibold>mobileStack (stacks below 768px)</Text>
  <Row mobileStack>
    <Col flex1 className="p-4 bg-primary-100 rounded">
      <Text fontSemibold>Column 1</Text>
      <Text>Horizontal until mobile.</Text>
    </Col>
    <Col flex1 className="p-4 bg-primary-100 rounded">
      <Text fontSemibold>Column 2</Text>
      <Text>Stacks only on narrow viewports.</Text>
    </Col>
  </Row>
</Col>
```

Breakpoints are desktop-first and exclusive: `mobileStack` collapses to a column below 768px, `tabletStack` below 1024px, `desktopStack` below 1280px. The boundary pixel itself stays in the row layout. Combining several stack props resolves to the widest, so `mobileStack tabletStack` stacks below 1024px. `*Stack` only affects row-direction components: it emits `flex-col`, so it is a no-op on `Col`, `Stack`, `Container`, and `Section`, which are already columns.

A stacked `Row` keeps its default `itemsCenter`, so stacked children shrink to content width. Add `itemsStretch` for full-width stacked cards.

## Variants

Use `filled` or `outline` with appearance props for styled rows. Row uses `sharp` (no border-radius) by default: pair with `rounded` or `pill` for curved corners.

```tsx demo
<Col>
  <Row filled primary padding rounded>
    <div className="p-4 bg-white/80 rounded">Filled Primary</div>
    <div className="p-4 bg-white/80 rounded">Item 2</div>
  </Row>
  <Row border success padding rounded>
    <div className="p-4 rounded">Outline Success</div>
    <div className="p-4 rounded">Item 2</div>
  </Row>
</Col>
```

## Text alignment

Use `textCenter`, `textLeft`, `textRight`, or `textJustify` to control text alignment within the row.

```tsx demo
<Col>
  <Row textLeft className="border-2 border-dashed border-gray-300 p-4">
    <Text>Left aligned content in a row.</Text>
  </Row>
  <Row textCenter className="border-2 border-dashed border-gray-300 p-4">
    <Text>Center aligned content in a row.</Text>
  </Row>
  <Row textRight className="border-2 border-dashed border-gray-300 p-4">
    <Text>Right aligned content in a row.</Text>
  </Row>
</Col>
```

## Inside a Card

Row composes naturally inside a Card to lay out header actions, button groups, or any horizontal cluster.

```tsx demo
<Card>
  <Row justifyBetween>
    <Title>Settings</Title>
    <Badge success>Active</Badge>
  </Row>
  <Text>Configure your preferences below.</Text>
  <Row justifyEnd>
    <Button secondary>Cancel</Button>
    <Button filled>Save</Button>
  </Row>
</Card>
```

## As Link

Add `href` to render the Row as an `<a>` tag, useful for clickable list rows. A keyboard focus-visible outline auto-renders so the link is reachable via Tab; opt out with `noFocusVisible`.

```tsx demo
<Col>
  <Row href="#as-link" justifyBetween padding border rounded>
    <Text fontSemibold>Inbox</Text>
    <Badge primary filled>12</Badge>
  </Row>
  <Row href="#as-link" justifyBetween padding border rounded>
    <Text fontSemibold>Drafts</Text>
    <Badge secondary>3</Badge>
  </Row>
  <Row href="https://github.com" target="_blank" rel="noopener noreferrer" justifyBetween padding border rounded>
    <Text fontSemibold>GitHub</Text>
    <Text sm secondary>External</Text>
  </Row>
</Col>
```

## Next.js Link integration

Use the `tag` prop to render the Row as a Next.js `Link` for client-side navigation.

```tsx
import Link from 'next/link';
import { Row, Text, Badge } from '@vaneui/ui';

<Row href="/inbox" tag={Link} justifyBetween padding border rounded>
  <Text fontSemibold>Inbox</Text>
  <Badge primary filled>12</Badge>
</Row>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Breakpoint: `desktopStack`, `tabletStack`, `mobileStack`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Padding: `padding`, `paddingX`, `paddingY`, `noPadding` (default)
- Shape: `pill`, `sharp` (default), `rounded`
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Strong Border: `strongBorder`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Pointer Events, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Col

> React Col component for Tailwind CSS v4: a vertical flex column with a gap and no padding, for content inside a Row, Card or Section. See when to use Stack.

Source: https://vaneui.com/docs/layout-components/col

Import: `import { Col, Badge, Button, Card, NavLink, Row, Text, Title } from "@vaneui/ui"`

Col stacks content inside a surface that already supplies spacing, such as a Card or a Section, and forms the columns of a [Row](/docs/layout-components/row). It is a vertical flex column with a gap between its children and no padding or border. When the column needs padding of its own, use [Stack](/docs/layout-components/stack). For cells that should all share one column width, a [Grid](/docs/layout-components/grid) component such as Grid3 lays them out without a Col around each one.

## Basic usage

`Col` defaults to `column`, `flex`, `gap`, `md`, `noPadding`, `noBorder`, `noInsetRing`, `outline`, and `sharp`: you don't need to pass any of these. Pass `href` to render `Col` as `<a>` instead of `<div>`. A focus-visible outline auto-enables when `href` is set.

```tsx demo
<Col>
  <div className="p-4 bg-gray-100 rounded">Item 1</div>
  <div className="p-4 bg-gray-100 rounded">Item 2</div>
  <div className="p-4 bg-gray-100 rounded">Item 3</div>
</Col>
```

## Spacing

Use size props (`xs`, `sm`, `md`, `lg`, `xl`) to control the gap, or `noGap` to disable.

```tsx demo
<Row itemsStart>
  <Col xs flex1>
    <Text fontSemibold>xs</Text>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
  </Col>
  <Col sm flex1>
    <Text fontSemibold>sm</Text>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
  </Col>
  <Col flex1>
    <Text fontSemibold>md (default)</Text>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
  </Col>
  <Col lg flex1>
    <Text fontSemibold>lg</Text>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
  </Col>
  <Col xl flex1>
    <Text fontSemibold>xl</Text>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
  </Col>
  <Col noGap flex1>
    <Text fontSemibold>noGap</Text>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
  </Col>
</Row>
```

## Items (cross axis)

Col has no `items` default, so children stretch to fill the width. Use `itemsStart`, `itemsCenter`, `itemsEnd`, `itemsBaseline`, or `itemsStretch` to override.

```tsx demo
<Row itemsStart>
  <Col flex1 className="border-2 border-dashed border-gray-300 p-2">
    <Text fontSemibold>default (stretch)</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Col>
  <Col itemsStart flex1 className="border-2 border-dashed border-gray-300 p-2">
    <Text fontSemibold>itemsStart</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Col>
  <Col itemsCenter flex1 className="border-2 border-dashed border-gray-300 p-2">
    <Text fontSemibold>itemsCenter</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Col>
  <Col itemsEnd flex1 className="border-2 border-dashed border-gray-300 p-2">
    <Text fontSemibold>itemsEnd</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Col>
</Row>
```

## Justify (main axis)

Control vertical distribution with `justifyStart`, `justifyEnd`, `justifyCenter`, `justifyBetween`, `justifyAround`, or `justifyEvenly`. The Col needs a fixed height for these to have any effect.

```tsx demo
<Row itemsStart>
  <Col justifyStart flex1 className="h-48 border-2 border-dashed border-gray-300 p-2">
    <Text fontSemibold>justifyStart</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Col>
  <Col justifyCenter flex1 className="h-48 border-2 border-dashed border-gray-300 p-2">
    <Text fontSemibold>justifyCenter</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Col>
  <Col justifyEnd flex1 className="h-48 border-2 border-dashed border-gray-300 p-2">
    <Text fontSemibold>justifyEnd</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Col>
  <Col justifyBetween flex1 className="h-48 border-2 border-dashed border-gray-300 p-2">
    <Text fontSemibold>justifyBetween</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Col>
  <Col justifyAround flex1 className="h-48 border-2 border-dashed border-gray-300 p-2">
    <Text fontSemibold>justifyAround</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Col>
  <Col justifyEvenly flex1 className="h-48 border-2 border-dashed border-gray-300 p-2">
    <Text fontSemibold>justifyEvenly</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Col>
</Row>
```

## Reverse order

Use `columnReverse` to reverse the visual order of children.

```tsx demo
<Col columnReverse className="border-2 border-dashed border-gray-300 p-2">
  <div className="p-3 bg-gray-100 rounded">First in DOM</div>
  <div className="p-3 bg-gray-100 rounded">Second</div>
  <div className="p-3 bg-gray-100 rounded">Last in DOM</div>
</Col>
```

## Variants

Use `filled` with an appearance prop for a filled background. Col defaults to `sharp`: pair with `rounded` or `pill` for curved corners, and add `padding` so the background has breathing room.

```tsx demo
<Row itemsStart>
  <Col filled primary padding rounded flex1>
    <div className="p-4 bg-white/80 rounded">Filled Primary</div>
    <div className="p-4 bg-white/80 rounded">Item 2</div>
  </Col>
  <Col border success padding rounded flex1>
    <div className="p-4 rounded">Outline Success</div>
    <div className="p-4 rounded">Item 2</div>
  </Col>
</Row>
```

## Text alignment

Use `textLeft`, `textCenter`, `textRight`, or `textJustify` to control text alignment within the column.

```tsx demo
<Row itemsStart>
  <Col textLeft flex1 className="border-2 border-dashed border-gray-300 p-4">
    <Text fontSemibold>Left Aligned</Text>
    <Text>Content aligned to the left.</Text>
  </Col>
  <Col textCenter flex1 className="border-2 border-dashed border-gray-300 p-4">
    <Text fontSemibold>Center Aligned</Text>
    <Text>Content centered within the column.</Text>
  </Col>
  <Col textRight flex1 className="border-2 border-dashed border-gray-300 p-4">
    <Text fontSemibold>Right Aligned</Text>
    <Text>Content aligned to the right.</Text>
  </Col>
</Row>
```

## Nested in Row

Col is commonly used inside Row to create multi-column layouts. Use `flex1` so each column shares the available width equally.

```tsx demo
<Row itemsStart>
  <Col flex1>
    <Card>
      <Title>Column 1</Title>
      <Text sm secondary>First column content.</Text>
    </Card>
  </Col>
  <Col flex1>
    <Card>
      <Title>Column 2</Title>
      <Text sm secondary>Second column content.</Text>
    </Card>
  </Col>
  <Col flex1>
    <Card>
      <Title>Column 3</Title>
      <Text sm secondary>Third column content.</Text>
    </Card>
  </Col>
</Row>
```

## Inside a Card

Col composes naturally inside a Card to lay out a vertical cluster: labelled fields, key/value pairs, or a list of actions.

```tsx demo
<Card>
  <Title>Account</Title>
  <Col>
    <Row justifyBetween>
      <Text secondary>Plan</Text>
      <Badge success>Pro</Badge>
    </Row>
    <Row justifyBetween>
      <Text secondary>Seats</Text>
      <Text fontSemibold>12 / 25</Text>
    </Row>
    <Row justifyBetween>
      <Text secondary>Renews</Text>
      <Text fontSemibold>Jan 14, 2026</Text>
    </Row>
  </Col>
  <Row justifyEnd>
    <Button secondary>Manage</Button>
    <Button filled>Upgrade</Button>
  </Row>
</Card>
```

## As a navigation column

Col is a natural container for a vertical stack of `NavLink`s in a sidebar.

```tsx demo
<Col className="w-56 border-2 border-dashed border-gray-300 p-3">
  <NavLink href="#" active>Dashboard</NavLink>
  <NavLink href="#">Projects</NavLink>
  <NavLink href="#">Team</NavLink>
  <NavLink href="#">Billing</NavLink>
  <NavLink href="#">Settings</NavLink>
</Col>
```

## As Link

Add `href` to render the Col as an `<a>` tag, useful for clickable feature tiles. A keyboard focus-visible outline auto-renders so the link is reachable via Tab; opt out with `noFocusVisible`.

```tsx demo
<Row itemsStart>
  <Col href="/docs" flex1 padding border rounded>
    <BookOpen size={20} />
    <Title>Documentation</Title>
    <Text secondary>Browse guides and API reference.</Text>
  </Col>
  <Col href="#as-link" flex1 padding border rounded>
    <Codepen size={20} />
    <Title>Examples</Title>
    <Text secondary>Copy-ready component patterns.</Text>
  </Col>
  <Col href="https://github.com" target="_blank" rel="noopener noreferrer" flex1 padding border rounded>
    <GitHub size={20} />
    <Title>Source</Title>
    <Text secondary>View the project on GitHub.</Text>
  </Col>
</Row>
```

## Next.js Link integration

Use the `tag` prop to render the Col as a Next.js `Link` for client-side navigation.

```tsx
import Link from 'next/link';
import { Col, Title, Text } from '@vaneui/ui';

<Col href="/docs" tag={Link} padding border rounded>
  <Title>Documentation</Title>
  <Text secondary>Browse guides and API reference.</Text>
</Col>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Breakpoint: `desktopStack`, `tabletStack`, `mobileStack`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Padding: `padding`, `paddingX`, `paddingY`, `noPadding` (default)
- Shape: `pill`, `sharp` (default), `rounded`
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Strong Border: `strongBorder`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Pointer Events, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Stack

> React Stack component for Tailwind CSS v4: a padded, wrapping column or row with even gaps, set by boolean props. See when to use Col, Row or Card instead.

Source: https://vaneui.com/docs/layout-components/stack

Import: `import { Stack, Button, Card, Checkbox, Col, Input, Label, PageTitle, Row, Text, Title } from "@vaneui/ui"`

Stack holds a group of items and keeps them clear of its own edges: unlike [Col](/docs/layout-components/col), it comes with `padding` and `flexWrap`. It has no border and square corners, so when the group needs a visible border and rounded corners, use [Card](/docs/layout-components/card), which has both by default. For a single line of items that should not wrap, use [Row](/docs/layout-components/row).

## Basic usage

`Stack` defaults to `column`, `flex`, `gap`, `padding`, `flexWrap`, `md`, `noBorder`, `noInsetRing`, `outline`, and `sharp`: you don't need to pass any of these. Pass `href` to render `Stack` as `<a>` instead of `<div>`. A focus-visible outline auto-enables when `href` is set.

```tsx demo
<Stack>
  <div className="p-4 bg-gray-100 rounded">Item 1</div>
  <div className="p-4 bg-gray-100 rounded">Item 2</div>
  <div className="p-4 bg-gray-100 rounded">Item 3</div>
</Stack>
```

## Stack vs Col

`Stack` and `Col` are both vertical flex columns. The difference is opinion:

- **`Stack`** = `padding: true` + `flexWrap: true`: a padded, wrap-friendly container.
- **`Col`** = `noPadding`: a bare structural column you compose inside other surfaces.

Use `Stack` when the column owns its own breathing room. Use `Col` when an outer `Card` / `Section` / `Container` already supplies the padding.

```tsx demo
<Row itemsStart>
  <Col flex1>
    <Text fontSemibold>Stack (padded by default)</Text>
    <Stack className="border-2 border-dashed border-gray-300">
      <div className="p-3 bg-gray-100 rounded">Item 1</div>
      <div className="p-3 bg-gray-100 rounded">Item 2</div>
    </Stack>
  </Col>
  <Col flex1>
    <Text fontSemibold>Col (no padding)</Text>
    <Col className="border-2 border-dashed border-gray-300">
      <div className="p-3 bg-gray-100 rounded">Item 1</div>
      <div className="p-3 bg-gray-100 rounded">Item 2</div>
    </Col>
  </Col>
</Row>
```

## Direction

Use `row` for horizontal layout. Default is `column` (vertical).

```tsx demo
<Row itemsStart>
  <Col flex1>
    <Text fontSemibold>column (default)</Text>
    <Stack className="border-2 border-dashed border-gray-300">
      <div className="p-3 bg-gray-100 rounded">Item 1</div>
      <div className="p-3 bg-gray-100 rounded">Item 2</div>
    </Stack>
  </Col>
  <Col flex1>
    <Text fontSemibold>row</Text>
    <Stack row className="border-2 border-dashed border-gray-300">
      <div className="p-3 bg-gray-100 rounded">Item 1</div>
      <div className="p-3 bg-gray-100 rounded">Item 2</div>
    </Stack>
  </Col>
</Row>
```

## Spacing

Use size props (`xs`, `sm`, `md`, `lg`, `xl`) to scale gap and padding together, or `noGap` to remove the gap.

```tsx demo
<Row itemsStart>
  <Stack xs flex1 className="border-2 border-dashed border-gray-300">
    <Text fontSemibold>xs</Text>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
  </Stack>
  <Stack sm flex1 className="border-2 border-dashed border-gray-300">
    <Text fontSemibold>sm</Text>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
  </Stack>
  <Stack flex1 className="border-2 border-dashed border-gray-300">
    <Text fontSemibold>md (default)</Text>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
  </Stack>
  <Stack lg flex1 className="border-2 border-dashed border-gray-300">
    <Text fontSemibold>lg</Text>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
  </Stack>
  <Stack xl flex1 className="border-2 border-dashed border-gray-300">
    <Text fontSemibold>xl</Text>
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
  </Stack>
</Row>
```

## Padding sizes

`padding` is on by default. The padding value scales with the size prop. Use `noPadding` to remove it entirely.

```tsx demo
<Row itemsStart>
  <Stack xs filled secondary flex1>
    <Text fontSemibold>xs padding</Text>
    <Card xs>Item</Card>
  </Stack>
  <Stack sm filled secondary flex1>
    <Text fontSemibold>sm padding</Text>
    <Card xs>Item</Card>
  </Stack>
  <Stack filled secondary flex1>
    <Text fontSemibold>md padding (default)</Text>
    <Card xs>Item</Card>
  </Stack>
  <Stack lg filled secondary flex1>
    <Text fontSemibold>lg padding</Text>
    <Card xs>Item</Card>
  </Stack>
  <Stack xl filled secondary flex1>
    <Text fontSemibold>xl padding</Text>
    <Card xs>Item</Card>
  </Stack>
  <Stack noPadding filled secondary flex1>
    <Text fontSemibold>noPadding</Text>
    <Card xs>Item</Card>
  </Stack>
</Row>
```

## Items (cross axis)

Stack has no `items` default, so children stretch to fill the width. Override with `itemsStart`, `itemsCenter`, `itemsEnd`, `itemsBaseline`, or `itemsStretch`.

```tsx demo
<Row itemsStart>
  <Stack flex1 className="border-2 border-dashed border-gray-300">
    <Text fontSemibold>default (stretch)</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Stack>
  <Stack itemsStart flex1 className="border-2 border-dashed border-gray-300">
    <Text fontSemibold>itemsStart</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Stack>
  <Stack itemsCenter flex1 className="border-2 border-dashed border-gray-300">
    <Text fontSemibold>itemsCenter</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Stack>
  <Stack itemsEnd flex1 className="border-2 border-dashed border-gray-300">
    <Text fontSemibold>itemsEnd</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Stack>
</Row>
```

## Justify (main axis)

Control vertical distribution with `justifyStart`, `justifyEnd`, `justifyCenter`, `justifyBetween`, `justifyAround`, or `justifyEvenly`. The Stack needs a fixed height for these to have any effect.

```tsx demo
<Row itemsStart>
  <Stack justifyStart flex1 className="h-48 border-2 border-dashed border-gray-300">
    <Text fontSemibold>justifyStart</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Stack>
  <Stack justifyCenter flex1 className="h-48 border-2 border-dashed border-gray-300">
    <Text fontSemibold>justifyCenter</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Stack>
  <Stack justifyEnd flex1 className="h-48 border-2 border-dashed border-gray-300">
    <Text fontSemibold>justifyEnd</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Stack>
  <Stack justifyBetween flex1 className="h-48 border-2 border-dashed border-gray-300">
    <Text fontSemibold>justifyBetween</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Stack>
  <Stack justifyAround flex1 className="h-48 border-2 border-dashed border-gray-300">
    <Text fontSemibold>justifyAround</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Stack>
  <Stack justifyEvenly flex1 className="h-48 border-2 border-dashed border-gray-300">
    <Text fontSemibold>justifyEvenly</Text>
    <div className="p-2 bg-gray-100 rounded">A</div>
    <div className="p-2 bg-gray-100 rounded">B</div>
  </Stack>
</Row>
```

## Wrap behavior

`flexWrap` is on by default. In a horizontal Stack, items wrap to the next line when they would overflow the container. Use `flexNoWrap` to force everything onto a single line.

```tsx demo
<Col>
  <Text fontSemibold>flexWrap (default): items wrap when they overflow</Text>
  <Stack row className="max-w-md border-2 border-dashed border-gray-300">
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
    <div className="p-3 bg-gray-100 rounded">Item 4</div>
    <div className="p-3 bg-gray-100 rounded">Item 5</div>
  </Stack>
  <Text fontSemibold>flexNoWrap: items shrink to fit</Text>
  <Stack row flexNoWrap className="max-w-md border-2 border-dashed border-gray-300">
    <div className="p-3 bg-gray-100 rounded">Item 1</div>
    <div className="p-3 bg-gray-100 rounded">Item 2</div>
    <div className="p-3 bg-gray-100 rounded">Item 3</div>
    <div className="p-3 bg-gray-100 rounded">Item 4</div>
    <div className="p-3 bg-gray-100 rounded">Item 5</div>
  </Stack>
</Col>
```

## Variants

Use `filled` or `outline` with appearance props for styled containers. Stack defaults to `sharp`: pair with `rounded` or `pill` for curved corners.

```tsx demo
<Row itemsStart>
  <Stack filled primary rounded flex1>
    <Card sm>Filled Primary</Card>
    <Card sm>Item 2</Card>
  </Stack>
  <Stack border success rounded flex1>
    <Card sm success>Outline Success</Card>
    <Card sm success>Item 2</Card>
  </Stack>
</Row>
```

## Text alignment

Use `textLeft`, `textCenter`, `textRight`, or `textJustify` to control text alignment within the stack.

```tsx demo
<Row itemsStart>
  <Stack textLeft flex1 className="border-2 border-dashed border-gray-300">
    <Text fontSemibold>Left Aligned</Text>
    <Text>Content aligned to the left.</Text>
  </Stack>
  <Stack textCenter flex1 className="border-2 border-dashed border-gray-300">
    <Text fontSemibold>Center Aligned</Text>
    <Text>Content centered within the stack.</Text>
  </Stack>
  <Stack textRight flex1 className="border-2 border-dashed border-gray-300">
    <Text fontSemibold>Right Aligned</Text>
    <Text>Content aligned to the right.</Text>
  </Stack>
</Row>
```

## Responsive layout

Use `mobileStack` or `tabletStack` on a horizontal Stack to switch back to a column on narrower viewports.

```tsx demo
<Stack row tabletStack>
  <Col flex1 className="p-4 bg-primary-100 rounded">
    <Text fontSemibold>Column 1</Text>
    <Text>Horizontal on desktop, stacked on tablet and below.</Text>
  </Col>
  <Col flex1 className="p-4 bg-primary-100 rounded">
    <Text fontSemibold>Column 2</Text>
    <Text>Resize to see the responsive behavior.</Text>
  </Col>
</Stack>
```

## As a form container

Stack's built-in padding makes it a natural container for a form: each `Label` stacks its text above its input, and the Stack provides the vertical rhythm and outer breathing room without any extra wrapper.

```tsx demo
<Stack border rounded className="max-w-sm">
  <Title>Sign in</Title>
  <Label>
    Email
    <Input type="email" placeholder="you@example.com" />
  </Label>
  <Label>
    Password
    <Input type="password" placeholder="********" />
  </Label>
  <Label row itemsCenter>
    <Checkbox />
    Remember me
  </Label>
  <Button filled>Sign in</Button>
</Stack>
```

## As Link

Add `href` to render the Stack as an `<a>` tag, useful for hero cards and large clickable surfaces. A keyboard focus-visible outline auto-renders so the link is reachable via Tab; opt out with `noFocusVisible`.

```tsx demo
<Stack href="/docs/getting-started/installation" border rounded itemsStart className="max-w-md">
  <Zap size={28} />
  <PageTitle>Get started in minutes</PageTitle>
  <Text>Install the package, drop in ThemeProvider, and start shipping.</Text>
  <Button filled>Read the guide</Button>
</Stack>
```

## Next.js Link integration

Use the `tag` prop to render the Stack as a Next.js `Link` for client-side navigation.

```tsx
import Link from 'next/link';
import { Stack, PageTitle, Text, Button } from '@vaneui/ui';

<Stack href="/docs/getting-started" tag={Link} border rounded itemsStart>
  <PageTitle>Get started in minutes</PageTitle>
  <Text>Install the package, drop in ThemeProvider, and start shipping.</Text>
  <Button filled>Read the guide</Button>
</Stack>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Breakpoint: `desktopStack`, `tabletStack`, `mobileStack`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Shape: `pill`, `sharp` (default), `rounded`
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Strong Border: `strongBorder`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Pointer Events, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Card

> Card is a container that groups related content with consistent styling. It can contain text, images, and other components.

Source: https://vaneui.com/docs/layout-components/card

Import: `import { Card, Badge, Button, CardBody, CardFooter, CardHeader, Col, Grid2, Row, Text, ThemeProvider, Title } from "@vaneui/ui"`

Use a Card for one self-contained unit of content, such as a product, a profile or a group of settings, that should read as its own panel. A set of cards usually goes in a [Grid](/docs/layout-components/grid), so each card gets the same column width. When the content needs padding and spacing but no border, use [Stack](/docs/layout-components/stack); for a full-width band with its own background, use [Section](/docs/layout-components/section).

## Basic usage

A card container with default styling. `md`, `primary`, `outline`, `rounded`, `border`, `padding`, `gap`, `flex`, and `column` are all defaults: no need to specify them.

```tsx demo
<Card>
  <Title>Welcome to VaneUI</Title>
  <Text>Compose interfaces with ready-to-use components.</Text>
</Card>
```

## Sizes

Cards come in different sizes: `xs`, `sm`, `md` (default), `lg`, `xl`. Size also scales padding, gap, and border-radius.

```tsx demo
<Row flexWrap itemsStart>
  <Card xs>
    <Title xs>Extra Small</Title>
    <Text xs>Tight content</Text>
  </Card>
  <Card sm>
    <Title sm>Small Card</Title>
    <Text sm>Compact content</Text>
  </Card>
  <Card>
    <Title>Medium Card</Title>
    <Text>Default size</Text>
  </Card>
  <Card lg>
    <Title lg>Large Card</Title>
    <Text lg>More spacious</Text>
  </Card>
  <Card xl>
    <Title xl>Extra Large</Title>
    <Text xl>Maximum room</Text>
  </Card>
</Row>
```

## Appearances

Cards support color appearances: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`.

```tsx demo
<Row flexWrap>
  <Card>
    <Title>Primary</Title>
    <Text>Default</Text>
  </Card>
  <Card accent>
    <Title>Accent</Title>
    <Text>Highlight</Text>
  </Card>
  <Card secondary>
    <Title>Secondary</Title>
    <Text>Subtle styling</Text>
  </Card>
  <Card tertiary>
    <Title>Tertiary</Title>
    <Text>Quiet emphasis</Text>
  </Card>
  <Card success>
    <Title>Success</Title>
    <Text>Positive status</Text>
  </Card>
  <Card danger>
    <Title>Danger</Title>
    <Text>Error or alert</Text>
  </Card>
  <Card warning>
    <Title>Warning</Title>
    <Text>Caution</Text>
  </Card>
  <Card info>
    <Title>Info</Title>
    <Text>Informational</Text>
  </Card>
</Row>
```

## Variants

`outline` is the default. Use `filled` for solid backgrounds. Add `shadow` for elevation.

```tsx demo
<Row flexWrap>
  <Card>
    <Title>Outline</Title>
    <Text>Default: border only</Text>
  </Card>
  <Card filled>
    <Title filled>Filled</Title>
    <Text filled>Solid background</Text>
  </Card>
  <Card shadow>
    <Title>Shadow</Title>
    <Text>Elevated appearance</Text>
  </Card>
</Row>
```

## Strong border for a selected card

`strongBorder` paints the border in the appearance's strong color, the one its focus ring uses, instead of the soft border tint. Use it to mark a selected option or a highlighted plan in a set of cards. A `filled` Card, whose border is otherwise transparent, shows the strong border too.

```tsx demo
<Grid2>
  <Card>
    <Title>Starter</Title>
    <Text secondary>Default border</Text>
  </Card>
  <Card strongBorder>
    <Title>Team</Title>
    <Text secondary>strongBorder</Text>
  </Card>
  <Card accent strongBorder>
    <Title>Business</Title>
    <Text secondary>accent strongBorder</Text>
  </Card>
  <Card info filled strongBorder>
    <Title filled>Enterprise</Title>
    <Text filled>info filled strongBorder</Text>
  </Card>
</Grid2>
```

`strongBorder` changes the color only, so it shows wherever the component already draws a border. The same prop works on `Row`, `Col`, `Stack`, `Grid2` to `Grid6`, `Container` and `Section`, which draw no border until you add `border` or a side prop such as `borderB`. It needs `@vaneui/ui` 1.4.5 or later.

## Shadow sizes

`shadow` follows the card's size, so an `lg` Card casts a larger shadow than an `sm` one. `shadowXs`, `shadowSm`, `shadowMd`, `shadowLg` and `shadowXl` fix the shadow size whatever the card's size. Card uses the deeper layout shadow ramp; UI components such as Button take the same props on their compact ramp.

```tsx demo
<Row flexWrap>
  <Card sm shadowXs><Text sm>shadowXs</Text></Card>
  <Card sm shadowSm><Text sm>shadowSm</Text></Card>
  <Card sm shadowMd><Text sm>shadowMd</Text></Card>
  <Card sm shadowLg><Text sm>shadowLg</Text></Card>
  <Card sm shadowXl><Text sm>shadowXl</Text></Card>
</Row>
```

The shadow props share one category with `shadow` and `noShadow`, so set one of them at a time. The fixed sizes need `@vaneui/ui` 1.4.5 or later.

## Shapes

`rounded` is the default. Use `pill` for fully rounded corners or `sharp` for none.

```tsx demo
<Row flexWrap>
  <Card>
    <Title>Rounded</Title>
    <Text>Default style</Text>
  </Card>
  <Card pill>
    <Title>Pill</Title>
    <Text>Fully rounded</Text>
  </Card>
  <Card sharp>
    <Title>Sharp</Title>
    <Text>No radius</Text>
  </Card>
</Row>
```

## Card with sub-components

Use `CardHeader`, `CardBody`, and `CardFooter` to give a card explicit structural regions. When any sub-component is present the parent Card switches to compound mode and the sub-components own padding.

```tsx demo
<Card>
  <CardHeader>
    <Title>Settings</Title>
    <Badge success filled>Active</Badge>
  </CardHeader>
  <CardBody>
    <Text>Configure your preferences below. The body grows to fill available space.</Text>
  </CardBody>
  <CardFooter>
    <Button secondary>Cancel</Button>
    <Button filled>Save</Button>
  </CardFooter>
</Card>
```

## Responsive layout

Use `row` for horizontal layout and `mobileStack` or `tabletStack` to switch to column on smaller screens.

```tsx demo
<Card row tabletStack>
  <Col>
    <Title>Product Image</Title>
    <Text secondary>Visual content area</Text>
  </Col>
  <Col>
    <Title>Product Details</Title>
    <Text>This layout switches to column on tablets and below. Resize to see the effect.</Text>
  </Col>
</Card>
```

## Nested cards

Cards can be nested. Pair a `secondary` or `tertiary` inner card with the default `primary` outer card to create clear visual hierarchy.

```tsx demo
<Card>
  <Title>Account</Title>
  <Text>Manage the resources tied to your workspace.</Text>
  <Card secondary>
    <Title sm>Storage</Title>
    <Text sm>4.2GB of 10GB used</Text>
  </Card>
  <Card secondary>
    <Title sm>Members</Title>
    <Text sm>3 active collaborators</Text>
  </Card>
</Card>
```

## As Link

Add `href` to make the card a clickable link. The card automatically renders as an `<a>` tag when `href` is provided, ensuring valid HTML. When `href` is set, the card gains a keyboard focus-visible outline in its appearance's focus color and tints on hover. Opt out of the outline with `noFocusVisible`.

The whole card becomes one link, so don't put a `Button`, `Link` or field inside it: one click would trigger both, and the link's accessible name would swallow the card's text (a development build warns). For a card with its own actions, render the card without `href`, put a `Link` in its title, and keep the `Button` beside it.

```tsx demo
<Row flexWrap>
  <Card href="#as-link" filled>
    <Title filled>Services</Title>
    <Text filled>Click to navigate</Text>
  </Card>
  <Card href="#as-link" secondary filled>
    <Title secondary filled>Pricing</Title>
    <Text secondary filled>View our plans</Text>
  </Card>
  <Card href="https://github.com" target="_blank" rel="noopener noreferrer">
    <Title>External Link</Title>
    <Text>Opens in new tab</Text>
  </Card>
</Row>
```

## Next.js Link integration

Use the `tag` prop to render the card as a Next.js `Link` for client-side navigation.

```tsx
import Link from 'next/link';
import { Card, Title, Text } from '@vaneui/ui';

<Card href="/docs" tag={Link}>
  <Title>Documentation</Title>
  <Text>Browse component guides and API reference.</Text>
</Card>
```

## Customizing

Set app-wide Card defaults with `ThemeProvider`'s `themeDefaults`:

```tsx demo
<ThemeProvider themeDefaults={{
  card: { main: { shadow: true } },
}}>
  <Card>Content</Card>
</ThemeProvider>
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Breakpoint: `desktopStack`, `tabletStack`, `mobileStack`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Strong Border: `strongBorder`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Pointer Events, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Grid

> Responsive equal-width column layouts. Grid2 through Grid6 render two to six columns that reduce on smaller screens; they share one API and differ only in column count.

Source: https://vaneui.com/docs/layout-components/grid

Import: `import { Grid2, Grid3, Grid4, Grid5, Grid6, Card, Col, Stack, Text, ThemeProvider, Title } from "@vaneui/ui"`

Use a Grid component when cards or tiles should line up in columns. Each one renders a `<div>` with CSS grid display, so the cells in a row all get the same width whatever their content. For flex items that keep their content width, use [Row](/docs/layout-components/row); for data compared across rows and columns, use [Table](/docs/layout-components/table).

## Basic usage

The Grid family renders equal-width column layouts: `Grid2` through `Grid6` for two to six columns. Children flow left to right and wrap to the next row. `md`, `gap`, `noPadding`, `outline`, and `sharp` are defaults, so none of them need to be specified.

```tsx demo
<Grid3>
  <Card>
    <Title>Item 1</Title>
    <Text>Three-column layout</Text>
  </Card>
  <Card>
    <Title>Item 2</Title>
    <Text>Equal widths</Text>
  </Card>
  <Card>
    <Title>Item 3</Title>
    <Text>Wraps to next row</Text>
  </Card>
</Grid3>
```

## Column counts

Pick the component for the number of columns you need, from `Grid2` to `Grid6`. They share the same API and differ only in the column count.

```tsx demo
<Col>
  <Text fontSemibold>Grid2</Text>
  <Grid2>
    <Card><Text textCenter>1</Text></Card>
    <Card><Text textCenter>2</Text></Card>
  </Grid2>
  <Text fontSemibold>Grid3</Text>
  <Grid3>
    <Card><Text textCenter>1</Text></Card>
    <Card><Text textCenter>2</Text></Card>
    <Card><Text textCenter>3</Text></Card>
  </Grid3>
  <Text fontSemibold>Grid4</Text>
  <Grid4>
    <Card><Text textCenter>1</Text></Card>
    <Card><Text textCenter>2</Text></Card>
    <Card><Text textCenter>3</Text></Card>
    <Card><Text textCenter>4</Text></Card>
  </Grid4>
  <Text fontSemibold>Grid6</Text>
  <Grid6>
    <Card><Text textCenter>1</Text></Card>
    <Card><Text textCenter>2</Text></Card>
    <Card><Text textCenter>3</Text></Card>
    <Card><Text textCenter>4</Text></Card>
    <Card><Text textCenter>5</Text></Card>
    <Card><Text textCenter>6</Text></Card>
  </Grid6>
</Col>
```

## Responsive columns

Each grid reduces its column count on smaller screens so cells never get too narrow. The breakpoints are tablet (below 1024px) and mobile (below 768px). Resize the window to see the reflow.

| Component | Desktop | Tablet | Mobile |
|-----------|---------|--------|--------|
| `Grid2`   | 2       | 2      | 1      |
| `Grid3`   | 3       | 2      | 1      |
| `Grid4`   | 4       | 3      | 2      |
| `Grid5`   | 5       | 3      | 2      |
| `Grid6`   | 6       | 4      | 2      |

## Sizes

Sizes (`xs`, `sm`, `md`, `lg`, `xl`) scale the grid's `gap` and `border-radius`.

```tsx demo
<Col>
  <Text fontSemibold>xs</Text>
  <Grid3 xs>
    <Card xs><Text xs>Item 1</Text></Card>
    <Card xs><Text xs>Item 2</Text></Card>
    <Card xs><Text xs>Item 3</Text></Card>
  </Grid3>
  <Text fontSemibold>sm</Text>
  <Grid3 sm>
    <Card sm><Text sm>Item 1</Text></Card>
    <Card sm><Text sm>Item 2</Text></Card>
    <Card sm><Text sm>Item 3</Text></Card>
  </Grid3>
  <Text fontSemibold>md (default)</Text>
  <Grid3>
    <Card><Text>Item 1</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
  <Text fontSemibold>lg</Text>
  <Grid3 lg>
    <Card lg><Text lg>Item 1</Text></Card>
    <Card lg><Text lg>Item 2</Text></Card>
    <Card lg><Text lg>Item 3</Text></Card>
  </Grid3>
  <Text fontSemibold>xl</Text>
  <Grid3 xl>
    <Card xl><Text xl>Item 1</Text></Card>
    <Card xl><Text xl>Item 2</Text></Card>
    <Card xl><Text xl>Item 3</Text></Card>
  </Grid3>
</Col>
```

## Appearances

Grid supports color appearances. Pair with `filled` or `border` to make the surface visible.

```tsx demo
<Col>
  <Grid3 filled primary>
    <Card><Text>Item 1</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
  <Grid3 filled success>
    <Card><Text>Item 1</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
</Col>
```

## Variants

`outline` is the default. Use `filled` for a solid background, or add `border` for a visible outline.

```tsx demo
<Col>
  <Grid3 filled primary>
    <Card><Text>Filled primary</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
  <Grid3 border success>
    <Card><Text>Outline success</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
</Col>
```

## Shapes

`sharp` is the default. Use `rounded` for soft corners or `pill` for fully rounded edges. Shape applies to the grid container itself, so pair with `filled` or `border` to see it.

```tsx demo
<Col>
  <Grid3 filled secondary sharp padding>
    <Card><Text>Sharp (default)</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
  <Grid3 filled secondary rounded padding>
    <Card><Text>Rounded</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
</Col>
```

## With gap

`gap` is on by default. Use `noGap` to remove spacing between cells.

```tsx demo
<Col>
  <Text fontSemibold>Default gap</Text>
  <Grid3>
    <Card><Text>Item 1</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
  <Text fontSemibold>noGap</Text>
  <Grid3 noGap>
    <Card sharp><Text>Item 1</Text></Card>
    <Card sharp><Text>Item 2</Text></Card>
    <Card sharp><Text>Item 3</Text></Card>
  </Grid3>
</Col>
```

## Divided grid with 1px lines

`divided` replaces the gap with 1px lines in the divider color, between the cells and around the outside, for a feature list or a strip of stats that reads as one ruled block. Each cell draws its line as an outline, so give the cells their own padding: a `Stack` per cell works, since it pads by default and its corners are `sharp`. `divided` is on `Grid2` to `Grid6` from `@vaneui/ui` 1.4.5, and the column count still reduces on smaller screens.

```tsx demo
<Grid3 divided>
  <Stack sm>
    <Title sm>Boolean props</Title>
    <Text sm secondary>Size, appearance and shape as flags.</Text>
  </Stack>
  <Stack sm>
    <Title sm>Theme overrides</Title>
    <Text sm secondary>App-wide defaults through ThemeProvider.</Text>
  </Stack>
  <Stack sm>
    <Title sm>Dark mode</Title>
    <Text sm secondary>One data-theme attribute.</Text>
  </Stack>
  <Stack sm>
    <Title sm>Tailwind CSS v4</Title>
    <Text sm secondary>Utilities and CSS variables.</Text>
  </Stack>
  <Stack sm>
    <Title sm>Accessible</Title>
    <Text sm secondary>Roles, labels and focus states.</Text>
  </Stack>
  <Stack sm>
    <Title sm>TypeScript</Title>
    <Text sm secondary>Typed props on every component.</Text>
  </Stack>
</Grid3>
```

A divided grid owns its 1px gap, so `gap`, `noGap` and the size props no longer change the spacing between cells. The lines take the grid's divider color, which follows its appearance.

## Customizing

Set app-wide Grid defaults with `ThemeProvider`'s `themeDefaults`. Each column count has its own key (`grid2` through `grid6`).

```tsx demo
<ThemeProvider themeDefaults={{
  grid3: { lg: true },
}}>
  <Grid3>
    <Card><Text>Item 1</Text></Card>
    <Card><Text>Item 2</Text></Card>
    <Card><Text>Item 3</Text></Card>
  </Grid3>
</ThemeProvider>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Divided: `divided`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Padding: `padding`, `paddingX`, `paddingY`, `noPadding` (default)
- Shape: `pill`, `sharp` (default), `rounded`
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Strong Border: `strongBorder`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Display, Flex Direction, Gap, Height, Hide, Items, Justify, Overflow, Pointer Events, Position, Responsive Sizing, Responsive Width, Show, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Divider

> Renders a thin line to separate content and create a clear visual hierarchy. Dividers can be used to group related items in lists and layouts.

Source: https://vaneui.com/docs/layout-components/divider

Import: `import { Divider, Card, Col, Row, Stack, Text } from "@vaneui/ui"`

Use Divider between items that share one surface, such as groups of controls or the rows of a card. It renders a `<div>` with `role="separator"` and an `aria-orientation` that follows the `vertical` prop, so assistive technology reads the line as a separator. Inside a [Menu](/docs/overlay-components/menu), a Divider takes its size and spacing from the menu; to split a page into bands with different backgrounds, use [Section](/docs/layout-components/section) instead.

## Basic usage

A horizontal divider.

```tsx demo
<Col>
  <Text>Content above the divider</Text>
  <Divider />
  <Text>Content below the divider</Text>
</Col>
```

## Sizes

Sizes (`xs`, `sm`, `md`, `lg`, `xl`) drive the per-size vertical padding via `--py-unit`. The line itself stays one pixel; pass `padding` to make the surrounding spacing visible.

```tsx demo
<Col lg>
  <div>
    <Text fontSemibold>Divider xs</Text>
    <Divider xs padding />
    <Text>Content after xs divider</Text>
  </div>
  <div>
    <Text fontSemibold>Divider sm</Text>
    <Divider sm padding />
    <Text>Content after sm divider</Text>
  </div>
  <div>
    <Text fontSemibold>Divider md (default)</Text>
    <Divider padding />
    <Text>Content after md divider</Text>
  </div>
  <div>
    <Text fontSemibold>Divider lg</Text>
    <Divider lg padding />
    <Text>Content after lg divider</Text>
  </div>
  <div>
    <Text fontSemibold>Divider xl</Text>
    <Divider xl padding />
    <Text>Content after xl divider</Text>
  </div>
</Col>
```

## Appearances

Dividers use `inheritAppearance` by default. Pass an explicit appearance for a colored line.

```tsx demo
<Col lg>
  <div>
    <Text fontSemibold>Divider primary</Text>
    <Divider primary />
    <Text>Content after primary divider</Text>
  </div>
  <div>
    <Text fontSemibold>Divider accent</Text>
    <Divider accent />
    <Text>Content after accent divider</Text>
  </div>
  <div>
    <Text fontSemibold>Divider secondary</Text>
    <Divider secondary />
    <Text>Content after secondary divider</Text>
  </div>
  <div>
    <Text fontSemibold>Divider tertiary</Text>
    <Divider tertiary />
    <Text>Content after tertiary divider</Text>
  </div>
  <div>
    <Text fontSemibold>Divider success</Text>
    <Divider success />
    <Text>Content after success divider</Text>
  </div>
  <div>
    <Text fontSemibold>Divider danger</Text>
    <Divider danger />
    <Text>Content after danger divider</Text>
  </div>
  <div>
    <Text fontSemibold>Divider warning</Text>
    <Divider warning />
    <Text>Content after warning divider</Text>
  </div>
</Col>
```

## Variants

`filled` paints the line with a translucent light scrim (`--color-divider-filled`), the same for every appearance, so it reads on a filled surface.

```tsx demo
<Row flexWrap>
  <Card primary filled>
    <Text>Above</Text>
    <Divider filled />
    <Text>Below</Text>
  </Card>
  <Card success filled>
    <Text>Above</Text>
    <Divider filled />
    <Text>Below</Text>
  </Card>
</Row>
```

## Vertical divider

Pass `vertical` to render a vertical separator. Useful for inline navigation or toolbars; place it inside a `Row` so it can stretch to the row's height.

```tsx demo
<Row className="h-10">
  <Text>Home</Text>
  <Divider vertical />
  <Text>About</Text>
  <Divider vertical />
  <Text>Contact</Text>
</Row>
```

## Separating list items

Use `Divider` between items in a `Stack` or `Col` to group related rows.

```tsx demo
<Stack>
  <Row justifyBetween>
    <Text fontSemibold>Plan</Text>
    <Text>Pro</Text>
  </Row>
  <Divider />
  <Row justifyBetween>
    <Text fontSemibold>Seats</Text>
    <Text>12</Text>
  </Row>
  <Divider />
  <Row justifyBetween>
    <Text fontSemibold>Renews</Text>
    <Text>May 2026</Text>
  </Row>
</Stack>
```

## Separating content blocks

Dividers also work as section breaks between larger blocks of content.

```tsx demo
<Col lg>
  <div>
    <Text fontSemibold lg>Block 1</Text>
    <Text>The first block introduces the topic and sets context for the sections that follow.</Text>
  </div>
  <Divider />
  <div>
    <Text fontSemibold lg>Block 2</Text>
    <Text>The second block expands on the idea, with the divider providing a clear visual break.</Text>
  </div>
  <Divider />
  <div>
    <Text fontSemibold lg>Block 3</Text>
    <Text>The third block closes out the sequence, demonstrating consistent rhythm throughout.</Text>
  </div>
</Col>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance` (default)
- Padding: `padding`, `paddingX`, `paddingY`, `noPadding` (default)
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Display, Height, Hide, Items, Justify, Orientation, Overflow, Position, Responsive Sizing, Responsive Width, Show, Transparent, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Img

> Displays images with VaneUI styling support including sizes, shapes, borders, shadows, and object-fit options.

Source: https://vaneui.com/docs/layout-components/img

Import: `import { Img, Card, Col, Row, Stack, Text, Title } from "@vaneui/ui"`

Img is for photos, screenshots, avatars and other content images. It renders a native `<img>` element and takes no children, so an image that needs a title or caption next to it goes in a [Card](/docs/layout-components/card) or a [Col](/docs/layout-components/col) together with its text. For an icon, use [Icon](/docs/basic-components/icon), which wraps an inline SVG in a `<span>` rather than loading an image file.

```tsx setup
const placeholderSrc = "https://placehold.co/300x200/e2e8f0/64748b?text=Image";
const portraitSrc = "https://placehold.co/200x300/cbd5e1/475569?text=Portrait";
const avatarSrc = "https://placehold.co/120x120/c7d2fe/4338ca?text=Avatar";
```

## Basic usage

Render an image with the `Img` component.

```tsx demo
<Img src={placeholderSrc} alt="Sample landscape photo" />
```

## Alt text

Always pass a descriptive `alt` attribute. Use an empty `alt=""` for decorative images so assistive technology can skip them.

```tsx demo
<Row flexWrap>
  <Img src={placeholderSrc} alt="Team standing in front of the office building" />
  <Img src={placeholderSrc} alt="" />
</Row>
```

## Shapes

Control border radius with `rounded` (default), `pill` (great for avatars), and `sharp`.

```tsx demo
<Row flexWrap>
  <Col itemsCenter>
    <Img src={placeholderSrc} alt="Rounded image" />
    <Text sm secondary>rounded (default)</Text>
  </Col>
  <Col itemsCenter>
    <Img pill src={avatarSrc} alt="Avatar" />
    <Text sm secondary>pill</Text>
  </Col>
  <Col itemsCenter>
    <Img sharp src={placeholderSrc} alt="Sharp image" />
    <Text sm secondary>sharp</Text>
  </Col>
</Row>
```

## Border and shadow

Add `border` and `shadow` props for visual emphasis.

```tsx demo
<Row flexWrap>
  <Col itemsCenter>
    <Img border src={placeholderSrc} alt="Bordered image" />
    <Text sm secondary>border</Text>
  </Col>
  <Col itemsCenter>
    <Img shadow src={placeholderSrc} alt="Image with shadow" />
    <Text sm secondary>shadow</Text>
  </Col>
  <Col itemsCenter>
    <Img border shadow src={placeholderSrc} alt="Bordered image with shadow" />
    <Text sm secondary>border + shadow</Text>
  </Col>
</Row>
```

## Appearances and variants

Img paints no surface of its own, so an appearance only shows through the border it draws. `filled` gives it a background, which is visible behind a transparent PNG or while the image is still loading.

```tsx demo
<Row flexWrap itemsCenter>
  <Img border success src="https://placehold.co/80x60/png" alt="Success border" />
  <Img border danger src="https://placehold.co/80x60/png" alt="Danger border" />
  <Img filled secondary className="w-20 h-15" alt="" />
</Row>
```

## Sizes

Images support five sizes: `xs`, `sm`, `md` (default), `lg`, `xl`. Size controls border-radius scaling.

```tsx demo
<Row flexWrap itemsEnd>
  <Col itemsCenter>
    <Img xs src={placeholderSrc} alt="xs image" />
    <Text sm secondary>xs</Text>
  </Col>
  <Col itemsCenter>
    <Img sm src={placeholderSrc} alt="sm image" />
    <Text sm secondary>sm</Text>
  </Col>
  <Col itemsCenter>
    <Img src={placeholderSrc} alt="md image" />
    <Text sm secondary>md (default)</Text>
  </Col>
  <Col itemsCenter>
    <Img lg src={placeholderSrc} alt="lg image" />
    <Text sm secondary>lg</Text>
  </Col>
  <Col itemsCenter>
    <Img xl src={placeholderSrc} alt="xl image" />
    <Text sm secondary>xl</Text>
  </Col>
</Row>
```

## Object fit

Control how an image fills a sized container with `objectCover` (default), `objectContain`, and `objectFill`. The examples below constrain the image to a fixed box so the difference is visible.

```tsx demo
<Row flexWrap>
  <Col itemsCenter>
    <Img src={portraitSrc} alt="Cover crops to fill the box" className="w-[200px] h-[150px]" />
    <Text sm secondary>objectCover (default)</Text>
  </Col>
  <Col itemsCenter>
    <Img objectContain src={portraitSrc} alt="Contain fits inside the box" className="w-[200px] h-[150px]" />
    <Text sm secondary>objectContain</Text>
  </Col>
  <Col itemsCenter>
    <Img objectFill src={portraitSrc} alt="Fill stretches to the box" className="w-[200px] h-[150px]" />
    <Text sm secondary>objectFill</Text>
  </Col>
</Row>
```

## Inside a Card

`Img` composes naturally inside `Card` for media tiles. Use `wFull` so the image spans the card width.

```tsx demo
<Row flexWrap>
  <Card noPadding overflowHidden className="w-[240px]">
    <Img sharp wFull src={placeholderSrc} alt="Sunset over the harbor" className="h-[140px]" />
    <Stack>
      <Title sm>Harbor Sunset</Title>
      <Text sm secondary>Captured last weekend on a walk along the pier.</Text>
    </Stack>
  </Card>
  <Card noPadding overflowHidden className="w-[240px]">
    <Img sharp wFull src={placeholderSrc} alt="Forest trail at dawn" className="h-[140px]" />
    <Stack>
      <Title sm>Forest Trail</Title>
      <Text sm secondary>Early morning hike through the pine forest.</Text>
    </Stack>
  </Card>
</Row>
```

## Keeping its size in a row with noShrink

In a flex [Row](/docs/layout-components/row), an image is a flex item that can give up width when the row runs out of room. `noShrink` sets `flex-shrink: 0`, so a logo or an avatar keeps its size and the text beside it gives way instead. Here the row also takes `whitespaceNowrap` and `overflowHidden`, so the label stays on one line and clips at the row's edge. `noShrink` on Img needs `@vaneui/ui` 1.4.5 or later.

```tsx demo
<Row whitespaceNowrap overflowHidden className="max-w-80">
  <Img noShrink pill src={avatarSrc} alt="" width={32} height={32}/>
  <Text sm>A long label that stays on one line and clips at the edge of its row</Text>
</Row>
```

## Native HTML attributes

`Img` forwards all standard `<img>` attributes including `loading`, `decoding`, `srcSet`, `sizes`, `referrerPolicy`, and `crossOrigin`. Use `loading="lazy"` for below-the-fold images.

```tsx demo
<Img
  src={placeholderSrc}
  alt="Lazy-loaded image"
  loading="lazy"
  decoding="async"
/>
```

## Props

- Appearance: `primary`, `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Display, Focus Visible, Height, Hide, Items, Justify, Object Fit, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transparent, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Table

> Renders semantic table markup with Table, Thead, Tbody, Tfoot, Tr, Th, Td, and Caption. The size prop cascades from the table to every cell, and a cell or row can override it.

Source: https://vaneui.com/docs/layout-components/table

Import: `import { Table, Thead, Tbody, Tfoot, Tr, Th, Td, Caption, Badge, Col, Stack, Text, ThemeProvider } from "@vaneui/ui"`

Use Table for data that readers compare across rows and down columns, such as a price list, a schedule or an order summary. To place cards or tiles in columns, use [Grid](/docs/layout-components/grid); for a single run of items, one per line, use [List](/docs/typography-components/list).

## Basic usage

Compose a table from `Table`, `Thead`, `Tbody`, `Tr`, `Th`, and `Td`. Header cells (`Th`) render semibold with muted text, and every cell gets a bottom row rule. `Table` defaults to `md`, `wFull`, `noBorder`, and `fontSans`. Add `scope="col"` to header cells so assistive technology associates each column with its data.

```tsx demo
<Table>
  <Thead>
    <Tr>
      <Th scope="col">Service</Th>
      <Th scope="col">Region</Th>
      <Th scope="col" textRight>Latency</Th>
    </Tr>
  </Thead>
  <Tbody>
    <Tr>
      <Td>api-gateway</Td>
      <Td>europe-west</Td>
      <Td textRight>42ms</Td>
    </Tr>
    <Tr>
      <Td>auth</Td>
      <Td>us-east</Td>
      <Td textRight>88ms</Td>
    </Tr>
  </Tbody>
</Table>
```

## Sizes

The size prop scales both text and cell padding, and it cascades from the table to every cell. Set it once on `Table` to size the whole table: `xs`, `sm`, `md` (default), `lg`, `xl`.

```tsx demo
<Stack>
  <Table xs>
    <Thead><Tr><Th scope="col">Size</Th><Th scope="col" textRight>Value</Th></Tr></Thead>
    <Tbody><Tr><Td>xs table</Td><Td textRight>tightest</Td></Tr></Tbody>
  </Table>
  <Table sm>
    <Thead><Tr><Th scope="col">Size</Th><Th scope="col" textRight>Value</Th></Tr></Thead>
    <Tbody><Tr><Td>sm table</Td><Td textRight>compact</Td></Tr></Tbody>
  </Table>
  <Table>
    <Thead><Tr><Th scope="col">Size</Th><Th scope="col" textRight>Value</Th></Tr></Thead>
    <Tbody><Tr><Td>md table</Td><Td textRight>default</Td></Tr></Tbody>
  </Table>
  <Table lg>
    <Thead><Tr><Th scope="col">Size</Th><Th scope="col" textRight>Value</Th></Tr></Thead>
    <Tbody><Tr><Td>lg table</Td><Td textRight>spacious</Td></Tr></Tbody>
  </Table>
  <Table xl>
    <Thead><Tr><Th scope="col">Size</Th><Th scope="col" textRight>Value</Th></Tr></Thead>
    <Tbody><Tr><Td>xl table</Td><Td textRight>widest</Td></Tr></Tbody>
  </Table>
</Stack>
```

## Appearances and variants

An appearance on `Table` cascades to its rows and cells. `outline` (the default) colours the borders; `filled` fills the surface instead.

```tsx demo
<Col>
  <Table success>
    <Thead><Tr><Th scope="col">Check</Th><Th scope="col" textRight>Result</Th></Tr></Thead>
    <Tbody><Tr><Td>outline success</Td><Td textRight>borders take the colour</Td></Tr></Tbody>
  </Table>
  <Table filled secondary>
    <Thead><Tr><Th scope="col">Check</Th><Th scope="col" textRight>Result</Th></Tr></Thead>
    <Tbody><Tr><Td>filled secondary</Td><Td textRight>surface takes the colour</Td></Tr></Tbody>
  </Table>
</Col>
```

## Per-cell and per-row size

A size on a `Th`, `Td`, or `Tr` overrides the table for that cell or row. Here an `xs` table keeps one `xl` cell and one `lg` row. An explicit `md` cell also holds `md` against a differently sized table.

```tsx demo
<Table xs>
  <Thead><Tr><Th scope="col">Metric</Th><Th scope="col" xl textRight>xl cell</Th></Tr></Thead>
  <Tbody>
    <Tr><Td>tiny row</Td><Td xl textRight>large</Td></Tr>
    <Tr lg><Td>lg row</Td><Td textRight>lg row</Td></Tr>
  </Tbody>
</Table>
```

## Column alignment

Set `textLeft` (default), `textCenter`, or `textRight` per cell. Right-align numeric columns so the digits line up.

```tsx demo
<Table>
  <Thead>
    <Tr>
      <Th scope="col">Plan</Th>
      <Th scope="col" textCenter>Seats</Th>
      <Th scope="col" textRight>Price</Th>
    </Tr>
  </Thead>
  <Tbody>
    <Tr><Td>Starter</Td><Td textCenter>3</Td><Td textRight>$0</Td></Tr>
    <Tr><Td>Team</Td><Td textCenter>25</Td><Td textRight>$99</Td></Tr>
    <Tr><Td>Business</Td><Td textCenter>100</Td><Td textRight>$499</Td></Tr>
  </Tbody>
</Table>
```

A `Text` inside a right-aligned cell is its own fit-width box, so give it `wFull textRight` to line up with the column.

```tsx demo
<Table>
  <Tbody>
    <Tr><Td>Trail Runner 2</Td><Td textRight><Text wFull textRight>$89.00</Text></Td></Tr>
    <Tr><Td>Merino socks (3 pairs)</Td><Td textRight><Text wFull textRight>$48.00</Text></Td></Tr>
  </Tbody>
</Table>
```

Text in a cell wraps between words, never inside one, so a name or a price stays whole in a narrow column.

## Footer row

Add a `Tfoot` for totals or summary rows. Header cells (`Th`) carry the semibold treatment, so they read well for a total.

```tsx demo
<Table>
  <Thead>
    <Tr><Th scope="col">Item</Th><Th scope="col" textRight>Amount</Th></Tr>
  </Thead>
  <Tbody>
    <Tr><Td>Compute</Td><Td textRight>$120</Td></Tr>
    <Tr><Td>Storage</Td><Td textRight>$30</Td></Tr>
  </Tbody>
  <Tfoot>
    <Tr><Th scope="row">Total</Th><Th textRight>$150</Th></Tr>
  </Tfoot>
</Table>
```

## Caption

`Caption` renders a `<caption>` element that titles the table for screen readers. Its text follows the table size and accepts its own size to override.

```tsx demo
<Table>
  <Caption>Monthly active users by region</Caption>
  <Thead>
    <Tr><Th scope="col">Region</Th><Th scope="col" textRight>Users</Th></Tr>
  </Thead>
  <Tbody>
    <Tr><Td>Europe</Td><Td textRight>18,400</Td></Tr>
    <Tr><Td>North America</Td><Td textRight>22,100</Td></Tr>
  </Tbody>
</Table>
```

## Outer border

`Table` has no border by default. Add `border` for an appearance-colored outer border. The table uses collapsed borders, so the corners stay square and there is no shape prop.

```tsx demo
<Table border>
  <Thead><Tr><Th scope="col">Name</Th><Th scope="col">Role</Th></Tr></Thead>
  <Tbody>
    <Tr><Td>Ada</Td><Td>Engineer</Td></Tr>
    <Tr><Td>Grace</Td><Td>Architect</Td></Tr>
  </Tbody>
</Table>
```

## Components in cells

Cells accept any VaneUI component. Drop a `Badge` into a status column.

```tsx demo
<Table>
  <Thead>
    <Tr><Th scope="col">Service</Th><Th scope="col">Region</Th><Th scope="col">Status</Th></Tr>
  </Thead>
  <Tbody>
    <Tr>
      <Td>api-gateway</Td>
      <Td>europe-west</Td>
      <Td><Badge success filled>Healthy</Badge></Td>
    </Tr>
    <Tr>
      <Td>worker</Td>
      <Td>us-east</Td>
      <Td><Badge warning filled>Degraded</Badge></Td>
    </Tr>
    <Tr>
      <Td>scheduler</Td>
      <Td>us-east</Td>
      <Td><Badge danger filled>Down</Badge></Td>
    </Tr>
  </Tbody>
</Table>
```

## Font family

Cells render in the sans font (`fontSans`, the default), whatever font the page around them uses. Pass `fontMono` for machine output such as ids and hashes, or `fontSerif` / `fontHeading`.

```tsx demo
<Table fontMono sm>
  <Thead><Tr><Th scope="col">Commit</Th><Th scope="col">Message</Th></Tr></Thead>
  <Tbody>
    <Tr><Td>6aba224</Td><Td>fix: make components consistent</Td></Tr>
    <Tr><Td>899e2fd</Td><Td>chore: release 1.4.3</Td></Tr>
  </Tbody>
</Table>
```

## Wide tables on small screens

A table never shrinks below its content. Wrap a wide one in `<Col overflowXAuto relative>` so it scrolls inside its own box instead of widening the page; `relative` keeps positioned children (a visually hidden header label, for example) inside the scroll box.

```tsx demo
<Col overflowXAuto relative>
  <Table>
    <Thead><Tr><Th scope="col">Service</Th><Th scope="col">Region</Th><Th scope="col">Owner</Th><Th scope="col" textRight>p95 latency</Th></Tr></Thead>
    <Tbody><Tr><Td>api-gateway</Td><Td>europe-west</Td><Td>platform-team</Td><Td textRight>42ms</Td></Tr></Tbody>
  </Table>
</Col>
```

## Customizing

Set table defaults with `ThemeProvider`'s `themeDefaults`. The `table` node has a slot for each part: `main`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`, and `caption`.

```tsx demo
<ThemeProvider themeDefaults={{
  table: { main: { sm: true } },
}}>
  <Table>
    <Thead><Tr><Th scope="col">Compact by default</Th></Tr></Thead>
    <Tbody><Tr><Td>Set the size once on the provider</Td></Tr></Tbody>
  </Table>
</ThemeProvider>
```

## Props

- Appearance: `primary`, `accent`, `secondary` (default), `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Margin: `margin`, `marginX`, `marginY`, `marginT`, `marginB`, `noMargin`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Hide, Responsive Sizing, Responsive Width, Show, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Overlay

> A fullscreen backdrop overlay for creating modal backgrounds, loading screens, and lightbox effects. Renders via portal with click-to-close and optional blur.

Source: https://vaneui.com/docs/overlay-components/overlay

Import: `import { Overlay, Button, Card, Img, Modal, Row, Text } from "@vaneui/ui"`

Use Overlay for a dimmed or transparent backdrop that needs no dialog role. It renders a plain `<div>` with the layout defaults `fixed`, `flex`, `itemsCenter` and `justifyCenter`. For a dialog, use [Modal](/docs/overlay-components/modal), which provides its own backdrop with the same layout defaults; for a panel attached to a trigger, use a [Popup](/docs/overlay-components/popup).

## Basic usage

A fullscreen semi-transparent backdrop. Click the overlay background to dismiss.


```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Show Overlay</Button>
    <Overlay open={open} onClose={() => setOpen(false)}>
      <Text>Click the background to close</Text>
    </Overlay>
  </>
);
```

## Overlay with content

Place content inside the overlay. Click handlers on the overlay only fire when the event target is the overlay itself, so children receive their own clicks without dismissing the overlay.

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Show Overlay</Button>
    <Overlay open={open} onClose={() => setOpen(false)}>
      <Card>
        <Text>Overlay content here</Text>
        <Button onClick={() => setOpen(false)}>Close</Button>
      </Card>
    </Overlay>
  </>
);
```

## Blur effect

Add `backdropBlur` for a backdrop-filter blur behind the overlay. Blur intensity follows the `--overlay-blur` CSS variable.

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Show Blur Overlay</Button>
    <Overlay open={open} onClose={() => setOpen(false)} backdropBlur>
      <Card>
        <Text>Blurred background</Text>
      </Card>
    </Overlay>
  </>
);
```

## Custom backdrop color

The backdrop paints the `--overlay-bg` scrim by default. Pass a `className` with a background utility to override it, or `transparent` to drop the scrim entirely.

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Show Tinted Overlay</Button>
    <Overlay open={open} onClose={() => setOpen(false)} className="bg-red-500/40">
      <Card>
        <Text>Tinted overlay</Text>
      </Card>
    </Overlay>
  </>
);
```

Use `className` for gradients or backgrounds the appearance system doesn't cover:

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Show Gradient Overlay</Button>
    <Overlay
      open={open}
      onClose={() => setOpen(false)}
      className="bg-gradient-to-br from-black/80 to-transparent"
    >
      <Card>
        <Text>Custom gradient backdrop</Text>
      </Card>
    </Overlay>
  </>
);
```

## Non-dismissible Overlay

Use `pointerEventsNone` for loading states where the overlay should pass clicks through and never close on its own. Useful for full-screen spinners that sit above the page.

```tsx demo
const [loading, setLoading] = useState(false);

return (
  <>
    <Button onClick={() => setLoading(!loading)}>Toggle Loading</Button>
    <Overlay open={loading} pointerEventsNone>
      <Text>Loading...</Text>
    </Overlay>
  </>
);
```

## Transparent Overlay

Use `transparent` to create an invisible backdrop that still captures clicks. Useful for click-away dismissal without visually dimming the page.

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Show Transparent Overlay</Button>
    <Overlay open={open} onClose={() => setOpen(false)} transparent>
      <Card>
        <Text>Content on a transparent overlay</Text>
        <Button onClick={() => setOpen(false)}>Close</Button>
      </Card>
    </Overlay>
  </>
);
```

## Foundation for Modal

`Modal` layers a dialog surface over its own portal-rendered backdrop, which handles portaling, backdrop click, and stacking (the same mechanics as `Overlay`). For accessible dialogs with focus trap, scroll lock, and ARIA wiring, prefer `Modal`. Reach for `Overlay` directly when you need a custom backdrop layer (lightbox, loading shade, drawer scrim) without dialog semantics.

```tsx
{/* High-level: use Modal for dialogs */}
<Modal open={open} onClose={() => setOpen(false)}>
  <Text>Accessible dialog with focus trap</Text>
</Modal>

{/* Low-level: use Overlay for custom backdrops */}
<Overlay open={open} onClose={() => setOpen(false)} backdropBlur>
  <Img src="/photo.jpg" className="max-h-[90vh]" />
</Overlay>
```

## Portal target

Overlay renders into `document.body` by default via React portal. Set `portal={false}` to render in-place, useful when the overlay must be scoped to a positioned ancestor (e.g., scrim over a single card instead of the whole viewport).

```tsx demo
const [open, setOpen] = useState(false);

return (
  <Card relative className="h-64">
    <Text>Parent card</Text>
    <Button onClick={() => setOpen(true)}>Show scoped overlay</Button>
    <Overlay open={open} onClose={() => setOpen(false)} portal={false} absolute>
      <Text>Scoped to this card</Text>
    </Overlay>
  </Card>
);
```

When `portal={false}` and `absolute` is set, the overlay anchors to the nearest `relative`/`absolute` ancestor instead of the viewport.

## Z-index / stacking

Overlay reads its `z-index` from a managed stacking context (`--z-index`), so multiple overlays stack in mount order automatically. Override per instance with an inline `style={{ zIndex: 9999 }}` when you need to layer above a specific element (toasts, page chrome). A class that sets `--z-index` loses to the managed inline value.

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Show Overlay</Button>
    <Overlay
      open={open}
      onClose={() => setOpen(false)}
      style={{ zIndex: 9999 }}
    >
      <Card>
        <Text>Above everything</Text>
      </Card>
    </Overlay>
  </>
);
```

## Custom animation duration

Control how the overlay transitions in and out. Use `transitionDuration` to set a custom duration in milliseconds (default `200`), or `noAnimation` to disable transitions entirely for an instant open/close.

```tsx demo
const [openSlow, setOpenSlow] = useState(false);
const [openInstant, setOpenInstant] = useState(false);

return (
  <>
    <Row>
      <Button onClick={() => setOpenSlow(true)}>Slow fade (500ms)</Button>
      <Button onClick={() => setOpenInstant(true)}>Instant</Button>
    </Row>

    {/* Slow fade - 500ms */}
    <Overlay open={openSlow} onClose={() => setOpenSlow(false)} transitionDuration={500}>
      <Card>Slow transition content</Card>
    </Overlay>

    {/* Instant - no animation */}
    <Overlay open={openInstant} onClose={() => setOpenInstant(false)} noAnimation>
      <Card>Instant content</Card>
    </Overlay>
  </>
);
```

## Lifecycle and mounting

| Prop | Default | Description |
|------|---------|-------------|
| `open` | `true` | Whether the overlay is visible |
| `onClose` | - | Called when the overlay is dismissed (backdrop click or `Escape`) |
| `portal` | `true` | Render into `document.body` via React portal |
| `keepMounted` | `false` | Keep DOM mounted when closed (useful for transition state preservation) |
| `noAnimation` | `false` | Disable enter/exit transitions |
| `transitionDuration` | `200` | Animation duration in ms |
| `onEnterComplete` | - | Called when enter transition completes |
| `onExitComplete` | - | Called when exit transition completes |

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Show Overlay</Button>
    <Overlay
      open={open}
      onClose={() => setOpen(false)}
      keepMounted
      transitionDuration={300}
      onExitComplete={() => console.log('overlay closed')}
    >
      <Card>Persistent DOM, custom timing</Card>
    </Overlay>
  </>
);
```

## Props

- Size: `xs`, `sm`, `md`, `lg`, `xl`

Layout and utility props (Blur, Display, Height, Hide, Items, Justify, Overflow, Pointer Events, Position, Responsive Sizing, Responsive Width, Show, Transparent, Width) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Modal

> Modal is an accessible dialog with focus trapping, scroll lock, and keyboard navigation. Renders its portal backdrop with role="dialog" and aria-modal="true".

Source: https://vaneui.com/docs/overlay-components/modal

Import: `import { Modal, Button, Checkbox, Input, Label, ModalBody, ModalCloseButton, ModalFooter, ModalHeader, Row, Stack, Text, ThemeProvider, Title } from "@vaneui/ui"`

Use Modal when the user has to finish or dismiss a task before returning to the page, such as a confirmation, a short form or a detail view. While it is open, the rest of the page gets `inert` and `aria-hidden`. A panel that leaves the page usable belongs in a [Popup](/docs/overlay-components/popup), and a message that needs no response in an [Alert](/docs/basic-components/alert).

## Basic usage

A controlled modal opened by a Button. The Modal portals to `document.body`, traps focus inside the dialog while open, locks body scroll, and closes on overlay click or `Escape`.

Modal content defaults: `md`, `primary`, `outline`, `rounded`, `shadow`, `flex column`, `gap`, `wFull`, `overflowAuto`, `relative`, `noPadding` (sub-components own their own padding).

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Open Modal</Button>
    <Modal open={open} onClose={() => setOpen(false)}>
      <Stack>
        <Text fontBold>Confirm Action</Text>
        <Text>Are you sure?</Text>
        <Row justifyEnd>
          <Button onClick={() => setOpen(false)}>Cancel</Button>
          <Button primary filled onClick={() => setOpen(false)}>Confirm</Button>
        </Row>
      </Stack>
    </Modal>
  </>
);
```

## Compound Modal

Use `ModalHeader`, `ModalBody`, `ModalFooter`, and `ModalCloseButton` for full control over layout. When a `ModalHeader`, `ModalBody`, or `ModalFooter` is a direct child, Modal renders the children as-is without auto-wrapping. Each sub-component carries its own layout defaults:

- `ModalHeader`: `flex row`, `itemsCenter`, `justifyBetween`, `gap`, `padding`
- `ModalBody`: `flex column`, `gap`, `padding`, `overflowAuto`
- `ModalFooter`: `flex row`, `itemsCenter`, `justifyEnd`, `gap`, `padding`
- `ModalCloseButton`: `sm`, `secondary`, `outline`, `transparent`, `noShadow`, `noInsetRing`

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Edit Profile</Button>
    <Modal open={open} onClose={() => setOpen(false)}>
      <ModalHeader>
        <Title>Edit Profile</Title>
        <ModalCloseButton />
      </ModalHeader>
      <ModalBody>
        <Stack>
          <Label>Name</Label>
          <Input placeholder="Enter your name" />
          <Label>Email</Label>
          <Input placeholder="Enter your email" />
        </Stack>
      </ModalBody>
      <ModalFooter>
        <Button sm onClick={() => setOpen(false)}>Cancel</Button>
        <Button sm primary filled onClick={() => setOpen(false)}>Save</Button>
      </ModalFooter>
    </Modal>
  </>
);
```

## Customizing the close button

`ModalCloseButton` takes the props of [Button](/docs/basic-components/button) except `href`, `tag` and `loading`. A prop you pass wins over its defaults, so `<ModalCloseButton lg />` or `<ModalCloseButton danger />` changes the × button. With children it renders a labelled button with Button's own look, such as a Cancel button in the footer. This needs `@vaneui/ui` 1.5.0 or later.

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Rename project</Button>
    <Modal open={open} onClose={() => setOpen(false)}>
      <ModalHeader>
        <Title>Rename project</Title>
        <ModalCloseButton lg />
      </ModalHeader>
      <ModalBody>
        <Input placeholder="Project name" />
      </ModalBody>
      <ModalFooter>
        <ModalCloseButton secondary>Cancel</ModalCloseButton>
        <Button filled onClick={() => setOpen(false)}>Save</Button>
      </ModalFooter>
    </Modal>
  </>
);
```

A passed `onClick` runs before the modal closes, and `event.preventDefault()` in it keeps the modal open:

```tsx
<ModalCloseButton
  onClick={(event) => {
    if (hasUnsavedChanges) event.preventDefault();
  }}
/>
```

## Convenience props

Use the `title`, `footer`, and `withCloseButton` shorthand props to compose a structured modal without writing sub-components. A close button is shown by default regardless of `title` (toggle with `withCloseButton`): with a title it sits in the header, without one it floats top-right. A plain-text `title` renders as a `Title`. Children become the body.

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Open Confirmation</Button>
    <Modal
      open={open}
      onClose={() => setOpen(false)}
      title="Quick Confirmation"
      footer={
        <Row justifyEnd>
          <Button sm onClick={() => setOpen(false)}>Cancel</Button>
          <Button sm primary filled onClick={() => setOpen(false)}>Confirm</Button>
        </Row>
      }
    >
      <Text>Are you sure you want to proceed?</Text>
    </Modal>
  </>
);
```

## Confirmation dialog

A common pattern is a destructive action that requires explicit confirmation. Disable `closeOnOverlayClick` so users can't dismiss accidentally by clicking outside.

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button danger filled onClick={() => setOpen(true)}>Delete Account</Button>
    <Modal
      open={open}
      onClose={() => setOpen(false)}
      closeOnOverlayClick={false}
      title="Delete account?"
      footer={
        <Row justifyEnd>
          <Button sm onClick={() => setOpen(false)}>Cancel</Button>
          <Button sm danger filled onClick={() => setOpen(false)}>Delete</Button>
        </Row>
      }
    >
      <Text>This action is permanent and cannot be undone.</Text>
    </Modal>
  </>
);
```

## Form Modal

Modals can host forms. Focus trapping keeps `Tab` / `Shift+Tab` navigation inside the modal, and pressing `Escape` closes it (unless disabled). Use `initialFocus` to direct keyboard focus to a specific field on open.

```tsx demo
const [open, setOpen] = useState(false);
const nameRef = useRef(null);

return (
  <>
    <Button onClick={() => setOpen(true)}>Edit Profile</Button>
    <Modal
      open={open}
      onClose={() => setOpen(false)}
      initialFocus={nameRef}
      title="Edit Profile"
      footer={
        <Row justifyEnd>
          <Button sm onClick={() => setOpen(false)}>Cancel</Button>
          <Button sm primary filled onClick={() => setOpen(false)}>Save</Button>
        </Row>
      }
    >
      <Stack>
        <Label>Name</Label>
        <Input ref={nameRef} placeholder="Enter your name" />
        <Label>Email</Label>
        <Input type="email" placeholder="you@example.com" />
        <Label row><Checkbox />Send me email updates</Label>
      </Stack>
    </Modal>
  </>
);
```

## Shape, variant and appearance

These apply to the modal panel, not the backdrop. Modal is `rounded`, `outline` and `primary` by default.

```tsx demo
const [shape, setShape] = useState('');
const close = () => setShape('');

return (
  <>
    <Row flexWrap>
      <Button onClick={() => setShape('sharp')}>sharp</Button>
      <Button onClick={() => setShape('pill')}>pill</Button>
      <Button onClick={() => setShape('filled')}>filled secondary</Button>
      <Button onClick={() => setShape('danger')}>danger border</Button>
    </Row>
    <Modal sharp open={shape === 'sharp'} onClose={close}>
      <ModalBody><Text>Sharp corners</Text></ModalBody>
    </Modal>
    <Modal pill open={shape === 'pill'} onClose={close}>
      <ModalBody><Text>Pill corners</Text></ModalBody>
    </Modal>
    <Modal filled secondary open={shape === 'filled'} onClose={close}>
      <ModalBody><Text>Filled secondary panel</Text></ModalBody>
    </Modal>
    <Modal danger border open={shape === 'danger'} onClose={close}>
      <ModalBody><Text>Danger border</Text></ModalBody>
    </Modal>
  </>
);
```

## Sizes

Size props control modal content width via `--modal-width`. Padding, gap, and border-radius scale with it.

```tsx demo
const [size, setSize] = useState('');
const close = () => setSize('');
const body = (
  <ModalBody>
    <Text>Width, padding, gap and border-radius all scale together.</Text>
  </ModalBody>
);

return (
  <>
    <Row flexWrap>
      <Button xs onClick={() => setSize('xs')}>xs</Button>
      <Button sm onClick={() => setSize('sm')}>sm</Button>
      <Button onClick={() => setSize('md')}>md</Button>
      <Button lg onClick={() => setSize('lg')}>lg</Button>
      <Button xl onClick={() => setSize('xl')}>xl</Button>
    </Row>
    <Modal xs open={size === 'xs'} onClose={close}>
      <ModalHeader><Title>Extra small</Title><ModalCloseButton/></ModalHeader>
      {body}
    </Modal>
    <Modal sm open={size === 'sm'} onClose={close}>
      <ModalHeader><Title>Small</Title><ModalCloseButton/></ModalHeader>
      {body}
    </Modal>
    <Modal open={size === 'md'} onClose={close}>
      <ModalHeader><Title>Medium, the default</Title><ModalCloseButton/></ModalHeader>
      {body}
    </Modal>
    <Modal lg open={size === 'lg'} onClose={close}>
      <ModalHeader><Title>Large</Title><ModalCloseButton/></ModalHeader>
      {body}
    </Modal>
    <Modal xl open={size === 'xl'} onClose={close}>
      <ModalHeader><Title>Extra large</Title><ModalCloseButton/></ModalHeader>
      {body}
    </Modal>
  </>
);
```

## Appearances

Apply appearance and variant props to style the content surface (border, text, background).

```tsx demo
const [openPrimary, setOpenPrimary] = useState(false);
const [openDanger, setOpenDanger] = useState(false);

return (
  <>
    <Row>
      <Button primary filled onClick={() => setOpenPrimary(true)}>Primary modal</Button>
      <Button danger filled onClick={() => setOpenDanger(true)}>Danger modal</Button>
    </Row>
    <Modal open={openPrimary} onClose={() => setOpenPrimary(false)} primary filled>Primary modal</Modal>
    <Modal open={openDanger} onClose={() => setOpenDanger(false)} danger filled>Danger modal</Modal>
  </>
);
```

## Blur overlay

Pass `overlayProps={{ backdropBlur: true }}` to add a backdrop-filter blur behind the modal.

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Open Modal</Button>
    <Modal open={open} onClose={() => setOpen(false)} overlayProps={{ backdropBlur: true }}>
      <Text>Blurred background</Text>
    </Modal>
  </>
);
```

## Non-dismissible Modal

Disable `closeOnOverlayClick` and `closeOnEscape` to force the user to take an explicit action (typically a button in the footer) before the modal can close.

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Open Modal</Button>
    <Modal
      open={open}
      onClose={() => setOpen(false)}
      closeOnOverlayClick={false}
      closeOnEscape={false}
    >
      <Text>Must click a button to close</Text>
      <Button onClick={() => setOpen(false)}>Close</Button>
    </Modal>
  </>
);
```

## Full-screen Modal

Set `fullScreen` to make the modal fill the entire viewport. Full-screen modals have no border-radius (`sharp` is applied automatically) and use a transparent overlay, useful for immersive experiences or mobile-optimized views.

```tsx demo
const [open, setOpen] = useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Open Full Screen</Button>
    <Modal open={open} onClose={() => setOpen(false)} fullScreen>
      <ModalHeader>
        <Title>Full Screen View</Title>
        <ModalCloseButton />
      </ModalHeader>
      <ModalBody>
        <Text>Content fills the entire viewport.</Text>
      </ModalBody>
    </Modal>
  </>
);
```

## Accessibility and advanced props

Modal ships accessibility features enabled by default. The dialog renders with `role="dialog"` and `aria-modal="true"`, and is automatically wired with `aria-labelledby` (when `ModalHeader` is used) and `aria-describedby` (when `ModalBody` is used).

| Prop | Default | Description |
|------|---------|-------------|
| `scrollLock` | `true` | Lock body scroll when modal is open |
| `focusTrap` | `true` | Trap `Tab` / `Shift+Tab` focus inside the modal |
| `returnFocus` | `true` | Return focus to the trigger element on close |
| `initialFocus` |   | Ref to the element that should receive focus on open |
| `portal` | `true` | Render via portal into `document.body` |
| `keepMounted` | `false` | Keep DOM node mounted when closed |
| `noAnimation` | `false` | Disable enter/exit transitions |
| `transitionDuration` | `200` | Animation duration in ms |

```tsx
{/* Custom focus target */}
<Modal open={open} onClose={onClose} initialFocus={inputRef}>
  <Input ref={inputRef} placeholder="Auto-focused" />
</Modal>

{/* Keep mounted for animation or state preservation */}
<Modal open={open} onClose={onClose} keepMounted transitionDuration={300}>
  <Text>Stays in DOM when closed</Text>
</Modal>
```

## Customizing

Set app-wide Modal defaults with `ThemeProvider`'s `themeDefaults`:

```tsx demo
const [open, setOpen] = useState(false);

return (
  <ThemeProvider themeDefaults={{
    modal: { content: { lg: true, border: true } },
  }}>
    <Button onClick={() => setOpen(true)}>Open Modal</Button>
    <Modal open={open} onClose={() => setOpen(false)}>Content</Modal>
  </ThemeProvider>
);
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans`, `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Padding: `padding`, `paddingX`, `paddingY`, `noPadding` (default)
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Border, Display, Flex Direction, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transparent, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Popup

> A floating element anchored to a trigger element using CSS Anchor Positioning. Supports 12 placement options, width matching, and click-outside dismissal.

Source: https://vaneui.com/docs/overlay-components/popup

Import: `import { Popup, Button, Divider, Input, PopupTrigger, Row, Text } from "@vaneui/ui"`

Popup holds content that floats beside the element that opened it, and Menu and Tooltip are built on it. It renders a `<div>` with `role="dialog"` unless `role` says otherwise. For a short hover hint, use a [Tooltip](/docs/overlay-components/tooltip); for a dialog that blocks the page, use a [Modal](/docs/overlay-components/modal). Its surface defaults are `md`, `flex column`, `padding`, `gap`, `rounded`, `border`, `shadow`, `primary`, `outline`, `wFit` and `placeBottom`.

> **Browser support:** Popup uses the CSS Anchor Positioning API (Chrome/Edge 129+, for the `span-*` alignment it relies on). Other browsers fall back to a JS positioning path that recomputes on scroll/resize.

## Basic usage

A controlled floating element anchored to a button. Closes on outside click or `Escape`. Pass an `anchorRef` pointing at the trigger element.

```tsx demo
const [open, setOpen] = useState(false);
const anchorRef = useRef<HTMLButtonElement>(null);

return (
  <>
    <Button ref={anchorRef} onClick={() => setOpen(!open)}>Toggle</Button>
    <Popup open={open} onClose={() => setOpen(false)} anchorRef={anchorRef}>
      <Text>Popup content</Text>
    </Popup>
  </>
);
```

## Uncontrolled with `defaultOpen`

Skip `open`/`onClose` and let Popup manage its own state. Use `onOpenChange` to react to opens/closes without owning the state.

```tsx demo
const anchorRef = useRef<HTMLButtonElement>(null);

return (
  <>
    <Button ref={anchorRef}>Trigger</Button>
    <Popup defaultOpen anchorRef={anchorRef} onOpenChange={(o) => console.log(o)}>
      <Text>Uncontrolled popup</Text>
    </Popup>
  </>
);
```

## PopupTrigger (click)

`PopupTrigger` is a convenience wrapper that manages open/close state and ref wiring automatically. No `useState` or `useRef` needed: wrap the trigger element and provide popup content via the `popup` prop. Default trigger mode is `"click"`.

```tsx demo
<PopupTrigger popup={<Text sm>Click-triggered popup</Text>}>
  <Button>Click Me</Button>
</PopupTrigger>
```

## PopupTrigger (hover)

Set `triggerOnHover` to show on mouse enter and hide on mouse leave. `openDelay` (default `0`) delays appearance; `closeDelay` (default `150`) delays dismissal so the user can move the cursor over the popup. Keyboard focus also opens it for accessibility.

```tsx demo
<PopupTrigger
  triggerOnHover
  openDelay={200}
  popup={<Text sm>Tooltip text</Text>}
>
  <Button>Hover Me</Button>
</PopupTrigger>
```

## PopupTrigger (focus)

Set `triggerOnFocus` to show on focus and hide on blur. Useful for search autocomplete, input hints, and dropdown suggestions.

```tsx demo
<PopupTrigger
  triggerOnFocus
  popup={<Text sm>Search suggestions...</Text>}
>
  <Input placeholder="Search..." />
</PopupTrigger>
```

## All 12 placements

Placement is set via boolean props: `placeTop`, `placeTopStart`, `placeTopEnd`, `placeBottom`, `placeBottomStart`, `placeBottomEnd`, `placeLeft`, `placeLeftStart`, `placeLeftEnd`, `placeRight`, `placeRightStart`, `placeRightEnd`. Exactly one wins (first-truthy per category). Default is `placeBottom`.

```tsx demo
const ref = useRef<HTMLButtonElement>(null);
const [open, setOpen] = useState(false);

return (
  <>
    <Button ref={ref} onClick={() => setOpen(!open)}>Anchor</Button>

    {/* Above the anchor, aligned to the anchor's left edge */}
    <Popup placeTopStart open={open} onClose={() => setOpen(false)} anchorRef={ref}>
      <Text>Top Start</Text>
    </Popup>

    {/* Centered to the right of the anchor */}
    <Popup placeRight open={open} onClose={() => setOpen(false)} anchorRef={ref}>
      <Text>Right</Text>
    </Popup>

    {/* Below the anchor, aligned to the anchor's right edge */}
    <Popup placeBottomEnd open={open} onClose={() => setOpen(false)} anchorRef={ref}>
      <Text>Bottom End</Text>
    </Popup>
  </>
);
```

When the requested placement would overflow the viewport, Popup falls back through `flip-block → flip-inline → shift → clamp` and exposes the resolved placement via the `data-placement` attribute.

## Size, shape, variant and appearance

Popup is `md`, `rounded`, `outline` and `primary` by default. Size drives the frame's padding, gap and radius together.

```tsx demo
const xsRef = useRef<HTMLButtonElement>(null);
const xlRef = useRef<HTMLButtonElement>(null);
const sharpRef = useRef<HTMLButtonElement>(null);
const filledRef = useRef<HTMLButtonElement>(null);

return (
  <Row flexWrap>
    <Button ref={xsRef}>xs</Button>
    <Popup xs defaultOpen anchorRef={xsRef}><Text xs>Extra small frame</Text></Popup>

    <Button ref={xlRef}>xl</Button>
    <Popup xl defaultOpen anchorRef={xlRef}><Text>Extra large frame</Text></Popup>

    <Button ref={sharpRef}>sharp</Button>
    <Popup sharp defaultOpen anchorRef={sharpRef}><Text>Sharp corners</Text></Popup>

    <Button ref={filledRef}>filled info</Button>
    <Popup filled info defaultOpen anchorRef={filledRef}><Text>Filled info surface</Text></Popup>
  </Row>
);
```

## Match anchor width

`matchWidth` makes the popup track the anchor's width, useful for select-like dropdowns. It sets the popup width to the anchor's width, overriding the default `wFit`.

```tsx demo
const [open, setOpen] = useState(false);
const anchorRef = useRef<HTMLButtonElement>(null);

return (
  <>
    <Button ref={anchorRef} onClick={() => setOpen(!open)} wFull>Select option</Button>
    <Popup matchWidth open={open} onClose={() => setOpen(false)} anchorRef={anchorRef}>
      <Text>Same width as the anchor</Text>
    </Popup>
  </>
);
```

## Rich content

Children render directly inside the Popup surface. Use layout primitives (`Col`, `Row`, `Stack`) to compose multi-element content. Avoid nesting another `Card` inside; Popup already provides the bordered, padded, shadowed surface.

```tsx demo
const [open, setOpen] = useState(false);
const anchorRef = useRef<HTMLButtonElement>(null);

return (
  <>
    <Button ref={anchorRef} onClick={() => setOpen(!open)}>Account</Button>
    <Popup open={open} onClose={() => setOpen(false)} anchorRef={anchorRef}>
      <Text fontBold>User Menu</Text>
      <Divider />
      <Button>Profile</Button>
      <Button danger>Sign Out</Button>
    </Popup>
  </>
);
```

## Tooltip pattern

Pair `triggerOnHover` with `arrow` for a classic tooltip. The arrow auto-rotates to match the resolved placement.

```tsx demo
<PopupTrigger
  triggerOnHover
  openDelay={300}
  popupProps={{ placeTop: true, arrow: true, role: "tooltip", sm: true }}
  popup={<Text sm>Save your changes to the server</Text>}
>
  <Button>Save</Button>
</PopupTrigger>
```

## Dropdown via Popup

Popup is a low-level primitive. For action menus with keyboard navigation, focus management, and item semantics, prefer the dedicated [`Menu`](./menu) component. It wraps Popup and adds `MenuItem`/`MenuLabel` with full arrow-key navigation. Reach for raw `Popup` only when you need a non-menu surface (filter panels, custom autocompletes, info cards).

```tsx demo
<PopupTrigger popup={
  <>
    <Button transparent justifyStart>Edit</Button>
    <Button transparent justifyStart>Duplicate</Button>
    <Divider />
    <Button transparent justifyStart danger>Delete</Button>
  </>
}>
  <Button>Actions</Button>
</PopupTrigger>
```

## Arrow indicator

Set `arrow` to render a pointer that visually links the popup to its anchor. The arrow is positioned automatically based on the resolved placement. With an arrow, `offset` is measured from the arrow tip, so the tip sits `offset` pixels from the anchor and never overlaps it (`@vaneui/ui` 1.5.0 or later).

```tsx demo
const [open, setOpen] = useState(false);
const anchorRef = useRef<HTMLButtonElement>(null);

return (
  <>
    <Button ref={anchorRef} onClick={() => setOpen(!open)}>Toggle Arrow Popup</Button>
    <Popup arrow open={open} onClose={() => setOpen(false)} anchorRef={anchorRef}>
      <Text sm>Arrow points at the anchor.</Text>
    </Popup>
  </>
);
```

## Click-outside behavior

By default, clicking anywhere outside the popup or anchor closes it. Set `closeOnClickOutside={false}` to require an explicit dismiss (e.g., a close button inside the popup). `closeOnEscape={false}` similarly disables the keyboard dismiss.

```tsx demo
const [open, setOpen] = useState(false);
const anchorRef = useRef<HTMLButtonElement>(null);

return (
  <>
    <Button ref={anchorRef} onClick={() => setOpen(true)}>Open Sticky Popup</Button>
    <Popup
      open={open}
      onClose={() => setOpen(false)}
      anchorRef={anchorRef}
      closeOnClickOutside={false}
      closeOnEscape={false}
    >
      <Text>Stays open until dismissed.</Text>
      <Button sm onClick={() => setOpen(false)}>Close</Button>
    </Popup>
  </>
);
```

## Disabled trigger

Set `disabled` on `Popup` (or `PopupTrigger`) to suppress opening regardless of `open` state. Useful for conditional UI where the trigger remains rendered but inactive.

```tsx demo
<PopupTrigger disabled popup={<Text>Hidden</Text>}>
  <Button disabled>Cannot open</Button>
</PopupTrigger>
```

## Advanced props

`Popup` supports additional configuration props:

| Prop | Default | Description |
|------|---------|-------------|
| `offset` | `4` | Distance from anchor in pixels; with `arrow`, measured from the arrow tip |
| `style` |   | Merged with the positioning styles, which win on a conflict (before 1.5.0 it replaced them) |
| `closeOnEscape` | `true` | Close on `Escape` key press |
| `closeOnClickOutside` | `true` | Close when clicking outside the popup or anchor |
| `portal` | `true` | Render via portal into `document.body` |
| `keepMounted` | `false` | Keep DOM node mounted when closed |
| `noAnimation` | `false` | Disable enter/exit transitions |
| `transitionDuration` | `200` | Animation duration in ms |
| `disabled` | `false` | Prevent popup from opening |
| `hideWhenDetached` | `false` | Hide when anchor scrolls out of view (uses `IntersectionObserver`) |
| `role` | `"dialog"` | ARIA role (set `"tooltip"` for tooltip patterns) |
| `arrow` | `false` | Render arrow pointer |
| `onEnterComplete` |   | Called when the enter transition finishes |
| `onExitComplete` |   | Called when the exit transition finishes |

`PopupTrigger` additionally accepts:

| Prop | Default | Description |
|------|---------|-------------|
| `triggerOnClick` | `true` (when no other trigger set) | Toggle on click |
| `triggerOnHover` | `false` | Open on mouse enter / focus |
| `triggerOnFocus` | `false` | Open on focus only |
| `openDelay` | `0` | ms before opening on hover |
| `closeDelay` | `150` | ms before closing on hover-out |
| `popupProps` |   | Props forwarded to the internal `Popup` |
| `popupId` | auto | Override generated id for `aria-controls` |

```tsx demo
const [open, setOpen] = useState(false);
const anchorRef = useRef<HTMLButtonElement>(null);

return (
  <>
    <Button ref={anchorRef} onClick={() => setOpen(!open)}>Custom Config</Button>
    <Popup
      open={open}
      onClose={() => setOpen(false)}
      anchorRef={anchorRef}
      offset={8}
      noAnimation
      closeOnEscape={false}
    >
      <Text>Custom config</Text>
    </Popup>
  </>
);
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Placement: `placeTop`, `placeTopStart`, `placeTopEnd`, `placeBottom` (default), `placeBottomStart`, `placeBottomEnd`, `placeLeft`, `placeLeftStart`, `placeLeftEnd`, `placeRight`, `placeRightStart`, `placeRightEnd`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm`, `md` (default), `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Variant: `filled`, `outline` (default), `ghost`

Layout and utility props (Align Self, Border, Clamp Height, Constrain Width, Display, Flex Direction, Gap, Height, Hide, Items, Justify, Justify Self, Overflow, Pointer Events, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Menu

> A dropdown menu triggered by a button with full keyboard navigation. Contains MenuItem, Divider, and MenuLabel subcomponents.

Source: https://vaneui.com/docs/overlay-components/menu

Import: `import { Menu, Button, Divider, IconButton, MenuItem, MenuLabel, Row, Tooltip } from "@vaneui/ui"`

Menu holds actions that apply to one object or view, such as edit, duplicate or share. The dropdown is a Popup with `role="menu"`, each MenuItem is a `<button>` with `role="menuitem"` by default, and the trigger gets `aria-haspopup="menu"` and `aria-expanded`. To pick a value that a form submits, use [Select](/docs/form-components/select); for navigation that stays visible in a sidebar or header, use [NavLink](/docs/basic-components/navlink).

## Basic usage

A dropdown menu triggered by a button. Pass the trigger as a React element via the `trigger` prop; children are the menu contents. Includes full keyboard navigation (Arrow keys, Enter, Escape, Tab) and focus management with a keyboard-visible outline on each item. Focus returns to the trigger when the menu closes. Escape closes only the topmost layer: a submenu before its parent menu, and a menu inside a `Modal` before the dialog. Moving the pointer to another item closes a submenu that is open.

```tsx demo
<Menu trigger={<Button>Actions</Button>}>
  <MenuItem>Edit</MenuItem>
  <MenuItem>Duplicate</MenuItem>
  <MenuItem>Share</MenuItem>
</Menu>
```

## Labels and dividers

Use `MenuLabel` for section headings and `Divider` for visual separators between groups. `Divider` automatically picks up the Menu's size via the menu-divider sub-theme.

```tsx demo
<Menu trigger={<Button>Account</Button>}>
  <MenuLabel>Account</MenuLabel>
  <MenuItem>Profile</MenuItem>
  <MenuItem>Settings</MenuItem>
  <Divider />
  <MenuLabel>Workspace</MenuLabel>
  <MenuItem>Members</MenuItem>
  <MenuItem>Billing</MenuItem>
  <Divider />
  <MenuItem>Sign out</MenuItem>
</Menu>
```

## Items with icons

Place SVG icons directly inside `MenuItem`. They are automatically flex-aligned and pointer-events-disabled so clicks pass through to the item.

```tsx demo
<Menu trigger={<Button>File</Button>}>
  <MenuItem><Edit size={14} /> Edit</MenuItem>
  <MenuItem><Copy size={14} /> Duplicate</MenuItem>
  <Divider />
  <MenuItem danger><Trash2 size={14} /> Delete</MenuItem>
</Menu>
```

## Destructive item

Use the `danger` appearance prop on a `MenuItem` to flag a destructive action. Combine with a `Divider` to visually separate it from safe actions.

```tsx demo
<Menu trigger={<Button>Manage</Button>}>
  <MenuItem>Rename</MenuItem>
  <MenuItem>Archive</MenuItem>
  <Divider />
  <MenuItem danger>Delete permanently</MenuItem>
</Menu>
```

## Item appearances

Any appearance prop works on `MenuItem` for semantic coloring of individual actions.

```tsx demo
<Menu trigger={<Button>Review</Button>}>
  <MenuItem success>Approve</MenuItem>
  <MenuItem warning>Request changes</MenuItem>
  <MenuItem danger>Reject</MenuItem>
</Menu>
```

## Disabled items

Set `disabled` on a `MenuItem` to prevent interaction. Disabled items are skipped during keyboard navigation and announced via `aria-disabled`.

```tsx demo
<Menu trigger={<Button>Edit</Button>}>
  <MenuItem>Undo</MenuItem>
  <MenuItem disabled>Redo</MenuItem>
  <Divider />
  <MenuItem>Cut</MenuItem>
  <MenuItem>Copy</MenuItem>
  <MenuItem disabled>Paste</MenuItem>
</Menu>
```

## Items as links

Pass `href` to render a `MenuItem` as an anchor tag. For client-side navigation in a Next.js app, also pass `tag={Link}`.

```tsx demo
<Menu trigger={<Button>Navigate</Button>}>
  <MenuItem href="/settings">Settings</MenuItem>
  <MenuItem href="/profile">Profile</MenuItem>
  <Divider />
  <MenuItem href="https://github.com" target="_blank">GitHub</MenuItem>
</Menu>
```

## Selected items

A `MenuItem` with `aria-selected="true"` takes the hover fill, the same rule NavLink follows, so an item stays highlighted while the pointer and focus are elsewhere. The rule needs `@vaneui/ui` 1.4.5 or later.

MenuItem renders `role="menuitem"` by default, and ARIA defines no selected state for a menu item, so assistive technology may ignore `aria-selected` there. Treat the fill as a visual highlight only. For a list of options with one selected, such as search results under a search box, use NavLink with `role="option"` inside a `role="listbox"` container, where `aria-selected` is announced.

## Checkable items

A `MenuItem` keeps a `role` you pass, so `role="menuitemcheckbox"` or `role="menuitemradio"` with `aria-checked` makes a checkable item, and assistive technology announces the checked state. Keep your own state, show the mark yourself, and set `closeMenuOnClick={false}` to keep the menu open while the user toggles. This needs `@vaneui/ui` 1.5.0 or later.

```tsx demo
const [grid, setGrid] = useState(true);
const [density, setDensity] = useState('comfortable');
const mark = (on: boolean) => <Check size={14} style={{ visibility: on ? 'visible' : 'hidden' }} />;

return (
  <Menu trigger={<Button>View</Button>}>
    <MenuItem role="menuitemcheckbox" aria-checked={grid} closeMenuOnClick={false} onClick={() => setGrid(!grid)}>
      {mark(grid)} Show grid
    </MenuItem>
    <Divider />
    <MenuItem role="menuitemradio" aria-checked={density === 'comfortable'} closeMenuOnClick={false} onClick={() => setDensity('comfortable')}>
      {mark(density === 'comfortable')} Comfortable
    </MenuItem>
    <MenuItem role="menuitemradio" aria-checked={density === 'compact'} closeMenuOnClick={false} onClick={() => setDensity('compact')}>
      {mark(density === 'compact')} Compact
    </MenuItem>
  </Menu>
);
```

## Shape, variant and appearance

The props you set on `Menu` reach the dropdown frame, so the popup takes the shape, variant and appearance rather than the trigger.

```tsx demo
<Row flexWrap>
  <Menu trigger={<Button>rounded, the default</Button>}>
    <MenuItem>Edit</MenuItem>
    <MenuItem>Duplicate</MenuItem>
  </Menu>
  <Menu sharp trigger={<Button>sharp</Button>}>
    <MenuItem>Edit</MenuItem>
    <MenuItem>Duplicate</MenuItem>
  </Menu>
  <Menu filled secondary trigger={<Button>filled secondary</Button>}>
    <MenuItem>Edit</MenuItem>
    <MenuItem>Duplicate</MenuItem>
  </Menu>
  <Menu border info trigger={<Button>info border</Button>}>
    <MenuItem>Edit</MenuItem>
    <MenuItem>Duplicate</MenuItem>
  </Menu>
</Row>
```

## Sizes

Set a size on `Menu` (e.g. `<Menu lg>`) and the dropdown popup, every `MenuItem`, `MenuLabel`, and nested `Divider` scale together automatically. No need to repeat the size on every child. Items render with larger font-size and padding, the popup frame lifts its inner padding, and dividers match. Individual children can still override with their own size prop.

```tsx demo
<Row flexWrap>
  <Menu xs trigger={<Button xs>xs</Button>}>
    <MenuLabel>Actions</MenuLabel>
    <MenuItem>Edit</MenuItem>
    <Divider />
    <MenuItem danger>Delete</MenuItem>
  </Menu>
  <Menu sm trigger={<Button sm>sm</Button>}>
    <MenuLabel>Actions</MenuLabel>
    <MenuItem>Edit</MenuItem>
    <Divider />
    <MenuItem danger>Delete</MenuItem>
  </Menu>
  <Menu md trigger={<Button md>md</Button>}>
    <MenuLabel>Actions</MenuLabel>
    <MenuItem>Edit</MenuItem>
    <Divider />
    <MenuItem danger>Delete</MenuItem>
  </Menu>
  <Menu lg trigger={<Button lg>lg</Button>}>
    <MenuLabel>Actions</MenuLabel>
    <MenuItem>Edit</MenuItem>
    <Divider />
    <MenuItem danger>Delete</MenuItem>
  </Menu>
  <Menu xl trigger={<Button xl>xl</Button>}>
    <MenuLabel>Actions</MenuLabel>
    <MenuItem>Edit</MenuItem>
    <Divider />
    <MenuItem danger>Delete</MenuItem>
  </Menu>
</Row>
```

## Controlled state

Pass `open` and `onOpenChange` to drive the menu from outside state. Useful when you need to open the menu programmatically or react to its state.

```tsx demo
const [open, setOpen] = useState(false);

return (
  <Menu
    open={open}
    onOpenChange={setOpen}
    trigger={<Button>Menu ({open ? "open" : "closed"})</Button>}
  >
    <MenuItem onClick={() => console.log("Edit")}>Edit</MenuItem>
    <MenuItem closeMenuOnClick={false}>Stay open on click</MenuItem>
    <MenuItem>Close on click (default)</MenuItem>
  </Menu>
);
```

## Tooltip on the trigger

To label an icon-only trigger, wrap it in a [Tooltip](/docs/overlay-components/tooltip) and pass the Tooltip as the `trigger`. The menu's ref, click handler and `aria-haspopup` and `aria-expanded` attributes go to the button inside, so the menu opens on click and anchors to it, while the tooltip shows on hover and focus. This needs `@vaneui/ui` 1.5.0 or later.

```tsx demo
<Menu trigger={
  <Tooltip content="Options">
    <IconButton aria-label="Options"><Settings /></IconButton>
  </Tooltip>
}>
  <MenuItem>Edit</MenuItem>
  <MenuItem>Duplicate</MenuItem>
  <Divider />
  <MenuItem danger>Delete</MenuItem>
</Menu>
```

## Advanced props

Menu supports additional configuration for fine-tuning behavior:

| Prop | Default | Description |
|------|---------|-------------|
| `open` |   | Controlled open state |
| `defaultOpen` | `false` | Initial open state (uncontrolled) |
| `onOpenChange` |   | Called when open state changes |
| `onClose` |   | Called when the menu closes |
| `closeOnItemClick` | `true` | Close menu when any item is clicked |
| `loop` | `true` | Loop keyboard navigation from last to first |
| `disabled` | `false` | Prevent menu from opening |
| `transitionDuration` | `150` | Animation duration in ms |

`MenuItem` also accepts:

| Prop | Default | Description |
|------|---------|-------------|
| `closeMenuOnClick` | inherits | Override the menu-level `closeOnItemClick` for this item |
| `href` |   | Render as anchor tag |
| `disabled` | `false` | Prevent interaction |
| `focusVisible` | `true` | Render a keyboard focus-visible outline |
| `noFocusVisible` |   | Disable the keyboard focus-visible outline |

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Disabled: `disabled`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Inherit Size: `inheritSize`, `noInheritSize`
- Padding: `padding` (default), `paddingX`, `paddingY`, `noPadding`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm` (default), `md`, `lg`, `xl`
- Text Align: `textLeft` (default), `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Variant: `filled`, `outline` (default), `ghost`
- Word Break: `breakNormal`, `breakWords`, `breakAll`, `breakKeep`

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Tooltip

> A short ink label that describes its trigger on hover and keyboard focus. Comes in sizes xs to xl and takes Popup props directly.

Source: https://vaneui.com/docs/overlay-components/tooltip

Import: `import { Tooltip, Button, IconButton, PopupTrigger, Row, Text, ThemeProvider } from "@vaneui/ui"`

Tooltip is for hints of a few words, such as a keyboard shortcut or the full text of an abbreviation. The hint renders as a Popup with `role="tooltip"`, so opening it does not move focus. For content the user clicks into, such as a form or a list of links, open a [Popup](/docs/overlay-components/popup) on click instead; for a list of actions, use a [Menu](/docs/overlay-components/menu).

## Basic usage

Tooltip describes its trigger with a short hint on hover and on keyboard focus. Pass the trigger as the child and the hint as `content`. The hint renders as an ink label: near-black in light mode, near-white in dark mode.

```tsx demo
<Tooltip content="Saves without leaving the page">
  <Button>Save</Button>
</Tooltip>
```

The trigger must accept a ref. `Button`, `IconButton`, `Badge`, `Link` and the other element components do.

Tooltip takes [Popup](/docs/overlay-components/popup) props directly (size, appearance, variant, shape, placement, `arrow`, `offset`, `className` and the rest), and they style the label. Its own props are `content`, `open`, `defaultOpen`, `onOpenChange`, `openDelay` (default `300`), `closeDelay` (default `100`), `popupProps`, `popupId` and `disabled`.

## Keyboard and pointer

A tooltip that only opens on hover is invisible to keyboard users, so Tooltip opens on focus too. Tab to the second button to see it.

```tsx demo
<Row flexWrap>
  <Tooltip content="Opens on hover">
    <Button secondary>Hover me</Button>
  </Tooltip>
  <Tooltip content="Opens on focus as well">
    <Button secondary>Tab to me</Button>
  </Tooltip>
</Row>
```

## Sizes

Tooltip defaults to `sm`. Its text, padding and corner radius follow its own size, `xs` to `xl`, and the text sits one font step under a Button of the same size. The tooltip does not shrink on phones.

```tsx demo
<Row flexWrap>
  <Tooltip xs content="An xs tooltip">
    <Button xs>xs</Button>
  </Tooltip>
  <Tooltip content="An sm tooltip, the default">
    <Button>sm</Button>
  </Tooltip>
  <Tooltip md content="An md tooltip">
    <Button md>md</Button>
  </Tooltip>
  <Tooltip lg content="An lg tooltip">
    <Button lg>lg</Button>
  </Tooltip>
  <Tooltip xl content="An xl tooltip">
    <Button xl>xl</Button>
  </Tooltip>
</Row>
```

## Placement

Tooltip opens above its trigger and flips to the other side when there is no room. All twelve `place*` props from Popup work on `Tooltip` directly, and `arrow` adds a pointer. With `arrow`, the gap (`offset`, 4px by default) is measured from the arrow tip, so the tip sits that far from the trigger instead of touching it. Top and bottom tooltips stay on screen when the trigger sits at the edge of the viewport.

```tsx demo
<Row flexWrap>
  <Tooltip content="Above">
    <Button>Top</Button>
  </Tooltip>
  <Tooltip placeBottom content="Below">
    <Button>Bottom</Button>
  </Tooltip>
  <Tooltip placeRight content="To the right">
    <Button>Right</Button>
  </Tooltip>
  <Tooltip placeRight arrow content="Points at its trigger">
    <Button>Arrow</Button>
  </Tooltip>
</Row>
```

## Long hints

A long hint wraps inside a width cap that grows with size, from 16 to 32rem across `xs` to `xl` and 20rem at the default `sm`, instead of running across the page.

```tsx demo
<Tooltip content="Archiving moves the conversation out of your inbox. Replies bring it back, and nothing is deleted.">
  <Button secondary>Archive</Button>
</Tooltip>
```

## Color and shape

Appearance, variant and shape props restyle the label. `secondary` restores the gray look of earlier versions.

```tsx demo
<Row flexWrap>
  <Tooltip content="Ink, the default">
    <Button>default</Button>
  </Tooltip>
  <Tooltip secondary content="Gray">
    <Button>secondary</Button>
  </Tooltip>
  <Tooltip danger content="Deletes the project for everyone">
    <Button danger>danger</Button>
  </Tooltip>
  <Tooltip sharp content="Sharp corners">
    <Button>sharp</Button>
  </Tooltip>
  <Tooltip outline danger border content="Outline danger">
    <Button>outline danger</Button>
  </Tooltip>
</Row>
```

To change every tooltip in an app, set the default once on [`ThemeProvider`](/docs/customization/using-theme-provider):

```tsx
<ThemeProvider themeDefaults={{ tooltip: { secondary: true } }}>
  <App />
</ThemeProvider>
```

`popupProps` is still supported and is combined with the direct props, which helps when several tooltips share one props object. Pass one value per category (one size, one appearance, and so on) across the two.

## Delays

`openDelay` keeps tooltips from flashing as the pointer crosses the screen. `closeDelay` gives the pointer time to move onto the tooltip itself.

```tsx demo
<Row flexWrap>
  <Tooltip content="Appears at once" openDelay={0}>
    <Button>No delay</Button>
  </Tooltip>
  <Tooltip content="Waits half a second" openDelay={500}>
    <Button>Slow</Button>
  </Tooltip>
</Row>
```

## Accessibility

A tooltip describes its trigger, so while it is open the trigger carries `aria-describedby` pointing at it. It never gets `aria-haspopup` or `aria-expanded`, because those describe a disclosure, not a description, and there is no `aria-haspopup` value for tooltips.

Keep the content short and non-essential. Anything the user must read to complete a task belongs in the page, not behind a hover.

## Icon-only triggers

A common use is explaining a control that has no visible label.

```tsx demo
<Row>
  <Text sm>API key</Text>
  <Tooltip content="Rotating the key invalidates the old one immediately">
    <IconButton secondary aria-label="About API keys">?</IconButton>
  </Tooltip>
</Row>
```

## Tooltip on a Menu or PopupTrigger trigger

A Tooltip can be the trigger of a [Menu](/docs/overlay-components/menu) or a `PopupTrigger`. The ref, event handlers and `aria-*` attributes they pass to their trigger go on to the Tooltip's child, so a click opens the popup, it anchors to the button, and the tooltip still describes it on hover and focus. This needs `@vaneui/ui` 1.5.0 or later.

```tsx demo
<PopupTrigger popup={<Text sm>Display settings</Text>}>
  <Tooltip content="Settings">
    <IconButton aria-label="Settings"><Settings /></IconButton>
  </Tooltip>
</PopupTrigger>
```

## Props

- Appearance: `primary` (default), `accent`, `secondary`, `tertiary`, `success`, `danger`, `warning`, `info`, `inheritAppearance`
- Flex: `flex1`, `flexAuto`, `flexNone`
- Font Family: `fontSans` (default), `fontSerif`, `fontMono`, `fontHeading`
- Font Style: `italic`, `notItalic`
- Font Weight: `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- Padding: `padding`, `paddingX`, `paddingY`, `noPadding`
- Placement: `placeTop` (default), `placeTopStart`, `placeTopEnd`, `placeBottom`, `placeBottomStart`, `placeBottomEnd`, `placeLeft`, `placeLeftStart`, `placeLeftEnd`, `placeRight`, `placeRightStart`, `placeRightEnd`
- Shape: `pill`, `sharp`, `rounded` (default)
- Shrink: `noShrink`
- Size: `xs`, `sm` (default), `md`, `lg`, `xl`
- Text Align: `textLeft`, `textCenter`, `textRight`, `textJustify`, `textStart`, `textEnd`
- Text Decoration: `underline`, `lineThrough`, `noUnderline`, `overline`
- Text Transform: `uppercase`, `lowercase`, `capitalize`, `normalCase`
- Truncate: `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`
- Variant: `filled` (default), `outline`, `ghost`

Layout and utility props (Align Self, Border, Clamp Height, Constrain Width, Display, Flex Direction, Gap, Height, Hide, Items, Justify, Justify Self, Overflow, Pointer Events, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).

# Theming Overview

> How VaneUI theming works: ComponentTheme classes, class mappers, ThemeProvider props and data attributes that style every React component via Tailwind CSS.

Source: https://vaneui.com/docs/customization/theming-overview

Import: `import { Button, Card, ThemeProvider, useTheme } from "@vaneui/ui"`

VaneUI uses a theme system based on `ComponentTheme` classes that define styling for each component. This page explains the theme architecture and how to customize it.

## Theme architecture

### ComponentTheme class

Each component has a `ComponentTheme` instance that defines:
- **tag**: Default HTML element (e.g., "button", "div")
- **base**: Base CSS classes always applied
- **themes**: Tree of `BaseClassMapper` subclasses that generate CSS classes
- **defaults**: Default prop values
- **categories**: Which prop categories the component uses

```tsx
// Simplified view of how a component theme is structured
const buttonTheme = new ComponentTheme(
  "button",                           // Default tag
  "vane-button",                      // Base classes (kept minimal)
  {
    size: { px, py, text, gap },      // Size-related themes
    appearance: { bg, text, border }, // Appearance themes
    layout: { radius, border, ring }  // Layout themes
  },
  buttonDefaults,                     // Imported from buttonDefaults.ts
  BUTTON_CATEGORIES                   // Prop categories
);
```

### BaseClassMapper subclasses

Each `BaseClassMapper` subclass generates specific CSS classes based on extracted props:

```tsx
// FontSizeClassMapper returns consumer class for font size
class FontSizeClassMapper extends BaseClassMapper {
  getClasses(extractedKeys) {
    return ["text-(length:--fs)"];  // Consumes --fs CSS variable
  }
}

// SimpleConsumerClassMapper returns classes that consume color variables
class SimpleConsumerClassMapper extends BaseClassMapper {
  getClasses(extractedKeys) {
    if (!extractedKeys.appearance) return [];
    return ["bg-(--bg-color)", "text-(--text-color)"];
  }
}
```

## Accessing the theme

Use the `useTheme` hook to access the current theme:

```tsx
import { useTheme } from '@vaneui/ui';

function CustomComponent() {
  const theme = useTheme();

  // Compound themes are nested by sub-part
  const buttonMainTheme = theme?.button.main;
  const cardMainTheme = theme?.card.main;
  // Single-target themes are accessed directly
  const badgeTheme = theme?.badge;

  return <div>Custom component</div>;
}
```

## Available component themes

VaneUI includes themes for all components.

**Interactive:**
- `iconButton`, `badge`, `icon`, `chip`, `code`, `kbd`, `mark`, `input`, `label`, `img`, `spinner`
- `inputErrorIcon`, `inputWrapper`, `textarea`, `select`, `selectChevron`, `selectWrapper`, `radioGroup`
- `button`: compound with `button.main`, `button.spinner`
- `checkbox`: compound with `checkbox.input`, `checkbox.check`, `checkbox.indeterminate`, `checkbox.wrapper`
- `radio`: compound with `radio.input`, `radio.dot`, `radio.wrapper`
- `switch`: compound with `switch.input`, `switch.thumb`, `switch.wrapper`
- `field`: compound with `field.main`, `field.label`, `field.controlRow`, `field.description`, `field.error`

**Layout:**
- `divider`, `container`, `row`, `col`, `stack`, `section`, `alert`
- `grid2`, `grid3`, `grid4`, `grid5`, `grid6`
- `card`: compound with `card.main`, `card.header`, `card.body`, `card.footer`
- `table`: compound with `table.main`, `table.thead`, `table.tbody`, `table.tfoot`, `table.tr`, `table.th`, `table.td`, `table.caption`

**Typography:**
- `text`, `title`, `pageTitle`, `sectionTitle`, `blockquote`, `blockquoteCite`, `link`, `list`, `listItem`

**Overlay / Floating:**
- `overlay`: Overlay backdrop theme
- `popup`: Popup floating element theme
- `tooltip`: Tooltip floating element theme
- `modal`: compound with `modal.content`, `modal.overlay`, `modal.header`, `modal.body`, `modal.footer`, `modal.closeButton`
- `menu`: compound with `menu.item`, `menu.popup`, `menu.divider`, `menu.label`
- `navLink`: compound with `navLink.root`, `navLink.label`

## ThemeProvider props

### themeDefaults

[Set default prop values](/docs/customization/theme-defaults) for components:

```tsx
import { ThemeProvider, type ThemeDefaults } from '@vaneui/ui';

const defaults: ThemeDefaults = {
  button: {
    main: {
      filled: true, // change variant from outline (built-in) to filled
      lg: true,     // larger than built-in sm
    },
  },
  card: {
    main: { shadow: true }, // add shadow (not a default)
  },
};

<ThemeProvider themeDefaults={defaults}>
  <Button>Large filled button</Button>
  <Card>Card with shadow</Card>
</ThemeProvider>
```

### extraClasses

[Add additional CSS classes](/docs/customization/extra-classes) based on active props:

```tsx
import type { ThemeExtraClasses } from '@vaneui/ui';

const extraClasses: ThemeExtraClasses = {
  button: {
    main: {
      primary: 'shadow-lg hover:shadow-xl transition-shadow',
      danger: 'animate-pulse',
    },
  },
  card: {
    main: { filled: 'backdrop-blur-sm' },
  },
};

<ThemeProvider extraClasses={extraClasses}>
  <Button primary>Button with shadow</Button>
  <Button danger>Pulsing danger button</Button>
</ThemeProvider>
```

### themeOverride

A function with [direct access to the full theme](/docs/customization/theme-and-override), for changes the declarative options can't express (like appending to a component's base classes):

```tsx
<ThemeProvider themeOverride={(theme) => {
  // Modify button base classes
  theme.button.main.base += ' uppercase tracking-wide';

  // Modify defaults
  theme.button.main.defaults = {
    ...theme.button.main.defaults,
    fontSemibold: false, // clear the built-in weight, or it wins over fontBold
    fontBold: true,
  };

  return theme;
}}>
  <App />
</ThemeProvider>
```

### mergeStrategy

Control how nested ThemeProviders combine:

```tsx
// Default: 'merge' - child theme merges with parent
<ThemeProvider themeDefaults={{ button: { main: { lg: true } } }}>
  <ThemeProvider themeDefaults={{ button: { main: { filled: true } } }}>
    {/* Button gets both lg AND filled */}
    <Button>Large Filled</Button>
  </ThemeProvider>
</ThemeProvider>

// 'replace' - child theme replaces parent entirely (resets to defaultTheme + child)
<ThemeProvider themeDefaults={{ button: { main: { lg: true } } }}>
  <ThemeProvider
    themeDefaults={{ button: { main: { sm: true } } }}
    mergeStrategy="replace"
  >
    {/* Button is small only (parent's lg is ignored) */}
    <Button>Small Only</Button>
  </ThemeProvider>
</ThemeProvider>
```

## Data attributes

Components emit data attributes that CSS rules use for styling:

```html
<button
  class="vane-button text-(length:--fs) py-(--py) ..."
  data-vane-type="ui"
  data-size="md"
  data-appearance="danger"
  data-variant="filled"
>
  Click me
</button>
```

CSS rules in `rules.css` set [unit variables](/docs/customization/css-variables) per `data-size` and per-component class. `--fs-unit`, `--py-unit`, and (for Icon) `--icon-size` are all set together so font-size, padding, gap, and border-radius scale together:

```css
/* Per-component size mapping */
.vane-button[data-size="md"] {
  --fs-unit: var(--fs-unit-md);
  --py-unit: 2;
}

/* Icon uses a decoupled --icon-size, not --fs */
.vane-icon[data-size="md"] {
  --fs-unit: var(--fs-unit-md);
  --icon-size: calc(var(--spacing) * 8);
  --py-unit: 2;
}

/* Appearance + variant set the color palette */
[data-variant="filled"][data-appearance="danger"] {
  --text-color: var(--color-text-filled-danger);
  --bg-color: var(--color-bg-filled-danger);
}
```

## Color inheritance

Components with a concrete appearance emit `data-appearance` and `data-variant` and paint their own colors, so a default `<Button>` inside a filled `<Card>` keeps its own primary-outline palette. Inheritance is opt-in: only inherit-mode components (Text, Title, SectionTitle, PageTitle, Blockquote, Label, List, Divider, and Spinner, which default to `inheritAppearance`) and appearance-less `Icon` and `ListItem` emit nothing and read their colors from the nearest ancestor. The `:root` palette is the fallback those inherit-mode components use when no ancestor sets colors. See [Variant Inheritance](./variant-inheritance) for details.

## Style resolution flow

1. User writes: `<Button danger lg filled>Click</Button>`
2. Button component calls `useTheme()` to get `theme.button.main`
3. `ThemedComponent` calls `theme.getComponentConfig(props)`
4. Props merged with defaults, then extracted by category: `{ size: 'lg', appearance: 'danger', variant: 'filled' }`
5. Theme tree is walked, each `BaseClassMapper.getClasses()` returns CSS classes
6. Classes are merged with `twMerge()`, data attributes are added (because `danger` is a concrete, non-`inheritAppearance` appearance)
7. Final render: `<button class="..." data-vane-type="ui" data-size="lg" data-appearance="danger" data-variant="filled">`
8. CSS rules in `rules.css` set unit variables and the appearance/variant palette
9. Browser computes final styles from CSS variables

# Using ThemeProvider

> Wrap a React app in VaneUI's ThemeProvider to set default props for every component, add Tailwind CSS classes per prop, override the theme, or nest themes.

Source: https://vaneui.com/docs/customization/using-theme-provider

Import: `import { Badge, Button, Card, Section, ThemeProvider, useTheme } from "@vaneui/ui"`

The ThemeProvider is the foundation of VaneUI's theming system. It wraps your application and provides theme context to all child components, enabling consistent styling and customization throughout your app.

## Basic setup

### Minimal ThemeProvider

The most basic setup requires no configuration. Components use their built-in defaults:

```tsx
import { ThemeProvider, Button, Badge, Card } from '@vaneui/ui';

function App() {
  return (
    <ThemeProvider>
      <div>
        <Button>Default Button</Button>
        <Badge>Default Badge</Badge>
        <Card>Default Card</Card>
      </div>
    </ThemeProvider>
  );
}
```

### Setting default props

Configure default [boolean props](/docs/getting-started/core-concepts) for all components:

```tsx
import { ThemeProvider, Button, Card } from '@vaneui/ui';

function App() {
  return (
    <ThemeProvider themeDefaults={{
      button: {
        main: {
          lg: true,        // larger than built-in sm
          filled: true,    // override built-in outline
        },
      },
      card: {
        main: {
          shadow: true,    // add shadow (not a default)
        },
      },
    }}>
      <Button>Large Filled Button</Button>
      <Card>Card with Shadow</Card>
    </ThemeProvider>
  );
}
```

Most components take props directly. **Components with sub-themes** (`button`, `card`, `checkbox`, `field`, `radio`, `switch`, `modal`, `menu`, `navLink`, `table`) are nested by sub-theme name (`main`, `content`, `input`, `item`, `root`, etc.). For example, `Checkbox` keeps its box props under `input`: `themeDefaults={{ checkbox: { input: { lg: true, success: true } } }}` makes every checkbox large and green.

## ThemeProvider props

### themeDefaults

Set default boolean props per component type:

```tsx
<ThemeProvider themeDefaults={{
  button: { main: { md: true, filled: true } }, // nested under `main`
  badge: { success: true, sm: true },
  card: { main: { secondary: true } },          // nested under `main`
  text: { primary: true },
}}>
  <App />
</ThemeProvider>
```

### extraClasses

Add additional CSS classes based on active props:

```tsx demo
<ThemeProvider extraClasses={{
  button: {
    main: {
      primary: 'shadow-lg hover:shadow-xl transition-shadow',
      danger: 'animate-pulse',
    },
  },
  card: {
    main: { filled: 'backdrop-blur-sm' },
  },
}}>
  <Button primary>Button with shadow</Button>
  <Button danger>Pulsing danger button</Button>
</ThemeProvider>
```

### themeOverride

A function with [direct access to the full theme](/docs/customization/theme-and-override), for changes the declarative options can't express (like appending to a component's base classes):

```tsx
<ThemeProvider themeOverride={(theme) => {
  // Modify base classes
  theme.button.main.base += ' uppercase tracking-wide';

  // Modify default props
  theme.button.main.defaults = {
    ...theme.button.main.defaults,
    fontSemibold: false, // clear the built-in weight, or it wins over fontBold
    fontBold: true,
  };

  return theme;
}}>
  <App />
</ThemeProvider>
```

### mergeStrategy

Control how nested ThemeProviders combine (`'merge'` or `'replace'`):

```tsx demo
<ThemeProvider themeDefaults={{ button: { main: { lg: true } } }}>
  {/* mergeStrategy='merge' (default): child merges with parent */}
  <ThemeProvider themeDefaults={{ button: { main: { filled: true } } }}>
    <Button>Large Filled (both applied)</Button>
  </ThemeProvider>

  {/* mergeStrategy='replace': child resets to defaultTheme + its own defaults */}
  <ThemeProvider
    themeDefaults={{ button: { main: { sm: true } } }}
    mergeStrategy="replace"
  >
    <Button>Small Only (parent ignored)</Button>
  </ThemeProvider>
</ThemeProvider>
```

## Nested theming

Override themes for specific sections of your app:

```tsx
import { ThemeProvider, Button, Badge, Section } from '@vaneui/ui';

function NestedThemeApp() {
  return (
    <ThemeProvider themeDefaults={{
      button: { main: { fontBold: true } } // bold buttons across the app
    }}>
      <div>
        <Button>Bold Primary Outline Button</Button>

        <Section>
          {/* Override for this section only */}
          <ThemeProvider themeDefaults={{
            button: { main: { success: true, filled: true } }
          }}>
            <Button>Bold Success Filled Button</Button>
            <Badge>Inherits parent badge defaults</Badge>
          </ThemeProvider>
        </Section>
      </div>
    </ThemeProvider>
  );
}
```

## Accessing theme context

Use the `useTheme` hook to access theme values in custom components:

```tsx
import { useTheme } from '@vaneui/ui';

function CustomComponent() {
  const theme = useTheme();

  // Compound themes are nested by sub-part
  const buttonTheme = theme?.button.main;
  const cardTheme = theme?.card.main;

  return <div>Custom component</div>;
}
```

## Custom colors

VaneUI uses CSS variables for colors. Override them globally or for specific sections:

```css
/* Global color override */
:root {
  --color-text-primary: #8b5cf6;
  --color-bg-primary: #f3e8ff;
  --color-border-primary: #c4b5fd;
}

/* Scoped color override */
.marketing-section {
  --color-text-info: #6366f1;
  --color-bg-info: #eef2ff;
}
```

```tsx
function App() {
  return (
    <ThemeProvider>
      <Button primary>Uses CSS variable colors</Button>
      
      <div className="marketing-section">
        <Button info>Uses scoped info colors</Button>
      </div>
    </ThemeProvider>
  );
}
```

## Recurring ThemeProvider patterns

### Consistent appearance theme

Apply one appearance across components for a consistent look:

```tsx
function ConsistentThemeApp() {
  return (
    <ThemeProvider themeDefaults={{
      button: { main: { info: true, filled: true } },
      card: { main: { info: true } },
      badge: { info: true },
    }}>
      <nav>
        <Button>Home</Button>
        <Button>About</Button>
        <Badge>New</Badge>
      </nav>
    </ThemeProvider>
  );
}
```

### Section-specific styling

Different themes for different areas:

```tsx
function MultiSectionApp() {
  return (
    <>
      {/* Hero section - large, bold */}
      <ThemeProvider themeDefaults={{
        button: { main: { xl: true, filled: true } },
        title: { xl: true },
      }}>
        <HeroSection />
      </ThemeProvider>

      {/* Content section - medium */}
      <ThemeProvider themeDefaults={{
        button: { main: { md: true } },
        text: { sm: true },
      }}>
        <ContentSection />
      </ThemeProvider>

      {/* Footer - compact */}
      <ThemeProvider themeDefaults={{
        button: { main: { xs: true } },
        text: { xs: true },
      }}>
        <FooterSection />
      </ThemeProvider>
    </>
  );
}
```

## Advanced customization

For more detailed information about specific ThemeProvider properties, see these dedicated guides:

- **[Theming Overview](./theming-overview)**: Understand the theme architecture
- **[ThemeDefaults](./theme-defaults)**: Set application-wide default values
- **[ExtraClasses](./extra-classes)**: Add custom CSS classes
- **[CSS Variables](./css-variables)**: Customize colors using CSS custom properties

ThemeProvider lets you start with a few overrides and add more as needs grow.

# Theme & ThemeOverride

> Customize themes using ThemeProvider's theme and themeOverride properties (applied to providers, not components).

Source: https://vaneui.com/docs/customization/theme-and-override

Import: `import { Button, Card, ThemeProvider } from "@vaneui/ui"`

The `themeOverride` property is a function that receives the theme and returns it modified. Use it for changes the declarative options can't express, like adding [base classes](/docs/customization/theming-overview) or changing defaults for any subtree of your application.

## Basic usage

### Modifying base classes

Add CSS classes that apply to all instances of a component:

```tsx demo
<ThemeProvider themeOverride={(theme) => {
  // Compound themes are nested by sub-part: Button is `button.main`,
  // Card is `card.main`. Single-target themes (Badge, Chip, etc.) sit at the top level.
  theme.button.main.base += ' uppercase tracking-wide';
  theme.card.main.base += ' shadow-sm';
  return theme;
}}>
  <Button primary>Uppercase Button</Button>
  <Card>Card with Shadow</Card>
</ThemeProvider>
```

### Modifying default props

Change the default boolean props for components:

```tsx demo
<ThemeProvider themeOverride={(theme) => {
  theme.button.main.defaults = {
    ...theme.button.main.defaults,
    filled: true,
    pill: true,
  };
  return theme;
}}>
  <Button primary>Filled Pill Button</Button>
</ThemeProvider>
```

Note: For changing defaults, prefer using `themeDefaults` instead. It uses fewer pieces and the public `ThemeDefaults` type:

```tsx
// Preferred approach for defaults
<ThemeProvider themeDefaults={{
  button: { main: { filled: true, pill: true } }
}}>
```

## Combining with other props

Use `themeOverride` alongside `themeDefaults` and `extraClasses`:

```tsx demo
<ThemeProvider
  themeDefaults={{ button: { main: { filled: true } } }}
  themeOverride={(theme) => {
    theme.button.main.base += ' tracking-wide';
    return theme;
  }}
  extraClasses={{
    button: { main: { primary: 'hover:shadow-lg' } }
  }}
>
  <Button>Fully Customized</Button>
</ThemeProvider>
```

## Nested ThemeProviders

Child overrides build on parent modifications:

```tsx demo
<ThemeProvider themeOverride={(theme) => {
  theme.button.main.base += ' uppercase';
  return theme;
}}>
  <Button>Uppercase</Button>

  <ThemeProvider themeOverride={(theme) => {
    theme.button.main.base += ' tracking-widest';
    return theme;
  }}>
    <Button>Uppercase + Wide Tracking</Button>
  </ThemeProvider>
</ThemeProvider>
```

## When to use themeOverride

- **Use `themeOverride`** when you need to add base CSS classes to all component instances
- **Use `themeDefaults`** when you want to [change default boolean props](/docs/customization/theme-defaults) (smaller surface)
- **Use `extraClasses`** when you want to [add classes based on active props](/docs/customization/extra-classes)

# ThemeDefaults

> Set app-wide default props with ThemeProvider themeDefaults, such as a filled VaneUI Button everywhere, and see how defaults merge with component props.

Source: https://vaneui.com/docs/customization/theme-defaults

Import: `import { Badge, Button, Card, Container, Section, Stack, Text, ThemeProvider } from "@vaneui/ui"`

The `themeDefaults` property in VaneUI's [ThemeProvider](/docs/customization/using-theme-provider) allows you to set default [boolean props](/docs/getting-started/core-concepts) for components throughout your application. It establishes consistent defaults while still allowing individual components to override these values.

## Understanding themeDefaults

### themeDefaults?: ThemeDefaults

The `themeDefaults` property accepts an object where keys are component names and values are objects with boolean props. These defaults are merged with VaneUI's built-in defaults.

Most components take props directly. **[Components with sub-themes](/docs/customization/theming-overview)** (`button`, `card`, `checkbox`, `field`, `radio`, `switch`, `modal`, `menu`, `navLink`, `table`) take a nested object keyed by sub-theme name (`main`, `content`, `input`, `item`, `root`, etc.).

```tsx
<ThemeProvider themeDefaults={{
  button: { main: { md: true, filled: true } }, // nested under `main`
  badge: { success: true, sm: true },
  card: { main: { secondary: true } },          // nested under `main`
  checkbox: { input: { lg: true, success: true } }, // Checkbox box nests under `input`
  text: { primary: true },
}}>
  <App />
</ThemeProvider>
```

## Setting component defaults

### Basic defaults

Set default boolean props for specific component types. `IconButton` has its own node (`iconButton`), so `button.main` defaults do not reach it; set both when they should match. `ModalCloseButton` keeps its own variant and size, so a filled `button.main` default leaves the close button readable.

```tsx
import { ThemeProvider, Button, Badge, Card } from '@vaneui/ui';

function App() {
  return (
    <ThemeProvider themeDefaults={{
      button: {
        main: {
          lg: true,        // All buttons are large (overrides built-in sm)
          filled: true     // All buttons are filled
        }
      },
      badge: {
        success: true,   // All badges are success color
      },
      card: {
        main: {
          secondary: true, // All cards use secondary appearance
        }
      }
    }}>
      {/* Components use these defaults automatically */}
      <Button>Large Filled Button</Button>
      <Badge>Success Badge</Badge>
      <Card>Secondary Card</Card>
    </ThemeProvider>
  );
}
```

### Consistent appearance defaults

Apply one appearance consistently across components:

```tsx
import { ThemeProvider, Button, Card, Badge } from '@vaneui/ui';

function ConsistentThemeApp() {
  return (
    <ThemeProvider themeDefaults={{
      button: { main: { info: true, filled: true } },
      card: { main: { info: true } },
      badge: { info: true }
    }}>
      <nav>
        <Button>Home</Button>
        <Button>About</Button>
        <Badge>New</Badge>
      </nav>
    </ThemeProvider>
  );
}
```

## Available boolean props

### Size props
- `xs`, `sm`, `md`, `lg`, `xl`

### Appearance props
- `primary`, `accent`, `secondary`, `tertiary`
- `success`, `danger`, `warning`, `info`, `inheritAppearance`

### Variant props
- `filled`, `outline`, `ghost`
- `ghost`: transparent background, no border, appearance-colored text, tinted hover background

### Shape props
- `rounded`, `pill`, `sharp`

### Typography props
- `fontSans`, `fontSerif`, `fontMono`, `fontHeading`
- `fontThin`, `fontExtralight`, `fontLight`, `fontNormal`, `fontMedium`, `fontSemibold`, `fontBold`, `fontExtrabold`, `fontBlack`
- `italic`, `underline`, `lineThrough`, `noUnderline`, `uppercase`, `lowercase`, `capitalize`

### Layout props
- `flex`, `inlineFlex`, `block`, `inline`, `grid`, `hidden`
- `row`, `column`, `rowReverse`, `columnReverse`
- `itemsStart`, `itemsCenter`, `itemsEnd`, `itemsStretch`, `itemsBaseline`
- `justifyStart`, `justifyCenter`, `justifyEnd`, `justifyBetween`, `justifyAround`, `justifyEvenly`
- `flexWrap`, `flexNoWrap`
- `gap`, `noGap`, `padding`, `noPadding`
- `border`, `noBorder`, `borderT`, `borderB`, `borderL`, `borderR`, `borderX`, `borderY`
- `insetRing`, `noInsetRing`, `shadow`, `noShadow`, `transparent`

### Width / height props
- `wFull`, `wFit`, `wAuto`, `wScreen`
- `hFull`, `hFit`, `hAuto`, `hScreen`

### Truncate props
- `truncate`, `lineClamp2`, `lineClamp3`, `lineClamp4`, `lineClamp5`, `noTruncate`

### Letter spacing props
- `trackingTighter`, `trackingTight`, `trackingNormal`, `trackingWide`, `trackingWider`, `trackingWidest`

### Cursor props
- `cursorPointer`, `cursorDefault`, `cursorNotAllowed`, `cursorNone`, `cursorText`, `cursorMove`, `cursorWait`

### Position props
- `relative`, `absolute`, `fixed`, `sticky`, `static`

### Responsive props (layout)
- `mobileStack`, `tabletStack`, `desktopStack`
- `mobileHide`, `tabletHide`, `desktopHide`
- `mobileShow`, `tabletShow`, `desktopShow`
- `mobileWFull`, `tabletWFull`, `desktopWFull`

### Misc
- `transition`, `noTransition`, `focusVisible`, `noFocusVisible`
- `inheritSize`, `inheritColor`, `inheritBg`, `inheritBorder`
- `responsiveSizing`, `horizontal`, `vertical`, `listDisc`, `listDecimal`

## Override priority

Understanding how defaults interact with component props:

### Priority order

1. **Component props** (highest priority)
2. **ThemeDefaults from closest ThemeProvider**
3. **ThemeDefaults from parent ThemeProviders**
4. **VaneUI built-in defaults** (lowest priority)

```tsx
function OverrideExample() {
  return (
    <ThemeProvider themeDefaults={{
      button: { main: { lg: true } }
    }}>
      {/* Uses defaults: primary (built-in), lg (from provider) */}
      <Button>Default Button</Button>

      {/* Props override defaults: danger replaces primary; lg still applies */}
      <Button danger>Danger Button</Button>

      {/* Explicit prop overrides default: secondary replaces primary; lg still applies */}
      <Button secondary>Secondary Button</Button>
    </ThemeProvider>
  );
}
```

## Layout component defaults

Configure defaults for layout components:

```tsx
import { ThemeProvider, Container, Section, Card, Stack, Text } from '@vaneui/ui';

function LayoutDefaults() {
  return (
    <ThemeProvider themeDefaults={{
      container: { lg: true },
      section: { secondary: true },
      card: { main: { primary: true } }, // card is nested under `main`
      stack: { lg: true },                // larger gap/padding than default
    }}>
      <Container>
        <Section>
          <Card>
            <Stack>
              <Text>Content with layout defaults</Text>
            </Stack>
          </Card>
        </Section>
      </Container>
    </ThemeProvider>
  );
}
```

## Dynamic defaults

### Runtime default changes

Update defaults based on user preferences or application state:

```tsx
import { useState } from 'react';
import { ThemeProvider, Button } from '@vaneui/ui';

function DynamicDefaults() {
  const [isCompactMode, setIsCompactMode] = useState(false);

  const themeDefaults = isCompactMode
    ? {
        button: { main: { sm: true } },
        card: { main: { sm: true } },
        text: { sm: true }
      }
    : {
        button: { main: { lg: true } },
        card: { main: { lg: true } },
        text: { md: true }
      };

  return (
    <ThemeProvider themeDefaults={themeDefaults}>
      <Button onClick={() => setIsCompactMode(!isCompactMode)}>
        Toggle Compact Mode
      </Button>
    </ThemeProvider>
  );
}
```

### Contextual defaults

Different defaults for different areas of your app:

```tsx
import { ThemeProvider } from '@vaneui/ui';

function ContextualDefaults() {
  return (
    <>
      {/* Admin area - compact, subtle styling */}
      <ThemeProvider themeDefaults={{
        button: { main: { secondary: true } }
      }}>
        <AdminPanel />
      </ThemeProvider>

      {/* User area - larger, prominent styling */}
      <ThemeProvider themeDefaults={{
        button: { main: { lg: true, filled: true } }
      }}>
        <UserInterface />
      </ThemeProvider>
    </>
  );
}
```

## Section-specific styling

Different themes for different page sections:

```tsx
import { ThemeProvider } from '@vaneui/ui';

function MultiSectionApp() {
  return (
    <>
      {/* Hero section - large, bold */}
      <ThemeProvider themeDefaults={{
        button: { main: { xl: true, filled: true } },
        title: { xl: true }
      }}>
        <HeroSection />
      </ThemeProvider>

      {/* Content section - medium */}
      <ThemeProvider themeDefaults={{
        button: { main: { md: true } },
        text: { sm: true }
      }}>
        <ContentSection />
      </ThemeProvider>

      {/* Footer - compact */}
      <ThemeProvider themeDefaults={{
        button: { main: { xs: true } },
        text: { xs: true }
      }}>
        <FooterSection />
      </ThemeProvider>
    </>
  );
}
```

## Patterns that keep themeDefaults predictable

### Know VaneUI's built-in defaults

VaneUI components come with sensible built-in defaults. Only set defaults that differ from these:

**Built-in defaults you don't need to specify** (cite the component's `{component}Defaults.ts` file as the source of truth when in doubt). Components that tag-switch to `<a>` via `href` (Badge, Card, Chip, Code, Row, Col, Stack) also get `focusVisible: true` auto-injected when `href` is set. Opt out per-instance with `noFocusVisible`.

- **Button**: `sm`, `primary`, `outline`, `rounded`, `fontSemibold`, `padding`, `gap`, `insetRing`, `focusVisible`, `cursorPointer`, `transition` (note: defaults to `sm`, not `md`; no `shadow`)
- **Card**: `md`, `primary`, `outline`, `rounded`, `border`, `padding`, `gap`, `flex`, `column`
- **Row**: `md`, `row`, `flex`, `itemsCenter`, `gap`, `noPadding`, `noBorder`, `noInsetRing`, `outline`, `sharp`
- **Col**: `md`, `column`, `flex`, `gap`, `noPadding`, `noBorder`, `noInsetRing`, `outline`, `sharp`
- **Stack**: `md`, `flex`, `column`, `flexWrap`, `gap`, `padding`, `noBorder`, `noInsetRing`, `outline`, `sharp`
- **Section**: `md`, `wFull`, `flex`, `column`, `itemsStart`, `gap`, `padding`, `noBorder`, `noInsetRing`, `noShadow`, `outline`, `sharp`, `responsiveSizing`
- **Container**: `md`, `wFull`, `flex`, `column`, `itemsCenter`, `gap`, `noPadding`, `outline`, `sharp`
- **Input**: `md`, `wFull`, `primary`, `outline`, `rounded`, `padding`, `insetRing`, `focusVisible`
- **Label**: `sm`, `flex`, `column`, `itemsStart`, `gap`, `inheritAppearance` (not `primary`), `fontMedium` (stacked label above field; use `<Label row itemsCenter>` for inline controls like `Checkbox`)
- **Badge**: `md`, `secondary` (not `primary`), `outline`, `pill`, `fontSemibold`
- **Chip**: `md`, `secondary` (not `primary`), `outline`, `rounded`, `fontSans`
- **Link**: `md`, `underline`, `fontSans`, `cursorPointer`, `inheritSize`, `wFit`, `focusVisible` (link color by default; no appearance or variant default)
- **NavLink**: `sm`, `primary`, `outline`, `rounded`, `wFull`, `textLeft`, `focusVisible`
- **MenuItem**: `sm`, `primary`, `outline`, `rounded`, `wFull`, `textLeft`, `focusVisible`
- **Typography** (`Text`, `Title`, `SectionTitle`, `PageTitle`, `Blockquote`): `md`, `inheritAppearance` (not `primary`), `outline`
- **Icon**: `md`, `inlineFlex`, `itemsCenter`, `justifyCenter`, `outline`, `rounded`, `noPadding`, `noBorder`, `noInsetRing`, `noShadow`, `noShrink`, `noTransition`, `wFit`
- **Modal** content: `md`, `wFull`, `flex`, `column`, `rounded`, `shadow`, `primary`, `outline`
- **Popup**: `md`, `flex`, `column`, `padding`, `gap`, `rounded`, `shadow`, `border`, `primary`, `outline`

```tsx
// Unnecessary - these are already the defaults
<ThemeProvider themeDefaults={{
  stack: { gap: true },                 // gap is already true
  button: { main: { primary: true } },  // primary is already true
  card: { main: { rounded: true } },    // rounded is already true
}}>

// Better - only specify what you're changing
<ThemeProvider themeDefaults={{
  button: { main: { filled: true } },   // change from outline to filled
  card: { main: { lg: true } },         // change from md to lg
}}>
```

### Consistent defaults

Establish defaults that align with your design system:

```tsx
import { ThemeProvider, type ThemeDefaults } from '@vaneui/ui';

const designSystemDefaults: ThemeDefaults = {
  // Interactive elements
  button: { main: { md: true, filled: true } }, // change sm→md, outline→filled
  link: { info: true },

  // Informational elements
  badge: { secondary: true, sm: true },

  // Layout elements
  card: { main: { shadow: true } }, // add shadow (not default)
  section: { lg: true }             // larger spacing
};

<ThemeProvider themeDefaults={designSystemDefaults}>
  <App />
</ThemeProvider>
```

### Logical groupings

Group related defaults together for maintainability:

```tsx
import { ThemeProvider, type ThemeDefaults } from '@vaneui/ui';

const interactiveDefaults: ThemeDefaults = {
  button: { main: { filled: true } },
  link: { info: true }
};

const informationalDefaults: ThemeDefaults = {
  badge: { secondary: true, sm: true },
};

const layoutDefaults: ThemeDefaults = {
  card: { main: { shadow: true } },
  stack: { lg: true }
};

<ThemeProvider themeDefaults={{
  ...interactiveDefaults,
  ...informationalDefaults,
  ...layoutDefaults
}}>
  <App />
</ThemeProvider>
```

`themeDefaults` establishes consistent default values across the application while allowing per-instance overrides on individual components.

# ExtraClasses

> Attach your own Tailwind CSS classes to VaneUI components when a boolean prop is active, with ThemeProvider extraClasses: hover effects, animations, sizes.

Source: https://vaneui.com/docs/customization/extra-classes

Import: `import { Badge, Button, Card, ThemeProvider } from "@vaneui/ui"`

The `extraClasses` property in VaneUI's [ThemeProvider](/docs/customization/using-theme-provider) allows you to add additional CSS classes to components based on which boolean props are active. This enables custom styling, animations, and effects while maintaining VaneUI's [theming architecture](/docs/customization/theming-overview).

## Understanding extraClasses

### extraClasses?: ThemeExtraClasses

The `extraClasses` property accepts an object where keys are component names and values map boolean prop names to CSS class strings. When a prop is active, its associated classes are added.

Most components are keyed directly. **Components with sub-themes** (`button`, `card`, `checkbox`, `field`, `radio`, `switch`, `modal`, `menu`, `navLink`, `table`) are nested by sub-theme name (`main`, `content`, `input`, `item`, `root`, etc.). The shape mirrors `themeDefaults`. For example, `Checkbox` keys its box classes under `input`: `extraClasses={{ checkbox: { input: { success: 'ring-2 ring-green-200' } } }}`.

## Basic usage

### Adding classes based on props

Apply extra classes when specific boolean props are active:

```tsx
import { ThemeProvider, Button, Badge } from '@vaneui/ui';

function App() {
  return (
    <ThemeProvider extraClasses={{
      button: {
        main: {
          primary: 'shadow-lg hover:shadow-xl transition-shadow',
          danger: 'animate-pulse',
        },
      },
      badge: {
        success: 'ring-2 ring-green-200',
      },
    }}>
      <Button primary>Button with shadow</Button>
      <Button danger>Pulsing danger button</Button>
      <Badge success>Badge with ring</Badge>
    </ThemeProvider>
  );
}
```

### Size-based classes

Add classes based on size props:

```tsx demo
<ThemeProvider extraClasses={{
  button: {
    main: {
      lg: 'font-bold',
      xl: 'font-extrabold',
    },
  },
}}>
  <Button lg>Large bold button</Button>
</ThemeProvider>
```

## Animation and effects

### Hover and transition effects

Create engaging interactions with animation classes:

```tsx demo
<ThemeProvider extraClasses={{
  button: {
    main: {
      primary: 'hover:scale-105 active:scale-95 transition-transform duration-150',
      success: 'hover:brightness-110 transition-all',
    },
  },
  card: {
    main: {
      primary: 'hover:shadow-xl transition-shadow duration-300',
    },
  },
}}>
  <Button primary>Scalable Button</Button>
  <Card primary>Hoverable Card</Card>
</ThemeProvider>
```

### Attention-grabbing effects

Draw attention to important elements:

```tsx demo
<ThemeProvider extraClasses={{
  button: {
    main: {
      danger: 'animate-pulse',
      warning: 'animate-bounce',
    },
  },
  badge: {
    danger: 'animate-ping',
  },
}}>
  <Button danger>Pulsing Alert</Button>
  <Badge danger>New</Badge>
</ThemeProvider>
```

## Combining multiple props

When multiple props are active, all their associated classes are combined:

```tsx demo
<ThemeProvider extraClasses={{
  button: {
    main: {
      primary: 'shadow-lg',
      lg: 'font-bold',
      filled: 'border-2',
    },
  },
}}>
  {/* Gets all three: shadow-lg + font-bold + border-2 */}
  <Button primary lg filled>Combined Styles</Button>
</ThemeProvider>
```

## Conditional extra classes

### Dynamic class application

Apply classes based on application state:

```tsx
import { useState } from 'react';
import { ThemeProvider, Button, type ThemeExtraClasses } from '@vaneui/ui';

function DynamicExtraClasses() {
  const [isHighContrast, setIsHighContrast] = useState(false);

  const extraClasses: ThemeExtraClasses = isHighContrast
    ? {
        button: {
          main: {
            primary: 'border-4 border-black font-black',
            danger: 'border-4 border-red-900 font-black',
          },
        },
      }
    : {
        button: {
          main: {
            primary: 'shadow-sm',
            danger: 'shadow-sm',
          },
        },
      };

  return (
    <ThemeProvider extraClasses={extraClasses}>
      <Button onClick={() => setIsHighContrast(!isHighContrast)}>
        Toggle High Contrast
      </Button>
      <Button primary>Primary Button</Button>
      <Button danger>Danger Button</Button>
    </ThemeProvider>
  );
}
```

## Patterns that keep extraClasses predictable

### Consistent naming

Use consistent class patterns:

```tsx
const extraClasses = {
  button: {
    main: {
      // Hover effects
      primary: 'hover:shadow-lg',
      secondary: 'hover:shadow-md',

      // Active states
      danger: 'active:scale-95',

      // Transitions
      success: 'transition-all duration-200',
    },
  },
};
```

### Avoid conflicting classes

Be careful not to add classes that conflict with VaneUI's [size-driven system](/docs/customization/css-variables) (padding, gap, font-size, border-radius scale via the size prop):

```tsx
// Avoid: fights the size system; padding is set by --py-unit per size
extraClasses: {
  button: { main: { primary: 'p-8' } }
}

// Better: adds effects that complement base styles
extraClasses: {
  button: { main: { primary: 'hover:brightness-110' } }
}
```

The `extraClasses` system lets you extend VaneUI components with prop-conditional classes and integrate with any CSS framework while keeping the theming system intact.

# CSS Variables

> Change VaneUI colors and sizing with CSS custom properties: the three-tier variable system, color groups, and global or scoped overrides, no component edits.

Source: https://vaneui.com/docs/customization/css-variables

VaneUI components use a three-tier CSS variable system. Override these variables to change colors globally or for any subtree. This page explains the variable architecture and how to customize it.

## Three-tier variable system

### Tier 1: unit variables
Set per-component in `rules.css` based on the `data-size` attribute. Each per-size block sets all the unit vars that scale with size (typically `--fs-unit`, `--py-unit`, and for Icon `--icon-size`) so font-size, padding, gap, and border-radius all change together:
```css
.vane-button[data-size="md"] {
  --fs-unit: var(--fs-unit-md);   /* Font size unit (8 by default) */
  --py-unit: 2;                   /* Padding Y unit */
}

/* --gap-unit and --br-unit (for layout) come from data-vane-type defaults */
[data-vane-type="ui"][data-size="md"]     { --gap-unit: 2; }
[data-vane-type="layout"][data-size="md"] { --br-unit: 5; --gap-unit: 4; --py-unit: 4; }
```

### Tier 2: computed variables
Calculated from unit variables in `@layer base`:
```css
[data-size] {
  --fs: calc(var(--fs-unit) * var(--fs-base));                       /* Font size */
  --py: calc(var(--py-unit) * var(--spacing));                       /* Padding Y */
  --px: calc(var(--aspect-ratio) * var(--py-unit) * var(--spacing)); /* Padding X */
  --br: calc(var(--br-unit) * var(--br-base));                       /* Border radius (layout) */
  --gap: calc(var(--gap-unit) * var(--spacing));                     /* Gap */
}

/* UI border-radius is a ratio of element height, not a flat multiplier: */
[data-vane-type="ui"][data-size] {
  --br: calc((var(--fs-unit) * 0.5 * var(--lh) + 2 * var(--py-unit))
             * var(--br-unit) * var(--spacing));
}
```

### Tier 3: semantic color variables
Set by `data-variant` + `data-appearance` attribute combinations:
```css
[data-variant="outline"][data-appearance="primary"] {
  --text-color: var(--color-text-primary);
  --bg-color: var(--color-bg-primary);
  --border-color: var(--color-border-primary);
}
```

### Icon sizing: decoupled from font size
Components that render icons (`Button`, `IconButton`, `Icon`, `Badge`, `Chip`, `Menu`, `NavLink`, `Link`, `ListItem`) size icons via `--icon-size`, not `--fs`. For most components this is `var(--fs)` (the element's own font-size), but `Icon` sets it independently per size as `calc(var(--spacing) * N)`. An `<Icon md>` is 8 × `--spacing` regardless of any inherited font-size:

```css
.vane-icon[data-size="md"] { --icon-size: calc(var(--spacing) * 8); }
.vane-icon[data-size="lg"] { --icon-size: calc(var(--spacing) * 12); }
```

## Appearance values

Replace `{appearance}` in variable names with one of:
- `primary` - neutral/default styling (gray tones)
- `secondary` - subtle styling (light gray)
- `tertiary` - muted styling (darker gray)
- `accent` - highlight color (rose)
- `success` - positive feedback (green)
- `danger` - error/destructive (red)
- `warning` - caution (amber)
- `info` - informational (cyan)
- `inheritAppearance` - inherits from parent element

> The `inheritAppearance` appearance works differently from all other appearances. Instead of setting `data-appearance` and `data-variant` attributes, it omits them entirely. This allows the semantic color CSS variables (`--text-color`, `--bg-color`, `--border-color`) to [cascade from parent elements](/docs/customization/variant-inheritance) rather than being set explicitly on the component. Text, Title, SectionTitle, PageTitle, Blockquote, Label, List, Divider, and Spinner default to `inheritAppearance`.

## Color variable groups

### Text colors
- `--color-text-{appearance}` - text color for outline variant
- `--color-text-filled-{appearance}` - text color for filled variant

### Background colors
- `--color-bg-{appearance}` - background for outline variant
- `--color-bg-hover-{appearance}` - hover state background
- `--color-bg-active-{appearance}` - active state background
- `--color-bg-filled-{appearance}` - background for filled variant
- `--color-bg-filled-hover-{appearance}` - filled hover state
- `--color-bg-filled-active-{appearance}` - filled active state

### Border colors
- `--color-border-{appearance}` - border color for outline variant
- `--color-border-form` - border color for unchecked `Checkbox`, `Radio`, and `Switch` controls. One step darker than the layout border (`gray-300` vs `gray-200`) so controls stay distinct on light surfaces. Kept off the appearance system, so secondary or tertiary `Card`, `Button`, and `Chip` keep their lighter border.

### Focus ring colors
- `--color-focus-{appearance}` - focus-visible outline color (used by all variants)

## Base variables

VaneUI defines base variables in the `@theme` block (in `tokens.css`) that control the foundation of the sizing system:

```css
@theme {
  --fs-base: calc(var(--spacing) * 0.5);  /* Font size base (0.125rem at default spacing) */
  --br-base: var(--spacing);               /* Border radius base */
  --lh-base: 1.6;                          /* Line height base */
}
```

### Font size unit scale
These variables define the font size multipliers for each size. At Tailwind's default `--spacing: 0.25rem`, `--fs-base` = 0.125rem:

```css
--fs-unit-xs: 6;   /* xs = 6  × 0.125rem = 0.75rem  (12px) */
--fs-unit-sm: 7;   /* sm = 7  × 0.125rem = 0.875rem (14px) */
--fs-unit-md: 8;   /* md = 8  × 0.125rem = 1rem     (16px) */
--fs-unit-lg: 9;   /* lg = 9  × 0.125rem = 1.125rem (18px) */
--fs-unit-xl: 10;  /* xl = 10 × 0.125rem = 1.25rem  (20px) */
```

### Component-specific sizing

Padding, gap, and radius values are set per-component (and per `data-vane-type`) in `rules.css`:

```css
/* UI defaults (Button, Badge, Chip, Text, etc.) */
[data-vane-type="ui"][data-size="md"] { --gap-unit: 2; }

/* Layout defaults (Card, Row, Col, Stack, Section, Container, Grid*) */
[data-vane-type="layout"][data-size="md"] { --br-unit: 5; --gap-unit: 4; --py-unit: 4; }

/* Per-component overrides: Button sets its own --py-unit per size */
.vane-button[data-size="md"] { --fs-unit: var(--fs-unit-md); --py-unit: 2; }
```

To customize sizing globally, override the computed variables in your CSS:
```css
:root {
  /* Make all spacing slightly larger */
  --spacing: 0.3rem;  /* Tailwind's default is 0.25rem */
}
```

## Global override (site-wide)
```css
/* styles/globals.css */
:root {
  /* Customize info colors */
  --color-text-info: #8b5cf6;
  --color-bg-info: #f3e8ff;
  --color-border-info: #c4b5fd;
}
```

## Scoped override (specific section)
```css
/* Only affects components inside .marketing */
.marketing {
  --color-text-primary: #059669;
  --color-bg-primary: #ecfdf5;
  --color-border-primary: #6ee7b7;
}
```

## Notes and tips
- Use the semantic names above; avoid inventing new variable names.
- Values cascade. The closest definition (inline, container, :root) wins.
- Prefer semantic overrides (primary, success, danger) for consistent theming.
- [ThemeProvider](/docs/customization/using-theme-provider) does not expose a `colors` field; use these CSS variables to change colors.
- Components inherit the closest CSS variable values automatically via CSS cascade.

# Dark Mode

> Enable dark mode with data-theme="dark" on html or a wrapper, keep light regions with data-theme="light", and change colors in both schemes with light-dark().

Source: https://vaneui.com/docs/customization/dark-mode

Import: `import { Button, Card, Row, Text } from "@vaneui/ui"`

`data-theme="dark"` is the official dark-mode extension point. Set it on `<html>` or on a wrapping element, and every VaneUI component inside switches to its dark colors with no component code changes. `data-theme="light"` makes a subtree light again inside a dark page. A page with no `data-theme` attribute keeps the `@theme` values and is unaffected by the dark-mode rules.

## How the light-dark() color pairs resolve

From `@vaneui/ui` 1.4.5, each scheme color is one [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark) pair of a light and a dark value, such as `--color-bg-primary: light-dark(#fff, oklch(13% 0.028 261.692))` (white and gray-950). The full list of pairs, covering text, background, hover, active, border, focus ring and overlay colors, is declared on every `data-theme="dark"` element and on every `data-theme="light"` element below `<html>`. The same rules set `color-scheme`, which picks the side of each pair:

| Attribute | `color-scheme` | Each pair resolves to |
|-----------|----------------|-----------------------|
| `data-theme="dark"` | `dark` | its dark value |
| `data-theme="light"` below `<html>` | `light` | its light value |
| none | not set | no pairs apply; the `@theme` values do |

Tokens not in the list keep their `@theme` value in both schemes. Most of them are filled-variant colors, such as the 100-level text tints on filled `success` or `danger` surfaces. Because the tokens are CSS custom properties, any element under a `data-theme` ancestor reads the resolved values through the cascade.

The dark scheme also deepens shadows: it raises `--shadow-alpha` from 0.1 to 0.4 and `--shadow-alpha-soft` from 0.06 to 0.25, and a light subtree resets both.

## Whole-page dark mode

Set `data-theme="dark"` on the `<html>` element to theme the entire page, including portaled content (Modal, Popup, Overlay) and native controls. The rule sets `color-scheme: dark`, so scrollbars and form controls render in their dark forms, and VaneUI paints the page itself with the dark surface color. A background you set on `html` or `body` still wins.

```html
<html data-theme="dark">
```

Under server-side rendering, the attribute must already be present in the server-rendered markup, otherwise the first paint shows light mode and then flips. When the theme is stored client-side, set the attribute from an inline `<head>` script that runs before first paint:

```html
<script>
  if (localStorage.theme === 'dark') {
    document.documentElement.dataset.theme = 'dark';
  }
</script>
```

## Theming one subtree

To darken a region of an otherwise light page, set `data-theme="dark"` on a wrapping element. The dark token values inherit through that subtree:

```tsx
<div data-theme="dark">
  <Card>Dark card on an otherwise light page</Card>
</div>
```

The wrapper `<div>` paints nothing on its own. Give the subtree a surface: a [Card](/docs/layout-components/card), or a [Section](/docs/layout-components/section) with an explicit appearance (`<Section primary>`). Either reads the dark background token and fills the area; a bare `Section` paints nothing.

## Light regions inside a dark page

`data-theme="light"` on an element inside a dark page or a dark wrapper makes that subtree light. It sets `color-scheme: light`, so every pair resolves to its light value, and it resets the shadow alphas. Use it for a light preview panel, an embedded document or a sample that must stay light whatever the page theme. Before 1.4.5, it only reset `color-scheme`, and the dark colors still came through.

```tsx demo
<div data-theme="dark">
  <Card>
    <Text>Dark surface</Text>
    <div data-theme="light">
      <Card sm>
        <Text>Light card inside the dark surface</Text>
        <Row>
          <Button>Primary</Button>
          <Button filled>Filled</Button>
        </Row>
      </Card>
    </div>
  </Card>
</div>
```

The demo renders the same in both site themes: the outer wrapper is always dark and the inner one always light. On `<html>` itself, `data-theme="light"` changes nothing, since the light rule skips the root element. Token customizations for the light page keep working when a theme toggle sets `data-theme="light"` on `<html>`.

## Overlays follow the page theme

[Modal](/docs/overlay-components/modal), `Popup`, and `Overlay` render through a portal at the end of `<body>`, so they resolve the theme set on `<html>` or `<body>`, not the theme of an inner wrapper. Subtree theming covers in-flow content. For overlays, `<html data-theme="dark">` is the primary supported mode.

## Changing a color in both schemes

A token you re-declare on `:root` alone (as in the [CSS variables global override](/docs/customization/css-variables)) reaches pages without `data-theme`, but the scheme rules declare it again on dark elements and light subtrees, so the change does not show on a dark page or in a light region. To change a color in both schemes, declare it as a `light-dark()` pair on the `data-theme` elements, and keep the light value on `:root` for pages without `data-theme`:

```css
/* after the @vaneui/ui stylesheet */
:root {
  --color-bg-info: oklch(95% 0.02 220);
}

:root[data-theme],
[data-theme]:not(:root) {
  --color-bg-info: light-dark(oklch(95% 0.02 220), oklch(30% 0.05 220));
}
```

`:root[data-theme]` covers `<html data-theme="...">` and `[data-theme]:not(:root)` covers subtree wrappers. Both selectors carry the same weight as the built-in scheme rules, so the rule wins when it comes after the VaneUI stylesheet, including in a light region inside a dark page.

Keep `light-dark()` pairs off a `:root`-only rule. Bundlers that compile `light-dark()` for older browsers resolve it where the variable is declared, so a pair declared once on `:root` would not switch inside nested `data-theme` subtrees.

## Browser support for light-dark()

Uncompiled, `light-dark()` needs Chrome 123, Firefox 120 or Safari 17.5. Bundlers that compile it for older browsers keep those browsers working, and Next.js does so by default. The pairs apply only on `data-theme` elements, so a page without `data-theme` does not depend on `light-dark()` support.

## Custom named themes

The dark scheme is one instance of a general pattern: re-declare any `--color-*` token under a selector of your choice. A named theme works the same way:

```css
[data-theme="ocean"] {
  --color-bg-info: oklch(95% 0.02 220);
  --color-text-info: oklch(45% 0.12 220);
}
```

Apply it with `data-theme="ocean"` on any element, and the subtree reads the overridden tokens.

# Customizing Styles

> Override VaneUI React component styles with Tailwind CSS classes in className: which properties win, when a CSS variable or a prop fits better, and pitfalls.

Source: https://vaneui.com/docs/customization/customizing-styles

Import: `import { Badge, Button, Card, Divider, Img, Input, Row, Text } from "@vaneui/ui"`

VaneUI components are styled through boolean props and [CSS variables](/docs/customization/css-variables), but you can override any visual property using standard Tailwind CSS classes via the `className` prop. This page explains how overrides work, when to use each approach, and common pitfalls.

## How className overrides work

VaneUI uses [`tailwind-merge`](https://github.com/dcastil/tailwind-merge) to combine theme-generated classes with your `className`. When a conflict exists, **your class always wins** because `className` is passed last:

```tsx
// Internally, VaneUI does:
const finalClasses = twMerge(...themeGeneratedClasses, className);
```

This means the conflict is resolved at the **JavaScript level**: the losing class is removed from the string entirely before the DOM renders. There are no CSS specificity wars or `!important` hacks.

## Properties className can override

VaneUI components use CSS variable consumer classes like `border-(--border-color)`, `text-(--text-color)`, and `bg-(--bg-color)`. These compile to standard CSS (`border-color: var(--border-color)`). Any Tailwind utility that targets the same CSS property will override them.

### Border color

```tsx
// VaneUI generates: border-(--border-color)
// Your class:       border-red-300
// Result:           border-red-300 (VaneUI class removed)
<Card className="border-red-300">Custom border</Card>
```

### Text color

```tsx
// VaneUI generates: text-(--text-color)
// Your class:       text-emerald-600
// Result:           text-emerald-600
<Text className="text-emerald-600">Custom text color</Text>
```

### Background color

```tsx
// VaneUI generates: bg-(--bg-color)
// Your class:       bg-gradient-to-r from-blue-500 to-purple-500
// Result:           bg-gradient-to-r from-blue-500 to-purple-500
<Card className="bg-gradient-to-r from-blue-500 to-purple-500">
  Gradient card
</Card>
```

### Hover, active, and focus states

State-specific overrides work too. Each state variant is resolved independently:

```tsx
// Override hover background
<Button className="hover:bg-blue-700">Custom hover</Button>

// Override focus ring
<Input className="focus-visible:outline-purple-500" placeholder="Custom focus" />

// Override active state
<Button className="active:bg-blue-900">Custom active</Button>
```

### Shadow

```tsx
<Card className="shadow-2xl">Extra large shadow</Card>
<Card className="shadow-none">No shadow</Card>
```

### Non-conflicting properties are preserved

`twMerge` only removes classes that target the **same CSS property**. Different properties coexist:

```tsx
// border-width and border-color are separate properties
// VaneUI's border-width stays, only color is overridden
<Card className="border-red-300">
  {/* Has both: border-[length:var(--bw)] (width) + border-red-300 (color) */}
</Card>
```

## Override hierarchy

From lowest to highest priority:

| Level | Mechanism | Scope | Use When |
|-------|-----------|-------|----------|
| 1 | Component defaults | Library-wide | You're the library author |
| 2 | `themeDefaults` | Provider subtree | Change defaults for all components in a section |
| 3 | `extraClasses` | Provider subtree | Add classes based on active props |
| 4 | `themeOverride` | Provider subtree | Modify theme internals programmatically |
| 5 | **`className`** | Single instance | One-off style adjustments |
| 6 | `style` | Single instance | Runtime-computed values that can't be a class |

For most use cases, `className` (level 5) is the right tool. Use `themeDefaults` or `extraClasses` when you need the override to apply across many components.

## CSS variable approach

Instead of replacing the consumer class with a utility like `border-red-300`, set the underlying CSS variable with an arbitrary-property class. This keeps VaneUI's consumer class active but changes the value it reads:

```tsx
// Set the variable with an arbitrary-property class: the component's own
// border-(--border-color) still fires, but reads your custom value instead of the theme's
<Card className="[--border-color:var(--color-red-300)]">
  Theme-aware border override
</Card>
```

**Replacing the utility vs setting the variable:**

- **`className="border-red-300"`**: static override, ignores the theme entirely. The component's `border-(--border-color)` class is removed by twMerge.
- **`className="[--border-color:...]"`**: theme-aware override. The component still uses its consumer class, but the variable value is different. Children inherit the new value.

The CSS variable approach is especially useful when you want [descendants to inherit](/docs/customization/variant-inheritance) your override:

```tsx
// All children of this Card inherit the custom border color
<Card className="[--border-color:red]">
  <Input /> {/* This Input also gets a red border */}
  <Divider /> {/* Red divider too */}
</Card>
```

## When to use VaneUI props instead

VaneUI provides [boolean props](/docs/getting-started/core-concepts) for most common styling needs. Always prefer props over Tailwind classes when a prop exists. This ensures the styling integrates with the size system, responds to theme changes, and works with `ThemeProvider` overrides.

| Instead of Tailwind | Use VaneUI Prop |
|---------------------|-----------------|
| `className="font-bold"` | `fontBold` |
| `className="text-center"` | `textCenter` |
| `className="uppercase"` | `uppercase` |
| `className="rounded-full"` | `pill` |
| `className="flex items-center"` | `flex itemsCenter` |
| `className="cursor-pointer"` | `cursorPointer` |
| `className="gap-4"` | Use size props (`xs` through `xl`) |
| `className="bg-red-500"` | `danger filled` |

## className is for things VaneUI props don't cover

Good uses of `className`:

```tsx
{/* Custom width/height */}
<Card className="w-full max-w-md">Fixed-width card</Card>

{/* Stacking order: the sticky prop already pins the row to the top edge */}
<Row sticky className="z-10">Sticky header</Row>

{/* Animations */}
<Badge className="animate-pulse">Live</Badge>

{/* Gradients */}
<Card className="bg-gradient-to-br from-indigo-500 to-purple-600">
  Gradient card
</Card>

{/* Aspect ratio */}
<Img className="aspect-video" src="/banner.jpg" alt="Banner" />
```

## className pitfalls to avoid

### Don't override gap with Tailwind classes

Gap is controlled by VaneUI's size system. Use size props instead:

```tsx
// Wrong: fights the size system
<Row className="gap-10">Content</Row>

// Right: gap scales with size
<Row lg>Content</Row>
<Row xs>Tight content</Row>
```

### Don't override padding with Tailwind classes

Padding is also size-driven and scales proportionally:

```tsx
// Wrong
<Card className="p-8">Content</Card>

// Right: padding scales with size
<Card lg>Content</Card>
```

### Don't use appearance-colored Tailwind classes when an appearance prop exists

```tsx
// Wrong: bypasses the theme system
<Button className="bg-red-500 text-white border-red-600">Delete</Button>

// Right: uses the theme system
<Button danger filled>Delete</Button>
```

### Beware of className on typography components

Typography components have built-in letter spacing, line height, and font size that scale with the size prop. Overriding these with Tailwind classes breaks the proportional scaling:

```tsx
// Wrong: breaks size scaling
<Text className="text-2xl tracking-wide leading-10">Content</Text>

// Right: use size props
<Text xl>Content</Text>
```

# Variant Inheritance

> Which VaneUI React components paint their own colors and which inherit them from a parent, why explicit props win, and how inheritAppearance works.

Source: https://vaneui.com/docs/customization/variant-inheritance

Import: `import { Badge, Card, Code, Link, Stack, Text, ThemeProvider, Title } from "@vaneui/ui"`

VaneUI has two color behaviors. Components with their own appearance (Button, Card, Badge, and most others) emit `data-appearance`/`data-variant` and paint their own colors regardless of context. Inherit-mode components (the typography components, plus Icon) emit nothing and read their colors from the nearest ancestor through native [CSS custom-property cascade](/docs/customization/css-variables). This page explains the split, how the cascade works, and how to control it.

## How variants and appearances cascade through nesting

VaneUI's color system has three layers:

1. **`:root` fallbacks**: set `--text-color`, `--bg-color`, `--border-color` etc. to the primary outline palette (dark text, white background, light border). Inherit-mode components fall back to these when no ancestor sets colors.
2. **Direct CSS rules**: when a component emits `data-appearance` (and `data-variant`), a CSS rule fires and sets those variables on the element and its subtree. Every component with a concrete appearance emits these.
3. **CSS cascade**: inherit-mode components set no variables of their own, so they read them from the nearest ancestor that did.

```
:root                           → --text-color: dark, --bg-color: white
  <Card filled primary>         → --text-color: white, --bg-color: dark  (emits attrs, own rule fires)
    <Button>                    → --text-color: dark, --bg-color: white  (emits its own primary-outline attrs)
    <Text>                      → inherits white text from Card          (inherit mode, no attrs)
    <Mark>                      → --text-color: amber (warning)          (emits its own warning attrs)
```

## Which components set vs. inherit

### Components that paint their own colors

Every component with a concrete appearance default emits `data-appearance` and `data-variant`, so its own CSS rule fires and it keeps its colors regardless of the surrounding context:

**Button, Card, Badge, Chip, Code, Kbd, Mark, Input, Checkbox, IconButton, NavLink** (and any component you give an explicit appearance).

A default `<Button>` inside a `<Card filled primary>` renders in its own primary-outline palette (dark text on white), not the Card's white-on-dark. A `<Mark>` inside a `<Card filled danger>` stays warning-yellow, and a `<Badge>` keeps its secondary colors. These components do not inherit color; set an explicit appearance to change them.

### Components that inherit

Two kinds of components emit no `data-appearance`, so they read colors from the nearest ancestor that set them:

- **Inherit mode**: `Text`, `Title`, `SectionTitle`, `PageTitle`, `Blockquote`, `Label`, `List`, `Divider`, and `Spinner` default to `inheritAppearance`. This is how a `<Text>` inside a `<Card filled primary>` gets white text with no props.
- **Icon**: has no appearance default at all, so it inherits `currentColor` from its surroundings. `ListItem` also has no appearance default and inherits its parent List's colors.

## Explicit props always win

When you explicitly set an appearance or variant on a component, VaneUI emits data attributes and the component's own CSS rule fires, overriding any inherited values:

```tsx demo
<Card filled primary>
  {/* Inherits from Card: white text on dark background */}
  <Text>I'm white</Text>

  {/* Explicit appearance: own CSS rule fires, ignoring the Card */}
  <Text warning>I'm amber</Text>
  <Text success>I'm green</Text>
</Card>
```

An explicit appearance opts out of inheritance completely, so pick one that reads on the surface you are on. `<Text primary outline>` inside a `filled primary` Card resolves to the surface's own dark colour and disappears into it.

## Nested layouts

When multiple layout components are nested, each child inherits from its **nearest ancestor** that sets variables, not from the outermost ancestor:

```tsx demo
<Card filled primary>
  {/* Card sets: --text-color = white, --bg-color = dark */}

  <Stack outline primary>
    {/* Stack sets its own: --text-color = dark, --bg-color = white */}
    {/* (explicit outline primary → own CSS rule fires) */}

    <Text>I'm dark (inherits from Stack, not Card)</Text>
  </Stack>

  <Stack filled danger>
    {/* Stack sets its own: --text-color = white, --bg-color = red */}

    <Text>I'm white on red (inherits from danger Stack)</Text>
  </Stack>
</Card>
```

## ThemeProvider overrides

`ThemeProvider.themeDefaults` sets a component's [default appearance](/docs/customization/theme-defaults) for a subtree. A concrete appearance emits data attributes and pins the color; giving an inherit-mode component a concrete appearance makes it stop inheriting:

```tsx
{/* All Badges in this subtree default to danger */}
<ThemeProvider themeDefaults={{ badge: { danger: true } }}>
  <Card filled primary>
    {/* This Badge renders red (danger), unaffected by the Card */}
    <Badge>Alert</Badge>
  </Card>
</ThemeProvider>
```

## The emission rule

The data-attribute gate uses one rule:

> **Emit `data-appearance` and `data-variant` for any concrete (non-`inheritAppearance`) appearance.** They are suppressed only in inherit mode (`inheritAppearance`, which activates `inheritColor`) or when a component has no appearance at all (Icon, ListItem).

This means:
- `<Button>` → primary → attrs emitted → own primary-outline colors
- `<Button filled>` → primary + filled → attrs emitted → own rule
- `<Badge>` → secondary → attrs emitted → own colors
- `<Text>` → inheritAppearance → no attrs → inherits from the nearest ancestor
- `<Icon>` → no appearance → no attrs → inherits `currentColor`

## Granular inheritance props

By default, the `inheritAppearance` appearance keyword inherits color, background, and border (but not size) from the nearest ancestor. But sometimes you need selective inheritance: a `Link` inside a `Title` should inherit font-size (so the link matches the heading size) but keep its own link-blue color.

VaneUI provides four independent boolean toggle props for this:

| Prop | What it inherits | Negative toggle |
|------|-----------------|-----------------|
| `inheritSize` | Font-size and line-height from parent | `noInheritSize` |
| `inheritColor` | Text color via CSS variable cascade | `noInheritColor` |
| `inheritBg` | Background color via CSS variable cascade | `noInheritBg` |
| `inheritBorder` | Border color via CSS variable cascade | `noInheritBorder` |

### How `inheritAppearance` expands

When a component has `inheritAppearance` appearance (the default for Text, Title, SectionTitle, PageTitle, Blockquote, Label, List, Divider, and Spinner), VaneUI expands it into color, background, and border inheritance, but **not size**:

```
<Text inheritAppearance>
  ↓ expands to:
  inheritColor + inheritBg + inheritBorder
  (NOT inheritSize: size uses own --fs variable so <Text sm> works as expected)
```

Size inheritance is separate. Only Link and Mark have `inheritSize: true` in their defaults (Code and Kbd achieve the same effect via em-relative geometry, described below). You can also set it explicitly:

```tsx demo
<Card filled primary>
  {/* Inherits color (white) but uses own md size */}
  <Text inheritAppearance>Inherited color, own size</Text>

  {/* Explicit inheritSize: also inherits font-size from parent */}
  <Text inheritAppearance inheritSize>Inherited color AND size</Text>
</Card>
```

### Link, Mark: exact size inheritance via `inheritSize`

[Link](/docs/typography-components/link) and Mark are not `inheritAppearance`-default components (Link sets no appearance and renders its own link-blue, Mark defaults to `warning`), so the `inheritAppearance` expansion does NOT fire. Instead, they have `inheritSize: true` set explicitly in their defaults. They render at the *exact* font-size of the nearest typography ancestor.

```tsx demo
<Title lg>
  Check the <Link href="/docs">documentation</Link> for details
</Title>
```

- **Link** renders at the Title's `lg` font-size (inherited 1:1) but stays **link-blue** (its own link color)
- **Mark** renders at parent size with its own warning highlight color

### Code, Kbd: em-relative geometry

[Code](/docs/basic-components/code) and Kbd use a different mechanism: their `.vane-code` / `.vane-kbd` rules override `--spacing` to `0.25em` locally, so the entire geometry pipeline (font-size, padding, border-radius, gap) resolves in em, proportional to the parent's font-size.

```tsx demo
<Title lg>
  Run <Code>npm install</Code> to add the package
</Title>
```

- **Code** renders at 87.5% of Title's `lg` font-size (Code's default `md` ratio = 0.875×)
- The size prop adjusts the ratio: `xs` = 0.625, `sm` = 0.75, `md` = 0.875 (default), `lg` = 1 (matches parent), `xl` = 1.125

So inline Code feels right-sized in every context: body text at 14px / 16px, headings at 21px / 24px, hero displays at 42px / 48px.

### Opting out (Link, Mark)

Use `noInheritSize` to keep Link or Mark at its own size instead of the parent's:

```tsx demo
<Title lg>
  Heading with <Link noInheritSize href="/docs">fixed-size link</Link>
</Title>
```

The Link renders at its default `md` size while the Title is `lg`. For Code/Kbd, the size prop already controls the ratio: pass any of `xs` / `sm` / `md` / `lg` / `xl` to adjust.

### Responsive overrides `inheritSize`

Title, PageTitle, and SectionTitle have `responsiveSizing: true` in their defaults. Responsive sizing takes priority over `inheritSize`: a responsive heading always uses its viewport-scaled size, even if `inheritSize` is set.

# Common Props

> Layout and utility props shared by most VaneUI React components, written as booleans: responsive hide, flex alignment, position, display, overflow and gap.

Source: https://vaneui.com/docs/reference/common-props

Layout and utility props shared across most VaneUI components. Documented here once instead of on every component page. Per-component pages link here from the "Layout & utility props" disclosure under their props table.

Component-specific categories are listed on each component's own page because defaults differ. These include **size** (`xs`/`sm`/`md`/`lg`/`xl`), **appearance** (`primary`/`accent`/`secondary`/`tertiary`/`success`/`danger`/`warning`/`info`/`inheritAppearance`), **variant** (`filled`/`outline`/`ghost`, default `outline`), **shape** (`pill`/`rounded`/`sharp`, default `rounded`), **padding** (`padding`/`paddingX`/`paddingY`/`noPadding`), **fontWeight**, and **textAlign**. Default **size** is `md`, except `Button`, `IconButton`, `NavLink`, `Label`, `MenuItem`, `MenuLabel`, and `Tooltip` which default to `sm`. The `ghost` variant renders a transparent background with no border and appearance-colored text, plus a tinted hover background.

## Hide

Hide elements at specific breakpoint sizes for responsive layouts.

| Prop | Description |
|------|-------------|
| `mobileHide` | Hide below 768px (48rem); the 768px boundary itself stays visible |
| `tabletHide` | Hide below 1024px (64rem); the 1024px boundary itself stays visible |
| `desktopHide` | Hide below 1280px (80rem); the 1280px boundary itself stays visible |

Breakpoints are exclusive (width `<` the boundary). Combining several `*Hide` props resolves to the widest, so `mobileHide tabletHide` hides below 1024px.

## Show

Show elements only below a breakpoint, the reverse of the hide props.

| Prop | Description |
|------|-------------|
| `mobileShow` | Show only below 768px (48rem); hidden from 768px up |
| `tabletShow` | Show only below 1024px (64rem); hidden from 1024px up |
| `desktopShow` | Show only below 1280px (80rem); hidden from 1280px up |

Show and hide are separate categories, so they combine: `mobileHide tabletShow` shows an element only from 768 to 1024px. A mobile menu button that disappears once the full navigation fits is `<IconButton tabletShow aria-label="Menu">`.

## Items

Cross-axis alignment for flex items (align-items). Controls how flex children align perpendicular to the flex direction.

| Prop | Description |
|------|-------------|
| `itemsStart` | Align items to start (top/left) |
| `itemsEnd` | Align items to end (bottom/right) |
| `itemsCenter` | Align items to center |
| `itemsBaseline` | Align items to baseline |
| `itemsStretch` | Stretch items to fill container |

## Justify

Main-axis alignment for flex items (justify-content). Controls how flex children distribute along the flex direction.

| Prop | Description |
|------|-------------|
| `justifyStart` | Pack items toward the start of the main axis |
| `justifyEnd` | Pack items toward the end of the main axis |
| `justifyCenter` | Center items along the main axis |
| `justifyBetween` | Distribute items with space between them |
| `justifyAround` | Distribute items with space around them |
| `justifyEvenly` | Distribute items with equal space around them |
| `justifyStretch` | Stretch items to fill the main axis |
| `justifyBaseline` | Align items along their baseline on main axis |

## Align self

Cross-axis alignment for a single flex or grid item (align-self), overriding the parent's `items` value for that one child.

| Prop | Description |
|------|-------------|
| `alignSelfAuto` | Use the parent's align-items value (`align-self: auto`) |
| `alignSelfStart` | Align this item to the start of the cross axis |
| `alignSelfEnd` | Align this item to the end of the cross axis |
| `alignSelfCenter` | Center this item on the cross axis |
| `alignSelfStretch` | Stretch this item to fill the cross axis |
| `alignSelfBaseline` | Align this item to its baseline |

## Justify self

Inline-axis alignment for a single grid item within its grid area (justify-self). Useful with CSS anchor positioning.

| Prop | Description |
|------|-------------|
| `justifySelfAuto` | Use the parent's justify-items value (`justify-self: auto`) |
| `justifySelfStart` | Align this item to the start of the inline axis |
| `justifySelfEnd` | Align this item to the end of the inline axis |
| `justifySelfCenter` | Center this item on the inline axis |
| `justifySelfStretch` | Stretch this item to fill the inline axis |

## Position

CSS positioning property values for controlling element position behavior.

| Prop | Description |
|------|-------------|
| `relative` | Relative positioning |
| `absolute` | Absolute positioning |
| `fixed` | Fixed positioning |
| `sticky` | Sticky positioning; sticks at the top edge with no `top-*` class |
| `static` | Static positioning |

`sticky` sticks at the top edge (`top: 0`) on its own. Set the `--sticky-top` CSS variable on the element or an ancestor to stick below a fixed header, for example `--sticky-top: 4rem`. A `top-*` class still wins, and an element with a `bottom-*` class gets no top. The default top edge needs `@vaneui/ui` 1.5.0 or later.

## Display

CSS display property values for controlling element layout behavior.

| Prop | Description |
|------|-------------|
| `inline` | Inline display - flows with text |
| `block` | Block display - takes full width, new line |
| `inlineBlock` | Inline-block display - inline but with block properties |
| `flex` | Flex display - flexbox container |
| `inlineFlex` | Inline-flex display - inline flexbox container |
| `grid` | Grid display - CSS grid container |
| `inlineGrid` | Inline-grid display - inline grid container |
| `contents` | Contents display - element's box is removed, children display as if parent didn't exist |
| `table` | Table display - behaves like table element |
| `tableCell` | Table-cell display - behaves like td element |
| `hidden` | Hidden display - element is not visible |

## Overflow

Overflow behavior for content that exceeds container bounds.

| Prop | Description |
|------|-------------|
| `overflowAuto` | Auto overflow - show scrollbars if needed |
| `overflowHidden` | Hidden overflow - clip content without scrollbars |
| `overflowClip` | Clip overflow - hard clip without scrollbars |
| `overflowVisible` | Visible overflow - content extends beyond bounds |
| `overflowScroll` | Scroll overflow - always show scrollbars |
| `overflowXAuto` | Auto overflow on X-axis only |
| `overflowYAuto` | Auto overflow on Y-axis only |
| `overflowXHidden` | Hidden overflow on X-axis only |
| `overflowYHidden` | Hidden overflow on Y-axis only |
| `overflowXClip` | Clip overflow on X-axis only |
| `overflowYClip` | Clip overflow on Y-axis only |
| `overflowXVisible` | Visible overflow on X-axis only |
| `overflowYVisible` | Visible overflow on Y-axis only |
| `overflowXScroll` | Scroll overflow on X-axis only |
| `overflowYScroll` | Scroll overflow on Y-axis only |

## Wrap

Flex item wrapping behavior for multiline layouts.

| Prop | Description |
|------|-------------|
| `flexWrap` | Allow flex items to wrap to new lines when container is too narrow |
| `flexNoWrap` | Force flex items to stay on single line (may overflow) |
| `flexWrapReverse` | Wrap flex items in reverse order (last items wrap first) |

## Gap

Spacing between flex/grid items.

| Prop | Description |
|------|-------------|
| `gap` | Enable gap spacing between children |
| `noGap` | Disable gap spacing |

## Flex direction

Flex layout direction for arranging children.

| Prop | Description |
|------|-------------|
| `row` | Flex direction row (horizontal) |
| `column` | Flex direction column (vertical) |
| `rowReverse` | Flex direction row-reverse |
| `columnReverse` | Flex direction column-reverse |

## Flex

Flex-grow / flex-shrink shorthand for distributing space along the main axis. Mutually exclusive: only one value can be active.

| Prop | Description |
|------|-------------|
| `flex1` | Take up remaining space (`flex: 1 1 0%`); the standard "fill the rest" behavior |
| `flexAuto` | Grow but respect intrinsic content size (`flex: 1 1 auto`) |
| `flexNone` | Don't grow and don't shrink (`flex: none`); fixed-size in a flex container |

## Shrink

Flex-shrink override. Independent toggle so it can be combined with `flex1`/`flexAuto` or used standalone.

| Prop | Description |
|------|-------------|
| `noShrink` | Prevent the item from shrinking below its content size (`shrink-0`); typical for fixed-width sidebars in a flex row |

## Border

Border visibility on component sides. Side props compose: `borderT borderL` applies both. `noBorder` resets and wins.

| Prop | Description |
|------|-------------|
| `border` | Enable border on all sides |
| `borderT` | Enable border on top |
| `borderB` | Enable border on bottom |
| `borderL` | Enable border on left |
| `borderR` | Enable border on right |
| `borderX` | Enable border on left and right |
| `borderY` | Enable border on top and bottom |
| `borderStart` | Enable border on the inline-start side (flips under `dir="rtl"`) |
| `borderEnd` | Enable border on the inline-end side (flips under `dir="rtl"`) |
| `noBorder` | Disable all borders |

The layout components (`Row`, `Col`, `Stack`, `Grid2` to `Grid6`, `Container`, `Card` and `Section`) also take `strongBorder`, which keeps the border sides as set and paints them in the appearance's strong color, the one its focus ring uses. A `filled` Card, whose border is otherwise transparent, shows it too. It is listed in each of those components' own props tables, and the [Card strong border example](/docs/layout-components/card#strong-border-for-a-selected-card) shows it on a row of plans. `strongBorder` needs `@vaneui/ui` 1.4.5 or later.

## Margin

External spacing that scales with the component's size prop, available on layout components and block typography. Side props compose: `marginT marginB` applies both. `noMargin` resets and wins. Block typography defaults to `noMargin`.

| Prop | Description |
|------|-------------|
| `margin` | Enable margin on all sides |
| `marginX` | Enable margin on left and right |
| `marginY` | Enable margin on top and bottom |
| `marginT` | Enable margin on top |
| `marginB` | Enable margin on bottom |
| `noMargin` | Disable all margins |

## Shadow

Drop shadow visibility and size. `shadow` follows the component's size prop. `shadowXs` to `shadowXl` fix the size whatever the component's size, on the component's own ramp: compact for UI components such as `Button` and `Input`, deeper for layout components such as `Card`, `Modal` and `Popup`. All seven props share one category, so set one at a time. The fixed sizes need `@vaneui/ui` 1.4.5 or later.

| Prop | Description |
|------|-------------|
| `shadow` | Enable drop shadow at the component's size |
| `shadowXs` | Extra-small drop shadow, whatever the component's size |
| `shadowSm` | Small drop shadow, whatever the component's size |
| `shadowMd` | Medium drop shadow, whatever the component's size |
| `shadowLg` | Large drop shadow, whatever the component's size |
| `shadowXl` | Extra-large drop shadow, whatever the component's size |
| `noShadow` | Disable drop shadow |

## Ring

Inset ring visibility. `insetRing` is an always-on decorative inset ring, not the keyboard focus indicator (that is `focusVisible`, in the Focus visible section).

| Prop | Description |
|------|-------------|
| `insetRing` | Enable the inset ring |
| `noInsetRing` | Disable the inset ring |

## Focus visible

Focus-visible outline visibility for keyboard navigation indicators.

| Prop | Description |
|------|-------------|
| `focusVisible` | Enable focus-visible outline |
| `noFocusVisible` | Disable focus-visible outline |

Default on `Button`, `IconButton`, `Link`, `NavLink`, `MenuItem`, and the form controls (`Input`, `Textarea`, `Select`, `Checkbox`, `Radio`, `Switch`). Auto-enabled on components that tag-switch to `<a>` via `href` (`Badge`, `Card`, `Chip`, `Code`, `Row`, `Col`, `Stack`).

## Cursor

Cursor appearance for interactive elements and states.

| Prop | Description |
|------|-------------|
| `cursorPointer` | Pointer cursor - indicates clickable element |
| `cursorDefault` | Default cursor - standard arrow |
| `cursorNotAllowed` | Not-allowed cursor - indicates disabled state |
| `cursorNone` | No cursor - hides the cursor |
| `cursorText` | Text cursor - indicates selectable text |
| `cursorMove` | Move cursor - indicates draggable element |
| `cursorWait` | Wait cursor - indicates loading/processing |

## Transition

Animation effects for state changes.

| Prop | Description |
|------|-------------|
| `transition` | Enable smooth transitions between states |
| `noTransition` | Disable transitions for instant state changes |

## Whitespace

Text wrapping and whitespace behavior. Typography components and UI elements such as `Button`, `Badge`, `Code` and `Input` take these props, and from `@vaneui/ui` 1.4.5 so do the layout components `Row`, `Col`, `Stack`, `Grid2` to `Grid6`, `Container`, `Card` and `Section`. `white-space` is inherited, so `<Row whitespaceNowrap>` keeps every line of text inside the row from wrapping, as in the [Img noShrink example](/docs/layout-components/img#keeping-its-size-in-a-row-with-noshrink).

| Prop | Description |
|------|-------------|
| `whitespaceNowrap` | No wrap - text stays on single line |
| `whitespaceNormal` | Normal wrapping - default browser behavior |
| `whitespacePre` | Preserve whitespace and line breaks |
| `whitespacePreWrap` | Preserve whitespace, wrap text |
| `whitespacePreLine` | Preserve line breaks, collapse spaces, wrap text |
| `whitespaceBreakSpaces` | Preserve whitespace including trailing spaces, wrap text (`white-space: break-spaces`) |

## Width

Component width sizing.

| Prop | Description |
|------|-------------|
| `wFull` | Set width to 100% |
| `wFit` | Set width to fit-content |
| `wAuto` | Set width to auto |
| `wScreen` | Set width to 100vw (viewport width), removes max-width constraint |

## Responsive width

Full width below a breakpoint, on top of the component's base width.

| Prop | Description |
|------|-------------|
| `mobileWFull` | Full width below 768px (48rem); base width from 768px up |
| `tabletWFull` | Full width below 1024px (64rem); base width from 1024px up |
| `desktopWFull` | Full width below 1280px (80rem); base width from 1280px up |

`<Button mobileWFull>` fills a row that `mobileStack` turns into a column on a phone, and keeps its fit width on wider screens.

## Height

Component height sizing.

| Prop | Description |
|------|-------------|
| `hFit` | Set height to fit-content |
| `hFull` | Set height to 100% |
| `hAuto` | Set height to auto |
| `hScreen` | Set height to 100vh (viewport height), removes max-height constraint |

## Transparent

Disable background color, making the component transparent.

| Prop | Description |
|------|-------------|
| `transparent` | Disable background color - makes component background transparent |

## Responsive

Enable breakpoint-specific sizing for adaptive layouts.

| Prop | Description |
|------|-------------|
| `responsiveSizing` | Enable responsive sizing - uses breakpoint-specific classes for font size, padding, and gap |

## Object fit

Image and video sizing within their containers.

| Prop | Description |
|------|-------------|
| `objectCover` | Cover - image covers container, may be cropped |
| `objectContain` | Contain - image fits inside container, may have letterboxing |
| `objectFill` | Fill - image stretches to fill container |
| `objectNone` | None - image displays at natural size |
| `objectScaleDown` | Scale down - like contain, but never scales up |

## Blur

Backdrop blur effect for overlays and visual effects.

| Prop | Description |
|------|-------------|
| `backdropBlur` | Enable backdrop blur effect |
| `noBackdropBlur` | Disable backdrop blur effect |

## Pointer events

Element interactivity with the pointer. `Overlay` and `Popup` take these props, and from `@vaneui/ui` 1.4.5 so do the layout components `Row`, `Col`, `Stack`, `Grid2` to `Grid6`, `Container`, `Card` and `Section`. `pointer-events` is inherited: a layer with `pointerEventsNone` lets clicks through to the page behind it, and a child with `pointerEventsAuto` inside it, such as a floating toolbar, takes clicks again.

| Prop | Description |
|------|-------------|
| `pointerEventsNone` | Disable pointer events - clicks pass through the element |
| `pointerEventsAuto` | Enable pointer events (default browser behavior) |

## Constrain width

Minimum width constraint for popup and floating components.

| Prop | Description |
|------|-------------|
| `constrainWidth` | Apply size-dependent minimum width (uses --popup-min-w CSS variable) |

## Clamp height

Maximum height constraint for components.

| Prop | Description |
|------|-------------|
| `clampHeight` | Apply size-dependent maximum height (uses --max-height CSS variable) |

## Orientation

Horizontal or vertical layout direction for certain components.

| Prop | Description |
|------|-------------|
| `horizontal` | Display as a horizontal line (default) |
| `vertical` | Display as a vertical line instead of horizontal |

# Changelog

> Release notes for every @vaneui/ui version: added props and components, changes and fixes in the VaneUI React and Tailwind CSS library, newest first.

Source: https://vaneui.com/docs/reference/changelog

All notable changes to `@vaneui/ui` are recorded here.

The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html): patch for
fixes, minor for additive props and components, major for anything that changes an
existing prop name, default, or rendered element. Releases ship when work is ready
rather than on a fixed calendar.

## 1.5.0

`2026-10-31`

Fixes for the bugs found in the 1.4.6 component review, each covered by tests. A few fixes need
a new prop to work, so this is a minor release.

### Added

- `disabled`, `readOnly`, `required` and `invalid` on `RadioGroup`: they reach every `Radio` in
  the group, and a `Radio`'s own prop wins. The group also gets the matching `aria-*`
  attributes.
- `invalid` on `Field`: marks the control invalid without showing error text, for checks
  reported elsewhere on the page.
- `placeholder` on `Select`: a muted first option that can't be picked again. An uncontrolled
  select starts on it, and with `required` the empty value fails validation. `<Field select
  placeholder>` passes it through.
- `ModalCloseButton` takes every `Button` prop and children. With children it renders a
  labelled close button, such as a footer "Cancel", with Button's own look.

### Fixed

- A `Tooltip` can be the trigger of a `Menu` or `PopupTrigger`. Its ref, event handlers and
  `aria-*` attributes now go to the child element, so the menu opens on click and anchors to
  the button. Before, the menu never opened.
- `RadioGroup` and `<Field radiogroup>` honour `readOnly` and `error` from the Field (and now
  their own state props). Before, only `disabled` and `required` reached the radios.
- `MenuItem` keeps a passed `role`, so `menuitemcheckbox` and `menuitemradio` items work.
- `ModalCloseButton`: a passed size or appearance wins over its defaults (before, `lg` lost to
  the built-in `sm` with a conflict warning); a passed `onClick` runs before the close instead
  of replacing it, and `event.preventDefault()` in it keeps the modal open.
- `sticky` sticks at the top edge without a `top-*` class. Set `--sticky-top` to stick below a
  fixed header; a `top-*` class still wins, and an element with a `bottom-*` class gets no top.
- `indicatorBottom` draws the accent bar for `aria-selected="true"` (a tab), like
  `indicatorStart` does.
- `Field`: `error={true}` marks the control invalid without rendering an empty error paragraph,
  and a disabled Field (or a disabled child control) dims its label.
- A clickable `Chip` (`onClick` without `href`) is reachable by keyboard: it gets
  `role="button"`, a tab stop, and Enter and Space activation. A disabled one stays focusable
  but does nothing.
- A `Popup` or `Tooltip` with `arrow` measures `offset` from the arrow tip, so the tip no longer
  touches or overlaps the trigger (by up to 3px at `xl`).
- A `style` passed to `Popup` merges with its positioning instead of replacing it, which left
  the popup unpositioned.

[Full diff](https://github.com/vaneui/vaneui/compare/v1.4.6...v1.5.0)

## 1.4.6

`2026-10-29`

Breakpoint props for showing an element only on smaller screens and for full width below a
breakpoint, so sites no longer need `lg:hidden` or `max-mobile:w-full`.

### Added

- `mobileShow`, `tabletShow` and `desktopShow`: show an element only below 768, 1024 or 1280px,
  the reverse of `mobileHide` and friends. They combine with a hide prop, so
  `<Row mobileHide tabletShow>` shows only between 768 and 1024px.
- `mobileWFull`, `tabletWFull` and `desktopWFull`: full width below 768, 1024 or 1280px,
  keeping the component's base width above it. `<Button mobileWFull>` fills a stacked row on a
  phone and stays fit width on desktop. A `Select` applies both families to its wrapper.

[Full diff](https://github.com/vaneui/vaneui/compare/v1.4.5...v1.4.6)

## 1.4.5

`2026-10-29`

Additions that let vaneui.com drop most of its custom CSS: a progress bar, divided grids,
strong borders, NavLink indicators, shadow sizes and real light subtrees.

### Added

- `Progress`: a determinate bar, `<Progress value={40} aria-label="Upload" />`. A
  `role="progressbar"` track with `aria-valuenow`, `aria-valuemin` and `aria-valuemax`;
  `value` is clamped to 0 to `max` (100 by default). The fill is its own themed element
  (`progress.fill`), a filled bar in the appearance color over a neutral track, and it follows
  the track's shape and `transition`/`noTransition`. Heights run 2, 4, 8, 12 and 16px from `xs`
  to `xl`; `pill` by default. The fill eases to a new value, with no motion under reduced motion.
- `divided` on `Grid2` to `Grid6`: 1px lines in the divider color between and around
  the cells, in place of the gap.
- `strongBorder` on layout components (`Row`, `Col`, `Stack`, `Grid*`, `Container`, `Card`,
  `Section`): the border takes the appearance's strong color, the one its focus ring uses. A
  filled `Card`, whose border is otherwise transparent, shows it too.
- `indicatorStart` and `indicatorBottom` on `NavLink`: a 1px rail on the start edge that
  turns into a 2px accent mark when `active` or `aria-selected`, or an accent bar under the
  active tab. They are inset shadows, so the text does not move. The rail flips in
  right-to-left text.
- `shadowXs` to `shadowXl`: fix the drop shadow size on the component's own ramp
  (compact for UI components, deeper for layout ones), whatever the component's size.
  `shadow` still follows the size.
- `pointerEventsNone`/`pointerEventsAuto` and the `whitespace*` props on layout
  components: `Row`, `Col`, `Stack`, `Grid*`, `Container`, `Card` and `Section`.
- `noShrink` on `Img`, so an image keeps its size in a tight `Row`.
- Selected options: a `NavLink` or `MenuItem` with `aria-selected="true"` (an option in a
  listbox, like a search result) takes the hover fill.

### Changed

- Dark mode colors are `light-dark()` pairs. The dark block's colors are now one list of
  `light-dark(light, dark)` pairs on every `data-theme` element, and `data-theme` sets
  `color-scheme`, which picks the side. Pages without `data-theme` keep the `@theme` values and
  are unaffected. Uncompiled, `light-dark()` needs Chrome 123, Firefox 120 or Safari 17.5;
  bundlers that compile it for older browsers (Next.js does by default) keep those working. To
  change a color in both schemes, re-declare it as a pair under
  `:root[data-theme], [data-theme]:not(:root)`, after the VaneUI stylesheet.

### Fixed

- `data-theme="light"` makes a subtree light inside a dark page or wrapper. It only reset
  `color-scheme`, so the dark colors still came through. It now resolves every pair to its light
  side. On `<html>` it changes nothing, so token customizations made with `@theme` keep working.

## 1.4.4

`2026-10-10`

A consistency pass on `Tooltip`: it is now sized and coloured as a label, not a panel.

### Added

- `Tooltip` takes `Popup` props directly, like `Menu`: `<Tooltip lg placeBottom arrow>`.
  Size, appearance, variant, shape, placement, `arrow`, `offset` and `className` style the
  tooltip. `popupProps` still works and is combined with them.

### Changed

- `Tooltip` is filled in ink: near-black, and near-white in dark mode, like a filled
  primary `Button`. It was gray. `<Tooltip secondary>` or
  `themeDefaults={{ tooltip: { secondary: true } }}` brings the gray back.
- `Tooltip` text follows its size: 10, 12, 14, 16 and 18px from `xs` to `xl`, one step
  under a `Button` of the same size. It inherited the page's text (16px at every size).
- `Tooltip` padding and radius follow the `Button` ramp, so a tooltip is about as tall as a
  `Button` of the same size (29px instead of 44px at the default `sm`). Padding no longer
  shrinks on tablets and phones.
- Long tooltips wrap inside a cap that grows with size (16–32rem, 20rem at `sm`) instead
  of running on one line across the page.

### Fixed

- Popups placed above or below stay on screen next to an anchor at the viewport edge in
  browsers with CSS anchor positioning. They were centred on the anchor and cut off; they
  now line up with the anchor's edge, and the arrow follows.

## 1.4.3

`2026-09-30`

Fixes from a review of the components composed into real screens (dashboards, forms,
landing pages, articles, overlays, a storefront).

### Added

- `Table` and `Alert` take a font family (`fontSans`, `fontMono`, …) and default to
  `fontSans`. Their cells and raw text used to fall back to the page's own font (a serif
  on an unstyled page), because the scoped reset never sets one.

### Changed

- `Input` and `Select` are as tall as `Button` at every size. They used a looser line
  height, so a field was 4.8px taller than the button beside it at `md`. Their corner
  radius now matches too. Every `Input` and `Select` gets slightly shorter.
- List markers sit inside the list box. The marker gutter was 12px at `md`, so bullets
  and `10.` hung outside it; it is now 16–32px by size. An `icon` item's icon moves into the
  same gutter, so icon items and plain items share one text column.
- `transition` no longer animates the focus ring, only colors, shadows and transforms.

### Fixed

- Words no longer break mid-word in rows and tables. The long-token wrapping added for
  URLs let a short label beside a full-width control shrink to one letter per line, and
  split prices and names in table cells. Titles, lists and blockquotes now wrap long tokens
  too, instead of overflowing on a phone.
- An unselected `RadioGroup` no longer shows every radio as selected.
- The invalid state is visible. `Input`, `Select` and `Textarea` drew their danger ring at
  30% strength, fainter than a normal field; it is now full strength. Text fields also use
  the form-control border token, like `Checkbox`, `Radio` and `Switch`.
- The active `NavLink` stands out: it is semibold on a stronger tint, and hover no longer
  looks the same as the current page. A trailing `Badge` sits at the row's end.
- `Link` and a `Card` with `href` draw a visible focus ring in dark mode and on colored
  surfaces. It used the browser's default color.
- Text stays readable on filled surfaces. Secondary and tertiary text, ghost buttons and
  links on a filled `Card` or `Section` take the surface's text color.
- `filled` without an appearance no longer turns text white on an unpainted surface.
- Whole-page dark mode paints the page, so cards no longer sit darker than the page.
  Any background you set on `html` or `body` still wins.
- `Mark` shows a visible highlight.
- An svg in running text stays inline instead of breaking the line.
- `Tooltip`, `Popup` and menus render in the library font. A string `title` on `Modal`
  renders as a `Title`.
- `Modal` returns focus to the button that opened it on every close path.
- Escape inside a `Menu` closes only that menu, not the `Modal` around it or the whole
  menu tree.
- Menu items sit flush again; a 16px gap had appeared between them.
- Popups placed above or below keep their own width instead of shrinking to a small
  trigger, so tooltips no longer wrap one word per line.
- End-aligned and left popups stay at their trigger under `dir="rtl"`.
- `Modal` keeps a margin on a phone instead of running edge to edge.
- `ModalCloseButton` keeps its own look under app-wide `button.main` defaults (a filled
  default made the × invisible) and is square like `IconButton`.
- A loading `Button` with an icon keeps its size.
- A read-only `Checkbox` no longer toggles, a read-only `Select` can no longer be changed,
  and read-only toggles dim like read-only text fields.
- `Field` passes `disabled`, `required` and `readOnly` to a child control, including every
  `Radio` of a child `RadioGroup`. Control-only attributes no longer land on its wrapper div.
- `<Link sm>` renders at `sm`; an explicit size used to be ignored.
- A size set on the switch input theme reaches the track.
- A disabled `Link` looks disabled, and disabled fields show the not-allowed cursor.
  Disabled opacity now reads the `--disabled-opacity` token.
- `Select` stays on one line in a row, `noShrink` reaches it, and a placeholder option
  is muted like an `Input` placeholder.
- `Textarea` honours `rows` below three lines.
- A clickable `Chip` shows the focus ring, and linked `Card`, `Chip` and `Badge` get a hover
  tint.
- Hovering another menu item closes an open sibling submenu, and a submenu's trigger keeps
  its tint while the submenu is open.
- `Alert` text uses body line-height and a leading icon centres on the first line.
- A `Card` with `href` warns in development when it contains a button, link or field.

## 1.4.2

`2026-08-22`

### Fixed

- `Field`'s label now scales with the field. The label, description and error
  were pinned to `sm` at every size, so `<Field xl>` grew the control and left its
  label behind. The label now takes the field's size and the help and error text
  sit one step below it.
- `Field`'s inline checkbox and switch line up with their label. The control
  resolved its line box against the page root instead of the label's font
  metrics, so it sat high and the switch track overflowed its own box.
- `Field`'s help and error text stay readable on a filled surface. Their pinned
  secondary and danger colors lost contrast on a fill; under any filled ancestor,
  the field itself or a `Card` or `Row` above it, they now take that surface's
  text color.

## 1.4.1

`2026-08-22`

### Added

- `Field` can render its own control, instead of only wrapping one passed as
  a child. Pass `type` (a control kind such as `select`, or a native input type
  such as `password`, `email`, `date`) or one of the six booleans `textInput`,
  `textarea`, `select`, `checkbox`, `switch`, `radiogroup`. Surface props
  (`appearance`, `variant`, `shape`, `border`, `ring`, `shadow`, `transparent`)
  route to the rendered control, native attributes go to the control, and
  `ref` now points at the control instead of the wrapper. Layout props and
  `className` stay on the wrapper. Children still reach the control, so
  `<option>` and `<Radio>` children keep working. `checkbox` and
  `switch` lay out inline, control first and label beside it, unless an
  explicit `row`/`column` falls back to the plain stacked layout. Naming no
  control leaves today's children mode completely unchanged.

### Changed

- `Field`'s `type` prop is now a closed union of the control kinds and
  native input types above. It previously accepted any string, inherited from
  the anchor attributes `Field` spreads for tag switching, and Field has no
  `href`-based tag switching of its own, so a value like `<Field type="button">`
  was already reaching the wrapper `<div>` and emitting an invalid `type`
  attribute at runtime. The type change surfaces that pre-existing bug at
  compile time rather than removing a working option.

### Fixed

- The conflicting-props dev warning no longer fires on composable side
  toggles. `border` and `margin` side toggles compose by design, so
  `<Card borderT borderL>` and `<Card marginT marginB>` are correct usage, yet
  every component warned that they conflicted. The warning now skips composable
  categories, matching the rule the resolver itself already used. It still warns
  in the one case that is genuinely ambiguous there: when a `no*` reset is
  combined with a side toggle (`<Card borderT noBorder>`), where the reset
  discards the toggle and wins.
- `Field` no longer emits a dangling `htmlFor` for a radio group. A
  `radiogroup` is not a labelable element and never claims the generated id, so
  the label pointed at nothing. `Field` now omits `htmlFor` for a radio group in
  both modes; the accessible name continues to come from `aria-labelledby`.

## 1.4.0

`2026-08-20`

### Changed

- Portalled floating content waits for hydration before it mounts. A portal
  has no server markup, so `Popup`, `Modal` and `Overlay` returned `null` during
  SSR — but the *first client render* portalled immediately, giving React DOM it
  never emitted server-side and forcing it to throw the subtree away and rebuild
  it. They now stay closed through the hydrating render and mount on the next one.

  The gate is on the open state rather than the portal call, so the transition
  and every element-dependent effect sit downstream of it and run once the
  element actually attaches. Two consequences worth knowing:

  - Portalled content that is open on its first render now transitions in
    (`entering` → `entered`) instead of appearing already `entered`. Content
    opened by interaction is unaffected: hydration is long since complete.
  - `portal={false}` is untouched. Inline content has server markup, so it still
    renders server-side and still starts `entered` — the SSR test that pins this
    behaviour is unchanged.

  `Menu` now tracks its content element in state rather than a bare ref. Its
  "focus the first item on open" effect was keyed on the open flag alone, so a
  `defaultOpen` menu focused nothing once the content mounted a render later.

## 1.3.1

`2026-08-20`

### Fixed

- A `sharp` Select opened a rounded dropdown. The shape props emit Tailwind
  classes onto the field and never touch `--br`, so the list — a pseudo-element
  that cannot take a class — always painted the size-driven radius. `Select` now
  publishes its resolved shape as `data-shape`, which the picker rules read.
  `pill` deliberately still keeps `--br`: its own radius is effectively infinite
  and a tall list box given that radius swallows its first and last rows.

- `Modal`, `Popup` and `Tooltip` listed the `shape` category twice.
  `VISUAL_LAYOUT` already folds `SHAPE` in, and all three spread `...SHAPE` over
  it again. The duplicate is invisible to the type system — the `as const` union
  is identical either way — but every consumer that iterates the array saw the
  category twice, which rendered the shape props twice in generated prop tables
  and produced duplicate React keys. `categoryUniqueness.test.ts` now asserts no
  component names a category more than once.

## 1.3.0

`2026-08-20`

### Added

- `Label` supports `disabled`. It was the only form control without the
  category, so a disabled field kept a full-strength label. `<Label disabled>`
  now dims to the same `opacity-50` every other control uses, and a Label
  containing a disabled control dims with it, so you disable the field rather
  than both. The dim is opacity-only: a Label wraps its control, so
  `pointer-events-none` would have made the control it labels unclickable.

  A wrapper that dims what it contains must not let the contained control fade
  a second time. `Label` and the `Select` wrapper now cancel the nested
  `opacity-50`, which previously rendered a disabled `Select` field at a
  quarter strength rather than a half.

### Changed

- The `Select` dropdown takes its colours from the field. `option`,
  `optgroup` and `::picker(select)` were pinned to `--color-bg-primary` /
  `--color-text-primary`, so a `filled` or `danger` Select opened a plain light
  list. They now resolve `--bg-color` / `--text-color` / `--border-color`, which
  options already inherit as children of the field. `ghost` resolves its
  background to transparent, which would let the page show through the popup,
  so it falls back to the theme surface.

  A disabled option, typically a placeholder, was pinned to
  `--color-text-secondary` and sat at 1.58:1 on a filled list. It now fades
  toward the list's own background instead, which reproduces the previous
  contrast on the default surface and lifts the filled case to 2.71:1.

### Fixed

- The `Select` dropdown opened upward over the page. The UA styles
  `::picker(select)` with `position-try-order: most-block-size`, which picks
  whichever side has MORE room rather than the first side that fits — so any
  field past the middle of the window opened its list above itself even with
  several hundred pixels free below. Pinning the order back to `normal` opens
  the list downward and keeps the flip for when it genuinely does not fit. The
  gap between field and list is now `margin-block` rather than
  `margin-block-start`, because the flipped-up position anchors the picker's
  bottom edge and a top margin left it touching the field.

- `Field`'s help and error text could vanish on a filled `Field`. Both are
  rendered by the component with pinned appearances (`secondary` and `danger`),
  which an author cannot reach from outside, and `--color-text-secondary` IS
  `--color-bg-filled-secondary` — so `<Field filled secondary>` painted its
  description at exactly 1.00:1 against its own surface. On a filled `Field`
  both now take the surface's own text colour. A plain `Field` keeps its muted
  description.

## 1.2.1

`2026-08-20`

### Fixed

- Every appearance on `Img` painted the same neutral border. An appearance is
  only a palette: it sets the intermediate `--app-*` variables, and the variant
  axis is what maps those onto `--border-color`. `data-variant` is emitted only
  when a variant key is extracted, and `Img` declared the variant category but
  set no variant default, so `<Img border danger>` and `<Img border success>`
  resolved identically. `Img` now defaults to `outline`, like every other
  component. A plain `<Img>` is unchanged: with no appearance it still emits
  neither attribute.

  This is the same failure as `Spinner` in 1.1.3, reached a different way, so it
  is now a test rather than a fix. `appearanceResolution.test.ts` asserts that
  every component declaring an appearance also resolves a variant, with `Link`
  as the one documented exception (its `LinkVariantClassMapper` consumes
  `--app-text` directly). Class-name assertions cannot see this class of bug:
  the class list is identical whether or not the colour resolves.

## 1.2.0

`2026-08-19`

### Changed

- `Button` and `IconButton` now render the `Spinner` component for their
  loading state, instead of a private ring the library maintained separately.
  There was one ring drawn two ways: `.vane-button-spinner-ring` and
  `.vane-spinner` had already drifted to different stroke rules once, and every
  future change to the spinner had to be made in both places.

  The button forwards its own size, so the ring still matches the button rather
  than falling back to `Spinner`'s `md` default, and the ring still inherits the
  button's text color, so a filled button gets a light ring. It stays decorative:
  `aria-busy` on the button already conveys the state, so the `Spinner`'s
  `role="status"` is suppressed and the wrapper is `aria-hidden`.

  Two things change for consumers who reach into the theme:

  - The `.vane-button-spinner-ring` class no longer exists. The element a
    loading button renders is now `.vane-spinner`.
  - `theme.button.spinner.spinnerElement` is gone. Restyle the ring through
    `theme.spinner` instead, which now covers standalone spinners and buttons
    at once:

    ```tsx
    <ThemeProvider extraClasses={{ spinner: { primary: 'border-4' } }}>
    ```

## 1.1.3

`2026-08-19`

### Fixed

- `Spinner`'s appearance props did nothing. `<Spinner danger>` emitted
  `data-appearance="danger"` and resolved the danger palette, but an appearance
  only reaches `--text-color` through the variant axis, and `Spinner` had no
  `variant` category, so no `data-variant` was emitted and the mapping never
  fired. Every appearance rendered the same inherited color. `Spinner` now
  carries `variant` (defaulting to `outline`, with `inheritAppearance`), so:

  ```tsx
  <Spinner danger />               {/* the danger color */}
  <Spinner danger filled />        {/* the on-danger-fill color */}
  <Spinner />                      {/* still inherits its surface */}
  ```

  A bare `Spinner` is unchanged: it emits neither attribute and keeps inheriting,
  which is what makes it readable inside a filled `Button`, `Badge` or `Card`.
  The variant carries no background here, since a ring has nothing to fill; it
  only selects which color of the appearance the ring paints in.

- The spinner ring was a 1px hairline at `xs` and `sm`. Its stroke was
  `0.125em`, and browsers floor `border-width` to whole pixels, so 1.5px and
  1.75px both painted as 1px. The stroke now floors at 2px.

- `Button`'s loading ring and `Spinner` had drifted to different strokes
  (a pinned 2px against the scaling `0.125em`), so the same ring rendered at two
  weights depending on where it came from. Both now share one rule.

## 1.1.2

`2026-08-18`

### Added

- A `Select`'s dropdown list is now styled where the engine allows it. A native
  `<select>` hands its option list to the operating system, which draws a flat,
  square, unpadded menu: the options get no layout box at all, so padding, radius
  and shadow were inert and only their colors landed. Behind
  `@supports (appearance: base-select)` the list becomes real DOM and is themed to
  match a `Menu` (surface, border, radius, shadow, padded rows, hover, and a
  checkmark on the selected option). Engines without it keep the OS picker
  unchanged, and the control is the same `<select>` either way.

### Fixed

- A `sharp` or `rounded` `Switch` reshaped only its track. The knob was
  rendered with no props and its theme pins `pill`, so a square track kept a
  circular knob. The shape now reaches the knob, and its radius insets from the
  track's by the track padding, so the two corners stay concentric rather than
  sharing one radius across boxes of different sizes.

`2026-08-18`

### Fixed

- The `Input` error icon rendered as a solid disc with a slot cut through it,
  not an exclamation mark. Its stem and dot are meant to be holes punched in the
  disc, which under the nonzero fill rule requires them to wind opposite to it.
  The stem did; the dot did not, so it merged into the disc and vanished. The
  glyph is now sampled pixel-by-pixel in the e2e suite, because both the class
  list and the icon's geometry are identical either way.

- A `Select`'s dropdown list ignored the theme. `<option>` and `<optgroup>`
  default to a transparent background, and the browser paints the popup from the
  option's own colors, so the list fell back to user-agent colors instead of the
  field's. Both now carry the surface and text tokens, group labels lose the
  user-agent italic, and a disabled option is muted.

### Changed

- A `Select`'s chevron turns danger when the field is invalid. The chevron is
  a sibling of the field rather than a descendant, so the error state was not
  reaching it and the control's trailing edge stayed neutral while `Input` and
  `Textarea` both changed.

## 1.1.0

`2026-08-18`

### Added

- `Field` wires a form control to its label, help text and error message.
  `invalid` already emitted `aria-invalid`, but nothing associated an error
  message, so a screen reader announced that a control was invalid without
  saying why. `Field` owns one id and publishes it, the label id, the
  `aria-describedby` list and the validity to whichever control it wraps.
  `Input`, `Textarea`, `Select`, `Checkbox`, `Radio` and `Switch` all read it,
  and an explicit prop on the control still wins.

  ```tsx
  <Field label="Email" description="We never share it." error={errors.email}>
    <Input type="email" />
  </Field>
  ```

  Passing an `error` also marks the control invalid, so the danger cue and the
  message can never disagree. A `RadioGroup` is not a labelable element, so it
  takes the label by reference through `aria-labelledby` instead. `Field`'s own
  size becomes the control's default, the same way `Label` already worked.

- `Tooltip` describes its trigger on hover and on keyboard focus. Built on
  `PopupTrigger`'s tooltip semantics: the trigger gets `aria-describedby` while
  open and never `aria-haspopup` or `aria-expanded`, which do not apply.

- `Spinner` promotes the ring that already existed inside `Button` to a
  component of its own. `role="status"`, sized by the size prop and coloured by
  the appearance prop.

- `Alert` is a live-region surface: `role="alert"` by default, or
  `role="status"` with `polite` for messages that should wait for a pause.

### Changed

- `Card` and `Stack` now scale their padding down on small viewports, matching the
  behavior `Section` already had. A surface's inset is chrome rather than rhythm: it
  used to stay at its desktop value while the viewport shrank, so nesting a `Stack`
  inside a `Card` inside a `Section` left as little as 220px of content on a 390px
  phone. Both axes step down together so the box stays square.

  | Size | `Card` desktop / tablet / mobile | `Stack` desktop / tablet / mobile |
  | ---- | ------------------------------- | --------------------------------- |
  | `xs` | 12 / 12 / 8 | 8 / 8 / 4 |
  | `sm` | 18 / 16 / 12 | 12 / 10 / 8 |
  | `md` | 24 / 20 / 16 | 16 / 12 / 8 |
  | `lg` | 36 / 28 / 20 | 24 / 16 / 12 |
  | `xl` | 48 / 36 / 24 | 32 / 24 / 16 |

  Desktop values are unchanged, so nothing moves above 1024px. `CardHeader`, `CardBody`
  and `CardFooter` follow the parent `Card`'s curve. To keep the previous fixed padding,
  turn the ramp off per component:
  `<ThemeProvider themeDefaults={{ card: { main: { responsiveSizing: false } } }}>`.

- `Container`, `Modal` and `Popup` ramp their padding the same way, so every surface now
  behaves consistently. `Container` follows `Section` rather than `Card`, capping its
  gutter independently of its block rhythm because a page margin is bounded by the
  viewport. `ModalHeader`, `ModalBody` and `ModalFooter` follow the parent `Modal`.
  Menu dropdowns keep their existing tighter padding at every viewport.

### Fixed

- `Container` now applies the 2:1 inline-to-block padding ratio it has always declared.
  `--aspect-ratio: 2` sat at a lower specificity than the per-size layout rule that
  resets it to `1`, so the declaration never reached the computed value and a padded
  `Container` rendered a square inset. The reset moved to a selector components can
  override. `Container` is `noPadding` by default, so this only affects callers that
  opted in, where the inline padding doubles: 32px to 64px at `md` on desktop.

  `Divider` declared the same ratio and is deliberately left at `1`: it renders with
  `box-sizing: content-box` and `width: 100%`, so inline padding is added outside the
  100% and overflows the parent rather than insetting the rule.

[Full diff](https://github.com/vaneui/vaneui/compare/v1.0.2...v1.1.0)

## 1.0.2

`2026-08-17`

### Added

- `CHANGELOG.md` now ships inside the published package. It is the single source of
  truth for release notes, and
  [the changelog page](https://vaneui.com/docs/reference/changelog) renders it directly
  from the installed package rather than keeping a second copy.

[Full diff](https://github.com/vaneui/vaneui/compare/v1.0.1...v1.0.2)

## 1.0.1

`2026-08-17`

### Fixed

- Added the missing `./table` subpath export. `import { Table } from "@vaneui/ui/table"`
  threw `ERR_PACKAGE_PATH_NOT_EXPORTED` even though the built chunks shipped, because
  `table` was the only component directory absent from the `exports` map. The
  main-barrel import was never affected.

[Full diff](https://github.com/vaneui/vaneui/compare/v1.0.0...v1.0.1)

## 1.0.0

`2026-08-16`

First stable release. The `latest` dist-tag previously pointed at `0.2.0` while all
development shipped under the `alpha` tag, so this is the first time the current
architecture is installable with a plain `npm install @vaneui/ui`.

`1.0.0` marks the public API as stable: 55 exported components across layout,
typography, controls, and overlays, driven by the boolean props API and themed
through `ThemeProvider`.

### Added

- [Table](https://vaneui.com/docs/layout-components/table) family. `Table`, `Thead`,
  `Tbody`, `Tfoot`, `Tr`, `Th`, `Td`, `Caption`, with the size prop cascading from any
  container element down to the cells.
- Dark mode through the `data-theme="dark"` token contract. No component code
  changes are required, and consumers can declare their own themes by re-declaring the
  same tokens under any selector.
- RTL support. Logical CSS utilities behind the existing props, plus `textStart` and
  `textEnd` alongside the physical `textLeft` and `textRight`.
- Nested submenus on [Menu](https://vaneui.com/docs/overlay-components/menu), with
  the full keyboard model including typeahead, `Home`, `End`, and arrow-key traversal.
- Icon container mode. [Icon](https://vaneui.com/docs/basic-components/icon) gained
  opt-in padding, shape, border, and ring, and its glyph size decoupled from the
  font-size variable.
- List markers and spacing. `listCircle`, `listSquare`, `listLowerAlpha`,
  `listLowerRoman`, inside/outside positioning, per-item gap control, automatic marker
  progression on nested lists, and a
  [ListItem](https://vaneui.com/docs/typography-components/list) `icon` prop for custom
  markers.
- Size-driven margin props on layout components and block typography, on the same
  scale as gap and padding.
- Per-side border widths and logical `borderStart` / `borderEnd` props.
- `alignSelf` and `justifySelf` props, with
  [Popup](https://vaneui.com/docs/overlay-components/popup) edge alignment driven
  through them.
- Granular inherit props (`inheritSize`, `inheritColor`, `inheritBg`,
  `inheritBorder`) alongside `inheritAppearance`.
- `wordBreak` category, and `whitespace` extended to typography components.
- `href` support on `Row`, `Col`, and `Stack`, with a conditional focus ring.

### Changed

- Prop names now mirror the Tailwind class they emit, keeping the CSS-property prefix:
  `fontLight`, `listInside`, `insetRing`, `backdropBlur`, `placeTop`, and so on. Emitted
  classes, `data-*` values, and computed styles are unchanged. The rule is in
  `.claude/rules/naming-law.md`.
- List position defaults to `listOutside`.
- Gaps and padding scale on a shared accelerating curve, and the icon-to-label gap is
  role-aware so controls and compact pills space differently at the same size.
- [Button](https://vaneui.com/docs/basic-components/button) and `IconButton` share a
  control height.
- [Badge](https://vaneui.com/docs/basic-components/badge) no longer sets `uppercase` by
  default.
- [Label](https://vaneui.com/docs/form-components/label) defaults to a stacked column
  layout, which suits forms. Use `row` for inline controls such as a checkbox.
- [Modal](https://vaneui.com/docs/overlay-components/modal) always offers a close
  button, floating it when there is no title.

### Removed

- The `brand` and `link` appearance values. `primary` keeps the same color `brand` had,
  and [Link](https://vaneui.com/docs/typography-components/link) still renders its blue
  through the `--link-text` cascade, so `<Link>` itself is unchanged.
- The `reverse` category. Use `rowReverse` or `columnReverse`.

### Fixed

- Popups and menus opened inside a `Modal` now render above the backdrop, and
  <kbd>Escape</kbd> closes the innermost overlay rather than the whole modal.
- `Popup` gained a maximum width and an inner scroll box, so wide or tall content no
  longer runs off-screen on small viewports.
- Popup arrow alignment for the `*Start` and `*End` placements, and a spurious vertical
  flip in the JavaScript positioning fallback.
- Responsive breakpoints are exclusive (`width <` the boundary), and combining several
  `*Stack` or `*Hide` props resolves to the widest.
- `Modal` no longer strands focus on `<body>` when the trigger unmounts.
- Error state is announced, not just colored: `invalid` emits `aria-invalid` and a
  `data-status` attribute, and [Input](https://vaneui.com/docs/form-components/input)
  renders a non-color alert icon.
- Keyboard focus rings on `NavLink`, `MenuItem`, `Link`, `Card`, and `Chip`.

### Accessibility

- `Modal` wires `aria-labelledby` and `aria-describedby` from `ModalHeader` and
  `ModalBody` automatically, and traps focus.
- `Input` gained a muted read-only treatment with `aria-readonly`.
- [Blockquote](https://vaneui.com/docs/typography-components/blockquote) gained a `cite`
  prop for source attribution.

[Full history](https://github.com/vaneui/vaneui/commits/v1.0.0)