# Accessibility (/ui/docs/react/accessibility)



Accessibility is built in, not bolted on. Appica UI wraps [Base UI](https://base-ui.com)
primitives, which implement the WAI-ARIA patterns — keyboard interaction, focus
management, and ARIA wiring — so the hard parts are handled. This page covers
what you get for free and the few things that remain your responsibility.

## What's handled for you [#whats-handled-for-you]

* **Keyboard interaction** — menus, listboxes, tabs, sliders, and dialogs
  implement the expected arrow-key, `Home`/`End`, `Escape`, and typeahead
  behavior, including roving `tabindex` within groups.
* **Focus management** — overlays (Dialog, Drawer, Popover) trap focus while open
  and restore it to the trigger on close.
* **ARIA wiring** — roles, `aria-expanded`, `aria-controls`, `aria-selected`, and
  label/description associations are set on the right elements.
* **Reduced motion** — every animation is reduced-motion aware (via
  `motion-reduce:transition-none` or `motion-safe:`), so motion is skipped for
  users who ask for it. See [Animation](/ui/docs/react/animation).

## Focus visibility [#focus-visibility]

A focus ring is applied globally on `:focus-visible` (keyboard focus), using the
ring tokens from [Colors](/ui/docs/react/colors#focus-rings). It stays out of the way for mouse
users and appears for keyboard users. Keep it intact — don't strip outlines from
interactive elements.

## Labeling controls [#labeling-controls]

Associate a visible label with a single control using `Field` and `FieldLabel`,
which wire up the `for`/`id` relationship automatically:

```tsx
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'

export default function EmailField() {
  return (
    <Field>
      <FieldLabel>Email</FieldLabel>
      <Input type="email" />
    </Field>
  )
}
```

<Callout type="warning" title="Groups need a different label">
  `FieldLabel` renders a `<label for>`, which targets a *single* control. For grouped components that have
  `role="group"` — `RadioGroup`, `CheckboxGroup`, `ToggleGroup` — a `<label>` can't point at the group. Label
  those with `aria-label` or `aria-labelledby` instead.
</Callout>

```tsx
<ToggleGroup aria-label="Text alignment">
  <Toggle value="left">Left</Toggle>
  <Toggle value="center">Center</Toggle>
</ToggleGroup>
```

Controls with no visible label (an icon-only button, a search field) still need an
accessible name — give them `aria-label`:

```tsx
<Button variant="ghost" size="icon-md" aria-label="Close" />
```

## Color contrast [#color-contrast]

The default light and dark palettes are tuned for legible contrast. If you
[recolor the system](/ui/docs/react/theming), re-check your accent and foreground
pairings against [WCAG](https://www.w3.org/WAI/WCAG22/quickref/) — especially the
`*-foreground` token that sits on a colored fill.

## Internationalization [#internationalization]

For right-to-left languages, mirror the UI with
[`DirectionProvider`](/ui/docs/react/rtl) so keyboard navigation and layout follow
the reading direction.

## Verify your own usage [#verify-your-own-usage]

The components are tested with `vitest-axe`, but composition is where issues
creep in. Audit your screens with the same tooling (axe, Lighthouse) and test
keyboard-only flows — the components give you a correct foundation, not a
guarantee that every assembled page is accessible.


# Animation (/ui/docs/react/animation)



Components in Appica UI animate their open, close, and state changes out of the
box. Most of this motion is plain CSS, but a few components use
[Motion](https://motion.dev) when an interaction needs smoother, interruptible
animation. In both cases, if the user has asked their system to reduce motion,
the animations are turned off automatically — see [Reduced motion](#reduced-motion).

## State-driven transitions [#state-driven-transitions]

Interactive components expose their state as `data-*` attributes — `data-open`,
`data-closed`, `data-starting-style`, `data-ending-style`, and so on. Transitions
hang off those attributes through Tailwind's `data-*` variants, so enter and exit
animations are just utility classes — no animation library required:

```tsx
// The pattern components use internally
<div
  className={cn(
    'transition-[opacity,scale] duration-200 motion-reduce:transition-none',
    'data-starting-style:scale-95 data-starting-style:opacity-0',
    'data-ending-style:scale-95 data-ending-style:opacity-0',
  )}
/>
```

The element starts and ends scaled-down and transparent, and animates to its
natural state while open. Because exit is just another state
(`data-ending-style`), elements animate out before they unmount. The single
`motion-reduce:transition-none` is what drops the animation when the user prefers
reduced motion — see below.

## Reduced motion [#reduced-motion]

Every animated component is reduced-motion aware. Most disable their transition
in one line with `motion-reduce:transition-none`; a few instead gate each rule
behind `motion-safe:`. Both rely on the same pair of custom variants the library
defines:

```css
@custom-variant motion-reduce {
  @media (prefers-reduced-motion: reduce) {
    @slot;
  }
  &:is([data-disable-animations] *) {
    @slot;
  }
}

@custom-variant motion-safe {
  @media (prefers-reduced-motion: no-preference) {
    &:not([data-disable-animations] *) {
      @slot;
    }
  }
}
```

This means animations are skipped in two situations: when the OS requests reduced
motion, **or** when a [`ReducedMotionProvider`](/ui/docs/react/reduced-motion-provider)
sets `data-disable-animations` — which also reaches portaled popups, since they
render outside the React tree.

Use the same variants in your own markup so it honors the preference too:

```tsx
// One-line opt-out — the common pattern
<div className="transition-transform duration-200 hover:scale-105 motion-reduce:transition-none">…</div>

// Or gate each rule with motion-safe:
<div className="hover:scale-105 motion-safe:transition-transform motion-safe:duration-200">…</div>
```

## Disabling animations globally [#disabling-animations-globally]

Wrap a subtree (or the whole app) to force-disable animation regardless of the OS
setting — useful for tests, demos, or a user preference toggle:

```tsx
import { ReducedMotionProvider } from '@appica/ui-react/providers/reduced-motion-provider'

export default function Providers({ children }) {
  return <ReducedMotionProvider disableAnimations>{children}</ReducedMotionProvider>
}
```

For JavaScript-driven animation (e.g. with Motion), read the resolved preference
with [`useReducedMotion`](/ui/docs/react/use-reduced-motion):

```tsx
'use client'

import { useReducedMotion } from '@appica/ui-react/hooks/use-reduced-motion'

function Reveal() {
  const reduced = useReducedMotion()
  return <div style={{ transition: reduced ? 'none' : 'opacity 300ms' }}>…</div>
}
```

## Customizing transitions [#customizing-transitions]

Tune timing per instance by overriding the relevant utilities through `className`
— tailwind-merge keeps the last value:

```tsx
<Dialog>
  <DialogContent className="motion-safe:duration-500">…</DialogContent>
</Dialog>
```

For larger durations, easing, and keyframes, override the corresponding tokens in
your stylesheet — see [Theming](/ui/docs/react/theming).


# Colors (/ui/docs/react/colors)



Appica UI's palette is organized by **role**, not by hue. Instead of `blue-500`,
you use `primary` or `info-emphasis`. This keeps components meaningful and lets a
single token override retheme the whole system. Every color is defined in
[oklch](https://oklch.com) and is overridable — see [Theming](/ui/docs/react/theming).

Each color is exposed as a Tailwind utility (`bg-*`, `text-*`, `border-*`) and as
a raw CSS variable named after the role — `var(--primary)`, `var(--foreground)`,
and so on. See [Theming](/ui/docs/react/theming#using-tokens-in-your-own-ui).

## Base colors [#base-colors]

The grayscale foundation of every layout: backgrounds, text, and borders. Each family
is a scale from subtle to intense.

### Foreground (text & icons) [#foreground-text--icons]

| Token                 | Use for                                |
| --------------------- | -------------------------------------- |
| `foreground`          | Default body text                      |
| `foreground-muted`    | Secondary text, descriptions           |
| `foreground-subtle`   | Placeholders, disabled labels, markers |
| `foreground-strong`   | Emphasized text                        |
| `foreground-emphasis` | Stronger emphasis                      |
| `foreground-intense`  | Headings, highest-contrast text        |
| `foreground-inverse`  | Text on an inverted surface            |

### Background (surfaces) [#background-surfaces]

| Token                | Use for                           |
| -------------------- | --------------------------------- |
| `background`         | The base page surface             |
| `background-subtle`  | Slightly raised areas, cards      |
| `background-muted`   | Hover fills, inset panels         |
| `background-strong`  | More prominent fills              |
| `background-inverse` | Inverted surfaces (e.g. tooltips) |

### Border [#border]

| Token             | Use for                      |
| ----------------- | ---------------------------- |
| `border`          | Default borders and dividers |
| `border-muted`    | Faint separators             |
| `border-strong`   | Higher-contrast borders      |
| `border-emphasis` | Emphasized outlines          |
| `border-intense`  | Strongest outlines           |
| `border-inverse`  | Borders on inverted surfaces |

## Accent palettes [#accent-palettes]

Six semantic accents share an identical scale, so they're interchangeable by
intent. `primary` and `secondary` carry your brand; `error`, `success`,
`warning`, and `info` carry status.

| Step           | Role                                            |
| -------------- | ----------------------------------------------- |
| `*-subtle`     | Translucent tint — soft background wash         |
| `*-soft`       | Slightly stronger translucent fill              |
| `*-muted`      | Muted solid                                     |
| `*` (base)     | The default accent fill                         |
| `*-strong`     | Stronger, for hover/active                      |
| `*-emphasis`   | The vivid, on-brand value                       |
| `*-intense`    | The boldest value                               |
| `*-foreground` | Text/icon color that sits legibly on the accent |

For example, an info alert pairs `bg-info-subtle` (surface), `bg-info-soft` (border), with `text-info-foreground`;
a solid primary button pairs `bg-primary` with `text-primary-foreground`.

## Focus rings [#focus-rings]

Focus styling has its own token set so the ring can differ from borders. Each maps
to a matching role, and components apply them automatically on `:focus-visible` —
see [Accessibility](/ui/docs/react/accessibility).

| Token            | Use for                              |
| ---------------- | ------------------------------------ |
| `ring`           | Default focus ring, neutral controls |
| `ring-input`     | Inputs and form fields               |
| `ring-primary`   | Primary controls                     |
| `ring-secondary` | Secondary controls                   |
| `ring-error`     | Error / invalid controls             |
| `ring-success`   | Success controls                     |
| `ring-warning`   | Warning controls                     |
| `ring-info`      | Info controls                        |
| `ring-light`     | Controls on inverted / dark surfaces |

## Overriding the palette [#overriding-the-palette]

Any token can be redefined after the stylesheet import, separately per theme:

```css
:root {
  --secondary: oklch(0.827 0.119 306.383);
}
.dark {
  --secondary: oklch(0.714 0.203 305.504);
}
```

Head to [Theming](/ui/docs/react/theming) for the raw-vs-theme token model and the
non-color tokens (radius, shadows, typography).


# Composition (/ui/docs/react/composition)



Appica UI components ship fully styled, but you often need them to *be* something
else — a navigation link that's actually your router's `Link`, a tooltip trigger
that's actually your own button. The `render` prop, inherited from
[Base UI](https://base-ui.com), makes that possible without losing the
component's styling or behavior.

For the related case of a plain link that should merely *look* like a button, use
the exported variant helpers instead — see [Links that look like a button](#links-that-look-like-a-button).

## Rendering as a different element [#rendering-as-a-different-element]

Pass an element to `render` and the component adopts it as its output, merging in
its own props, classes, and event handlers. For instance, render a `Badge` as an
`<a>` so a status chip becomes a real link:

```tsx
import { Badge } from '@appica/ui-react/badge'

// Renders an <a> styled as a badge.
export default function TagBadge() {
  return <Badge render={<a href="/tags/react" />}>React</Badge>
}
```

<Callout type="warning" title="Don't render links as buttons">
  This is safe because `Badge` adds no interactive semantics. `Button` is different — it *enforces* button
  semantics (`role`, keyboard handling), so rendering an `<a>` through it produces a link masquerading as a
  button, which misleads assistive tech. To make a link merely *look* like a button, style the `<a>` directly —
  see [Links that look like a button](#links-that-look-like-a-button).
</Callout>

## Rendering as a component [#rendering-as-a-component]

`render` also accepts a component element — ideal for framework routers. A
`NavigationLink` stays a link while delegating navigation to your router's `Link`:

```tsx
import Link from 'next/link'
import { NavigationLink } from '@appica/ui-react/navigation'

export default function PricingLink() {
  return <NavigationLink render={<Link href="/pricing" />}>Pricing</NavigationLink>
}
```

The same pattern composes the interactive parts of larger components. For
instance, make a tooltip's trigger your own button:

```tsx
import { Tooltip, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'
import { Button } from '@appica/ui-react/button'

export default function HintedButton() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline">Hover me</Button>} />
      <TooltipContent>Helpful hint</TooltipContent>
    </Tooltip>
  )
}
```

## Links that look like a button [#links-that-look-like-a-button]

Sometimes you don't want to *change* a component's element — you want a plain link
(or other element) to simply wear a component's styling. Don't reach for `render`
here: rendering an `<a>` through `Button` forces button semantics onto a link.
Instead, apply the exported `buttonVariants` classes directly to the element that
already has the right semantics:

```tsx
import { buttonVariants } from '@appica/ui-react/button'

// A real link that looks like a primary button.
<a href="/ui/docs" className={buttonVariants({ variant: 'primary', size: 'md' })}>
  Read the docs
</a>

// Works with a router Link too.
<Link href="/pricing" className={buttonVariants({ variant: 'outline' })}>
  View pricing
</Link>
```

<Callout type="note" title="Why not just render the link as a Button?">
  Links and buttons have different, non-interchangeable semantics: a link navigates, a button performs an
  action. The `render` prop is for adopting a *different element while keeping the component's role* — not for
  repainting a link as a button. Styling the `<a>` with `buttonVariants` keeps link semantics intact and gives
  you the identical look.
</Callout>

`buttonVariants` isn't the only one — several components export their variant
recipe for exactly this purpose:

| Helper                   | Import from                   | Style any element like             |
| ------------------------ | ----------------------------- | ---------------------------------- |
| `buttonVariants`         | `@appica/ui-react/button`     | Button (`variant`, `size`)         |
| `inputVariants`          | `@appica/ui-react/input`      | Input (`variant`, `size`, `state`) |
| `navigationLinkVariants` | `@appica/ui-react/navigation` | NavigationLink (`variant`, `size`) |

Each takes the same variant props as its component and returns a className string,
so they drop into any element and compose with your own classes through `cn` or a
template literal.

## Where to put `className` [#where-to-put-classname]

This is the one rule worth memorizing. When composing a render-prop wrapper:

* **Visual overrides** (`className`, `style`) go on the **wrapper**.
* **Structural/behavioral props** (`href`, `type`, `variant`, `size`, rendering as a different element) go on the JSX inside `render`.

```tsx
// ✅ Do — className on the wrapper
<TooltipTrigger
  className="rounded-full"
  render={<Button variant="ghost">Help</Button>}
/>

// ❌ Don't — className on the render JSX
<TooltipTrigger render={<Button variant="ghost" className="rounded-full">Help</Button>} />
```

<Callout type="warning" title="Why this matters">
  Putting `className` on the inner JSX can cause a **React hydration mismatch** in Server Components: the styled element
  is built on the server, serialized across the boundary, then cloned on the client, and the final class strings can
  disagree. Keeping `className` on the wrapper avoids it — and class precedence still works, since the wrapper's classes
  are merged last and win on conflicts.
</Callout>

If you specifically need a class on the inner element, extract the trigger into
its own `'use client'` component rather than promoting the whole page to client.

## Class merging [#class-merging]

Overrides are merged with [tailwind-merge](https://github.com/dcastil/tailwind-merge),
so conflicting utilities are de-duplicated and the last one wins. You don't need
to fight specificity:

```tsx
// `rounded-full` overrides the component's default radius cleanly.
<Button className="rounded-full px-8">Pill</Button>
```


# Dark Mode (/ui/docs/react/dark-mode)



Appica UI is dark-mode-ready out of the box. The token system ships both a light
and a dark palette; switching themes is a matter of toggling a class on the
`<html>` element, which [`ThemeProvider`](/ui/docs/react/theme-provider) manages for
you — including persistence and a no-flash first paint.

## How it works [#how-it-works]

Dark mode is **class-based**. When the `dark` class is on a `<html>` ancestor,
the dark token values apply. The library defines the variant as:

```css
@custom-variant dark (&:is(.dark *));
```

So you can write dark-only utilities in your own markup too:

```tsx
<div className="bg-background text-foreground dark:shadow-xl">…</div>
```

## Setup [#setup]

Wrap your app in `ThemeProvider` at your app's root (covered in
[Installation](/ui/docs/react/installation)). It applies the correct class before
the page paints, so there's no flash of the wrong theme on load. The example
uses Next.js's root layout — see the
[Framework notes](/ui/docs/react/installation#framework-notes) for where this file
lives in Vite, React Router / Remix, TanStack Start, and Astro:

```tsx title="app/layout.tsx (Next.js)"
import { ThemeProvider } from '@appica/ui-react/providers/theme-provider'

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

<Callout type="note">
  `suppressHydrationWarning` on `<html>` is expected: the no-flash script sets the theme class before React
  hydrates, so the server and client markup intentionally differ by that one attribute.
</Callout>

By default `ThemeProvider` follows the OS preference (`enableSystem`) and persists
the user's choice under the `theme` key in `localStorage`.

## Building a theme toggle [#building-a-theme-toggle]

Read and set the theme with [`useTheme`](/ui/docs/react/use-theme). Guard
theme-dependent UI with `mounted` so the server-rendered output matches the first
client render:

```tsx title="theme-toggle.tsx"
'use client'

import { useTheme } from '@appica/ui-react/hooks/use-theme'
import { Button } from '@appica/ui-react/button'
import { SunHigh, MoonStars } from '@appica/icons-react'

export function ThemeToggle() {
  const { resolvedTheme, setTheme, mounted } = useTheme()

  // Avoid rendering theme-specific content until mounted.
  if (!mounted) return <Button variant="ghost" size="icon-md" aria-label="Toggle theme" />

  const next = resolvedTheme === 'dark' ? 'light' : 'dark'
  return (
    <Button variant="ghost" size="icon-md" aria-label="Toggle theme" onClick={() => setTheme(next)}>
      {resolvedTheme === 'dark' ? <MoonStars /> : <SunHigh />}
    </Button>
  )
}
```

* `theme` is the stored choice, which may be `'system'`.
* `resolvedTheme` is what's actually applied — `'system'` resolved to `'light'` or `'dark'`.
* `systemTheme` is the current OS preference.

## Common options [#common-options]

`ThemeProvider` accepts several props to tune behavior:

| Prop                        | Default                        | Description                                       |
| --------------------------- | ------------------------------ | ------------------------------------------------- |
| `defaultTheme`              | `'system'` (if `enableSystem`) | Theme used before the user makes a choice         |
| `enableSystem`              | `true`                         | Follow the OS `prefers-color-scheme`              |
| `storageKey`                | `'theme'`                      | `localStorage` key for the persisted choice       |
| `forcedTheme`               | —                              | Pin a theme for a subtree (e.g. a marketing page) |
| `disableTransitionOnChange` | `false`                        | Suppress CSS transitions during the switch        |
| `enableColorScheme`         | `true`                         | Set `color-scheme` so native controls match       |

To force a single theme on a specific route, nest another provider with
`forcedTheme`:

```tsx
<ThemeProvider forcedTheme="dark">
  <MarketingPage />
</ThemeProvider>
```

See [`ThemeProvider`](/ui/docs/react/theme-provider) for the full prop reference and
[`useTheme`](/ui/docs/react/use-theme) for the hook.


# Direction Provider (/ui/docs/react/direction-provider)



`DirectionProvider` sets the reading direction for descendant components. It's a
thin wrapper over [Base UI](https://base-ui.com)'s direction provider, so your app
depends on `@appica/ui-react` rather than the underlying primitive.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'
```

## Usage [#usage]

Wrap your app at its root and set `dir`. For full RTL support, also set the `dir`
attribute on `<html>` so CSS logical properties and native text flow resolve
correctly — see [Right-to-Left (RTL)](/ui/docs/react/rtl). The example uses Next.js's
root layout; for the equivalent root file in other frameworks, see the
[Framework notes](/ui/docs/react/installation#framework-notes) in Installation.

```tsx title="app/layout.tsx (Next.js)"
<html lang="ar" dir="rtl">
  <body>
    <DirectionProvider dir="rtl">{children}</DirectionProvider>
  </body>
</html>
```

Descendant components read the value via [`useDirection`](/ui/docs/react/use-direction).
Components that position elements with JavaScript — Slider, Switch, Carousel, and
overlays like menus — rely on it to know which side is "end."

<Callout type="note">
  Optional. With no provider, components default to `ltr`. Reach for it only when supporting RTL.
</Callout>

## Props [#props]

| Prop       | Type             | Default | Description                                 |
| ---------- | ---------------- | ------- | ------------------------------------------- |
| `dir`      | `'ltr' \| 'rtl'` | `'ltr'` | Reading direction for descendant components |
| `children` | `ReactNode`      | —       | The subtree that should read this direction |


# Fonts (/ui/docs/react/fonts)



Typography in Appica UI is driven by two design tokens — `--font-sans` and
`--font-mono` — exactly like colors and radii. Switching fonts is a two-part job:
**load** the font in your app, then **point the token at it**. The first part is
framework-specific; the second is one line of CSS that's the same everywhere.

## The default fonts [#the-default-fonts]

Out of the box, `@appica/ui-react/styles.css` sets both tokens to native system
font stacks:

```css
:root {
  --font-sans:
    ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;
}
```

System fonts download nothing, render instantly, and never cause layout shift — a
good default. They feed Tailwind's `font-sans` / `font-mono` utilities through the
`@theme inline` block, and Tailwind's preflight applies `--font-sans` as the base
family for the whole document. So **overriding the raw `--font-sans` token re-fonts
your entire UI** — every component included.

<Callout type="note">
  Override the raw `--font-sans` token at `:root`, not its alias inside the `@theme inline` block. This mirrors how
  [Theming](/ui/docs/react/theming) treats colors and radii — the theme layer is derived, so the raw token is the one to
  redefine.
</Callout>

## The one line that always applies [#the-one-line-that-always-applies]

Whatever loads the font, you finish by redefining the raw token after the import,
keeping a fallback stack so text stays readable while the web font loads:

```css title="globals.css"
@import 'tailwindcss';
@import '@appica/ui-react/styles.css';

@source '@appica/ui-react';

:root {
  --font-sans: 'Geist', ui-sans-serif, system-ui, sans-serif;
}
```

The font name on the left of the fallback list must match whatever the loading step
below makes available — a `font-family` from `@font-face`, an `@fontsource` package,
or the CSS variable `next/font` generates. The rest of this guide is just the
different ways to get that name onto the page.

## Loading the font [#loading-the-font]

How you load a font depends on your framework. Next.js has a first-class font
pipeline (`next/font`); everywhere else you self-host with [Fontsource](https://fontsource.org)
or a plain `@font-face`. All of these self-host the files, which is faster and more
private than linking to a third-party CDN.

### Next.js — `next/font` [#nextjs--nextfont]

`next/font` downloads the font at build time, self-hosts it, and hands you a CSS
variable with zero layout shift. Use `next/font/google` for a Google font:

```tsx title="app/layout.tsx"
import { Geist } from 'next/font/google'

const geist = Geist({
  subsets: ['latin'],
  variable: '--font-geist',
  display: 'swap',
})

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={geist.variable}>
      <body>{children}</body>
    </html>
  )
}
```

…or `next/font/local` for font files you ship yourself:

```tsx title="app/layout.tsx"
import localFont from 'next/font/local'

const brand = localFont({
  src: [
    { path: './fonts/Brand-Regular.woff2', weight: '400', style: 'normal' },
    { path: './fonts/Brand-Bold.woff2', weight: '700', style: 'normal' },
  ],
  variable: '--font-brand',
  display: 'swap',
})
```

Either way, map the generated variable onto the Appica token:

```css title="app/globals.css"
:root {
  --font-sans: var(--font-geist), ui-sans-serif, system-ui, sans-serif;
}
```

<Callout type="warning" title="Apply the variable, not the className">
  `next/font` only exposes `--font-geist` on the element you put `geist.variable` on (and its
  descendants), so apply it to `<html>`. Don't also spread `geist.className` onto `<body>` — that hardcodes
  the font on the body and bypasses the token, so component-level `font-mono` and any later override stop
  working. Pick the variable approach and let `--font-sans` flow through.
</Callout>

### Vite, TanStack Start, React Router 7 / Remix — Fontsource [#vite-tanstack-start-react-router-7--remix--fontsource]

These bundlers have no built-in font helper, so self-host with Fontsource — one npm
package per family, imported once:

<InstallTabs name="@fontsource-variable/geist" />

```ts title="src/main.tsx"
import '@fontsource-variable/geist'
```

```css title="src/index.css"
:root {
  --font-sans: 'Geist Variable', ui-sans-serif, system-ui, sans-serif;
}
```

The `font-family` Fontsource registers is shown on each font's page — variable fonts
use the `… Variable` suffix as above; static weights use the bare name (`'Geist'`).

### Any framework — local files with `@font-face` [#any-framework--local-files-with-font-face]

If you'd rather not add a dependency, declare the face yourself and drop the files in
your `public/` (or `static/`) folder. This works in every framework, including Astro:

```css title="globals.css"
@font-face {
  font-family: 'Brand Sans';
  src: url('/fonts/brand-sans.woff2') format('woff2');
  font-weight: 100 900; /* a single variable file */
  font-display: swap;
}

:root {
  --font-sans: 'Brand Sans', ui-sans-serif, system-ui, sans-serif;
}
```

<Callout type="tip" title="Prefer self-hosting over Google's link tag">
  You *can* load a font with Google's `<link href="https://fonts.googleapis.com/…">` snippet and it works
  anywhere, but it adds a third-party request, an extra DNS round-trip, and sends your visitors' IPs to
  Google. `next/font`, Fontsource, and `@font-face` all serve the files from your own origin — faster and
  privacy-friendly. Reach for the link tag only as a quick prototype.
</Callout>

## The monospace font [#the-monospace-font]

`--font-mono` works identically — load the font, then redefine the token. It feeds
`font-mono`, code blocks, and anything that opts into monospace:

```css
:root {
  --font-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
}
```

## Framework notes [#framework-notes]

The CSS override is identical everywhere; only the loading mechanism and where it
lives change:

| Framework                                                                                                   | How to load                        | Where                             |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------- | --------------------------------- |
| <span className="flex items-center text-nowrap"><FrameworkLogo name="nextjs" />Next.js (App Router)</span>  | `next/font` → CSS variable         | `app/layout.tsx` + `globals.css`  |
| <span className="flex items-center text-nowrap"><FrameworkLogo name="vite" />Vite / CRA</span>              | Fontsource import or `@font-face`  | `src/main.tsx` + `src/index.css`  |
| <span className="flex items-center text-nowrap"><FrameworkLogo name="tanstack" />TanStack Start</span>      | Fontsource import or `@font-face`  | root route + `src/styles/app.css` |
| <span className="flex items-center text-nowrap"><FrameworkLogo name="remix" />React Router 7 / Remix</span> | Fontsource import or `@font-face`  | `app/root.tsx` + `app/app.css`    |
| <span className="flex items-center text-nowrap"><FrameworkLogo name="astro" />Astro</span>                  | `@font-face` (or Astro's font API) | `src/styles/global.css`           |

Whatever the source, the contract is the same: make a `font-family` name resolvable
on the page, then put it first in `--font-sans` / `--font-mono` with the original
stack trailing as a fallback.

## Next steps [#next-steps]

* [Theming](/ui/docs/react/theming) — the token system fonts plug into.
* [Colors](/ui/docs/react/colors) — recolor with the same override pattern.
* [Dark Mode](/ui/docs/react/dark-mode) — switch and persist themes.


# Forms & Validation (/ui/docs/react/forms)



Forms are built from two pieces: `Field`, which groups a control with its label,
description, and error message and wires up the accessibility relationships; and
`Form`, which coordinates the fields and surfaces server-side errors. Both wrap
[Base UI](https://base-ui.com) primitives.

## Anatomy of a field [#anatomy-of-a-field]

A `Field` composes a label, a control, an optional description, and an error
slot. The `for`/`id` and `aria-describedby` associations are handled for you.

```tsx
import { Field, FieldLabel, FieldDescription, FieldError } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'

export default function EmailField() {
  return (
    <Field name="email">
      <FieldLabel>Email</FieldLabel>
      <Input type="email" required placeholder="you@example.com" />
      <FieldDescription>We'll only use this to send receipts.</FieldDescription>
      <FieldError />
    </Field>
  )
}
```

## Validation [#validation]

### Native constraints [#native-constraints]

Standard HTML attributes — `required`, `type`, `min`, `maxLength`, `pattern` —
are validated automatically. Point `FieldError` at a specific failure with
`match`, or render the browser's default message with a bare `<FieldError />`:

```tsx
<Field name="email">
  <FieldLabel>Email</FieldLabel>
  <Input type="email" required />
  <FieldError match="valueMissing">An email is required.</FieldError>
  <FieldError match="typeMismatch">Enter a valid email address.</FieldError>
</Field>
```

### Custom validation [#custom-validation]

For rules HTML can't express, pass a `validate` function to the `Field`. Return a
string (or array of strings) to fail, or `null` to pass. Control when it runs
with `validationMode` (`'onBlur'` or `'onChange'`):

```tsx
<Field
  name="username"
  validationMode="onBlur"
  validate={(value) => (String(value).length < 3 ? 'At least 3 characters.' : null)}
>
  <FieldLabel>Username</FieldLabel>
  <Input />
  <FieldError />
</Field>
```

`validate` can be async — return a promise — which is handy for availability
checks against an API.

### Shake on invalid [#shake-on-invalid]

For an extra cue when validation fails, hang the `animate-shake` utility off the
control's invalid state. Base UI sets `data-invalid` on the control when the field
fails validation, so put the class on the `Input` to shake just the control:

```tsx
<Field name="email">
  <FieldLabel>Email</FieldLabel>
  <Input type="email" required className="data-invalid:motion-safe:animate-shake" />
  <FieldError />
</Field>
```

<Callout type="note">
  The shake plays once, when the field *becomes* invalid (the moment `data-invalid` is added) — not on every failed
  submit while it stays invalid. Gating it behind `motion-safe:` keeps it off for users who prefer reduced motion, per
  [Animation](/ui/docs/react/animation).
</Callout>

## Grouping with Fieldset [#grouping-with-fieldset]

Use `Fieldset` and `FieldsetLegend` to group related fields under a shared label
(an accessible `<fieldset>`/`<legend>`):

```tsx
import { Fieldset, FieldsetLegend } from '@appica/ui-react/fieldset'

export default function BillingAddress() {
  return (
    <Fieldset>
      <FieldsetLegend>Billing address</FieldsetLegend>
      <Field name="street">
        <FieldLabel>Street</FieldLabel>
        <Input />
      </Field>
      <Field name="city">
        <FieldLabel>City</FieldLabel>
        <Input />
      </Field>
    </Fieldset>
  )
}
```

## The Form wrapper [#the-form-wrapper]

`Form` ties the fields together and handles submission. Its most useful job is
displaying **server-side** errors: return them keyed by field `name` and pass
them to `errors`, and each `Field` shows its message in place.

```tsx
'use client'

import * as React from 'react'
import { Form } from '@appica/ui-react/form'
import { Field, FieldLabel, FieldError } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Button } from '@appica/ui-react/button'

export default function SignupForm() {
  const [errors, setErrors] = React.useState({})

  return (
    <Form
      errors={errors}
      onClearErrors={setErrors}
      onSubmit={async (event) => {
        event.preventDefault()
        const data = new FormData(event.currentTarget)
        const result = await signUp(data) // your server action / API call
        if (result.errors) setErrors(result.errors) // e.g. { email: 'Already taken.' }
      }}
    >
      <Field name="email">
        <FieldLabel>Email</FieldLabel>
        <Input type="email" required />
        <FieldError />
      </Field>
      <Button type="submit">Create account</Button>
    </Form>
  )
}
```

<Callout type="note">
  Inputs are uncontrolled by default — read values from `FormData` on submit, as above. You can still control any field
  with `value`/`onValueChange` (or `onChange`) when you need to.
</Callout>

## Accessibility [#accessibility]

Labels, descriptions, and error messages are associated with their control
automatically, and invalid fields are marked with `aria-invalid`. See
[Accessibility](/ui/docs/react/accessibility) — and note that grouped controls
(`RadioGroup`, `CheckboxGroup`) are labeled with `aria-label`/`aria-labelledby`,
not `FieldLabel`.


# Installation (/ui/docs/react/installation)



Appica UI ships as a single tree-shakeable package. Components are built on
[Base UI](https://base-ui.com) primitives and styled with Tailwind CSS v4 design
tokens, so installation is two steps: add the package, then point Tailwind at it.

## Prerequisites [#prerequisites]

Appica UI targets modern React and Tailwind. Make sure your project has:

| Dependency   | Version  |
| ------------ | -------- |
| React        | `>= 19`  |
| React DOM    | `>= 19`  |
| Tailwind CSS | `>= 4.0` |

**React 19 is a hard requirement:** components use the modern ref-as-prop API and
other React 19 patterns, with no `forwardRef` shims. If you're on React 18,
upgrade before installing.

<Callout type="warning" title="Tailwind v4 must be working first">
  Appica UI doesn't bundle Tailwind — it relies on *your* project's Tailwind to compile the component styles. Before
  installing, set up Tailwind v4 in your app: install `tailwindcss` **and** its build plugin (`@tailwindcss/vite` for
  Vite, `@tailwindcss/postcss` for PostCSS/Next.js), then confirm that `@import 'tailwindcss';` in your global
  stylesheet generates utilities. If Tailwind isn't compiling your own classes yet, Appica UI's components will render
  unstyled.
</Callout>

## Install [#install]

<InstallTabs name="@appica/ui-react" />

## Configure Tailwind [#configure-tailwind]

Import the design tokens after Tailwind in your global stylesheet, and add a
`@source` directive so Tailwind scans the compiled library for class names.

```css title="globals.css"
@import 'tailwindcss';
@import '@appica/ui-react/styles.css';

@source '../node_modules/@appica/ui-react/dist';
```

<Callout type="warning" title="Don't skip @source — and give it a real path">
  Tailwind ignores `node_modules` by default. Without the `@source` directive it won't generate the utility
  classes used inside the compiled components, and they'll render unstyled.

  `@source` takes a path or glob **relative to the stylesheet that contains it**, not a bare package name —
  `@source '@appica/ui-react'` does not resolve and silently scans nothing. Count the `../` needed to reach
  `node_modules` from your CSS file: a stylesheet one level deep (`app/globals.css`, `src/index.css`) needs a
  single `../`; a deeper one (`src/styles/app.css`) needs `../../`. This matches Tailwind's own
  [`@source` documentation](https://tailwindcss.com/docs/functions-and-directives#source-directive), whose
  example is `@source '../node_modules/@my-company/ui-lib';`.
</Callout>

The `styles.css` import brings in the full token system — colors, radii, shadows,
typography, and the `light`/`dark` themes. See [Theming](/ui/docs/react/theming) to
customize it.

### Why there's no prebuilt CSS to import [#why-theres-no-prebuilt-css-to-import]

Appica UI ships its components' class names as source for *your* Tailwind to
compile, rather than a prebuilt stylesheet you drop in. That extra `@source` line
buys a lot:

* **One deduplicated build.** The utilities the components use are generated into
  the same pass as your own, so shared classes (`flex`, `rounded-lg`, `px-4`…)
  are emitted once instead of shipping twice.
* **Only what you use.** Tailwind tree-shakes across your app and the library
  together — utilities for components you never import are never generated.
* **Your tokens win.** Because the classes are compiled against *your* Tailwind
  config, overrides to the design tokens in [Theming](/ui/docs/react/theming) — colors,
  radii, spacing, fonts — flow into the components automatically. A prebuilt
  stylesheet would freeze those values at publish time.
* **No version-locked CSS.** There's no compiled stylesheet to drift out of sync
  with your Tailwind version; the components restyle themselves against whatever
  Tailwind v4 you're on.

## Add the provider [#add-the-provider]

Wrap your app in `ThemeProvider` to enable theming and dark mode. It injects a
small inline script that applies the stored theme before first paint, so there's
no flash of the wrong theme. In Next.js that's the root layout's `<body>`; in a
Vite/CRA app, wrap your root the same way.

```tsx title="app/layout.tsx (Next.js)"
import { ThemeProvider } from '@appica/ui-react/providers/theme-provider'

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

That's all you need to start. See [Theme Provider](/ui/docs/react/theme-provider) for
the full API — custom themes, forcing a theme, and flash-prevention details — and
the optional [`DirectionProvider`](/ui/docs/react/direction-provider) (RTL) and
[`ReducedMotionProvider`](/ui/docs/react/reduced-motion-provider), which you add only
when you need them.

## Framework notes [#framework-notes]

Appica UI is a plain package, so the steps above are the same everywhere — unlike a
file-scaffolding CLI, there's no per-framework setup to learn. The only things that
move are which Tailwind build plugin you install, where your global stylesheet lives,
and where the provider goes:

| Framework                                                                                                   | Tailwind plugin        | Global stylesheet       | Wrap the provider            |
| ----------------------------------------------------------------------------------------------------------- | ---------------------- | ----------------------- | ---------------------------- |
| <span className="flex items-center text-nowrap"><FrameworkLogo name="nextjs" />Next.js (App Router)</span>  | `@tailwindcss/postcss` | `app/globals.css`       | root layout `<body>`         |
| <span className="flex items-center text-nowrap"><FrameworkLogo name="vite" />Vite / CRA</span>              | `@tailwindcss/vite`    | `src/index.css`         | root component in `main.tsx` |
| <span className="flex items-center text-nowrap"><FrameworkLogo name="tanstack" />TanStack Start</span>      | `@tailwindcss/vite`    | `src/styles/app.css`    | root route component         |
| <span className="flex items-center text-nowrap"><FrameworkLogo name="remix" />React Router 7 / Remix</span> | `@tailwindcss/vite`    | `app/app.css`           | root component in `root.tsx` |
| <span className="flex items-center text-nowrap"><FrameworkLogo name="astro" />Astro</span>                  | `@tailwindcss/vite`    | `src/styles/global.css` | see note below               |

Everything else — the `@import`s and the subpath imports — is identical regardless
of framework. The one value that tracks the stylesheet is the `@source` path: count
the `../` needed to reach `node_modules` from wherever your global CSS lives (see
[Configure Tailwind](#configure-tailwind) above).

<Callout type="warning" title="Astro needs the React integration and an island">
  Astro renders React as [islands](https://docs.astro.build/en/concepts/islands/), not a
  single tree, so it needs a little extra wiring. Add the `@astrojs/react` integration first,
  then mount anything interactive with a client directive (e.g. `client:load`) — components
  without one ship zero JS and won't react to theme changes. Because each island is its own
  React root, a `ThemeProvider` placed in an `.astro` layout **won't** share context across
  islands; either render an interactive section as one island wrapped in the provider, or apply
  the theme class in your `.astro` `<head>` and use the provider only inside hydrated islands.
</Callout>

## Use a component [#use-a-component]

Import components from their subpath for the smallest bundle, and you're ready:

```tsx
import { Button } from '@appica/ui-react/button'

export default function App() {
  return <Button>Get started</Button>
}
```

## Next steps [#next-steps]

* [Usage](/ui/docs/react/usage) — import conventions, variants, and composition basics.
* [Theming](/ui/docs/react/theming) — customize colors, radii, and tokens.
* [Dark Mode](/ui/docs/react/dark-mode) — build a theme toggle.
* [Components](/ui/components/react/button) — browse the full catalog.


# Reduced Motion Provider (/ui/docs/react/reduced-motion-provider)



`ReducedMotionProvider` opts a subtree out of animation. Components already honor
the OS `prefers-reduced-motion` setting on their own — this provider is the
explicit, global override (for a user preference toggle, demos, or tests).

```tsx
import { ReducedMotionProvider } from '@appica/ui-react/providers/reduced-motion-provider'
```

## Usage [#usage]

```tsx
<ReducedMotionProvider disableAnimations>
  <App />
</ReducedMotionProvider>
```

When `disableAnimations` is set, the provider writes a `data-disable-animations`
attribute to `<html>`. That's deliberate: it has to reach Base UI's portaled
popups, which render under `document.body` and so escape the React subtree.

## Two channels [#two-channels]

The provider drives motion through two coordinated channels:

* **CSS** — the `data-disable-animations` attribute on `<html>` triggers the
  `motion-reduce` variant page-wide (popups included). This is what stops
  component transitions. See [Animation](/ui/docs/react/animation).
* **JavaScript** — [`useReducedMotion`](/ui/docs/react/use-reduced-motion), scoped to
  this provider's React subtree, returns `true` so your own animation code can
  branch.

## Props [#props]

| Prop                | Type        | Default | Description                                              |
| ------------------- | ----------- | ------- | -------------------------------------------------------- |
| `disableAnimations` | `boolean`   | `false` | Force-disable animations regardless of the OS preference |
| `children`          | `ReactNode` | —       | The subtree to opt out of animation                      |

<Callout type="note">
  Leaving `disableAnimations` off doesn't re-enable motion for users who request reduced motion at the OS level — that
  preference is always respected. The provider can only make things *more* still, never less.
</Callout>


# Right-to-Left (RTL) (/ui/docs/react/rtl)



Appica UI supports right-to-left layouts. Most mirroring happens automatically
through CSS logical properties; a few components that compute layout in
JavaScript read the direction from [`DirectionProvider`](/ui/docs/react/direction-provider).

## Two things to set [#two-things-to-set]

For full RTL support, set the direction in **two** places:

**1. The `dir` attribute** on `<html>`, so the browser mirrors text flow and
logical CSS resolves correctly:

```html
<html dir="rtl" lang="ar"></html>
```

**2. `DirectionProvider`**, so components that position elements with JavaScript
(Slider, Switch, Carousel, menus, and other floating surfaces) know which way is
"end":

```tsx title="app/layout.tsx (Next.js)"
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

<Callout type="note">
  `DirectionProvider` defaults to `ltr`, so you only need it when supporting RTL. With no provider, components behave
  left-to-right.
</Callout>

The example uses Next.js's root layout; for the equivalent root file in Vite,
React Router / Remix, TanStack Start, and Astro, see the
[Framework notes](/ui/docs/react/installation#framework-notes) in Installation.

## Why most things "just work" [#why-most-things-just-work]

Appica UI styles with **logical** properties rather than physical ones — padding
and margins use `ps`/`pe` and `ms`/`me` (inline-start/end) instead of left/right,
and positioning uses `start`/`end`. These resolve against the document direction,
so a component laid out for LTR mirrors for RTL without any extra work.

Write your own RTL-ready markup the same way:

```tsx
// ✅ Mirrors automatically
<div className="ps-4 border-s-2 text-start">…</div>

// ❌ Stays put in RTL
<div className="pl-4 border-l-2 text-left">…</div>
```

## Floating popups in a scoped RTL region [#floating-popups-in-a-scoped-rtl-region]

Menus, selects, popovers, and other floating surfaces render in a **portal** at
the end of `<body>`. Their `start` / `end` **alignment** mirrors based on the
direction the portalled element inherits from the document — read from CSS by the
positioning engine, **not** from `DirectionProvider`. With `dir="rtl"` on `<html>`
(as above) this is automatic, so you never think about it.

It only matters when you scope RTL to a **subtree** of an otherwise-LTR page. The
popup escapes that subtree to the (LTR) `<body>`, so its alignment stays
left-to-right even though the submenu *side* still follows `DirectionProvider`.
Give the popup's positioner the direction explicitly, or portal it into your RTL
container:

```tsx
// Set the direction on the positioner…
<DropdownMenuContent positionerProps={{ dir: 'rtl' }}>…</DropdownMenuContent>

// …or render the popup inside your RTL container instead of <body>
<DropdownMenuContent container={rtlContainerRef}>…</DropdownMenuContent>
```

<Callout type="note">
  Prefer setting `dir="rtl"` on `<html>` whenever the whole document is RTL — then every floating popup mirrors with no
  per-component setup. The positioner override above is only for mixed LTR/RTL pages.
</Callout>

## Reading the direction in code [#reading-the-direction-in-code]

When your own component needs to branch on direction, read it with
[`useDirection`](/ui/docs/react/use-direction):

```tsx
'use client'

import { useDirection } from '@appica/ui-react/hooks/use-direction'

function NextIcon() {
  const dir = useDirection()
  return <span>{dir === 'rtl' ? '←' : '→'}</span>
}
```

## Switching at runtime [#switching-at-runtime]

To toggle direction without a full reload, update both the `<html dir>` attribute
and the `DirectionProvider` value together so the CSS and JS channels stay in
sync.

See [`DirectionProvider`](/ui/docs/react/direction-provider) and
[`useDirection`](/ui/docs/react/use-direction) for the full reference.


# Theme Provider (/ui/docs/react/theme-provider)



`ThemeProvider` owns the active theme. It applies the theme class to `<html>`,
persists the choice to storage, optionally follows the OS preference, and injects
an inline script that sets the theme **before first paint** so there's no flash.

```tsx
import { ThemeProvider } from '@appica/ui-react/providers/theme-provider'
```

## Usage [#usage]

Wrap your app once, as high as possible — at your app's root, inside `<body>`.
The example below uses Next.js's root layout; for the equivalent file in Vite,
React Router / Remix, TanStack Start, and Astro, see the
[Framework notes](/ui/docs/react/installation#framework-notes) in Installation.

```tsx title="app/layout.tsx (Next.js)"
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}
```

Read and change the theme anywhere below it with [`useTheme`](/ui/docs/react/use-theme).
For building a toggle, see [Dark Mode](/ui/docs/react/dark-mode).

<Callout type="note">
  Nesting `ThemeProvider` is safe — inner providers are a passthrough. Only the outermost one owns state, so you can use
  a nested provider purely to set `forcedTheme` on a subtree.
</Callout>

## Props [#props]

| Prop                        | Type                     | Default                      | Description                                                  |
| --------------------------- | ------------------------ | ---------------------------- | ------------------------------------------------------------ |
| `themes`                    | `string[]`               | `['light', 'dark']`          | Available theme names                                        |
| `defaultTheme`              | `string`                 | `'system'` if `enableSystem` | Theme used before a choice is stored                         |
| `forcedTheme`               | `string`                 | —                            | Force a theme for the whole subtree (overrides storage + OS) |
| `enableSystem`              | `boolean`                | `true`                       | Respect the OS `prefers-color-scheme`                        |
| `enableColorScheme`         | `boolean`                | `true`                       | Set `color-scheme` on `<html>` so native UI matches          |
| `disableTransitionOnChange` | `boolean`                | `false`                      | Suppress CSS transitions during a theme switch               |
| `storageKey`                | `string`                 | `'theme'`                    | `localStorage` key for the persisted choice                  |
| `value`                     | `Record<string, string>` | —                            | Map a theme name to a custom class applied on `<html>`       |
| `nonce`                     | `string`                 | —                            | CSP nonce forwarded to the inline script                     |
| `scriptProps`               | `ScriptHTMLAttributes`   | —                            | Extra props for the inline `<script>`                        |

## Custom theme names [#custom-theme-names]

`themes` plus `value` let you ship themes beyond light/dark. `value` maps each
name to the class written on `<html>`:

```tsx
<ThemeProvider themes={['light', 'dark', 'sepia']} value={{ light: 'light', dark: 'dark', sepia: 'theme-sepia' }}>
  {children}
</ThemeProvider>
```

Define the matching token overrides for `.theme-sepia` in your stylesheet — see
[Theming](/ui/docs/react/theming).

## Preventing flash [#preventing-flash]

The provider renders a tiny synchronous `<script>` that reads the stored theme
and sets the class before the page paints. That's why `<html>` needs
`suppressHydrationWarning`: the script intentionally changes one attribute before
React hydrates. The first post-mount render is skipped so it can't re-introduce a
flash from the hydration default.


# Theming (/ui/docs/react/theming)



Appica UI is themed entirely through CSS custom properties — design tokens. There
are no theme objects to import and no JavaScript config: you override a few CSS
variables and every component updates. This is what `@appica/ui-react/styles.css`
brings in.

## How tokens are structured [#how-tokens-are-structured]

Tokens live in two layers, and understanding the split is the key to customizing
safely.

**1. Raw value tokens** hold the actual values, defined per theme. `:root` (and
`.light`) hold the light values; `.dark` holds the dark ones.

```css
:root,
.light {
  --primary: oklch(0.21 0.034 264.665);
  --background: oklch(1 0 0);
  --radius: 0.875rem;
}

.dark {
  --primary: oklch(1 0 0);
  --background: oklch(0.13 0.028 261.692);
}
```

**2. Theme tokens** alias those raw values inside Tailwind's `@theme inline`
block, which is what generates the utility classes.

```css
@theme inline {
  --color-primary: var(--primary);
  --color-background: var(--background);
  --radius-lg: calc(var(--radius) + 0.125rem);
}
```

The `inline` keyword matters: it tells Tailwind to inline the raw token into each
utility instead of pointing it at a `--color-*` variable. So `bg-primary` compiles
to `background-color: var(--primary)` — not `var(--color-primary)`. The upshot is
that `bg-primary` and `text-foreground` resolve to the right value and flip
automatically between light and dark, because the raw layer changes underneath.
There's no `--color-primary` custom property to reference at runtime, though — when
you need a token in plain CSS, reach for the **raw** token (`var(--primary)`).

<Callout type="note">
  Override the <strong>raw</strong> tokens (`--primary`), not the theme tokens (`--color-primary`). The theme layer is
  derived — editing it would break the light/dark mapping.
</Callout>

## Recoloring [#recoloring]

Redefine any raw token after the import. To change the brand color:

```css title="globals.css"
@import 'tailwindcss';
@import '@appica/ui-react/styles.css';

@source '@appica/ui-react';

:root {
  --primary: oklch(0.62 0.21 28); /* a warm red */
}

.dark {
  --primary: oklch(0.7 0.18 28);
}
```

Colors use [oklch](https://oklch.com) for perceptually uniform lightness, which
keeps tints and shades consistent across hues. See [Colors](/ui/docs/react/colors)
for the full palette and the semantic roles each token plays.

## Radius [#radius]

A single base token, `--radius`, drives the entire corner-radius scale. Every
step (`--radius-xs` through `--radius-4xl`) is derived from it with `calc()`, so
changing one value rescales every component at once.

```css
:root {
  --radius: 0.5rem; /* sharper corners everywhere */
}
```

Use the scale through Tailwind utilities (`rounded-lg`, `rounded-2xl`) or the
variables directly (`var(--radius-md)`).

## Other token groups [#other-token-groups]

The same pattern covers the rest of the design language:

| Group          | Example tokens                            | Utilities                |
| -------------- | ----------------------------------------- | ------------------------ |
| Typography     | `--font-sans`, `--font-mono`, `--text-sm` | `font-sans`, `text-sm`   |
| Shadows        | `--shadow-sm` … `--shadow-2xl`            | `shadow-sm`, `shadow-xl` |
| Border width   | `--border-width`                          | `border`                 |
| Disabled state | `--opacity-disabled`                      | applied by components    |

Override any of them the same way — redefine the raw token after the import.

## Using tokens in your own UI [#using-tokens-in-your-own-ui]

Because the tokens are plain CSS variables, your own components can share the
exact look of Appica UI. Reach for the Tailwind utilities, or reference the raw
tokens directly — `var(--primary)` in CSS, or the `(--token)` shorthand in a
utility (`text-(--primary)`, *not* `text-(--color-primary)`):

```tsx
<div className="bg-background-subtle text-foreground border-border rounded-lg border p-4">
  Matches the system automatically — including in dark mode.
</div>

// Same token, referenced directly through the raw variable.
<div className="text-(--primary)">Brand-colored text</div>
```

## Next steps [#next-steps]

* [Colors](/ui/docs/react/colors) — every palette and semantic role.
* [Dark Mode](/ui/docs/react/dark-mode) — switch and persist themes.


# Usage (/ui/docs/react/usage)



Once Appica UI is [installed](/ui/docs/react/installation), every component follows
the same small set of conventions. Learn them once and the whole library feels
consistent.

## Importing components [#importing-components]

Import each component from its own subpath. This keeps bundles minimal — your app
only pulls in what it uses, even without a bundler that tree-shakes barrel files.

```tsx
import { Button } from '@appica/ui-react/button'
import { Input } from '@appica/ui-react/input'
import { Dialog, DialogTrigger, DialogContent } from '@appica/ui-react/dialog'
```

Every export is also available from the package root, which is convenient for
prototyping:

```tsx
import { Button, Input } from '@appica/ui-react'
```

<Callout type="tip">
  Prefer subpath imports (`@appica/ui-react/button`) in application code. Reserve the root import for quick experiments.
</Callout>

## Variants and sizes [#variants-and-sizes]

Visual style is controlled through a `variant` prop, and dimensions through a
`size` prop. The available values differ per component, but the prop names stay
consistent across the library.

```tsx
<Button variant="primary">Primary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost" size="sm">Small ghost</Button>
```

Each component documents its own `variant` and `size` options on its page. Need
the union type in your own code? Derive it from the component's props rather than
reaching for an internal type:

```tsx
import type { ComponentProps } from 'react'
import { Button } from '@appica/ui-react/button'

type ButtonVariant = ComponentProps<typeof Button>['variant']
```

## Styling and overrides [#styling-and-overrides]

Components are themed entirely through [design tokens](/ui/docs/react/theming), so
they adapt to your colors and dark mode automatically. For one-off tweaks, pass
`className` — it's merged intelligently (conflicting Tailwind utilities are
de-duplicated), so your class wins:

```tsx
<Button className="w-full rounded-full">Full width</Button>
```

## Composition [#composition]

Most components accept a `render` prop to change the element they output — for
example, rendering a `NavigationLink` as your router's `Link`. This is the key to
composing Appica UI with your router and your own components:

```tsx
import Link from 'next/link'
import { NavigationLink } from '@appica/ui-react/navigation'

<NavigationLink render={<Link href="/pricing" />}>Pricing</NavigationLink>
```

See [Composition](/ui/docs/react/composition) for the full pattern, including how to
merge classes and when overrides belong on the wrapper.

## Server Components [#server-components]

Appica UI works out of the box with React Server Components and the Next.js App
Router. Interactive components carry their own `'use client'` boundary
internally, so you can import them directly into a Server Component without
marking the whole page client:

```tsx title="app/page.tsx (Server Component)"
import { Button } from '@appica/ui-react/button'

export default function Page() {
  return <Button>Works in an RSC</Button>
}
```

<Callout type="note" title="Crossing the server/client boundary">
  You can render Appica UI components from Server Components, but you can't pass non-serializable props (functions like
  `onClick`, or `render={<ClientComponent />}`) across the boundary. Move that interactivity into a `'use client'`
  component of your own. Providers like `ThemeProvider` are client components — keep them inside a client boundary (your
  root layout's `body` is fine).
</Callout>

On a client-only stack (Vite, CRA, or any single-page app) there's no
server/client split to think about: import and use components normally. The
`'use client'` directives you'll see throughout these docs are a no-op there —
bundlers without React Server Components simply ignore them.

## Next steps [#next-steps]

* [Composition](/ui/docs/react/composition) — the `render` prop in depth.
* [Theming](/ui/docs/react/theming) and [Dark Mode](/ui/docs/react/dark-mode).
* [Forms & Validation](/ui/docs/react/forms) — build accessible forms.


# useDirection (/ui/docs/react/use-direction)



`useDirection` returns the current reading direction. Use it when your own
component needs to branch on direction — flipping a chevron, choosing an offset
sign, or mirroring a custom layout.

```tsx
import { useDirection } from '@appica/ui-react/hooks/use-direction'
```

## Usage [#usage]

```tsx
'use client'

import { useDirection } from '@appica/ui-react/hooks/use-direction'

function NextIcon() {
  const dir = useDirection()
  return <span>{dir === 'rtl' ? '←' : '→'}</span>
}
```

## Return value [#return-value]

Returns `'ltr' \| 'rtl'`. The value comes from the nearest
[`DirectionProvider`](/ui/docs/react/direction-provider), defaulting to `'ltr'` when
there is none.

<Callout type="tip">
  Prefer CSS logical properties (`ps`/`pe`, `ms`/`me`, `start`/`end`) for styling — they mirror automatically without a
  hook. Reach for `useDirection` only when the decision happens in JavaScript. See [RTL](/ui/docs/react/rtl).
</Callout>


# useDismissible (/ui/docs/react/use-dismissible)



`useDismissible` manages the show/hide state of a dismissible element — an alert, chip, banner or
announcement — and remembers the dismissal so it stays gone on the
next visit. It's built on [`useLocalStorage`](/ui/docs/react/use-local-storage), so
it's SSR-safe and synced across tabs and components.

```tsx
import { useDismissible } from '@appica/ui-react/hooks/use-dismissible'
```

## Usage [#usage]

```tsx
'use client'

import { useDismissible } from '@appica/ui-react/hooks/use-dismissible'

function AnnouncementBanner() {
  const { open, dismiss } = useDismissible('announcement-2024')
  if (!open) return null

  return (
    <div className="bg-info-subtle flex items-center justify-between rounded-lg p-3">
      <span>We just shipped dark mode!</span>
      <button onClick={dismiss} aria-label="Dismiss">
        ✕
      </button>
    </div>
  )
}
```

## Signature [#signature]

```ts
useDismissible(
  key: string,
  options?: { storage?: 'local' | 'session' },
): { open: boolean; dismiss: () => void; reset: () => void }
```

| Parameter         | Type                   | Default   | Description                                    |
| ----------------- | ---------------------- | --------- | ---------------------------------------------- |
| `key`             | `string`               | —         | Storage key the dismissal is persisted under   |
| `options.storage` | `'local' \| 'session'` | `'local'` | Persist for good (`local`) or just the session |

## Return value [#return-value]

| Property  | Type         | Description                                              |
| --------- | ------------ | -------------------------------------------------------- |
| `open`    | `boolean`    | Whether the surface should show (`true` until dismissed) |
| `dismiss` | `() => void` | Mark it dismissed and persist that                       |
| `reset`   | `() => void` | Clear the dismissal so it shows again                    |

<Callout type="note">
  `open` is `true` until the stored value is known, so the element renders immediately and won't pop in after hydration.
  Use `'session'` storage for messages that should reappear in a new tab or session.
</Callout>


# useLocalStorage (/ui/docs/react/use-local-storage)



`useLocalStorage` is a `useState`-like hook whose value persists to
`localStorage`. It's SSR-safe, syncs across browser tabs via the `storage` event,
and syncs other components in the same tab. A `useSessionStorage` variant backs
onto `sessionStorage`.

```tsx
import { useLocalStorage, useSessionStorage } from '@appica/ui-react/hooks/use-local-storage'
```

## Usage [#usage]

It returns a `[value, setValue, remove]` tuple. `setValue` accepts a value or an
updater function, just like `useState`:

```tsx
'use client'

import { useLocalStorage } from '@appica/ui-react/hooks/use-local-storage'

function Counter() {
  const [count, setCount, reset] = useLocalStorage('count', 0)

  return (
    <div>
      <button onClick={() => setCount((c) => c + 1)}>Count: {count}</button>
      <button onClick={reset}>Reset</button>
    </div>
  )
}
```

## Signature [#signature]

```ts
useLocalStorage<T>(
  key: string,
  defaultValue: T,
  options?: { serializer?: (value: T) => string; deserializer?: (raw: string) => T },
): readonly [T, (value: T | ((prev: T) => T)) => void, () => void]
```

| Parameter      | Type     | Description                                                          |
| -------------- | -------- | -------------------------------------------------------------------- |
| `key`          | `string` | Storage key                                                          |
| `defaultValue` | `T`      | Returned on the server, before hydration, and when nothing is stored |
| `options`      | `object` | Optional custom `serializer` / `deserializer`                        |

Values are JSON-serialized by default. Pass a `serializer`/`deserializer` to store
a raw string instead — for example a value an inline script must read without
parsing JSON:

```tsx
const [theme, setTheme] = useLocalStorage('theme', 'system', {
  serializer: (v) => v,
  deserializer: (v) => v,
})
```

<Callout type="note">
  SSR-safe by design: the server and first client render return `defaultValue`, then the stored value resolves on
  hydration. Writes are wrapped in try/catch, so private-mode or quota failures won't crash your app. Need to pick the
  backend at runtime? Use the lower-level `useStorage('local' | 'session', …)`.
</Callout>


# useMediaQuery (/ui/docs/react/use-media-query)



`useMediaQuery` tells you whether a CSS media query currently matches and
re-renders when that changes. It's SSR-safe and works in any React environment —
Vite, CRA, Next.js, Remix, Astro.

```tsx
import { useMediaQuery } from '@appica/ui-react/hooks/use-media-query'
```

## Usage [#usage]

A common pattern: render a `Dialog` on desktop and a `Drawer` on mobile.

```tsx
'use client'

import { useMediaQuery } from '@appica/ui-react/hooks/use-media-query'

function Responsive() {
  const isDesktop = useMediaQuery('(min-width: 768px)')
  return isDesktop ? <DesktopDialog /> : <MobileDrawer />
}
```

## Signature [#signature]

```ts
useMediaQuery(query: string, options?: { defaultValue?: boolean }): boolean
```

| Parameter              | Type      | Default | Description                                                               |
| ---------------------- | --------- | ------- | ------------------------------------------------------------------------- |
| `query`                | `string`  | —       | The media query to evaluate                                               |
| `options.defaultValue` | `boolean` | `false` | Value returned on the server and the first client render before hydration |

<Callout type="note">
  On the server and during the first client render `window.matchMedia` isn't available, so the hook returns
  `defaultValue`. The real value resolves on hydration via `useSyncExternalStore`. Set `defaultValue` to your most
  likely case to minimize layout shift.
</Callout>


# useReducedMotion (/ui/docs/react/use-reduced-motion)



`useReducedMotion` returns `true` when animations should be skipped. Use it in
JavaScript-driven animation (e.g. with [Motion](https://motion.dev)) — for CSS,
the `motion-safe`/`motion-reduce` variants handle this automatically (see
[Animation](/ui/docs/react/animation)).

```tsx
import { useReducedMotion } from '@appica/ui-react/hooks/use-reduced-motion'
```

## Usage [#usage]

```tsx
'use client'

import { useReducedMotion } from '@appica/ui-react/hooks/use-reduced-motion'

function Reveal({ children }: { children: React.ReactNode }) {
  const reduced = useReducedMotion()
  return <div style={{ transition: reduced ? 'none' : 'opacity 300ms ease' }}>{children}</div>
}
```

## Return value [#return-value]

Returns a `boolean` — `true` when motion should be reduced. It's `true` if
**either**:

* the OS exposes `prefers-reduced-motion: reduce`, or
* a [`ReducedMotionProvider`](/ui/docs/react/reduced-motion-provider) ancestor set
  `disableAnimations`.

<Callout type="note">
  Works without a provider — it falls back to the OS preference alone. Add a `ReducedMotionProvider` only when you want
  a way to force-disable motion beyond the system setting.
</Callout>


# useTheme (/ui/docs/react/use-theme)



`useTheme` reads and sets the active theme. It returns the stored choice, the
resolved theme, the OS preference, and a setter — everything you need to build a
theme switcher.

```tsx
import { useTheme } from '@appica/ui-react/hooks/use-theme'
```

## Usage [#usage]

Guard theme-dependent UI with `mounted` so the first client render matches the
server output and you avoid a hydration mismatch:

```tsx title="theme-toggle.tsx"
'use client'

import { useTheme } from '@appica/ui-react/hooks/use-theme'
import { Button } from '@appica/ui-react/button'
import { SunHigh, MoonStars } from '@appica/icons-react'

export function ThemeToggle() {
  const { resolvedTheme, setTheme, mounted } = useTheme()

  // Avoid rendering theme-specific content until mounted.
  if (!mounted) return <Button variant="ghost" size="icon-md" aria-label="Toggle theme" />

  const next = resolvedTheme === 'dark' ? 'light' : 'dark'
  return (
    <Button variant="ghost" size="icon-md" aria-label="Toggle theme" onClick={() => setTheme(next)}>
      {resolvedTheme === 'dark' ? <MoonStars /> : <SunHigh />}
    </Button>
  )
}
```

## Return value [#return-value]

| Property        | Type                                                    | Description                                       |
| --------------- | ------------------------------------------------------- | ------------------------------------------------- |
| `theme`         | `string \| undefined`                                   | The stored choice, possibly `'system'`            |
| `setTheme`      | `(value: string \| ((prev: string) => string)) => void` | Set the theme; persisted automatically            |
| `resolvedTheme` | `string \| undefined`                                   | What's actually applied — `'system'` resolved     |
| `systemTheme`   | `'light' \| 'dark' \| undefined`                        | The current OS preference                         |
| `themes`        | `string[]`                                              | Available theme names                             |
| `forcedTheme`   | `string \| undefined`                                   | The forced theme, if a provider pinned one        |
| `mounted`       | `boolean`                                               | `false` until the client mounts — guard themed UI |

<Callout type="note">
  Requires a [`ThemeProvider`](/ui/docs/react/theme-provider) ancestor. Without one, the hook returns inert values
  (`mounted` stays `false`) rather than throwing.
</Callout>


# Accordion (/ui/components/react/accordion)



<Playground component="accordion" />

## Usage [#usage]

```tsx
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@appica/ui-react/accordion'
```

```tsx
<Accordion defaultValue={['shipping']}>
  <AccordionItem value="shipping">
    <AccordionTrigger>How long does shipping take?</AccordionTrigger>
    <AccordionContent>Orders arrive in 3–5 days with standard delivery.</AccordionContent>
  </AccordionItem>
  <AccordionItem value="returns">
    <AccordionTrigger>What is your return policy?</AccordionTrigger>
    <AccordionContent>Return any unused item within 30 days for a full refund.</AccordionContent>
  </AccordionItem>
</Accordion>
```

`Accordion` stacks collapsible sections — ideal for FAQs, settings groups, and any content you want to keep scannable until it's needed. Compose it from four parts, all under `@appica/ui-react/accordion`:

* **`Accordion`** — the root. Owns which items are open (`value`/`defaultValue`), whether `multiple` can be open at once, and the shared `variant` and `icon` styling.
* **`AccordionItem`** — one section, identified by its `value`. Can be individually `disabled`.
* **`AccordionTrigger`** — the header button that toggles its panel; renders the open/close icon.
* **`AccordionContent`** — the collapsible panel, which animates its height open and closed.

The `variant`, `icon`, `iconVariant`, and `iconPosition` props set on the root cascade to every item, and any item or trigger can override them locally.

## Examples [#examples]

### Default [#default]

By default only one panel is open at a time — opening another closes the last. Set the initially open item(s) with `defaultValue`.

```tsx
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@appica/ui-react/accordion'

export default function AccordionDefault() {
  return (
    <Accordion className="max-w-110" defaultValue={['shipping']}>
      <AccordionItem value="shipping">
        <AccordionTrigger>How long does shipping take?</AccordionTrigger>
        <AccordionContent>
          Orders ship within one business day and arrive in 3–5 days with standard delivery.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem value="returns">
        <AccordionTrigger>What is your return policy?</AccordionTrigger>
        <AccordionContent>
          Return any unused item within 30 days for a full refund — no questions asked.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem value="support">
        <AccordionTrigger>How do I contact support?</AccordionTrigger>
        <AccordionContent>
          Reach our team any time at support@example.com; we reply within a few hours.
        </AccordionContent>
      </AccordionItem>
    </Accordion>
  )
}
```

### Variants [#variants]

Three `variant`s change the surface: `default` is a filled card, `alt` is a flat card that gains a border on hover/open, and `flush` drops the card entirely for a borderless list.

```tsx
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@appica/ui-react/accordion'

const variants = ['default', 'alt', 'flush'] as const

export default function AccordionVariants() {
  return (
    <div className="grid w-full max-w-110 gap-6">
      {variants.map((variant) => (
        <div key={variant}>
          <p className="text-foreground-muted mb-2 text-xs font-medium tracking-wide uppercase">{variant}</p>
          <Accordion variant={variant} defaultValue={['one']}>
            <AccordionItem value="one">
              <AccordionTrigger>First section</AccordionTrigger>
              <AccordionContent>The {variant} variant changes the surface, borders, and spacing.</AccordionContent>
            </AccordionItem>
            <AccordionItem value="two">
              <AccordionTrigger>Second section</AccordionTrigger>
              <AccordionContent>Each item still animates its panel height open and closed.</AccordionContent>
            </AccordionItem>
          </Accordion>
        </div>
      ))}
    </div>
  )
}
```

### Icons [#icons]

Switch the indicator with `icon="plus"` (a plus that morphs to a minus) or hide it with `icon={false}`. Wrap it in a tile with `iconVariant="icon-box"`, and move it ahead of the label with `iconPosition="start"`.

```tsx
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@appica/ui-react/accordion'

export default function AccordionIcons() {
  return (
    <div className="grid w-full max-w-110 gap-6">
      <Accordion icon="plus" defaultValue={['a']}>
        <AccordionItem value="a">
          <AccordionTrigger>Plus icon</AccordionTrigger>
          <AccordionContent>The plus morphs into a minus as the panel opens.</AccordionContent>
        </AccordionItem>
        <AccordionItem value="b">
          <AccordionTrigger>Second item</AccordionTrigger>
          <AccordionContent>Set icon="plus" on the Accordion to apply it to every trigger.</AccordionContent>
        </AccordionItem>
      </Accordion>

      <Accordion icon="chevron" iconVariant="icon-box" iconPosition="start" defaultValue={['c']}>
        <AccordionItem value="c">
          <AccordionTrigger>Boxed icon, leading</AccordionTrigger>
          <AccordionContent>
            iconVariant="icon-box" wraps the icon in a tile; iconPosition="start" moves it ahead of the label.
          </AccordionContent>
        </AccordionItem>
        <AccordionItem value="d">
          <AccordionTrigger>Second item</AccordionTrigger>
          <AccordionContent>The boxed icon sits in a bordered tile that matches the item's surface.</AccordionContent>
        </AccordionItem>
      </Accordion>
    </div>
  )
}
```

### Open multiple [#open-multiple]

Set `multiple` to let any number of panels stay open at once — useful when sections are independent rather than mutually exclusive.

```tsx
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@appica/ui-react/accordion'

export default function AccordionMultiple() {
  return (
    <Accordion className="max-w-110" multiple defaultValue={['plan', 'billing']}>
      <AccordionItem value="plan">
        <AccordionTrigger>Plan</AccordionTrigger>
        <AccordionContent>You're on the Pro plan, renewing on the 1st of each month.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="billing">
        <AccordionTrigger>Billing</AccordionTrigger>
        <AccordionContent>Invoices are emailed to your account owner and available in Settings.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="team">
        <AccordionTrigger>Team</AccordionTrigger>
        <AccordionContent>Invite up to 10 teammates on your current plan.</AccordionContent>
      </AccordionItem>
    </Accordion>
  )
}
```

### Disabled item [#disabled-item]

Add `disabled` to an `AccordionItem` to lock it shut. It dims, can't be toggled, and is skipped by keyboard navigation.

```tsx
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@appica/ui-react/accordion'

export default function AccordionDisabled() {
  return (
    <Accordion className="max-w-110" defaultValue={['available']}>
      <AccordionItem value="available">
        <AccordionTrigger>Available section</AccordionTrigger>
        <AccordionContent>This item opens and closes as usual.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="locked" disabled>
        <AccordionTrigger>Locked section</AccordionTrigger>
        <AccordionContent>A disabled item can't be opened and is skipped by keyboard navigation.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="another">
        <AccordionTrigger>Another section</AccordionTrigger>
        <AccordionContent>Focus moves straight here, past the locked item above.</AccordionContent>
      </AccordionItem>
    </Accordion>
  )
}
```

### Leading media [#leading-media]

The trigger label is just `children`, so you can prefix it with any media — a plain icon, a [`Thumbnail`](/ui/components/react/thumbnail), or an [`Avatar`](/ui/components/react/avatar). They line up with the text while the indicator icon stays pinned to the trailing edge.

```tsx
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@appica/ui-react/accordion'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { Thumbnail } from '@appica/ui-react/thumbnail'
import { GBRounded } from '@appica/country-flags-react'
import { Bell, CreditCard } from '@appica/icons-react'

export default function AccordionMixedMedia() {
  return (
    <Accordion className="max-w-110">
      <AccordionItem value="notifications">
        <AccordionTrigger>
          <Bell />
          Notifications
        </AccordionTrigger>
        <AccordionContent>Choose which emails and push alerts you'd like to receive.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="billing">
        <AccordionTrigger>
          <Thumbnail variant="icon-outline" size="sm" shape="rounded" className="-my-1">
            <CreditCard />
          </Thumbnail>
          Billing
        </AccordionTrigger>
        <AccordionContent>Manage your payment method and download past invoices.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="region">
        <AccordionTrigger>
          <GBRounded className="size-6" aria-hidden />
          Region &amp; language
        </AccordionTrigger>
        <AccordionContent>
          Set your country, preferred language, and the currency shown across the app.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem value="account">
        <AccordionTrigger>
          <Avatar size="xs">
            <AvatarImage src="/avatars/01.jpg" alt="Sarah Jenkins" />
            <AvatarFallback>SJ</AvatarFallback>
          </Avatar>
          Account
        </AccordionTrigger>
        <AccordionContent>Update your profile details, email address, and password.</AccordionContent>
      </AccordionItem>
    </Accordion>
  )
}
```

### Controlled [#controlled]

Drive the open items yourself with `value` + `onValueChange`. Here the open panel is read out and stepped through with external prev/next buttons, while clicking a header still updates the same state.

```tsx
'use client'

import { useState } from 'react'
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@appica/ui-react/accordion'
import { Button } from '@appica/ui-react/button'
import { ChevronUp, ChevronDown } from '@appica/icons-react'

const items = [
  {
    value: 'install',
    title: 'Install dependencies',
    body: 'Restore the lockfile and pull the package cache so every build starts from the same baseline.',
  },
  {
    value: 'test',
    title: 'Run the test suite',
    body: 'Unit and integration tests run in parallel; a single failure stops the pipeline before deploy.',
  },
  {
    value: 'deploy',
    title: 'Deploy to production',
    body: 'A green build promotes the artifact behind a canary, then rolls out to the rest of the fleet.',
  },
]

export default function AccordionControlled() {
  const [value, setValue] = useState(['test'])
  const index = items.findIndex((item) => item.value === value[0])

  function step(delta: number) {
    const next = items[Math.min(items.length - 1, Math.max(0, index + delta))]
    if (next) setValue([next.value])
  }

  return (
    <div className="flex w-full max-w-110 flex-col gap-3">
      <div className="flex items-center justify-between">
        <p className="text-foreground-muted text-sm">
          Expanded: <span className="text-foreground-intense font-medium">{value[0] ?? 'none'}</span>
        </p>
        <div className="flex gap-1">
          <Button
            variant="outline"
            size="icon-sm"
            disabled={index <= 0}
            onClick={() => step(-1)}
            aria-label="Previous section"
          >
            <ChevronUp />
          </Button>
          <Button
            variant="outline"
            size="icon-sm"
            disabled={index >= items.length - 1}
            onClick={() => step(1)}
            aria-label="Next section"
          >
            <ChevronDown />
          </Button>
        </div>
      </div>
      <Accordion icon={false} value={value} onValueChange={(next) => setValue(next as string[])}>
        {items.map((item) => (
          <AccordionItem key={item.value} value={item.value}>
            <AccordionTrigger>{item.title}</AccordionTrigger>
            <AccordionContent>{item.body}</AccordionContent>
          </AccordionItem>
        ))}
      </Accordion>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The trigger text aligns to the right and the indicator icon moves to the left, all from CSS logical properties. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="accordion" />

## API reference [#api-reference]

`Accordion` wraps [Base UI's Accordion](https://base-ui.com/react/components/accordion). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. The panel exposes the `--accordion-panel-height` CSS variable that powers the height animation. See the Base UI docs for the complete API.

### Accordion [#accordion]

The root. Renders a `<div>` and owns the open state and shared styling.

| Prop            | <ColMinWidth width="210">Type</ColMinWidth>      | Default     | <ColMinWidth width="220">Description</ColMinWidth>              |
| --------------- | ------------------------------------------------ | ----------- | --------------------------------------------------------------- |
| `variant`       | <Code>'default' \| 'alt' \| 'flush'</Code>       | `'default'` | Surface style applied to every item.                            |
| `icon`          | <Code>'chevron' \| 'plus' \| false</Code>        | `'chevron'` | The open/close indicator, or `false` to hide it.                |
| `iconVariant`   | <Code>'icon' \| 'icon-box'</Code>                | `'icon'`    | Plain glyph, or wrapped in a tinted tile.                       |
| `iconPosition`  | <Code>'end' \| 'start'</Code>                    | `'end'`     | Place the icon after or before the trigger label.               |
| `value`         | `string[]`                                       | —           | Controlled list of open item values. Pair with `onValueChange`. |
| `defaultValue`  | `string[]`                                       | —           | Uncontrolled initially open item(s).                            |
| `onValueChange` | <Code>(value: string\[], details) => void</Code> | —           | Fires when the set of open items changes.                       |
| `multiple`      | `boolean`                                        | `false`     | Allow several panels to be open simultaneously.                 |
| `disabled`      | `boolean`                                        | `false`     | Disable every item in the accordion.                            |
| `keepMounted`   | `boolean`                                        | `false`     | Keep closed panels in the DOM (e.g. for in-page search / SEO).  |
| `className`     | <Code>string \| ((state) => string)</Code>       | —           | Extra classes, merged via `tailwind-merge`.                     |

### AccordionItem [#accordionitem]

One section. Renders a `<div>` and exposes `data-open` / `data-disabled` for styling.

| Prop           | <ColMinWidth width="210">Type</ColMinWidth>   | Default | <ColMinWidth width="220">Description</ColMinWidth>                        |
| -------------- | --------------------------------------------- | ------- | ------------------------------------------------------------------------- |
| `value`        | `string`                                      | —       | Identifier reported in `value`/`onValueChange`. Auto-assigned if omitted. |
| `variant`      | <Code>'default' \| 'alt' \| 'flush'</Code>    | —       | Override the root's `variant` for this item.                              |
| `disabled`     | `boolean`                                     | `false` | Lock this item shut and skip it during keyboard navigation.               |
| `onOpenChange` | <Code>(open: boolean, details) => void</Code> | —       | Fires when this item opens or closes.                                     |
| `className`    | <Code>string \| ((state) => string)</Code>    | —       | Extra classes, merged via `tailwind-merge`.                               |

### AccordionTrigger [#accordiontrigger]

The header button. Rendered inside an `Accordion.Header`; toggles its panel and shows the icon.

| Prop           | <ColMinWidth width="210">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth> |
| -------------- | ------------------------------------------- | ------- | -------------------------------------------------- |
| `icon`         | <Code>'chevron' \| 'plus' \| false</Code>   | —       | Override the root's icon for this trigger.         |
| `iconVariant`  | <Code>'icon' \| 'icon-box'</Code>           | —       | Override the root's icon style.                    |
| `iconPosition` | <Code>'end' \| 'start'</Code>               | —       | Override the root's icon position.                 |
| `children`     | `ReactNode`                                 | —       | The header label.                                  |
| `className`    | <Code>string \| ((state) => string)</Code>  | —       | Extra classes, merged via `tailwind-merge`.        |

### AccordionContent [#accordioncontent]

The collapsible panel. Renders a `<div>` that animates its height between open and closed.

| Prop          | <ColMinWidth width="210">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth> |
| ------------- | ------------------------------------------- | ------- | -------------------------------------------------- |
| `children`    | `ReactNode`                                 | —       | The panel content.                                 |
| `keepMounted` | `boolean`                                   | `false` | Keep the panel mounted while closed.               |
| `className`   | <Code>string \| ((state) => string)</Code>  | —       | Extra classes, merged via `tailwind-merge`.        |

## Accessibility [#accessibility]

* Each `AccordionTrigger` is a real `<button>` inside a heading, with `aria-expanded` and `aria-controls` wired to its panel — assistive tech announces the open/closed state.
* Keyboard support follows the WAI-ARIA accordion pattern: **Tab** moves between triggers, **Enter**/**Space** toggles the focused panel, and the **arrow keys** move focus between headers (wrapping at the ends).
* A `disabled` item is removed from the tab order and skipped by arrow navigation, and exposes `data-disabled` for styling.
* The indicator icon is decorative (`aria-hidden`); the trigger's text label carries the meaning.
* The panel's height animation honours `prefers-reduced-motion`.


# Alert Dialog (/ui/components/react/alert-dialog)



<Playground component="alert-dialog" />

## Usage [#usage]

```tsx
import {
  AlertDialog,
  AlertDialogTrigger,
  AlertDialogContent,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogDescription,
  AlertDialogBody,
  AlertDialogFooter,
  AlertDialogClose,
} from '@appica/ui-react/alert-dialog'
import { Button } from '@appica/ui-react/button'
```

```tsx
<AlertDialog>
  <AlertDialogTrigger render={<Button variant="outline">Delete project</Button>} />
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Delete this project?</AlertDialogTitle>
      <AlertDialogDescription>This permanently removes the project and cannot be undone.</AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogClose render={<Button variant="soft">Cancel</Button>} />
      <AlertDialogClose render={<Button variant="destructive">Delete</Button>} />
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

`AlertDialog` is a compound component built on [Base UI's Alert Dialog](https://base-ui.com/react/components/alert-dialog). It's a [`Dialog`](/ui/components/react/dialog) tuned for **confirmations**: it's always modal, it has **no dismiss-by-clicking-outside and no close button**, and it carries `role="alertdialog"` so assistive tech announces it as an interruption. The user has to choose one of the actions you provide. The root holds the open state; the parts compose the trigger and the portalled popup:

* **`AlertDialogTrigger`** — the button that opens the dialog. Use `render` to project it onto your own [`Button`](/ui/components/react/button) (or any element).
* **`AlertDialogContent`** — the portalled, centered popup. It draws the card, the backdrop, and the focus trap, and accepts the shared **modal props** below.
* **`AlertDialogHeader`** — a layout wrapper grouping the title and description with the right spacing.
* **`AlertDialogTitle`** — an `<h2>` that labels the popup (`aria-labelledby`).
* **`AlertDialogDescription`** — a `<p>` that describes it (`aria-describedby`).
* **`AlertDialogBody`** — an optional region for longer content between the header and footer.
* **`AlertDialogFooter`** — a layout wrapper for the actions; stacks on small screens and right-aligns in a row from `sm` up.
* **`AlertDialogClose`** — a button that closes the dialog; project it onto your own [`Button`](/ui/components/react/button) with `render`. Put your confirm **and** cancel actions here.

Reach for an `AlertDialog` only when continuing is **consequential** — deleting data, signing out, discarding edits. For a dismissible panel with arbitrary content, use a [`Dialog`](/ui/components/react/dialog); for a transient, non-blocking message, use a [`Toast`](/ui/components/react/toast).

## Examples [#examples]

### Destructive confirmation [#destructive-confirmation]

The canonical use: a high-stakes action gated behind an explicit confirm. Give the confirm button the `destructive` [`Button`](/ui/components/react/button) variant so the danger reads at a glance, and keep the cancel action first so it's the easy, default-focused choice.

```tsx
import {
  AlertDialog,
  AlertDialogTrigger,
  AlertDialogContent,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogClose,
} from '@appica/ui-react/alert-dialog'
import { Button } from '@appica/ui-react/button'
import { Trash } from '@appica/icons-react'

export default function AlertDialogDestructive() {
  return (
    <AlertDialog>
      <AlertDialogTrigger
        render={
          <Button variant="outline">
            <Trash data-icon="start" />
            Delete account
          </Button>
        }
      />
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>Delete your account?</AlertDialogTitle>
          <AlertDialogDescription>
            Your profile, projects, and billing history will be erased immediately. This action cannot be undone.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogClose render={<Button variant="soft">Cancel</Button>} />
          <AlertDialogClose render={<Button variant="destructive">Delete account</Button>} />
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  )
}
```

### With media [#with-media]

Lead the header with media to anchor the message — an [`Avatar`](/ui/components/react/avatar), a [`Thumbnail`](/ui/components/react/thumbnail), or a plain icon. It sits above the title and inherits the dialog's spacing. This example also centers the header (`text-center`) and stretches the actions to equal widths (`flex-1`) for a more focused, app-like layout.

```tsx
import {
  AlertDialog,
  AlertDialogTrigger,
  AlertDialogContent,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogClose,
} from '@appica/ui-react/alert-dialog'
import { Button } from '@appica/ui-react/button'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { Send } from '@appica/icons-react'

export default function AlertDialogMedia() {
  return (
    <AlertDialog>
      <AlertDialogTrigger render={<Button variant="outline">Invite member</Button>} />
      <AlertDialogContent className="text-center">
        <AlertDialogHeader>
          <Avatar size="lg" className="mx-auto mb-1">
            <AvatarImage src="/avatars/01.jpg" alt="Sarah Jenkins" />
            <AvatarFallback>SJ</AvatarFallback>
          </Avatar>
          <AlertDialogTitle>Invite Sarah Jenkins?</AlertDialogTitle>
          <AlertDialogDescription>
            She'll get an email invitation to join the Orbit project as an editor. You can change her role later.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogClose
            render={
              <Button variant="soft" className="flex-1">
                Cancel
              </Button>
            }
          />
          <AlertDialogClose
            render={
              <Button className="flex-1">
                <Send data-icon="start" />
                Send invite
              </Button>
            }
          />
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  )
}
```

### Asynchronous action (controlled) [#asynchronous-action-controlled]

When confirming kicks off async work, keep the dialog open until it settles — this is the everyday reason to control the open state. Drive `open` yourself and **don't** close from `onOpenChange` while the request is in flight: swap the confirm button to a loading state and disable cancel, then close once the promise resolves.

```tsx
'use client'

import * as React from 'react'
import {
  AlertDialog,
  AlertDialogTrigger,
  AlertDialogContent,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogClose,
} from '@appica/ui-react/alert-dialog'
import { Button } from '@appica/ui-react/button'
import { Spinner } from '@appica/ui-react/spinner'

export default function AlertDialogAsync() {
  const [open, setOpen] = React.useState(false)
  const [pending, setPending] = React.useState(false)

  async function confirm() {
    setPending(true)
    await new Promise((resolve) => setTimeout(resolve, 1400))
    setPending(false)
    setOpen(false)
  }

  return (
    <AlertDialog open={open} onOpenChange={(next) => !pending && setOpen(next)}>
      <AlertDialogTrigger render={<Button variant="outline">Reset API key</Button>} />
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>Reset your API key?</AlertDialogTitle>
          <AlertDialogDescription>
            The current key stops working at once. Update every service that uses it before continuing.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogClose disabled={pending} render={<Button variant="soft">Cancel</Button>} />
          <Button disabled={pending} onClick={confirm}>
            {pending ? (
              <>
                <Spinner data-icon="start" currentColor className="text-base" />
                Resetting…
              </>
            ) : (
              'Reset key'
            )}
          </Button>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The header, body, and footer flip to read right-to-left, and the footer's actions mirror to the leading edge. The popup portals to `<body>`, so it follows the **document** direction — when you scope RTL to a subtree of an LTR page, set `dir="rtl"` on `AlertDialogContent` so the popup mirrors too. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="alert-dialog" />

## API reference [#api-reference]

`AlertDialog` wraps [Base UI's Alert Dialog](https://base-ui.com/react/components/alert-dialog). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### AlertDialog [#alertdialog]

The root. Holds the open state; renders no DOM of its own. Always modal, and not dismissible by an outside click — the user must pick an action.

| Prop                   | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth>      |
| ---------------------- | ------------------------------------------- | ------- | ------------------------------------------------------- |
| `open`                 | `boolean`                                   | —       | Controlled open state. Pair with `onOpenChange`.        |
| `defaultOpen`          | `boolean`                                   | `false` | Uncontrolled initial open state.                        |
| `onOpenChange`         | <Code>(open, eventDetails) => void</Code>   | —       | Fires when the dialog opens or closes.                  |
| `onOpenChangeComplete` | `(open) => void`                            | —       | Fires after the open/close transition finishes.         |
| `actionsRef`           | `RefObject`                                 | —       | Imperative handle to `close()` / `unmount()` the popup. |

### AlertDialogTrigger [#alertdialogtrigger]

The button that opens the dialog. Forwards Base UI's `AlertDialog.Trigger`; use `render` to project it onto your own element.

| Prop           | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                          |
| -------------- | ----------------------------------------------------------- | ------- | ---------------------------------------------------- |
| `render`       | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render the trigger as your own element (a `Button`). |
| `nativeButton` | `boolean`                                                   | `true`  | Whether the rendered element is a native `<button>`. |
| `className`    | `string`                                                    | —       | Extra classes, merged via `tailwind-merge`.          |

### AlertDialogContent [#alertdialogcontent]

The portalled, centered popup. Draws the card, the backdrop, and the focus trap, and maps the underlying Base UI Portal / Backdrop / Viewport so you don't have to reach into them. Shared with [`Dialog`](/ui/components/react/dialog) and [`Drawer`](/ui/components/react/drawer) through the **modal props**.

| Prop            | <ColMinWidth width="170">Type</ColMinWidth> | Default | Description                                                            |
| --------------- | ------------------------------------------- | ------- | ---------------------------------------------------------------------- |
| `backdrop`      | `boolean`                                   | `true`  | Render the dimmed, blurred backdrop behind the popup.                  |
| `initialFocus`  | `RefObject`                                 | —       | Element to focus when the dialog opens (defaults to the first action). |
| `finalFocus`    | `RefObject`                                 | —       | Element to focus when it closes (defaults to the trigger).             |
| `container`     | <Code>HTMLElement \| ref \| null</Code>     | —       | Portal target — render the popup into a different node.                |
| `keepMounted`   | `boolean`                                   | `false` | Keep the popup mounted in the DOM while closed.                        |
| `backdropProps` | `object`                                    | —       | Escape hatch for the backdrop element (`className`, `style`, …).       |
| `viewportProps` | `object`                                    | —       | Escape hatch for the viewport element that centers the popup.          |
| `portalProps`   | `object`                                    | —       | Escape hatch for the portal element.                                   |
| `className`     | `string`                                    | —       | Extra classes on the popup card (e.g. a wider `max-w-*`).              |

### AlertDialogHeader [#alertdialogheader]

A layout wrapper that groups the title and description with consistent padding and spacing.

| Prop        | Type        | Default | Description                                                                      |
| ----------- | ----------- | ------- | -------------------------------------------------------------------------------- |
| `children`  | `ReactNode` | —       | Optional leading media (`Avatar` / `Thumbnail`), the title, and the description. |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`.                                      |

### AlertDialogTitle [#alertdialogtitle]

An `<h2>` that labels the popup. Rendering one sets the popup's `aria-labelledby`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The title text.                             |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### AlertDialogDescription [#alertdialogdescription]

A `<p>` that describes the popup. Rendering one sets the popup's `aria-describedby`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The description text.                       |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### AlertDialogBody [#alertdialogbody]

An optional region between the header and footer, for confirmations that carry more than a sentence (a changelog, a list of affected items). It doesn't scroll on its own — for content taller than the viewport, wrap it in a [`ScrollArea`](/ui/components/react/scroll-area) between the pinned header and footer.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The body content.                           |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### AlertDialogFooter [#alertdialogfooter]

A layout wrapper for the actions. Stacks them vertically on small screens (confirm on top) and lays them out in a right-aligned row from `sm` up.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The action buttons.                         |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### AlertDialogClose [#alertdialogclose]

A button that closes the dialog. Forwards Base UI's `AlertDialog.Close`; project it onto your own element with `render`. Use it for **both** the confirm and the cancel action.

| Prop           | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                          |
| -------------- | ----------------------------------------------------------- | ------- | ---------------------------------------------------- |
| `render`       | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render the close control as your own element.        |
| `nativeButton` | `boolean`                                                   | `true`  | Whether the rendered element is a native `<button>`. |
| `className`    | `string`                                                    | —       | Extra classes, merged via `tailwind-merge`.          |

## Accessibility [#accessibility]

* The popup has `role="alertdialog"`, with `aria-labelledby` and `aria-describedby` wired automatically from `AlertDialogTitle` and `AlertDialogDescription` — always render both.
* Opening **traps focus** inside the popup and blocks scroll/interaction with the rest of the page; **Escape** closes it and focus returns to the trigger.
* Unlike a [`Dialog`](/ui/components/react/dialog), clicking the backdrop does **not** dismiss it and there's no built-in close button — the user must pick one of your actions, which is the point of an alert dialog.
* Focus lands on the first action by default; point it somewhere safer with `initialFocus` (e.g. the cancel button) for destructive confirmations.
* Popup enter/exit transitions are skipped when the user prefers reduced motion.


# Alert (/ui/components/react/alert)



<Playground component="alert" />

## Usage [#usage]

```tsx
import { Alert, AlertIcon, AlertTitle, AlertDescription, AlertAction } from '@appica/ui-react/alert'
```

```tsx
<Alert variant="info">
  <AlertIcon>
    <InfoCircleFilled />
  </AlertIcon>
  <AlertTitle>Scheduled maintenance</AlertTitle>
  <AlertDescription>Some features may be unavailable Sunday night.</AlertDescription>
</Alert>
```

`Alert` is a banner for a message that lives **in the page layout** — a status, a heads-up, a result. Compose it from its parts, all under `@appica/ui-react/alert`:

* **`Alert`** — the `role="alert"` container. Sets the `variant` color and `layout`, and owns the optional dismiss behavior.
* **`AlertIcon`** — a leading icon slot that automatically takes the variant's color.
* **`AlertTitle`** — the headline (`<h5>`).
* **`AlertDescription`** — the supporting body text.
* **`AlertAction`** — a trailing row for buttons.

Every part is optional except a meaningful label — most alerts have at least an `AlertTitle`. The slots are placed by a grid, so you can include only the ones you need and they'll lay out correctly in either layout.

For a transient, stacked notification that appears and disappears on its own, reach for a [`Toast`](/ui/components/react/toast) instead; for a blocking confirmation, use an [`Alert Dialog`](/ui/components/react/alert-dialog). `Alert` is for messages that sit inline with your content.

## Examples [#examples]

### Default [#default]

The neutral `default` variant with an icon, title, and description. Drop the parts you need inside `Alert` and the grid arranges them.

```tsx
import { Alert, AlertIcon, AlertTitle, AlertDescription } from '@appica/ui-react/alert'
import { InfoCircle } from '@appica/icons-react'

export default function AlertDefault() {
  return (
    <div className="w-full max-w-md">
      <Alert>
        <AlertIcon>
          <InfoCircle />
        </AlertIcon>
        <AlertTitle>Heads up</AlertTitle>
        <AlertDescription>
          A new version of the dashboard is available — refresh to pick up the latest features.
        </AlertDescription>
      </Alert>
    </div>
  )
}
```

### Variants [#variants]

Seven variants color the alert for its purpose: `default`, `primary`, `secondary`, `info`, `success`, `warning`, and `error`. The `AlertIcon` inherits the variant's accent color automatically.

```tsx
import { Alert, AlertIcon, AlertTitle, AlertDescription } from '@appica/ui-react/alert'
import {
  Bell,
  Sparkle,
  InfoCircleFilled,
  CircleCheckFilled,
  AlertTriangleFilled,
  CircleXFilled,
} from '@appica/icons-react'

const VARIANTS = [
  { variant: 'default', icon: Bell, title: 'Update available', desc: 'Version 2.4 is ready to install.' },
  { variant: 'primary', icon: Sparkle, title: 'New feature', desc: 'You can now schedule reports to run weekly.' },
  { variant: 'secondary', icon: InfoCircleFilled, title: 'Did you know?', desc: 'Press ⌘K to search from anywhere.' },
  {
    variant: 'info',
    icon: InfoCircleFilled,
    title: 'Maintenance window',
    desc: 'We will be offline Sunday 02:00–03:00 UTC.',
  },
  { variant: 'success', icon: CircleCheckFilled, title: 'Payment received', desc: 'Your invoice has been settled.' },
  {
    variant: 'warning',
    icon: AlertTriangleFilled,
    title: 'Storage almost full',
    desc: 'You have used 92% of your quota.',
  },
  {
    variant: 'error',
    icon: CircleXFilled,
    title: 'Payment failed',
    desc: 'We could not charge your card on file.',
  },
] as const

export default function AlertVariants() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      {VARIANTS.map(({ variant, icon: Icon, title, desc }) => (
        <Alert key={variant} variant={variant}>
          <AlertIcon>
            <Icon />
          </AlertIcon>
          <AlertTitle>{title}</AlertTitle>
          <AlertDescription>{desc}</AlertDescription>
        </Alert>
      ))}
    </div>
  )
}
```

### Inline layout [#inline-layout]

Set `layout="inline"` to flow the icon, title, and description onto a single row once there's room (the alert is container-query aware, so it falls back to the stacked block layout when it gets narrow). Good for slim page-top banners.

```tsx
import { Alert, AlertIcon, AlertTitle, AlertDescription } from '@appica/ui-react/alert'
import { InfoCircleFilled } from '@appica/icons-react'

export default function AlertInline() {
  return (
    <div className="w-full max-w-xl">
      <Alert layout="inline" variant="info">
        <AlertIcon>
          <InfoCircleFilled />
        </AlertIcon>
        <AlertTitle>Scheduled maintenance</AlertTitle>
        <AlertDescription>Some features may be unavailable Sunday night.</AlertDescription>
      </Alert>
    </div>
  )
}
```

### With actions [#with-actions]

Add an `AlertAction` row for buttons — say a primary action and a dismiss. It sits below the text in the block layout and trails the message inline.

```tsx
import { Alert, AlertIcon, AlertTitle, AlertDescription, AlertAction } from '@appica/ui-react/alert'
import { Button } from '@appica/ui-react/button'
import { AlertTriangleFilled } from '@appica/icons-react'

export default function AlertActions() {
  return (
    <div className="w-full max-w-md">
      <Alert variant="warning">
        <AlertIcon>
          <AlertTriangleFilled />
        </AlertIcon>
        <AlertTitle>Your trial ends in 3 days</AlertTitle>
        <AlertDescription>Upgrade now to keep access to your projects and team members.</AlertDescription>
        <AlertAction>
          <Button variant="ghost" size="sm" className="hover:before:bg-background">
            Maybe later
          </Button>
          <Button size="sm">Upgrade</Button>
        </AlertAction>
      </Alert>
    </div>
  )
}
```

### Dismissible [#dismissible]

Set `dismissible` to add a close button. By default the alert manages its own visibility and animates out when closed. To remember the dismissal across visits, give it a `persistKey` — the choice is stored (in `localStorage` by default, or `sessionStorage` via `persistStorage`) and the alert stays hidden on return.

```tsx
import { Alert, AlertIcon, AlertTitle, AlertDescription } from '@appica/ui-react/alert'
import { CircleCheckFilled } from '@appica/icons-react'

export default function AlertDismissible() {
  return (
    <div className="w-full max-w-md">
      <Alert variant="success" dismissible>
        <AlertIcon>
          <CircleCheckFilled />
        </AlertIcon>
        <AlertTitle>Profile updated</AlertTitle>
        <AlertDescription>Your changes have been saved. You can dismiss this message.</AlertDescription>
      </Alert>
    </div>
  )
}
```

### Controlled [#controlled]

Drive visibility yourself with `open` + `onOpenChange` — for instance to show a success banner after a save, or to bring a dismissed alert back.

```tsx
'use client'

import * as React from 'react'
import { Alert, AlertIcon, AlertTitle, AlertDescription } from '@appica/ui-react/alert'
import { Button } from '@appica/ui-react/button'
import { InfoCircleFilled } from '@appica/icons-react'

export default function AlertControlled() {
  const [open, setOpen] = React.useState(true)

  return (
    <div className="flex w-full max-w-md flex-col items-center gap-4">
      <div className="w-full">
        <Alert variant="info" open={open} onOpenChange={setOpen} dismissible>
          <AlertIcon>
            <InfoCircleFilled />
          </AlertIcon>
          <AlertTitle>Good to know</AlertTitle>
          <AlertDescription>This banner is controlled. Dismiss it and bring it back below.</AlertDescription>
        </Alert>
      </div>
      {!open && (
        <Button variant="outline" size="sm" onClick={() => setOpen(true)}>
          Show alert
        </Button>
      )}
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The icon moves to the right, the dismiss button to the left, and the action row aligns to the start edge — all from CSS logical properties. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="alert" />

## API reference [#api-reference]

### Alert [#alert]

The container. Renders a `<div role="alert">` and sets the variant, layout, and dismiss behavior.

| Prop             | <ColMinWidth width="210">Type</ColMinWidth>                                                       | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                                 |
| ---------------- | ------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| `variant`        | <Code>'default' \| 'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'error'</Code> | `'default'` | Color scheme; also drives the `AlertIcon` accent.                                                  |
| `layout`         | <Code>'block' \| 'inline'</Code>                                                                  | `'block'`   | Stack the parts (`block`) or flow them on one row when wide enough (`inline`).                     |
| `dismissible`    | `boolean`                                                                                         | `false`     | Render a close button that hides the alert (with an exit animation).                               |
| `open`           | `boolean`                                                                                         | —           | Controlled visibility. Pair with `onOpenChange`.                                                   |
| `onOpenChange`   | <Code>(open: boolean) => void</Code>                                                              | —           | Called when the alert is dismissed (with `false`).                                                 |
| `persistKey`     | `string`                                                                                          | —           | Remember the dismissal under this key so the alert stays hidden on return (uncontrolled).          |
| `persistStorage` | <Code>'local' \| 'session'</Code>                                                                 | `'local'`   | Which Web Storage backs `persistKey`.                                                              |
| `closeLabel`     | `string`                                                                                          | `'Dismiss'` | Accessible label for the close button.                                                             |
| `role`           | `AriaRole`                                                                                        | `'alert'`   | Live-region role announced by assistive tech. Use `'status'` for a polite, non-interruptive alert. |
| `className`      | `string`                                                                                          | —           | Extra classes on the container, merged via `tailwind-merge`.                                       |

Any other `<div>` attribute is forwarded to the container.

### AlertIcon [#alerticon]

A leading icon slot. Renders a `<span>` that colors its icon to match the variant.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The icon to display.                        |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### AlertTitle [#alerttitle]

The headline. Renders an `<h5>` by default.

| Prop        | Type                              | Default | Description                                                  |
| ----------- | --------------------------------- | ------- | ------------------------------------------------------------ |
| `children`  | `ReactNode`                       | —       | The title text.                                              |
| `as`        | <Code>'h1' … 'h6' \| 'div'</Code> | `'h5'`  | Heading level, so the alert fits the page's heading outline. |
| `className` | `string`                          | —       | Extra classes, merged via `tailwind-merge`.                  |

### AlertDescription [#alertdescription]

The supporting body text. Renders a `<p>`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The body text.                              |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### AlertAction [#alertaction]

A trailing row for buttons. Renders a `<div>`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | Action buttons.                             |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

## Accessibility [#accessibility]

* `Alert` renders with `role="alert"`, so assistive tech announces its contents when it appears — keep the message concise and meaningful.
* Because `role="alert"` is an assertive live region, mount it only when there's something to announce; an alert present on every page load isn't announced on later changes.
* The dismiss button is a real `<button>` with an accessible name from `closeLabel` (default "Dismiss"); customise it when "Dismiss" is ambiguous.
* `AlertIcon` is decorative — convey meaning in the `AlertTitle`/`AlertDescription`, not the icon alone.
* The enter/exit animation is skipped when the user prefers reduced motion.


# Autocomplete (/ui/components/react/autocomplete)



<Playground component="autocomplete" />

## Usage [#usage]

```tsx
import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'
```

```tsx
const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart']

<Autocomplete items={frameworks}>
  <AutocompleteInput placeholder="Search a framework" />
  <AutocompleteContent>
    <AutocompleteEmpty>No frameworks found.</AutocompleteEmpty>
    <AutocompleteList>
      {(item) => (
        <AutocompleteItem key={item} value={item}>
          {item}
        </AutocompleteItem>
      )}
    </AutocompleteList>
  </AutocompleteContent>
</Autocomplete>
```

`Autocomplete` is a compound component. The root holds the data (`items`) and shared options (`size`, `variant`, `clearable`, `icon`); the parts compose the input and the filtered popup:

* **`AutocompleteInput`** — the text field, styled like [`Input`](/ui/components/react/input). Add a clear button with `clearable` and a dropdown chevron with `icon` (both on the root, both off by default).
* **`AutocompleteContent`** — the portalled, auto-positioned popup. Accepts the shared [floating props](/ui/components/react/popover) (`side`, `align`, `sideOffset`, …).
* **`AutocompleteList`** — the scrollable list. Pass a render function to map over the filtered items, or static `AutocompleteItem`s.
* **`AutocompleteItem`** — one option; its `value` is what selection reports.
* **`AutocompleteEmpty`** — shown only when the filter matches nothing.

## Examples [#examples]

### Variants [#variants]

`variant` switches the input appearance between a bordered `outline` (default) and a filled `soft` field.

```tsx
'use client'

import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']
const variants = ['outline', 'soft'] as const

export default function AutocompleteVariants() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      {variants.map((variant) => (
        <div key={variant}>
          <Autocomplete items={frameworks} variant={variant}>
            <AutocompleteInput placeholder="Search a framework" aria-label={`Search (${variant})`} />
            <AutocompleteContent>
              <AutocompleteEmpty>No frameworks found.</AutocompleteEmpty>
              <AutocompleteList>
                {(item: string) => (
                  <AutocompleteItem key={item} value={item}>
                    {item}
                  </AutocompleteItem>
                )}
              </AutocompleteList>
            </AutocompleteContent>
          </Autocomplete>
        </div>
      ))}
    </div>
  )
}
```

### Sizes [#sizes]

`size` on the root scales the input, popup radius, and items together.

```tsx
'use client'

import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']
const sizes = ['sm', 'md', 'lg'] as const

export default function AutocompleteSizes() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      {sizes.map((size) => (
        <div key={size}>
          <Autocomplete items={frameworks} size={size}>
            <AutocompleteInput placeholder="Search a framework" aria-label={`Search (${size})`} />
            <AutocompleteContent>
              <AutocompleteEmpty>No frameworks found.</AutocompleteEmpty>
              <AutocompleteList>
                {(item: string) => (
                  <AutocompleteItem key={item} value={item}>
                    {item}
                  </AutocompleteItem>
                )}
              </AutocompleteList>
            </AutocompleteContent>
          </Autocomplete>
        </div>
      ))}
    </div>
  )
}
```

### Clearable & chevron [#clearable--chevron]

Set `clearable` to add a clear (✕) button once there's a value, and `icon` to add a chevron that toggles the popup. Both render inside the input and are off by default.

```tsx
'use client'

import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']

export default function AutocompleteClearable() {
  return (
    <div className="w-full max-w-70">
      <Autocomplete items={frameworks} defaultValue="Next.js" clearable icon>
        <AutocompleteInput placeholder="Search a framework" aria-label="Search a framework" />
        <AutocompleteContent>
          <AutocompleteEmpty>No frameworks found.</AutocompleteEmpty>
          <AutocompleteList>
            {(item: string) => (
              <AutocompleteItem key={item} value={item}>
                {item}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
    </div>
  )
}
```

### Items with icons [#items-with-icons]

Items can render any content. Mark a leading [icon](/ui/icons) with `data-icon="start"` so it gets the same inner spacing as in [`Button`](/ui/components/react/button). When `items` are objects rather than strings, give the root an `itemToStringValue` so the filter and input know how to read each one. Here the selected command's icon is mirrored back into the input via `AutocompleteInput`'s `startSlot`.

```tsx
'use client'

import * as React from 'react'
import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'
import { LayoutDashboard, User, Settings, CreditCard, Bell, Mail } from '@appica/icons-react'

interface Command {
  label: string
  icon: React.ElementType
}

const commands: Command[] = [
  { label: 'Dashboard', icon: LayoutDashboard },
  { label: 'Profile', icon: User },
  { label: 'Settings', icon: Settings },
  { label: 'Billing', icon: CreditCard },
  { label: 'Notifications', icon: Bell },
  { label: 'Messages', icon: Mail },
]

export default function AutocompleteWithIcons() {
  const [value, setValue] = React.useState('')
  const selected = commands.find((command) => command.label === value)

  return (
    <div className="w-full max-w-70">
      <Autocomplete
        items={commands}
        value={value}
        onValueChange={(v: string) => setValue(v)}
        itemToStringValue={(item) => (item as Command).label}
        clearable
        icon
      >
        <AutocompleteInput
          placeholder="Search commands"
          aria-label="Search commands"
          startSlot={selected ? <selected.icon aria-hidden /> : null}
        />
        <AutocompleteContent>
          <AutocompleteEmpty>No commands found.</AutocompleteEmpty>
          <AutocompleteList>
            {(command: Command) => (
              <AutocompleteItem key={command.label} value={command}>
                <command.icon data-icon="start" />
                {command.label}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
    </div>
  )
}
```

### Country search [#country-search]

The same object-item pattern with [country flags](/ui/country-flags) — a typical country picker. Each item renders a flag before the name, and the selected country's flag is mirrored into the input through `startSlot`.

```tsx
'use client'

import * as React from 'react'
import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'
import { CountryFlagRounded } from '@appica/country-flags-react'

interface Country {
  code: string
  name: string
}

const countries: Country[] = [
  { code: 'au', name: 'Australia' },
  { code: 'br', name: 'Brazil' },
  { code: 'ca', name: 'Canada' },
  { code: 'fr', name: 'France' },
  { code: 'de', name: 'Germany' },
  { code: 'it', name: 'Italy' },
  { code: 'jp', name: 'Japan' },
  { code: 'es', name: 'Spain' },
  { code: 'gb', name: 'United Kingdom' },
  { code: 'us', name: 'United States' },
]

export default function AutocompleteCountrySearch() {
  const [value, setValue] = React.useState('')
  const selected = countries.find((country) => country.name === value)

  return (
    <div className="w-full max-w-70">
      <Autocomplete
        items={countries}
        value={value}
        onValueChange={(v: string) => setValue(v)}
        itemToStringValue={(item) => (item as Country).name}
        clearable
        icon
      >
        <AutocompleteInput
          placeholder="Search a country"
          aria-label="Search a country"
          startSlot={selected ? <CountryFlagRounded code={selected.code} aria-hidden /> : null}
        />
        <AutocompleteContent>
          <AutocompleteEmpty>No countries found.</AutocompleteEmpty>
          <AutocompleteList>
            {(country: Country) => (
              <AutocompleteItem key={country.code} value={country}>
                <CountryFlagRounded code={country.code} data-icon="start" aria-hidden />
                {country.name}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
    </div>
  )
}
```

### Grouped options [#grouped-options]

Pass a grouped `items` array — `{ value, items }[]` — and render each group with `AutocompleteGroup` + `AutocompleteLabel` + `AutocompleteCollection`. The outer render function iterates groups; `AutocompleteCollection` renders the items inside each.

```tsx
'use client'

import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
  AutocompleteGroup,
  AutocompleteLabel,
  AutocompleteCollection,
} from '@appica/ui-react/autocomplete'

interface ProduceGroup {
  value: string
  items: string[]
}

const groups: ProduceGroup[] = [
  { value: 'Fruits', items: ['Apple', 'Banana', 'Cherry', 'Grapefruit', 'Mango', 'Orange', 'Strawberry'] },
  { value: 'Vegetables', items: ['Broccoli', 'Carrot', 'Cucumber', 'Lettuce', 'Potato', 'Spinach', 'Tomato'] },
  { value: 'Herbs', items: ['Basil', 'Mint', 'Oregano', 'Parsley', 'Rosemary', 'Thyme'] },
]

export default function AutocompleteGrouped() {
  return (
    <div className="w-full max-w-70">
      <Autocomplete items={groups}>
        <AutocompleteInput placeholder="Search produce" aria-label="Search produce" />
        <AutocompleteContent>
          <AutocompleteEmpty>No produce found.</AutocompleteEmpty>
          <AutocompleteList>
            {(group: ProduceGroup) => (
              <AutocompleteGroup key={group.value} items={group.items}>
                <AutocompleteLabel>{group.value}</AutocompleteLabel>
                <AutocompleteCollection>
                  {(item: string) => (
                    <AutocompleteItem key={item} value={item}>
                      {item}
                    </AutocompleteItem>
                  )}
                </AutocompleteCollection>
              </AutocompleteGroup>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
    </div>
  )
}
```

### Grid layout [#grid-layout]

Set `grid` on the root to lay options out in a grid (arrow keys move in two dimensions). `AutocompleteList`'s `cols` controls how many items per row.

```tsx
'use client'

import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'

const tags = ['React', 'Vue', 'Svelte', 'Angular', 'Solid', 'Qwik', 'Preact', 'Lit']

export default function AutocompleteGrid() {
  return (
    <div className="w-full max-w-70">
      <Autocomplete items={tags} grid icon>
        <AutocompleteInput placeholder="Search a library" aria-label="Search a library" />
        <AutocompleteContent>
          <AutocompleteEmpty>No libraries found.</AutocompleteEmpty>
          <AutocompleteList cols={2}>
            {(item: string) => (
              <AutocompleteItem key={item} value={item} className="flex-1">
                {item}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
    </div>
  )
}
```

### Controlled [#controlled]

Drive the input value yourself with `value` + `onValueChange` — useful for syncing with form state or reacting to every keystroke.

```tsx
'use client'

import * as React from 'react'
import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']

export default function AutocompleteControlled() {
  const [value, setValue] = React.useState('')

  return (
    <div className="flex w-full max-w-70 flex-col gap-3">
      <Autocomplete items={frameworks} value={value} onValueChange={(v: string) => setValue(v)} clearable>
        <AutocompleteInput placeholder="Search a framework" aria-label="Search a framework" />
        <AutocompleteContent>
          <AutocompleteEmpty>No frameworks found.</AutocompleteEmpty>
          <AutocompleteList>
            {(item: string) => (
              <AutocompleteItem key={item} value={item}>
                {item}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
      <p className="text-foreground-muted text-sm">
        Current value: <span className="text-foreground font-medium">{value || '—'}</span>
      </p>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="autocomplete" />

## API reference [#api-reference]

`Autocomplete` wraps [Base UI's Autocomplete](https://base-ui.com/react/components/autocomplete). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### Autocomplete [#autocomplete]

The root. Holds the data and the shared styling/behavior options; renders no DOM of its own.

| Prop                | <ColMinWidth width="180">Type</ColMinWidth>          | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                   |
| ------------------- | ---------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------ |
| `items`             | <Code>readonly T\[] \| {'{ value, items }[]'}</Code> | —           | The data to filter. A flat array, or `{ value, items }` objects for grouped options. |
| `size`              | <Code>'sm' \| 'md' \| 'lg'</Code>                    | `'md'`      | Input height, popup radius, and item sizing.                                         |
| `variant`           | <Code>'outline' \| 'soft'</Code>                     | `'outline'` | Input appearance — bordered or filled.                                               |
| `clearable`         | `boolean`                                            | `false`     | Render a clear button inside the input when a value is present.                      |
| `icon`              | `boolean`                                            | `false`     | Render a chevron button that toggles the popup.                                      |
| `grid`              | `boolean`                                            | `false`     | Lay options out as a navigable grid instead of a list.                               |
| `value`             | `string`                                             | —           | Controlled input value. Pair with `onValueChange`.                                   |
| `defaultValue`      | `string`                                             | —           | Uncontrolled initial input value.                                                    |
| `onValueChange`     | <Code>(value, details) => void</Code>                | —           | Fires as the value changes (typing, selection, clear).                               |
| `itemToStringValue` | <Code>(item: T) => string</Code>                     | —           | Required for object items: how the filter and input read each one.                   |
| `mode`              | <Code>'list' \| 'inline' \| 'both' \| 'none'</Code>  | `'list'`    | Inline modes autofill the input with the highlighted item while navigating.          |

### AutocompleteInput [#autocompleteinput]

The text field. Renders Base UI's `Input` inside an `InputGroup`, styled like [`Input`](/ui/components/react/input).

| Prop          | Type        | Default | Description                                                    |
| ------------- | ----------- | ------- | -------------------------------------------------------------- |
| `startSlot`   | `ReactNode` | —       | Adornment rendered before the field, inside the input frame.   |
| `endSlot`     | `ReactNode` | —       | Adornment rendered after the field, inside the input frame.    |
| `placeholder` | `string`    | `' '`   | Placeholder text.                                              |
| `disabled`    | `boolean`   | `false` | Disables the field and the clear/chevron buttons.              |
| `className`   | `string`    | —       | Extra classes on the input group, merged via `tailwind-merge`. |

Also forwards every native `<input>` prop (`onChange`, `name`, `aria-*`, `ref`, …).

### AutocompleteContent [#autocompletecontent]

The portalled, auto-positioned popup wrapping the list. Accepts the shared floating props.

| Prop              | <ColMinWidth width="160">Type</ColMinWidth>         | Default    | Description                                                     |
| ----------------- | --------------------------------------------------- | ---------- | --------------------------------------------------------------- |
| `side`            | <Code>'top' \| 'right' \| 'bottom' \| 'left'</Code> | `'bottom'` | Preferred side of the input to open on.                         |
| `align`           | <Code>'start' \| 'center' \| 'end'</Code>           | —          | Alignment along that side.                                      |
| `sideOffset`      | `number`                                            | `6`        | Gap between the input and the popup.                            |
| `alignOffset`     | `number`                                            | —          | Shift along the alignment axis.                                 |
| `container`       | <Code>HTMLElement \| ref \| null</Code>             | —          | Portal target — render the popup into a different node.         |
| `keepMounted`     | `boolean`                                           | `false`    | Keep the popup mounted in the DOM while closed.                 |
| `positionerProps` | `object`                                            | —          | Escape hatch for the positioner element (`style`, `render`, …). |
| `portalProps`     | `object`                                            | —          | Escape hatch for the portal element (`style`, `render`, …).     |
| `className`       | `string`                                            | —          | Extra classes on the popup.                                     |

### AutocompleteList [#autocompletelist]

The scrollable list container.

| Prop       | <ColMinWidth width="220">Type</ColMinWidth>          | Default | Description                                                               |
| ---------- | ---------------------------------------------------- | ------- | ------------------------------------------------------------------------- |
| `cols`     | `number`                                             | —       | Items per row in grid mode (defaults to 2 when `grid` is set).            |
| `children` | <Code>ReactNode \| (item, index) => ReactNode</Code> | —       | A render function over the filtered items, or static `AutocompleteItem`s. |

### AutocompleteItem [#autocompleteitem]

One option in the list.

| Prop        | Type     | Default | Description                                             |
| ----------- | -------- | ------- | ------------------------------------------------------- |
| `value`     | `T`      | —       | The item this option represents; reported on selection. |
| `className` | `string` | —       | Extra classes (e.g. `flex-1` to fill a grid cell).      |

### AutocompleteEmpty [#autocompleteempty]

Shown only when the filter matches nothing — otherwise it renders nothing.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The empty-state message.                    |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### AutocompleteStatus [#autocompletestatus]

A persistent row that stays mounted (e.g. a loading or count message), unlike `AutocompleteEmpty`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The status message.                         |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### AutocompleteGroup [#autocompletegroup]

Wraps one labelled section of a grouped list.

| Prop        | Type           | Default | Description                                                            |
| ----------- | -------------- | ------- | ---------------------------------------------------------------------- |
| `items`     | `readonly T[]` | —       | The group's items, so the inner `AutocompleteCollection` can map them. |
| `className` | `string`       | —       | Extra classes, merged via `tailwind-merge`.                            |

### AutocompleteLabel [#autocompletelabel]

The visible label for an `AutocompleteGroup`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The label text.                             |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### AutocompleteCollection [#autocompletecollection]

Renders the items inside an `AutocompleteGroup`.

| Prop       | <ColMinWidth width="200">Type</ColMinWidth> | Default | Description                                                         |
| ---------- | ------------------------------------------- | ------- | ------------------------------------------------------------------- |
| `children` | <Code>(item, index) => ReactNode</Code>     | —       | Render function for each item — `(item) => <AutocompleteItem … />`. |

### AutocompleteSeparator [#autocompleteseparator]

A thin divider between sections.

| Prop        | Type     | Default | Description                                 |
| ----------- | -------- | ------- | ------------------------------------------- |
| `className` | `string` | —       | Extra classes, merged via `tailwind-merge`. |

### AutocompleteTrigger [#autocompletetrigger]

A standalone button that opens the popup (e.g. a tag picker that isn't a text field).

| Prop        | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | Description                                 |
| ----------- | ------------------------------------------------------------- | ------- | ------------------------------------------- |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Compose the trigger with another element.   |
| `className` | `string`                                                      | —       | Extra classes, merged via `tailwind-merge`. |

Also forwards every native `<button>` prop (`onClick`, `aria-*`, `ref`, …).

### AutocompleteValue [#autocompletevalue]

Renders the current value for read-only display.

| Prop       | <ColMinWidth width="200">Type</ColMinWidth>    | Default | Description                                        |
| ---------- | ---------------------------------------------- | ------- | -------------------------------------------------- |
| `children` | <Code>ReactNode \| (value) => ReactNode</Code> | —       | Static content, or a render function of the value. |

## Accessibility [#accessibility]

* The input has `role="combobox"`; the popup is a `listbox` (or `grid` when `grid` is set) and items are `option`/`gridcell`. Selection and active state are wired through `aria-activedescendant`.
* **↑/↓** move the highlight, **Enter** selects, **Escape** closes the popup, and typing filters the list.
* The clear and chevron buttons have `aria-label`s (`Clear selection`, `Toggle popup`) and become `disabled` when the input is disabled.
* Always give `AutocompleteInput` a visible label or an `aria-label`.
* Popup enter/exit transitions are wrapped so they're skipped when the user prefers reduced motion.


# Avatar (/ui/components/react/avatar)



<Playground component="avatar" />

## Usage [#usage]

```tsx
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
```

```tsx
<Avatar>
  <AvatarImage src="/avatars/01.jpg" alt="Sarah Jenkins" />
  <AvatarFallback>SJ</AvatarFallback>
</Avatar>
```

`Avatar` represents a person or entity. Compose it from its parts, all under `@appica/ui-react/avatar`:

* **`Avatar`** — the root that sets `size` and `shape` and clips its children to the rounded silhouette.
* **`AvatarImage`** — the photo. Base UI preloads the `src` and only swaps it in once it has loaded, so a broken or slow image never flashes.
* **`AvatarFallback`** — what shows until (or unless) the image loads: initials or an icon.
* **`AvatarBadge`** — an optional status dot in the corner.
* **`AvatarGroup`** — a wrapper that overlaps a row of avatars and forwards a shared `size`/`shape`.

The whole component is sized in `em`, so a single `size` (a preset or a pixel number) scales the image, fallback text, and status badge together.

## Examples [#examples]

### Default [#default]

An `AvatarImage` with an `AvatarFallback` beneath it. The image is shown once loaded; until then — or if it fails — the fallback initials take its place.

```tsx
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'

export default function AvatarDefault() {
  return (
    <Avatar size="lg">
      <AvatarImage src="/avatars/01.jpg" alt="Sarah Jenkins" />
      <AvatarFallback>SJ</AvatarFallback>
    </Avatar>
  )
}
```

### Fallback [#fallback]

When the image is missing, still loading, or fails to load, the `AvatarFallback` renders instead. Use initials for people, or an icon for a generic placeholder.

```tsx
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { UserFilled } from '@appica/icons-react'

export default function AvatarFallbackExample() {
  return (
    <div className="flex items-center gap-4">
      <Avatar size="lg">
        <AvatarImage src="/avatars/does-not-exist.jpg" alt="Sarah Jenkins" />
        <AvatarFallback>SJ</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>MR</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>
          <UserFilled />
        </AvatarFallback>
      </Avatar>
    </div>
  )
}
```

### Sizes [#sizes]

Seven presets run from `2xs` to `2xl`. Because the avatar is sized in `em`, the fallback text and status badge scale along with the image.

```tsx
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'

const sizes = ['2xs', 'xs', 'sm', 'md', 'lg', 'xl'] as const

export default function AvatarSizes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-4">
      {sizes.map((size) => (
        <Avatar key={size} size={size}>
          <AvatarImage src="/avatars/02.jpg" alt="Daniel Reyes" />
          <AvatarFallback>DR</AvatarFallback>
        </Avatar>
      ))}
    </div>
  )
}
```

### Custom size [#custom-size]

Pass a number to `size` for an exact pixel dimension when a preset doesn't fit — say to match a specific line height. It drives the root's `font-size`, so everything inside still scales proportionally.

```tsx
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'

export default function AvatarCustomSize() {
  return (
    <div className="flex items-center gap-4">
      <Avatar size={28}>
        <AvatarImage src="/avatars/04.jpg" alt="Ava Thompson" />
        <AvatarFallback>AT</AvatarFallback>
      </Avatar>
      <Avatar size={44}>
        <AvatarImage src="/avatars/04.jpg" alt="Ava Thompson" />
        <AvatarFallback>AT</AvatarFallback>
      </Avatar>
      <Avatar size={72}>
        <AvatarImage src="/avatars/04.jpg" alt="Ava Thompson" />
        <AvatarFallback>AT</AvatarFallback>
      </Avatar>
    </div>
  )
}
```

### Shape [#shape]

`shape="circle"` (the default) renders a full circle; `shape="rounded"` uses a squircle-style rounded square for a more app-like look.

```tsx
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'

export default function AvatarShape() {
  return (
    <div className="flex items-center gap-4">
      <Avatar size="lg" shape="circle">
        <AvatarImage src="/avatars/03.jpg" alt="Mateo Rossi" />
        <AvatarFallback>MR</AvatarFallback>
      </Avatar>
      <Avatar size="lg" shape="rounded">
        <AvatarImage src="/avatars/03.jpg" alt="Mateo Rossi" />
        <AvatarFallback>MR</AvatarFallback>
      </Avatar>
    </div>
  )
}
```

### Status badge [#status-badge]

Drop an `AvatarBadge` inside the avatar for a corner status dot. Add `animate` for a gentle pulsing ping that draws the eye to an online indicator, and recolor it with a `text-*` class.

```tsx
import { Avatar, AvatarImage, AvatarFallback, AvatarBadge } from '@appica/ui-react/avatar'

export default function AvatarStatus() {
  return (
    <div className="flex items-center gap-4">
      <Avatar size="lg">
        <AvatarImage src="/avatars/08.jpg" alt="Liam Hudson" />
        <AvatarFallback>LH</AvatarFallback>
        <AvatarBadge />
      </Avatar>
      <Avatar size="lg">
        <AvatarImage src="/avatars/09.jpg" alt="Emma Garcia" />
        <AvatarFallback>EG</AvatarFallback>
        <AvatarBadge animate />
      </Avatar>
      <Avatar size="lg">
        <AvatarImage src="/avatars/06.jpg" alt="Lucas Müller" />
        <AvatarFallback>LM</AvatarFallback>
        <AvatarBadge className="text-foreground-subtle" />
      </Avatar>
    </div>
  )
}
```

### Avatar group [#avatar-group]

`AvatarGroup` overlaps a row of avatars and rings each one with the background color so they read as a stack. It forwards a shared `size`/`shape` to its children, and any non-image avatar — like a `+5` counter — sits in the same rhythm.

```tsx
import { Avatar, AvatarImage, AvatarFallback, AvatarGroup } from '@appica/ui-react/avatar'

const people = [
  { src: '/avatars/01.jpg', alt: 'Sarah Jenkins', initials: 'SJ' },
  { src: '/avatars/02.jpg', alt: 'Liam Hudson', initials: 'LH' },
  { src: '/avatars/03.jpg', alt: 'Mateo Rossi', initials: 'MR' },
  { src: '/avatars/04.jpg', alt: 'Ava Thompson', initials: 'AT' },
]

export default function AvatarGroupExample() {
  return (
    <AvatarGroup size="md">
      {people.map((person) => (
        <Avatar key={person.src}>
          <AvatarImage src={person.src} alt={person.alt} />
          <AvatarFallback>{person.initials}</AvatarFallback>
        </Avatar>
      ))}
      <Avatar>
        <AvatarFallback className="text-foreground-muted text-sm">+5</AvatarFallback>
      </Avatar>
    </AvatarGroup>
  )
}
```

### Next.js Image [#nextjs-image]

To serve optimized images, pass a Next.js `<Image>` to `AvatarImage`'s `render` prop. The wrapper lifts the `src` so Base UI's preloader still drives the fallback, and applies its own `object-cover` and rounded-corner classes to the rendered `<Image>`. Give the `Image` a `width`/`height` that matches the avatar's pixel size.

```tsx
import Image from 'next/image'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'

export default function AvatarNextImage() {
  return (
    <Avatar size="xl">
      <AvatarImage render={<Image src="/avatars/08.jpg" alt="Liam Hudson" width={64} height={64} />} />
      <AvatarFallback>LH</AvatarFallback>
    </Avatar>
  )
}
```

### Loading animation [#loading-animation]

`AvatarFallback` renders until the image finishes loading, so dropping a [`Skeleton`](/ui/components/react/skeleton) inside it gives a shimmering placeholder that Base UI swaps for the photo automatically — no extra state needed. Press **Reload** to fetch a fresh copy and watch it again.

```tsx
'use client'

import { useState, useEffect } from 'react'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { Skeleton } from '@appica/ui-react/skeleton'
import { Button } from '@appica/ui-react/button'

export default function AvatarLoading() {
  const [src, setSrc] = useState<string>()
  const [nonce, setNonce] = useState(0)

  useEffect(() => {
    setSrc(undefined)
    // Demo only: defer the image ~2.5s so the loading skeleton stays visible.
    const id = setTimeout(() => setSrc(`/avatars/09.jpg?reload=${nonce}`), 2500)
    return () => clearTimeout(id)
  }, [nonce])

  return (
    <div className="flex flex-col items-center gap-4">
      <Avatar size="xl" className="bg-transparent">
        <AvatarImage src={src} alt="Emma Garcia" />
        <AvatarFallback>
          <Skeleton className="size-full rounded-[inherit]" />
        </AvatarFallback>
      </Avatar>
      <Button variant="outline" size="sm" onClick={() => setNonce((n) => n + 1)} disabled={!src}>
        Reload
      </Button>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The status badge moves to the start (right) corner and the group stacks from the right, because both are expressed with logical properties. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="avatar" />

## API reference [#api-reference]

`Avatar` wraps [Base UI's Avatar](https://base-ui.com/react/components/avatar). Each part forwards `ref` and its remaining attributes to the matching Base UI primitive — `AvatarImage` preloads `src` and only mounts the image once it resolves. `AvatarBadge` and `AvatarGroup` are Appica additions. See the Base UI docs for the complete API.

### Avatar [#avatar]

The root. Renders a `<span>` that sizes and clips its children.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth>                                   | Default    | <ColMinWidth width="220">Description</ColMinWidth>              |
| ----------- | ----------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------- |
| `size`      | <Code>'2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| number</Code> | `'md'`     | A preset scale, or a pixel number for an exact size.            |
| `shape`     | <Code>'circle' \| 'rounded'</Code>                                            | `'circle'` | Full circle or rounded square.                                  |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code>                 | —          | Replace the root element, or compose it with another component. |
| `className` | `string`                                                                      | —          | Extra classes, merged via `tailwind-merge`.                     |

### AvatarImage [#avatarimage]

The photo. Renders an `<img>` (or the `render` element) once the source has loaded.

| Prop                    | <ColMinWidth width="200">Type</ColMinWidth>                               | Default | <ColMinWidth width="220">Description</ColMinWidth>               |
| ----------------------- | ------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `src`                   | `string`                                                                  | —       | Image URL. Lifted from the `render` element when omitted.        |
| `alt`                   | `string`                                                                  | —       | Alternative text describing the person/entity.                   |
| `onLoadingStatusChange` | <Code>(status: 'idle' \| 'loading' \| 'loaded' \| 'error') => void</Code> | —       | Fires as the image moves through its loading lifecycle.          |
| `render`                | <Code>ReactElement \| ((props, state) => ReactElement)</Code>             | —       | Swap the `<img>` for another element — e.g. a Next.js `<Image>`. |
| `className`             | `string`                                                                  | —       | Extra classes, merged via `tailwind-merge`.                      |

### AvatarFallback [#avatarfallback]

Shown until — or unless — the image loads. Renders a `<span>`.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>                               |
| ----------- | ------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------- |
| `delay`     | `number`                                                      | —       | Milliseconds to wait before showing the fallback (avoids a flash on fast loads). |
| `children`  | `ReactNode`                                                   | —       | Initials or an icon. Text is auto-shrunk; an `svg` is shown at full size.        |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the fallback element.                                                    |
| `className` | `string`                                                      | —       | Extra classes, merged via `tailwind-merge`.                                      |

### AvatarBadge [#avatarbadge]

An optional status dot in the corner. Renders a `<span>`.

| Prop        | Type      | Default | Description                                                       |
| ----------- | --------- | ------- | ----------------------------------------------------------------- |
| `animate`   | `boolean` | `false` | Add a pulsing ping behind the dot (skipped under reduced motion). |
| `className` | `string`  | —       | Extra classes — recolor with a `text-*` class.                    |

### AvatarGroup [#avatargroup]

Overlaps a row of avatars and forwards a shared size/shape. Renders a `<div>`.

| Prop          | <ColMinWidth width="200">Type</ColMinWidth> | Default        | <ColMinWidth width="220">Description</ColMinWidth>               |
| ------------- | ------------------------------------------- | -------------- | ---------------------------------------------------------------- |
| `size`        | `Avatar['size']`                            | —              | Default size applied to child avatars that don't set their own.  |
| `shape`       | `Avatar['shape']`                           | —              | Default shape applied to child avatars that don't set their own. |
| `orientation` | <Code>'horizontal' \| 'vertical'</Code>     | `'horizontal'` | Stack the avatars in a row or a column.                          |
| `className`   | `string`                                    | —              | Extra classes, merged via `tailwind-merge`.                      |

A child `Avatar`'s own `size`/`shape` always wins over the group default.

## Accessibility [#accessibility]

* Give every meaningful `AvatarImage` an `alt` that names the person or entity. For a purely decorative avatar, use `alt=""`.
* The `AvatarFallback` text (initials) is visible content, so it's announced; for an icon-only fallback, the icon is decorative — make sure the surrounding context names the user.
* `AvatarBadge` is a visual status indicator. If the status is important, convey it in text nearby (e.g. "Online") rather than relying on the dot's color alone.
* In an `AvatarGroup`, each avatar keeps its own accessible name; consider an `aria-label` on the group (e.g. "Project members") and visible text for any `+N` overflow count.
* The status badge's pulsing animation is skipped when the user prefers reduced motion.


# Background Pattern (/ui/components/react/background-pattern)



<Playground component="background-pattern" />

## Usage [#usage]

```tsx
import { BackgroundPattern } from '@appica/ui-react/background-pattern'
```

```tsx
<BackgroundPattern>
  <YourContent />
</BackgroundPattern>
```

`BackgroundPattern` is a `<div>` wrapper that paints a subtle, masked pattern behind its `children`.
Pick a texture with the `variant` prop — `dots` (the default), `grid`, `dashed-grid`, or `hexagons` —
and tune its density with `cellSize`. The pattern is drawn from the `--pattern-color` CSS variable
(defaulting to the `--color-border-intense` token) via `currentColor` masks, so it stays muted against
either light or dark surfaces; override that variable to [recolor it](#custom-color).

Enable `spotlight` to add a radial highlight that follows the cursor and brightens the pattern nearby;
pass `true` for the default, a number/length to size it, or `{ persistent: true }` to keep it always
on. The decorative layers are `aria-hidden`, so they never interfere with assistive tech — your
`children` remain fully accessible, and the wrapper accepts `className`, `style`, and any native
`<div>` attributes.

## Examples [#examples]

### Variants [#variants]

Four textures cover the common cases: scattered `dots`, a ruled `grid`, a finer `dashed-grid`, and a
`hexagons` mesh. Each carries a sensible default cell size, drawn at low opacity so content stays
legible.

```tsx
import { BackgroundPattern } from '@appica/ui-react/background-pattern'

const variants = ['dots', 'grid', 'dashed-grid', 'hexagons'] as const

export default function BackgroundPatternVariants() {
  return (
    <div className="grid w-full max-w-2xl grid-cols-1 gap-4 sm:grid-cols-2">
      {variants.map((variant) => (
        <BackgroundPattern
          key={variant}
          variant={variant}
          className="bg-background-subtle flex min-h-40 items-center justify-center overflow-hidden rounded-xl"
        >
          <span className="text-foreground-intense text-sm font-medium capitalize">{variant.replace('-', ' ')}</span>
        </BackgroundPattern>
      ))}
    </div>
  )
}
```

### Spotlight [#spotlight]

Set `spotlight` to add a cursor-following highlight that brightens the pattern near the pointer and
fades out when the cursor stops. Move your cursor over the panel to see it react.

```tsx
import { BackgroundPattern } from '@appica/ui-react/background-pattern'

export default function BackgroundPatternSpotlight() {
  return (
    <BackgroundPattern
      variant="dots"
      spotlight
      className="bg-background-subtle flex min-h-56 w-full max-w-xl items-center justify-center overflow-hidden rounded-xl"
    >
      <span className="text-foreground-intense text-sm font-medium">Move your cursor over the panel</span>
    </BackgroundPattern>
  )
}
```

### Persistent / sized spotlight [#persistent--sized-spotlight]

Pass an object to keep the highlight always on with `{ persistent: true }` and size it with `size`
(a number in px, or any CSS length). A persistent spotlight skips the fade entirely.

```tsx
import { BackgroundPattern } from '@appica/ui-react/background-pattern'

export default function BackgroundPatternPersistentSpotlight() {
  return (
    <BackgroundPattern
      variant="dashed-grid"
      spotlight={{ persistent: true, size: 150 }}
      className="bg-background-subtle flex min-h-56 w-full max-w-xl items-center justify-center overflow-hidden rounded-xl"
    >
      <span className="text-foreground-intense text-sm font-medium">Always-on highlight</span>
    </BackgroundPattern>
  )
}
```

### Custom cell size [#custom-cell-size]

`cellSize` overrides the per-variant default to make the texture denser or airier. Here the same
`grid` variant is shown at two scales.

```tsx
import { BackgroundPattern } from '@appica/ui-react/background-pattern'

export default function BackgroundPatternCellSize() {
  return (
    <div className="grid w-full max-w-2xl grid-cols-1 gap-4 sm:grid-cols-2">
      <BackgroundPattern
        variant="grid"
        cellSize={16}
        className="bg-background-subtle flex min-h-48 items-center justify-center overflow-hidden rounded-xl"
      >
        <span className="text-foreground-intense text-sm font-medium">cellSize 16</span>
      </BackgroundPattern>
      <BackgroundPattern
        variant="grid"
        cellSize={40}
        className="bg-background-subtle flex min-h-48 items-center justify-center overflow-hidden rounded-xl"
      >
        <span className="text-foreground-intense text-sm font-medium">cellSize 40</span>
      </BackgroundPattern>
    </div>
  )
}
```

### Custom color [#custom-color]

The pattern reads its color from the `--pattern-color` CSS variable, which defaults to the muted
`--color-border-intense` token. Set it to recolor the texture — point it at a theme token like
`var(--primary)`, or drop in any custom value. Here a bluish-purple hex tints the pattern and its
spotlight, paired with a matching surface mixed from the same hue and `var(--background)` via
`color-mix`, so the wash stays subtle in both light and dark mode.

```tsx
import { BackgroundPattern } from '@appica/ui-react/background-pattern'

export default function BackgroundPatternCustomColor() {
  return (
    <BackgroundPattern
      variant="hexagons"
      spotlight
      className="flex min-h-56 w-full max-w-xl items-center justify-center overflow-hidden rounded-xl bg-[color-mix(in_oklab,#7c6cf6_8%,var(--background))] [--pattern-color:#7c6cf6]"
    >
      <span className="text-foreground-intense text-sm font-medium">Tinted with a custom color</span>
    </BackgroundPattern>
  )
}
```

## API reference [#api-reference]

| Prop        | <ColMinWidth width="200">Type</ColMinWidth>                            | Default  | <ColMinWidth width="220">Description</ColMinWidth>                                                                                                             |
| ----------- | ---------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `variant`   | <Code>'dots' \| 'grid' \| 'dashed-grid' \| 'hexagons'</Code>           | `'dots'` | Pattern texture painted behind the content.                                                                                                                    |
| `spotlight` | <Code>boolean \| number \| string \| {'{ size?, persistent? }'}</Code> | `false`  | Cursor-following highlight. `true` for a 200px fading highlight; a number/length sizes it; an object with `persistent: true` keeps it always on.               |
| `cellSize`  | `number`                                                               | —        | Cell size in px; overrides the per-variant default (dots 14, grid/dashed-grid 28, hexagons 40).                                                                |
| `track`     | <Code>'self' \| 'window'</Code>                                        | `'self'` | Where the spotlight reads pointer movement. `'self'` tracks over this element; `'window'` tracks anywhere — for a pattern positioned behind unrelated content. |
| `className` | `string`                                                               | —        | Extra classes, merged via `tailwind-merge`.                                                                                                                    |
| `style`     | `CSSProperties`                                                        | —        | Inline styles on the wrapper.                                                                                                                                  |

`BackgroundPattern` renders a `<div>` and forwards every remaining native `<div>` attribute. The
decorative pattern and spotlight layers are `aria-hidden`. Set the `--pattern-color` CSS variable (via
`className` or `style`) to recolor the texture — see [Custom color](#custom-color).

## Accessibility [#accessibility]

* The pattern and spotlight layers are `aria-hidden` and `pointer-events-none`, so they're skipped by
  assistive tech and never intercept clicks.
* Content is wrapped, not replaced — your `children` stay in the normal flow and fully accessible.
* The pattern is intentionally low-emphasis; ensure your foreground content keeps sufficient contrast
  against the background for it to stay readable.
* The cursor spotlight honours `prefers-reduced-motion` — it's forced persistent (fade-free) when a
  user requests reduced motion.


# Badge (/ui/components/react/badge)



<Playground component="badge" />

## Usage [#usage]

```tsx
import { Badge } from '@appica/ui-react/badge'
```

```tsx
<Badge variant="success">Active</Badge>
```

`Badge` is a compact, non-interactive label for a piece of metadata — a status, a count, a tag, a category. It renders a `<span>` by default and sizes to its content. Pick a `variant` for the color scheme and a `size` for the scale; drop an icon next to the text and mark it with `data-icon="start"` / `data-icon="end"` so the padding tightens on that side.

To make a badge clickable — a filter chip, a category link — pass a `render` element (an `<a>` or `<button>`). The badge then becomes focusable and gains hover/press affordances automatically. For a user-removable token with a built-in dismiss control, reach for [`Chip`](/ui/components/react/chip) instead.

## Examples [#examples]

### Default [#default]

A single `Badge` with text children uses the `primary` variant at the `md` size.

```tsx
import { Badge } from '@appica/ui-react/badge'

export default function BadgeDefault() {
  return <Badge>Badge</Badge>
}
```

### Variants [#variants]

Each `variant` carries a semantic color. The solid `primary`/`secondary` and tinted `error`/`success`/`warning`/`info` schemes draw attention to a status, while `soft`, `outline`, and `primary-outline` stay quieter for neutral metadata.

```tsx
import { Badge } from '@appica/ui-react/badge'

export default function BadgeVariants() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <Badge variant="primary">Primary</Badge>
      <Badge variant="primary-outline">Primary outline</Badge>
      <Badge variant="secondary">Secondary</Badge>
      <Badge variant="soft">Soft</Badge>
      <Badge variant="outline">Outline</Badge>
      <Badge variant="error">Error</Badge>
      <Badge variant="success">Success</Badge>
      <Badge variant="warning">Warning</Badge>
      <Badge variant="info">Info</Badge>
    </div>
  )
}
```

### On dark backgrounds [#on-dark-backgrounds]

The `light` variant is built for dark or photographic backgrounds — a translucent white fill that reads against the surface beneath it.

```tsx
import { Badge } from '@appica/ui-react/badge'
import { Crown } from '@appica/icons-react'

export default function BadgeOnDark() {
  return (
    <div className="relative flex h-44 w-full max-w-66 items-end justify-start overflow-hidden rounded-xl">
      <img src="/thumbnail.jpg" alt="" className="absolute inset-0 size-full object-cover" />
      <div className="absolute inset-0 bg-linear-to-t from-black/25 via-transparent to-transparent" />
      <Badge variant="light" className="relative m-3">
        <Crown data-icon="start" />
        Premium
      </Badge>
    </div>
  )
}
```

### Sizes [#sizes]

Four sizes scale the badge from `xs` to `lg`. The text and any icons scale together.

```tsx
import { Badge } from '@appica/ui-react/badge'

export default function BadgeSizes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <Badge size="xs">Extra small</Badge>
      <Badge size="sm">Small</Badge>
      <Badge size="md">Medium</Badge>
      <Badge size="lg">Large</Badge>
    </div>
  )
}
```

### With an icon [#with-an-icon]

Place an icon before or after the text and tag it with `data-icon="start"` or `data-icon="end"` — the badge tightens the padding on that edge so the icon sits snug.

```tsx
import { Badge } from '@appica/ui-react/badge'
import { Check, Flame, BellRinging } from '@appica/icons-react'

export default function BadgeWithIcon() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <Badge variant="success">
        <Check data-icon="start" />
        Verified
      </Badge>
      <Badge variant="warning">
        <Flame data-icon="start" />
        Hot
      </Badge>
      <Badge variant="soft">
        Notification
        <BellRinging data-icon="end" />
      </Badge>
    </div>
  )
}
```

### Icon only [#icon-only]

The `icon-sm`, `icon-md`, and `icon-lg` sizes render a square badge for a lone icon. Give it an `aria-label` so the meaning is announced.

```tsx
import { Badge } from '@appica/ui-react/badge'
import { Check, Star, Bolt } from '@appica/icons-react'

export default function BadgeIconOnly() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <Badge variant="success" size="icon-sm" aria-label="Verified">
        <Check />
      </Badge>
      <Badge variant="primary-outline" size="icon-md" aria-label="Featured">
        <Star />
      </Badge>
      <Badge variant="warning" size="icon-lg" aria-label="Boosted">
        <Bolt />
      </Badge>
    </div>
  )
}
```

### Notification count [#notification-count]

Absolutely position a small badge against an icon button to surface an unread count. Keep the number in the badge and the count in its `aria-label`.

```tsx
import { Badge } from '@appica/ui-react/badge'
import { Button } from '@appica/ui-react/button'
import { Bell } from '@appica/icons-react'

export default function BadgeNotification() {
  return (
    <div className="relative inline-flex">
      <Button variant="outline" size="icon-md" aria-label="Notifications">
        <Bell />
      </Button>
      <Badge
        variant="secondary"
        size="xs"
        className="absolute -inset-e-1.5 -top-1.5 min-w-4 px-1 font-medium"
        aria-label="3 unread notifications"
      >
        3
      </Badge>
    </div>
  )
}
```

### Interactive (link or button) [#interactive-link-or-button]

Pass a `render` element to turn the badge into a link — a plain `<a>` or a framework one like a Next.js `<Link>` — or a `<button>`. It becomes focusable and animates on hover and press.

```tsx
'use client'

import { useState } from 'react'
import Link from 'next/link'
import { Badge } from '@appica/ui-react/badge'

export default function BadgeInteractive() {
  const [following, setFollowing] = useState(false)

  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <Badge variant="soft" render={<a href="#design" />}>
        Design
      </Badge>
      <Badge variant="outline" render={<Link href="#trending" />}>
        Trending
      </Badge>
      <Badge
        variant={following ? 'primary' : 'primary-outline'}
        render={<button type="button" onClick={() => setFollowing((value) => !value)} />}
      >
        {following ? 'Following' : 'Follow'}
      </Badge>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The icon flips to the start (right) edge and the tightened padding follows, because both are expressed with logical properties. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="badge" />

## API reference [#api-reference]

`Badge` is built on Base UI's [`useRender`](https://base-ui.com/react/utils/use-render) and renders a `<span>` by default. Pass a `render` element to swap the underlying tag (e.g. an `<a>` or `<button>`), which also makes it focusable and interactive; `render` and its `state` (`{ variant, size }`) follow Base UI's render conventions. Every other `<span>` (or the rendered element's) attribute is forwarded.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth>                                                                                                 | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `variant`   | <Code>'primary' \| 'primary-outline' \| 'secondary' \| 'soft' \| 'outline' \| 'error' \| 'success' \| 'warning' \| 'info' \| 'light'</Code> | `'primary'` | Color scheme.                                                                              |
| `size`      | <Code>'xs' \| 'sm' \| 'md' \| 'lg' \| 'icon-sm' \| 'icon-md' \| 'icon-lg'</Code>                                                            | `'md'`      | Scale. The `icon-*` sizes render a square badge for a lone icon.                           |
| `children`  | `ReactNode`                                                                                                                                 | —           | The label content. Tag an icon with `data-icon="start"`/`"end"` to tighten that edge.      |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code>                                                                               | —           | Replace the `<span>` with another element. Doing so makes the badge focusable/interactive. |
| `className` | `string`                                                                                                                                    | —           | Extra classes, merged via `tailwind-merge`.                                                |

## Accessibility [#accessibility]

* A plain `Badge` is a `<span>` — purely visual. Don't rely on color alone to convey meaning; back it with text (e.g. "Active", not just a green badge).
* For an **icon-only** badge, supply an `aria-label` so the icon's meaning is announced.
* For a **count** badge, keep the visible number short and put the full meaning in `aria-label` (e.g. `"3 unread notifications"`).
* When you make a badge interactive via `render`, render a real `<a>` or `<button>` so it's keyboard-focusable and announced with the correct role; the badge applies focusable styling automatically.
* Hover/press transitions are skipped when the user prefers reduced motion.


# Breadcrumb (/ui/components/react/breadcrumb)



<Playground component="breadcrumb" />

## Usage [#usage]

```tsx
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
  BreadcrumbEllipsis,
} from '@appica/ui-react/breadcrumb'
```

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/ui/components">Components</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink active>Breadcrumb</BreadcrumbLink>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

`Breadcrumb` is a small set of semantic primitives — there's no hidden state, so you lay the trail out yourself. Every part lives under `@appica/ui-react/breadcrumb`:

* **`Breadcrumb`** — the `<nav aria-label="breadcrumb">` landmark that wraps the trail.
* **`BreadcrumbList`** — the ordered list (`<ol>`) of crumbs; handles wrapping and spacing.
* **`BreadcrumbItem`** — one `<li>`, holding a link (or a collapsed menu).
* **`BreadcrumbLink`** — a crumb. By default it renders an `<a>`; mark the current page with `active` and it becomes a non-interactive `<span>` with `aria-current="page"`.
* **`BreadcrumbSeparator`** — the divider between crumbs (a chevron by default; pass `children` to override).
* **`BreadcrumbEllipsis`** — a "…" placeholder for crumbs collapsed out of a long trail.

`BreadcrumbLink` uses Base UI's [`useRender`](https://base-ui.com/react/utils/use-render), so you can project it onto your router's link with `render` — e.g. a Next.js [`Link`](https://nextjs.org/docs/app/api-reference/components/link) — without losing the styling or the active state.

Reach for a `Breadcrumb` to show **where the current page sits** in a hierarchy. For switching between sibling views, use [`Navigation`](/ui/components/react/navigation) or [`Tabs`](/ui/components/react/tabs); for a menu of links opened from a button, use a [`Dropdown Menu`](/ui/components/react/dropdown-menu).

## Examples [#examples]

### Basic [#basic]

A trail of links ending in the current page. Give every link before the last an `href`; mark the final crumb `active` so it renders as plain, non-focusable text with `aria-current="page"`.

```tsx
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
} from '@appica/ui-react/breadcrumb'

export default function BreadcrumbBasic() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#!">Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#!">Components</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink active>Breadcrumb</BreadcrumbLink>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

### With icons [#with-icons]

Drop an icon straight inside a `BreadcrumbLink` — it's sized and spaced automatically next to the label. A leading [icon](/ui/icons) on the Home crumb is a common space-saver.

```tsx
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
} from '@appica/ui-react/breadcrumb'
import { Home, Folder, FileText } from '@appica/icons-react'

export default function BreadcrumbIcons() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#!">
            <Home />
            Home
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#!">
            <Folder />
            Projects
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink active>
            <FileText />
            Roadmap
          </BreadcrumbLink>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

### Custom separators [#custom-separators]

`BreadcrumbSeparator` renders a chevron by default. Pass it `children` to swap in anything — a slash, a dot, or your own [icon](/ui/icons). The separator is decorative (`aria-hidden`), so it's skipped by screen readers.

```tsx
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
} from '@appica/ui-react/breadcrumb'

export default function BreadcrumbSeparators() {
  return (
    <div className="flex flex-col gap-5">
      <Breadcrumb>
        <BreadcrumbList>
          <BreadcrumbItem>
            <BreadcrumbLink href="#!">Home</BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator>/</BreadcrumbSeparator>
          <BreadcrumbItem>
            <BreadcrumbLink href="#!">Docs</BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator>/</BreadcrumbSeparator>
          <BreadcrumbItem>
            <BreadcrumbLink active>Breadcrumb</BreadcrumbLink>
          </BreadcrumbItem>
        </BreadcrumbList>
      </Breadcrumb>

      <Breadcrumb>
        <BreadcrumbList>
          <BreadcrumbItem>
            <BreadcrumbLink href="#!">Home</BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator>
            <span className="bg-foreground-muted size-0.75 rounded-full" />
          </BreadcrumbSeparator>
          <BreadcrumbItem>
            <BreadcrumbLink href="#!">Docs</BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator>
            <span className="bg-foreground-muted size-0.75 rounded-full" />
          </BreadcrumbSeparator>
          <BreadcrumbItem>
            <BreadcrumbLink active>Breadcrumb</BreadcrumbLink>
          </BreadcrumbItem>
        </BreadcrumbList>
      </Breadcrumb>
    </div>
  )
}
```

### Soft badges [#soft-badges]

Project each `BreadcrumbLink` onto a soft [`Badge`](/ui/components/react/badge) with `render` for a pill-style trail. The Badge's `soft` variant has built-in breadcrumb support — idle crumbs render muted like a plain link, brighten on hover, and the `active` crumb gains a bordered, filled pill. Project the Badge onto an `<a>` (`render={<a />}`) so the hover background animates.

```tsx
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
} from '@appica/ui-react/breadcrumb'
import { Badge } from '@appica/ui-react/badge'
import { Home, Components } from '@appica/icons-react'

export default function BreadcrumbBadges() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#!" render={<Badge variant="soft" render={<a />} />}>
            <Home data-icon="start" />
            Home
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#!" render={<Badge variant="soft" render={<a />} />}>
            <Components data-icon="start" />
            Library
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink active render={<Badge variant="soft" />}>
            <Components data-icon="start" />
            Component
          </BreadcrumbLink>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

### Collapsed trail [#collapsed-trail]

When a trail is too long, collapse the middle crumbs behind a menu. Wrap a [`Dropdown Menu`](/ui/components/react/dropdown-menu) in the `BreadcrumbItem`, project the trigger onto the `BreadcrumbEllipsis`, and list the hidden pages as `DropdownMenuLinkItem`s. The ellipsis carries an `sr-only` "More" label, so the trigger stays named for assistive tech.

```tsx
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
  BreadcrumbEllipsis,
} from '@appica/ui-react/breadcrumb'
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuLinkItem,
} from '@appica/ui-react/dropdown-menu'

export default function BreadcrumbCollapsed() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#!">Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <DropdownMenu>
            <DropdownMenuTrigger className="text-foreground-muted hover:text-foreground-intense outline-ring hover:bg-background-muted data-popup-open:bg-background-muted data-popup-open:text-foreground-intense rounded-2xs flex size-6 items-center justify-center transition">
              <BreadcrumbEllipsis />
            </DropdownMenuTrigger>
            <DropdownMenuContent align="start">
              <DropdownMenuLinkItem href="#!">Documentation</DropdownMenuLinkItem>
              <DropdownMenuLinkItem href="#!">Components</DropdownMenuLinkItem>
              <DropdownMenuLinkItem href="#!">Themes</DropdownMenuLinkItem>
            </DropdownMenuContent>
          </DropdownMenu>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#!">Breadcrumb</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink active>Collapsed</BreadcrumbLink>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

### Router links [#router-links]

For client-side routing, project a `BreadcrumbLink` onto your framework's link via `render` — here a Next.js [`Link`](https://nextjs.org/docs/app/api-reference/components/link). The crumb keeps its styling and `aria-current` handling while the router owns navigation.

```tsx
import Link from 'next/link'
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
} from '@appica/ui-react/breadcrumb'

export default function BreadcrumbLinks() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink render={<Link href="/ui/components/react/breadcrumb" />}>Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink render={<Link href="/ui/components/react/breadcrumb" />}>Components</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink active>Breadcrumb</BreadcrumbLink>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The trail flows from the right and the default chevron separator mirrors to point the other way. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="breadcrumb" />

## API reference [#api-reference]

Breadcrumb is a set of styled HTML elements. Each part forwards every remaining prop to its underlying element (`nav`, `ol`, `li`, `a`, `span`), so any native attribute works here — the tables below list the Appica additions and the most common props.

### Breadcrumb [#breadcrumb]

The navigation landmark. Renders a `<nav aria-label="breadcrumb">`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | A single `BreadcrumbList`.                  |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### BreadcrumbList [#breadcrumblist]

The ordered list of crumbs. Renders an `<ol>` that wraps and spaces its items.

| Prop        | Type        | Default | Description                                   |
| ----------- | ----------- | ------- | --------------------------------------------- |
| `children`  | `ReactNode` | —       | `BreadcrumbItem`s and `BreadcrumbSeparator`s. |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`.   |

### BreadcrumbItem [#breadcrumbitem]

One crumb's `<li>` wrapper.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | A `BreadcrumbLink`, ellipsis, or menu.      |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### BreadcrumbLink [#breadcrumblink]

A crumb link. Built on Base UI's [`useRender`](https://base-ui.com/react/utils/use-render); renders an `<a>` unless `active` (then a `<span>`), or use `render` to project it onto another element.

| Prop        | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                                                           |
| ----------- | ----------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `active`    | `boolean`                                                   | `false` | Mark the current page. Renders a non-interactive `<span>` with `aria-current="page"`. |
| `disabled`  | `boolean`                                                   | `false` | Make the link non-interactive and dimmed.                                             |
| `render`    | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render as your own element (e.g. a router `Link`).                                    |
| `href`      | `string`                                                    | —       | Navigation target (when rendered as an `<a>`).                                        |
| `className` | `string`                                                    | —       | Extra classes, merged via `tailwind-merge`.                                           |

### BreadcrumbSeparator [#breadcrumbseparator]

The divider between crumbs. Decorative (`aria-hidden`); renders a chevron unless you pass `children`.

| Prop        | Type        | Default      | Description                                        |
| ----------- | ----------- | ------------ | -------------------------------------------------- |
| `children`  | `ReactNode` | chevron icon | Override the separator with your own text or icon. |
| `className` | `string`    | —            | Extra classes, merged via `tailwind-merge`.        |

### BreadcrumbEllipsis [#breadcrumbellipsis]

A "…" placeholder for collapsed crumbs. Decorative, with an `sr-only` "More" label.

| Prop        | Type        | Default       | Description                                 |
| ----------- | ----------- | ------------- | ------------------------------------------- |
| `children`  | `ReactNode` | ellipsis dots | Override the placeholder mark.              |
| `className` | `string`    | —             | Extra classes, merged via `tailwind-merge`. |

## Accessibility [#accessibility]

* `Breadcrumb` renders a `<nav>` with `aria-label="breadcrumb"`, so it's exposed as a named navigation landmark.
* The current page (`active`) is a `<span>` with `aria-current="page"` — not a link — so it isn't announced as clickable.
* Separators and the ellipsis are `aria-hidden`/`role="presentation"`; the ellipsis keeps an `sr-only` "More" label for the collapse trigger.
* `disabled` links set `aria-disabled` and drop out of the tab order.
* Crumbs are keyboard-focusable links by default and inherit the page's focus-ring styling.


# Button Group (/ui/components/react/button-group)



<Playground component="button-group" />

## Usage [#usage]

```tsx
import { ButtonGroup } from '@appica/ui-react/button-group'
import { Button } from '@appica/ui-react/button'
```

```tsx
<ButtonGroup variant="outline">
  <Button>Years</Button>
  <Button>Months</Button>
  <Button>Days</Button>
</ButtonGroup>
```

`ButtonGroup` is a thin wrapper around your existing [`Button`](/ui/components/react/button)s. It collapses the inner corners and borders into one seamless control and shares `variant`, `size`, and `disabled` with every child through React context — so you set them once on the group instead of repeating them on each button.

## Examples [#examples]

### Variants [#variants]

Set `variant` on the group and every [`Button`](/ui/components/react/button) inherits it. Outlined variants (`outline`, `primary-outline`, `light`) overlap their shared borders so the seam stays a single hairline.

```tsx
import { ButtonGroup } from '@appica/ui-react/button-group'
import { Button } from '@appica/ui-react/button'

const variants = ['primary', 'primary-outline', 'secondary', 'soft', 'outline', 'destructive'] as const

export default function ButtonGroupVariants() {
  return (
    <div className="flex flex-col items-center gap-4">
      {variants.map((variant) => (
        <ButtonGroup key={variant} variant={variant}>
          <Button>Years</Button>
          <Button>Months</Button>
          <Button>Days</Button>
        </ButtonGroup>
      ))}
    </div>
  )
}
```

### Sizes [#sizes]

`size` cascades to the children too. Use it to scale the whole control at once.

```tsx
import { ButtonGroup } from '@appica/ui-react/button-group'
import { Button } from '@appica/ui-react/button'

const sizes = ['sm', 'md', 'lg'] as const

export default function ButtonGroupSizes() {
  return (
    <div className="flex flex-col items-center gap-4">
      {sizes.map((size) => (
        <ButtonGroup key={size} size={size} variant="outline">
          <Button>Left</Button>
          <Button>Center</Button>
          <Button>Right</Button>
        </ButtonGroup>
      ))}
    </div>
  )
}
```

### Vertical orientation [#vertical-orientation]

Set `orientation="vertical"` to stack the buttons; the group rounds the top and bottom of the stack instead of the left and right ends.

```tsx
import { ButtonGroup } from '@appica/ui-react/button-group'
import { Button } from '@appica/ui-react/button'

export default function ButtonGroupOrientation() {
  return (
    <ButtonGroup orientation="vertical" variant="outline">
      <Button>Profile</Button>
      <Button>Billing</Button>
      <Button>Settings</Button>
    </ButtonGroup>
  )
}
```

### Icon buttons [#icon-buttons]

Pair an `icon-*` size with icon-only buttons to build a compact toolbar. Give each button an `aria-label` since there's no visible text.

```tsx
import { ButtonGroup } from '@appica/ui-react/button-group'
import { Button } from '@appica/ui-react/button'
import { Bold, Italic, Underline } from '@appica/icons-react'

export default function ButtonGroupIconButtons() {
  return (
    <ButtonGroup variant="outline" size="icon-md">
      <Button aria-label="Bold">
        <Bold />
      </Button>
      <Button aria-label="Italic">
        <Italic />
      </Button>
      <Button aria-label="Underline">
        <Underline />
      </Button>
    </ButtonGroup>
  )
}
```

### Split button [#split-button]

A common pattern: a primary action joined to a [dropdown menu](/ui/components/react/dropdown-menu) of related actions. The menu trigger is rendered as a `Button`, so it still inherits the group's `variant` through context even though it's nested inside `DropdownMenu`.

```tsx
import { ButtonGroup } from '@appica/ui-react/button-group'
import { Button } from '@appica/ui-react/button'
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
} from '@appica/ui-react/dropdown-menu'
import { ChevronDown } from '@appica/icons-react'

export default function ButtonGroupSplitButton() {
  return (
    <ButtonGroup variant="outline">
      <Button>Save</Button>
      <DropdownMenu>
        <DropdownMenuTrigger
          className="group/split"
          render={
            <Button size="icon-md" aria-label="More save options">
              <ChevronDown className="group-data-popup-open/split:rotate-180 motion-safe:transition-transform motion-safe:duration-200" />
            </Button>
          }
        />
        <DropdownMenuContent>
          <DropdownMenuItem>Save and continue</DropdownMenuItem>
          <DropdownMenuItem>Save as draft</DropdownMenuItem>
          <DropdownMenuItem>Save as template</DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </ButtonGroup>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="button-group" />

## API reference [#api-reference]

| Prop          | <ColMinWidth width="200">Type</ColMinWidth>                                                                              | Default        | <ColMinWidth width="220">Description</ColMinWidth>                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------- | ----------------------------------------------------------------------------------------------- |
| `variant`     | <Code>'primary' \| 'primary-outline' \| 'secondary' \| 'soft' \| 'outline' \| 'ghost' \| 'destructive' \| 'light'</Code> | —              | Visual style applied to every child `Button`. Inherited unless a button sets its own `variant`. |
| `size`        | <Code>'sm' \| 'md' \| 'lg' \| 'icon-sm' \| 'icon-md' \| 'icon-lg'</Code>                                                 | —              | Height/padding applied to every child `Button`. Inherited unless a button sets its own `size`.  |
| `orientation` | <Code>'horizontal' \| 'vertical'</Code>                                                                                  | `'horizontal'` | Lay the buttons out in a row or a column; controls which corners are rounded.                   |
| `disabled`    | `boolean`                                                                                                                | `false`        | Disables every child `Button`. A child can't re-enable itself; the group's `disabled` wins.     |
| `className`   | `string`                                                                                                                 | —              | Extra classes, merged after the group classes via `tailwind-merge`.                             |

`ButtonGroup` renders a `<div role="group">` and forwards every other prop (`id`, `aria-*`, `ref`, …) to it. Each child reads `variant`, `size`, and `disabled` from group context — a value set directly on a `Button` always overrides the group, except `disabled`, which is additive (the group disabling can't be overridden by a child).

## Accessibility [#accessibility]

* Renders a `<div role="group">` so assistive tech announces the buttons as one related set. Add an `aria-label` or `aria-labelledby` to name the group when its purpose isn't clear from context.
* Each child remains a standalone [`Button`](/ui/components/react/button), so focus order, **Tab**, **Enter**, and **Space** behave exactly as they do for a lone button.
* Icon-only buttons have no text — give each one an `aria-label`.
* `disabled` on the group removes every child from the tab order and sets `data-disabled` for styling.


# Button (/ui/components/react/button)



<Playground component="button" />

## Usage [#usage]

```tsx
import { Button } from '@appica/ui-react/button'
```

```tsx
<Button>Click me</Button>
```

## Examples [#examples]

### Variants [#variants]

The `variant` prop sets the visual style. `light` is meant for dark or image backgrounds and is omitted below.

```tsx
import { Button } from '@appica/ui-react/button'

const variants = ['primary', 'primary-outline', 'secondary', 'soft', 'outline', 'ghost', 'destructive'] as const

const label = (variant: string) =>
  variant
    .split('-')
    .map((word) => word[0]!.toUpperCase() + word.slice(1))
    .join(' ')

export default function ButtonVariants() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      {variants.map((variant) => (
        <Button key={variant} variant={variant}>
          {label(variant)}
        </Button>
      ))}
    </div>
  )
}
```

### Sizes [#sizes]

```tsx
import { Button } from '@appica/ui-react/button'

export default function ButtonSizes() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </div>
  )
}
```

### With an icon [#with-an-icon]

Mark an icon with `data-icon="start"` or `data-icon="end"` so the button reserves the right inner spacing. Use an `icon-*` size for an icon-only button, and always give it an `aria-label`.

```tsx
import { Button } from '@appica/ui-react/button'
import { Download, ArrowUpRight, Bookmark } from '@appica/icons-react'

export default function ButtonWithIcon() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Button variant="secondary">
        <Download data-icon="start" />
        Download
      </Button>
      <Button variant="outline">
        Open
        <ArrowUpRight data-icon="end" />
      </Button>
      <Button size="icon-md" variant="soft" aria-label="Bookmark">
        <Bookmark />
      </Button>
    </div>
  )
}
```

### Loading state [#loading-state]

While an action is in flight, set `disabled` to block further clicks and swap the label to a [`Spinner`](/ui/components/react/spinner). Add `focusableWhenDisabled` so focus stays on the button when it becomes disabled — without it, focus would jump to the body. Give the `Spinner` `currentColor` so it inherits the button's text color, and `data-icon="start"` so it gets the same inner spacing as an icon.

```tsx
'use client'

import * as React from 'react'
import { Button } from '@appica/ui-react/button'
import { Spinner } from '@appica/ui-react/spinner'

export default function ButtonLoading() {
  const [loading, setLoading] = React.useState(false)

  return (
    <Button
      disabled={loading}
      focusableWhenDisabled
      onClick={() => {
        setLoading(true)
        setTimeout(() => setLoading(false), 3000)
      }}
    >
      {loading && <Spinner variant="dots" currentColor data-icon="start" className="text-[1.125rem]" />}
      {loading ? 'Submitting' : 'Submit'}
    </Button>
  )
}
```

### As a link [#as-a-link]

A link should stay a link. To make an `<a>` (or your router's `<Link>`) merely *look* like a button, apply the exported `buttonVariants` classes to it directly — don't `render` it through `Button`. See [Composition → Links that look like a button](/ui/docs/react/composition#links-that-look-like-a-button).

```tsx
import { buttonVariants } from '@appica/ui-react/button'
import { ArrowUpRight } from '@appica/icons-react'

export default function ButtonAsLink() {
  return (
    <a
      href="https://base-ui.com"
      target="_blank"
      rel="noreferrer"
      className={buttonVariants({ variant: 'soft', size: 'md' })}
    >
      Visit Base UI
      <ArrowUpRight data-icon="end" />
    </a>
  )
}
```

<Callout type="warning" title="Don't render a link through Button">
  Rendering an `<a>` through `Button` forces button semantics onto a link, which misleads assistive tech —
  use `buttonVariants` on the link instead. The `render` prop with `nativeButton={false}` is only for
  rendering as a *non-interactive* element (a `<div>` / `<span>`) where you still want button behavior.
</Callout>

```tsx
// render is for adopting a different element while KEEPING button semantics — e.g. a <div>:
<Button render={<div />} nativeButton={false}>
  Not a native button
</Button>
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="button" />

## API reference [#api-reference]

`Button` wraps [Base UI's Button](https://base-ui.com/react/components/button) and passes every remaining prop (`onClick`, `type`, `aria-*`, `ref`, …) straight through, so anything the Base UI primitive accepts works here — see its docs for the full API. Inside a [`ButtonGroup`](/ui/components/react/button-group), `variant` and `size` are inherited from the group unless set on the button.

| Prop           | <ColMinWidth width="200">Type</ColMinWidth>                                                                              | Default     | <ColMinWidth width="200">Description</ColMinWidth>                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------ |
| `variant`      | <Code>'primary' \| 'primary-outline' \| 'secondary' \| 'soft' \| 'outline' \| 'ghost' \| 'destructive' \| 'light'</Code> | `'primary'` | Visual style.                                                                                          |
| `size`         | <Code>'sm' \| 'md' \| 'lg' \| 'icon-sm' \| 'icon-md' \| 'icon-lg'</Code>                                                 | `'md'`      | Height and padding. The `icon-*` sizes are square, for icon-only buttons.                              |
| `disabled`     | `boolean`                                                                                                                | `false`     | Disables interaction; sets `data-disabled` for styling.                                                |
| `render`       | <Code>ReactElement \| ((props, state) => ReactElement)</Code>                                                            | —           | Replace the button's HTML element with a different tag, or compose it with another component.          |
| `nativeButton` | `boolean`                                                                                                                | `true`      | Whether the rendered element is a native `<button>`. Set `false` when `render`ing a non-button (link). |
| `className`    | `string`                                                                                                                 | —           | Extra classes, merged after the variant classes via `tailwind-merge`.                                  |

## Accessibility [#accessibility]

* Renders a native `<button>` (or whatever you pass to `render`), so it is focusable and in the tab order by default.
* **Enter** and **Space** activate the button.
* `disabled` removes the button from the tab order and sets `data-disabled` for styling; the pointer is disabled via `pointer-events-none`.
* Icon-only buttons have no text, so give them an `aria-label`.
* All press and hover transitions are wrapped in `motion-reduce:` variants, so they are skipped when the user prefers reduced motion.


# Calendar (/ui/components/react/calendar)



<Playground component="calendar" />

## Usage [#usage]

```tsx
import { Calendar } from '@appica/ui-react/calendar'
```

```tsx
<Calendar mode="single" selected={date} onSelect={setDate} />
```

`Calendar` wraps [react-day-picker](https://daypicker.dev)'s `DayPicker`, styled with Appica tokens and an added `size` prop. Set `mode` to choose the selection behavior, then drive the value with `selected` + `onSelect` (or omit both for an uncontrolled calendar). It defaults to Monday-first weeks and dropdown month/year navigation.

## Examples [#examples]

### Single date [#single-date]

The most common setup — `mode="single"` with a `Date | undefined` state.

```tsx
'use client'

import * as React from 'react'
import { Calendar } from '@appica/ui-react/calendar'

export default function CalendarSingle() {
  const [date, setDate] = React.useState<Date | undefined>(new Date())

  return <Calendar mode="single" selected={date} onSelect={setDate} />
}
```

### Date range [#date-range]

`mode="range"` selects a contiguous span. The value is a `DateRange` (`{ from, to }`); the start, middle, and end days are styled as one block.

```tsx
'use client'

import * as React from 'react'
import { Calendar, type DateRange } from '@appica/ui-react/calendar'

export default function CalendarRange() {
  const [range, setRange] = React.useState<DateRange | undefined>(() => {
    const from = new Date()
    const to = new Date()
    to.setDate(to.getDate() + 5)
    return { from, to }
  })

  return <Calendar mode="range" selected={range} onSelect={setRange} />
}
```

### Multiple dates [#multiple-dates]

`mode="multiple"` collects an array of dates — click to add, click again to remove.

```tsx
'use client'

import * as React from 'react'
import { Calendar } from '@appica/ui-react/calendar'

export default function CalendarMultiple() {
  const [days, setDays] = React.useState<Date[] | undefined>(() => {
    const base = new Date()
    return [10, 15, 22].map((d) => new Date(base.getFullYear(), base.getMonth(), d))
  })

  return <Calendar mode="multiple" selected={days} onSelect={setDays} />
}
```

### Disabled dates [#disabled-dates]

`disabled` accepts any react-day-picker [`Matcher`](https://daypicker.dev/api/type-aliases/Matcher) — a date, a range, a set of weekdays, or a predicate. Disabled days are struck through and can't be selected. This example blocks every weekend.

```tsx
import { Calendar } from '@appica/ui-react/calendar'

export default function CalendarDisabled() {
  return <Calendar mode="single" disabled={{ dayOfWeek: [0, 6] }} />
}
```

### Sizes [#sizes]

The `size` prop scales the cell size and text. `captionLayout="label"` swaps the month/year dropdowns for a static label with arrow navigation.

```tsx
import { Calendar } from '@appica/ui-react/calendar'

const sizes = ['sm', 'md', 'lg'] as const

export default function CalendarSizes() {
  return (
    <div className="flex flex-wrap items-start justify-center gap-6">
      {sizes.map((size) => (
        <Calendar key={size} mode="single" size={size} captionLayout="label" />
      ))}
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="calendar" />

## API reference [#api-reference]

| Prop                      | <ColMinWidth width="200">Type</ColMinWidth>                                 | Default         | <ColMinWidth width="220">Description</ColMinWidth>                       |
| ------------------------- | --------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------ |
| `size`                    | <Code>'sm' \| 'md' \| 'lg'</Code>                                           | `'md'`          | Cell size and text scale (Appica extension).                             |
| `mode`                    | <Code>'single' \| 'multiple' \| 'range'</Code>                              | —               | Selection behavior. Omit for a display-only calendar.                    |
| `selected`                | <Code>Date \| Date\[] \| DateRange</Code>                                   | —               | Controlled selection; the shape matches `mode`. Pair with `onSelect`.    |
| `onSelect`                | <Code>(value, triggerDate, modifiers, event) => void</Code>                 | —               | Fires when the selection changes.                                        |
| `captionLayout`           | <Code>'dropdown' \| 'dropdown-months' \| 'dropdown-years' \| 'label'</Code> | `'dropdown'`    | Month/year header: select dropdowns, or a static label with arrows.      |
| `showOutsideDays`         | `boolean`                                                                   | `true`          | Render days from the adjacent months.                                    |
| `weekStartsOn`            | <Code>0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6</Code>                                | `1` (Mon)       | First day of the week.                                                   |
| `numberOfMonths`          | `number`                                                                    | `1`             | How many months to display.                                              |
| `month`                   | `Date`                                                                      | —               | Controlled displayed month. Pair with `onMonthChange`.                   |
| `onMonthChange`           | <Code>(month: Date) => void</Code>                                          | —               | Fires when the user navigates to another month.                          |
| `defaultMonth`            | `Date`                                                                      | current month   | Uncontrolled initial month to display.                                   |
| `startMonth` / `endMonth` | `Date`                                                                      | `1925` / `2050` | Bounds of the navigable range.                                           |
| `disabled`                | `Matcher`                                                                   | —               | Dates that can't be selected (a date, range, weekday set, or predicate). |
| `required`                | `boolean`                                                                   | `false`         | Prevent clearing the selection by re-clicking the selected day.          |
| `className`               | `string`                                                                    | —               | Extra classes on the root, merged via `tailwind-merge`.                  |

`Calendar` forwards every other [`DayPicker`](https://daypicker.dev/api/interfaces/DayPickerProps) prop — `modifiers`/`modifiersClassNames`, `formatters`/`labels`, `dir`, mode-specific options, and more — straight through. See the react-day-picker docs for the full API.

## Accessibility [#accessibility]

* Renders a `role="grid"` of day buttons; selected days expose `aria-selected`, and the current day is marked `today`.
* **←/→/↑/↓** move between days, **Page Up/Down** change months, and **Enter**/**Space** select — react-day-picker's full keyboard model.
* The previous/next buttons and the month/year dropdowns carry accessible labels.
* Disabled days are removed from selection and the pointer, and are visually struck through.
* Day hover/press transitions are wrapped in `motion-reduce:` variants, so they're skipped when the user prefers reduced motion.


# Carousel (/ui/components/react/carousel)



<Playground component="carousel" />

## Usage [#usage]

```tsx
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
  CarouselProgress,
} from '@appica/ui-react/carousel'
```

```tsx
<Carousel loop>
  <CarouselContent>
    <CarouselSlide>Slide 1</CarouselSlide>
    <CarouselSlide>Slide 2</CarouselSlide>
    <CarouselSlide>Slide 3</CarouselSlide>
  </CarouselContent>
  <CarouselPrev
    render={
      <Button variant="outline" size="icon-md" className="rounded-full">
        <ChevronLeft />
      </Button>
    }
  />
  <CarouselNext
    render={
      <Button variant="outline" size="icon-md" className="rounded-full">
        <ChevronRight />
      </Button>
    }
  />
</Carousel>
```

`Carousel` wraps [Embla Carousel](https://www.embla-carousel.com) — a lightweight, dependency-free engine for dragging, snapping, and momentum — and exposes it as a small set of composable parts. `Carousel` sets up the engine and shares it through context; `CarouselContent` is the scroll viewport and track; each `CarouselSlide` is one snap point. Drop in `CarouselPrev` / `CarouselNext` for arrows and `CarouselPagination` or `CarouselProgress` for position feedback — each reads the engine from context, so they can sit anywhere inside the root.

Every slide is `basis-full` by default (one per view). Set a smaller `basis-*` on `CarouselSlide` to show several at once, and pick where they settle with `align`. Options that mirror Embla — `loop`, `align`, `slidesToScroll`, `dragFree`, `duration`, and more — are flat props on `Carousel`; the full option object is available through `options` as an escape hatch.

The arrows (`CarouselPrev` / `CarouselNext`) render an **unstyled** `<button>` by default so you own their look. Pass a [`Button`](/ui/components/react/button) (or any element) via `render` — put structural props like `variant`/`size` on that element, and use `position` to place the arrows inside, outside, or straddling the edge.

## Examples [#examples]

### Default [#default]

A single slide per view with arrows overlaid inside the frame and a pagination strip below. `loop` lets it wrap around from the last slide back to the first.

```tsx
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5]

export default function CarouselDefault() {
  return (
    <div className="w-full max-w-xl pb-8">
      <Carousel loop>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n}>
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
        <CarouselPagination className="absolute inset-x-0 top-full mt-5 justify-center" />
      </Carousel>
    </div>
  )
}
```

### Multiple slides (responsive) [#multiple-slides-responsive]

Give each `CarouselSlide` a fractional `basis-*` to fit several per view — here `basis-1/2` on small screens and `basis-1/3` above. `slidesToScroll="auto"` advances by however many slides are fully visible, and `align="start"` snaps them to the leading edge.

```tsx
import { Carousel, CarouselContent, CarouselSlide, CarouselPrev, CarouselNext } from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [4, 5, 6, 7, 8, 2]

export default function CarouselMultiple() {
  return (
    <div className="w-full max-w-xl px-15">
      <Carousel align="start" slidesToScroll="auto" loop>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="sm:basis-1/2 md:basis-1/3">
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-square w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          position="outside"
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          position="outside"
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
      </Carousel>
    </div>
  )
}
```

### Alignment [#alignment]

`align` controls where slides settle in the viewport — `start`, `center`, or `end`. Combined with a `basis` smaller than the viewport, `center` peeks the neighbouring slides on either side.

```tsx
import { Carousel, CarouselContent, CarouselSlide, CarouselPrev, CarouselNext } from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5, 6]

export default function CarouselAlignment() {
  return (
    <div className="w-full max-w-xl">
      <Carousel align="center" loop>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-2/3">
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
      </Carousel>
    </div>
  )
}
```

### Vertical [#vertical]

Set `orientation="vertical"` to drag and snap along the Y axis — same footprint as the horizontal carousel, just scrolling top-to-bottom. The viewport needs a fixed height (here `h-100` on `CarouselContent`); the arrows settle inside at the top and bottom edges automatically, and `CarouselPagination` takes `orientation="vertical"` to run its bullets down the side. The same 16px inter-slide gap as the horizontal carousel carries over, so slides don't butt together as you scroll.

```tsx
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronUp, ChevronDown } from '@appica/icons-react'

const SLIDES = [1, 2, 4, 5]

export default function CarouselVertical() {
  return (
    <div className="w-full">
      <Carousel orientation="vertical" loop className="flex w-full items-center justify-center gap-5">
        <div className="relative w-full max-w-xl">
          <CarouselContent className="h-100">
            {SLIDES.map((n) => (
              <CarouselSlide key={n}>
                <img
                  src={`/carousel/slide-${n}.jpg`}
                  alt={`Slide ${n}`}
                  className="size-full rounded-xl object-cover"
                />
              </CarouselSlide>
            ))}
          </CarouselContent>
          <CarouselPrev
            render={
              <Button variant="outline" size="icon-md" className="rounded-full">
                <ChevronUp />
              </Button>
            }
          />
          <CarouselNext
            render={
              <Button variant="outline" size="icon-md" className="rounded-full">
                <ChevronDown />
              </Button>
            }
          />
        </div>
        <CarouselPagination orientation="vertical" />
      </Carousel>
    </div>
  )
}
```

### Autoplay [#autoplay]

Pass `autoplay` to advance on a timer via Embla's [Autoplay](https://www.embla-carousel.com/docs/plugins/autoplay) plugin. Give it an object to tune the `delay`, and add `resumeAfter` extension to restart the timer a set time after the user interacts. When autoplay is running, the active pagination bullet grows into a filling progress pill.

```tsx
import { Carousel, CarouselContent, CarouselSlide, CarouselPagination } from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 5, 4, 7, 6]

export default function CarouselAutoplay() {
  return (
    <div className="w-full max-w-xl pb-8">
      <Carousel loop autoplay={{ delay: 4000, resumeAfter: 3000 }}>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n}>
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPagination className="absolute inset-x-0 top-full mt-5 justify-center" />
      </Carousel>
    </div>
  )
}
```

### Auto Scroll [#auto-scroll]

`autoScroll` swaps the discrete timer for continuous marquee-style motion via the [Auto Scroll](https://www.embla-carousel.com/docs/plugins/auto-scroll) plugin — pair it with `loop` and `dragFree` for an endless conveyor. Like `autoplay`, it accepts `resumeAfter` extension to restart the scroll a set time after the user interacts. `autoScroll` and `autoplay` are mutually exclusive. Auto Scroll pauses under `prefers-reduced-motion`.

```tsx
import { Carousel, CarouselContent, CarouselSlide } from '@appica/ui-react/carousel'

const SLIDES = [1, 2, 3, 4, 5, 6, 7, 8]

export default function CarouselAutoScroll() {
  return (
    <div className="w-full max-w-xl">
      <Carousel loop dragFree autoScroll={{ speed: 1.5, startDelay: 0, resumeAfter: 3000 }}>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-1/2 sm:basis-1/3">
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-square w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
      </Carousel>
    </div>
  )
}
```

### Fade [#fade]

`fade` cross-fades between slides instead of sliding them, using the [Fade](https://www.embla-carousel.com/docs/plugins/fade) plugin. It's meant for one slide per view — ideal for a hero or a full-bleed gallery.

```tsx
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5]

export default function CarouselFade() {
  return (
    <div className="w-full max-w-xl pb-8">
      <Carousel loop fade>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n}>
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
        <CarouselPagination className="absolute inset-x-0 top-full mt-5 justify-center" />
      </Carousel>
    </div>
  )
}
```

### Auto Height [#auto-height]

`autoHeight` animates the viewport to each slide's natural height as you navigate, via the [Auto Height](https://www.embla-carousel.com/docs/plugins/auto-height) plugin — so mixed-length content doesn't clip or leave dead space. Use `align="start"` so slides measure from the top.

```tsx
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const CARDS = [
  { title: 'Short', body: 'A compact slide.' },
  {
    title: 'Medium',
    body: 'This slide carries a couple of sentences, so it stands a little taller than the first. The viewport grows to fit it.',
  },
  {
    title: 'Tall',
    body: "And this one runs longer still. Auto Height animates the viewport between each slide's natural height as you navigate, so nothing is clipped and there's no empty space below shorter slides. It keeps mixed-length content — quotes, cards, forms — looking tidy inside a single carousel.",
  },
]

export default function CarouselAutoHeight() {
  return (
    <div className="w-full max-w-md">
      <Carousel loop autoHeight align="start">
        <CarouselContent>
          {CARDS.map((card) => (
            <CarouselSlide key={card.title}>
              <div className="border-border-muted bg-background-subtle rounded-xl border p-6">
                <h4 className="text-foreground-intense mb-2 font-semibold">{card.title}</h4>
                <p className="text-sm">{card.body}</p>
              </div>
            </CarouselSlide>
          ))}
        </CarouselContent>
        <div className="mt-5 flex items-center justify-between gap-4">
          <CarouselPrev
            position="none"
            render={
              <Button variant="outline" size="icon-md">
                <ChevronLeft />
              </Button>
            }
          />
          <CarouselPagination />
          <CarouselNext
            position="none"
            render={
              <Button variant="outline" size="icon-md">
                <ChevronRight />
              </Button>
            }
          />
        </div>
      </Carousel>
    </div>
  )
}
```

### Free drag & wheel gestures [#free-drag--wheel-gestures]

`dragFree` releases the snap points so the carousel glides to a momentum-based stop wherever the drag ends — a natural fit for a scrollable strip. Add `wheelGestures` to also scroll it with a trackpad or mouse wheel (horizontal swipes on a trackpad, vertical wheel on a mouse), via Embla's [Wheel Gestures](https://www.embla-carousel.com/docs/plugins/wheel-gestures) plugin.

```tsx
import { Carousel, CarouselContent, CarouselSlide } from '@appica/ui-react/carousel'

const SLIDES = [1, 2, 3, 4, 5, 6, 7, 8]

export default function CarouselDragFree() {
  return (
    <div className="w-full max-w-xl">
      <Carousel dragFree wheelGestures align="start" containScroll="trimSnaps">
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-1/2 sm:basis-1/3 md:basis-1/4">
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-square w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
      </Carousel>
    </div>
  )
}
```

### Progress [#progress]

`CarouselProgress` renders a scroll progress bar (or a circular ring with `variant="circular"`). By default it tracks drag position, and automatically switches to counting down the autoplay timer while autoplay is playing.

```tsx
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselProgress,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5, 6]

export default function CarouselProgressExample() {
  return (
    <div className="w-full max-w-xl">
      <Carousel align="start">
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-1/2 sm:basis-1/3">
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-square w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <div className="mt-5 flex items-center justify-between">
          <CarouselProgress className="w-14" />
          <div className="flex gap-2">
            <CarouselPrev
              position="none"
              render={
                <Button variant="outline" size="icon-md">
                  <ChevronLeft />
                </Button>
              }
            />
            <CarouselNext
              position="none"
              render={
                <Button variant="outline" size="icon-md">
                  <ChevronRight />
                </Button>
              }
            />
          </div>
        </div>
      </Carousel>
    </div>
  )
}
```

### Thumbnails [#thumbnails]

Two carousels kept in sync: a main viewer and a strip of thumbnails. The `useLinkedCarousels(mainApi, thumbsApi)` hook wires each one's `select` event to the other, so navigating either drives both. Grab each engine with `setApi`, and read `selectedIndex` / `scrollTo` from `useCarousel()` inside a thumbnail to highlight and jump.

```tsx
'use client'

import * as React from 'react'
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  useCarousel,
  useLinkedCarousels,
  type CarouselApi,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5, 6, 7]

export default function CarouselThumbnails() {
  const [mainApi, setMainApi] = React.useState<CarouselApi>()
  const [thumbsApi, setThumbsApi] = React.useState<CarouselApi>()
  useLinkedCarousels(mainApi, thumbsApi)

  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <Carousel loop setApi={setMainApi}>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n}>
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
      </Carousel>

      <Carousel setApi={setThumbsApi} align="start" containScroll="keepSnaps">
        <CarouselContent className="-ms-2">
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-1/4 sm:basis-1/5">
              <Thumb index={n - 1} src={`/carousel/slide-${n}.jpg`} alt={`Thumbnail ${n}`} />
            </CarouselSlide>
          ))}
        </CarouselContent>
      </Carousel>
    </div>
  )
}

function Thumb({ index, src, alt }: { index: number; src: string; alt: string }) {
  const { selectedIndex, scrollTo } = useCarousel()
  const isActive = index === selectedIndex
  return (
    <button
      type="button"
      onClick={() => scrollTo(index)}
      aria-label={`Go to slide ${index + 1}`}
      aria-current={isActive}
      className={`block w-full cursor-pointer overflow-hidden rounded-md border-2 transition-all duration-300 outline-none motion-reduce:transition-none ${isActive ? 'border-primary opacity-100' : 'border-transparent opacity-50 hover:opacity-80'}`}
    >
      <img src={src} alt={alt} className="aspect-square w-full object-cover" />
    </button>
  )
}
```

### Synced carousels [#synced-carousels]

`useLinkedCarousels` isn't limited to thumbnails — it links any two engines. Here a **sliding** image carousel drives a **fading** text carousel below it, so the caption cross-fades in as the image slides. The link is bidirectional, so the outside arrows move both engines in lockstep. Give the text carousel `fade` and `draggable={false}` so it only ever follows the images.

```tsx
'use client'

import * as React from 'react'
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  useLinkedCarousels,
  type CarouselApi,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [
  {
    n: 1,
    title: 'Sunlit summit',
    body: 'First light catches the ridgeline while the valley below stays in shadow — the clearest window for the summit push.',
  },
  {
    n: 2,
    title: 'Deer in bloom',
    body: 'A herd grazes the high meadow at golden hour, wildflowers running all the way to the treeline.',
  },
  {
    n: 3,
    title: 'Turquoise cove',
    body: 'Sea stacks shelter a quiet lagoon where the water shifts from pale sand to deep aquamarine.',
  },
  {
    n: 4,
    title: 'Rose plains',
    body: 'An abandoned homestead sits alone in a sea of pink grass, wide sky stretching to the horizon.',
  },
  {
    n: 5,
    title: 'Mirror lake',
    body: 'A lone peak doubles in glassy water as birds drift across a calm afternoon sky.',
  },
]

export default function CarouselSynced() {
  const [imagesApi, setImagesApi] = React.useState<CarouselApi>()
  const [textApi, setTextApi] = React.useState<CarouselApi>()
  useLinkedCarousels(imagesApi, textApi)

  return (
    <div className="flex w-full max-w-xl flex-col gap-4 px-15">
      <Carousel loop setApi={setImagesApi}>
        <CarouselContent>
          {SLIDES.map((slide) => (
            <CarouselSlide key={slide.n}>
              <img
                src={`/carousel/slide-${slide.n}.jpg`}
                alt={slide.title}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          position="outside"
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          position="outside"
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
      </Carousel>

      <Carousel loop fade draggable={false} setApi={setTextApi}>
        <CarouselContent>
          {SLIDES.map((slide) => (
            <CarouselSlide key={slide.n}>
              <div className="min-h-24 text-center">
                <p className="text-foreground-intense text-lg font-semibold">{slide.title}</p>
                <p className="text-foreground mt-1 text-sm">{slide.body}</p>
              </div>
            </CarouselSlide>
          ))}
        </CarouselContent>
      </Carousel>
    </div>
  )
}
```

### Parallax [#parallax]

A creative effect built on the engine's `scroll` event: each slide's inner layer is over-scaled and translated against the scroll, so the image drifts within its frame as you drag. Grab the api with `setApi`, then tween `slideNodes()` on every `scroll` — accounting for loop points from `internalEngine()`.

```tsx
'use client'

import * as React from 'react'
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  type CarouselApi,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5, 6]
const PARALLAX_FACTOR = 1.7

export default function CarouselParallax() {
  const [api, setApi] = React.useState<CarouselApi>()

  React.useEffect(() => {
    if (!api) return
    const layers = api.slideNodes().map((slide) => slide.querySelector<HTMLElement>('[data-parallax-layer]'))

    const tween = (_api: CarouselApi, event?: { type: string }) => {
      const engine = api.internalEngine()
      const scrollProgress = api.scrollProgress()
      const slidesInView = api.slidesInView()
      const isScroll = event?.type === 'scroll'

      api.snapList().forEach((snap, snapIndex) => {
        let diffToTarget = snap - scrollProgress
        const slidesInSnap = engine.scrollSnapList.slidesBySnap[snapIndex] ?? []

        slidesInSnap.forEach((slideIndex) => {
          if (isScroll && !slidesInView.includes(slideIndex)) return
          if (engine.options.loop) {
            engine.slideLooper.loopPoints.forEach((loopItem) => {
              const target = loopItem.target()
              if (slideIndex === loopItem.index && target !== 0) {
                const sign = Math.sign(target)
                if (sign === -1) diffToTarget = snap - (1 + scrollProgress)
                if (sign === 1) diffToTarget = snap + (1 - scrollProgress)
              }
            })
          }
          const translate = diffToTarget * (-1 * PARALLAX_FACTOR) * 100
          const layer = layers[slideIndex]
          if (layer) layer.style.transform = `translateX(${translate}%)`
        })
      })
    }

    tween(api)
    api.on('scroll', tween)
    api.on('slidefocus', tween)
    api.on('reinit', tween)
    return () => {
      api.off('scroll', tween)
      api.off('slidefocus', tween)
      api.off('reinit', tween)
    }
  }, [api])

  return (
    <div className="w-full max-w-xl">
      <Carousel loop align="center" setApi={setApi}>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-2/3">
              <div className="aspect-3/2 overflow-hidden rounded-xl">
                <div data-parallax-layer className="size-full">
                  <img
                    src={`/carousel/slide-${n}.jpg`}
                    alt={`Slide ${n}`}
                    className="size-full scale-[1.6] object-cover"
                  />
                </div>
              </div>
            </CarouselSlide>
          ))}
        </CarouselContent>
        <div className="mt-5 flex justify-center gap-2">
          <CarouselPrev
            position="none"
            render={
              <Button variant="outline" size="icon-md">
                <ChevronLeft />
              </Button>
            }
          />
          <CarouselNext
            position="none"
            render={
              <Button variant="outline" size="icon-md">
                <ChevronRight />
              </Button>
            }
          />
        </div>
      </Carousel>
    </div>
  )
}
```

### Scale [#scale]

The same `scroll`-driven tweening, applied to `transform: scale` and `opacity`: each slide shrinks and dims in proportion to its distance from the centre, so the focused slide pops. Pairs well with `align="center"` and a `basis` that peeks the neighbours.

```tsx
'use client'

import * as React from 'react'
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  type CarouselApi,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5, 6]
const TWEEN_FACTOR = 1.1

const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max)

export default function CarouselScale() {
  const [api, setApi] = React.useState<CarouselApi>()

  React.useEffect(() => {
    if (!api) return
    const nodes = api.slideNodes().map((slide) => slide.querySelector<HTMLElement>('[data-scale-layer]'))

    const tween = (_api: CarouselApi, event?: { type: string }) => {
      const engine = api.internalEngine()
      const scrollProgress = api.scrollProgress()
      const slidesInView = api.slidesInView()
      const isScroll = event?.type === 'scroll'

      api.snapList().forEach((snap, snapIndex) => {
        let diffToTarget = snap - scrollProgress
        const slidesInSnap = engine.scrollSnapList.slidesBySnap[snapIndex] ?? []

        slidesInSnap.forEach((slideIndex) => {
          if (isScroll && !slidesInView.includes(slideIndex)) return
          if (engine.options.loop) {
            engine.slideLooper.loopPoints.forEach((loopItem) => {
              const target = loopItem.target()
              if (slideIndex === loopItem.index && target !== 0) {
                const sign = Math.sign(target)
                if (sign === -1) diffToTarget = snap - (1 + scrollProgress)
                if (sign === 1) diffToTarget = snap + (1 - scrollProgress)
              }
            })
          }
          const tweenValue = 1 - Math.abs(diffToTarget * TWEEN_FACTOR)
          const scale = clamp(tweenValue, 0.58, 1)
          const opacity = clamp(tweenValue, 0.24, 1)
          const node = nodes[slideIndex]
          if (node) {
            node.style.transform = `scale(${scale})`
            node.style.opacity = `${opacity}`
            node.style.transformOrigin = diffToTarget > 0 ? 'left center' : diffToTarget < 0 ? 'right center' : 'center'
          }
        })
      })
    }

    tween(api)
    api.on('scroll', tween)
    api.on('slidefocus', tween)
    api.on('reinit', tween)
    return () => {
      api.off('scroll', tween)
      api.off('slidefocus', tween)
      api.off('reinit', tween)
    }
  }, [api])

  return (
    <div className="w-full max-w-xl">
      <Carousel loop align="center" setApi={setApi}>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-2/3">
              <div data-scale-layer className="transition-none">
                <img
                  src={`/carousel/slide-${n}.jpg`}
                  alt={`Slide ${n}`}
                  className="aspect-3/2 w-full rounded-xl object-cover"
                />
              </div>
            </CarouselSlide>
          ))}
        </CarouselContent>
        <div className="mt-5 flex justify-center gap-2">
          <CarouselPrev
            position="none"
            render={
              <Button variant="outline" size="icon-md">
                <ChevronLeft />
              </Button>
            }
          />
          <CarouselNext
            position="none"
            render={
              <Button variant="outline" size="icon-md">
                <ChevronRight />
              </Button>
            }
          />
        </div>
      </Carousel>
    </div>
  )
}
```

### Overlaid controls [#overlaid-controls]

Set `light` on `CarouselPagination` / `CarouselProgress` (and a `light`-variant [`Button`](/ui/components/react/button) for the arrows) when the controls sit over imagery, so they read against a dark scrim instead of the page background.

```tsx
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [
  { n: 1, title: 'Sunlit summit', caption: 'Aurora Range' },
  { n: 2, title: 'Deer in bloom', caption: 'Meadowvale Alps' },
  { n: 3, title: 'Turquoise cove', caption: 'Azure Isles' },
  { n: 4, title: 'Rose plains', caption: 'Crimson Flats' },
  { n: 5, title: 'Mirror lake', caption: 'Stillwater Valley' },
]

export default function CarouselLight() {
  return (
    <div className="w-full max-w-xl">
      <Carousel loop className="overflow-hidden rounded-xl">
        <CarouselContent>
          {SLIDES.map((slide) => (
            <CarouselSlide key={slide.n}>
              <div className="relative aspect-3/2 w-full">
                <img src={`/carousel/slide-${slide.n}.jpg`} alt={slide.title} className="size-full object-cover" />
                <div className="absolute inset-0 bg-linear-to-t from-black/70 via-black/10 to-transparent" />
                <div className="absolute inset-s-0 bottom-0 p-5">
                  <p className="text-lg font-semibold text-white">{slide.title}</p>
                  <p className="text-sm text-white/70">{slide.caption}</p>
                </div>
              </div>
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          render={
            <Button variant="light" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          render={
            <Button variant="light" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
        <CarouselPagination light className="absolute inset-x-0 bottom-5 justify-center" />
      </Carousel>
    </div>
  )
}
```

### Controlled with the api [#controlled-with-the-api]

Capture the Embla instance with `setApi` to drive the carousel imperatively and mirror its state elsewhere. Here external buttons call `goToPrev()` / `goToNext()` and a counter subscribes to the `select` event to show the current position.

```tsx
'use client'

import * as React from 'react'
import { Carousel, CarouselContent, CarouselSlide, type CarouselApi } from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5]

export default function CarouselControlled() {
  const [api, setApi] = React.useState<CarouselApi>()
  const [current, setCurrent] = React.useState(0)
  const [count, setCount] = React.useState(0)

  React.useEffect(() => {
    if (!api) return
    setCount(api.snapList().length)
    setCurrent(api.selectedSnap())
    const onSelect = () => setCurrent(api.selectedSnap())
    api.on('select', onSelect)
    return () => {
      api.off('select', onSelect)
    }
  }, [api])

  return (
    <div className="w-full max-w-xl">
      <Carousel loop setApi={setApi}>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n}>
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
      </Carousel>
      <div className="mt-5 flex items-center justify-between">
        <Button variant="outline" size="icon-md" aria-label="Previous slide" onClick={() => api?.goToPrev()}>
          <ChevronLeft />
        </Button>
        <p className="text-sm tabular-nums">
          Slide {current + 1} of {count}
        </p>
        <Button variant="outline" size="icon-md" aria-label="Next slide" onClick={() => api?.goToNext()}>
          <ChevronRight />
        </Button>
      </div>
    </div>
  )
}
```

### Next.js Image [#nextjs-image]

Render slides with `next/image` for automatic optimization. Give each slide a fixed-aspect wrapper and use `fill` with a matching `sizes` so the image resolves the right source; mark the first slide `priority` since it's the LCP candidate.

```tsx
import Image from 'next/image'
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5]

export default function CarouselNextImage() {
  return (
    <div className="w-full max-w-xl pb-8">
      <Carousel loop>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n}>
              <div className="relative aspect-3/2 w-full overflow-hidden rounded-xl">
                <Image
                  src={`/carousel/slide-${n}.jpg`}
                  alt={`Slide ${n}`}
                  fill
                  sizes="(max-width: 640px) 100vw, 576px"
                  className="object-cover"
                  priority={n === 1}
                />
              </div>
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
        <CarouselPagination className="absolute inset-x-0 top-full mt-5 justify-center" />
      </Carousel>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

A horizontal carousel reverses its drag axis and starting edge, so slides flow from the right and the Previous/Next arrows swap sides. Give the arrow buttons direction-appropriate icons and `aria-label`s. Vertical carousels are unaffected by direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="carousel" />

## API reference [#api-reference]

`Carousel` is a compound component. The root creates the [Embla](https://www.embla-carousel.com) engine and shares it through context; the parts read from it. Flat props on the root mirror [Embla options](https://www.embla-carousel.com/api/options/) and toggle its official plugins.

### Carousel [#carousel]

The root. Creates the engine, provides context, and renders a `<div role="region">`.

| Prop             | <ColMinWidth width="210">Type</ColMinWidth>                           | Default        | <ColMinWidth width="220">Description</ColMinWidth>                                              |
| ---------------- | --------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `orientation`    | <Code>'horizontal' \| 'vertical'</Code>                               | `'horizontal'` | Scroll axis. Maps to Embla's `axis`; exposed as `data-orientation`.                             |
| `loop`           | `boolean`                                                             | `false`        | Wrap around from the last slide to the first.                                                   |
| `align`          | <Code>'start' \| 'center' \| 'end'</Code>                             | `'start'`      | Where slides settle within the viewport.                                                        |
| `slidesToScroll` | <Code>number \| 'auto'</Code>                                         | `1`            | How many slides advance per step. `'auto'` groups by how many fit the viewport.                 |
| `containScroll`  | <Code>false \| 'trimSnaps' \| 'keepSnaps'</Code>                      | `'trimSnaps'`  | Clamp scrolling so there's no empty space at the edges. `false` disables containment.           |
| `dragFree`       | `boolean`                                                             | —              | Release snap points; glide to a momentum stop.                                                  |
| `startSnap`      | `number`                                                              | —              | Index of the slide to start on.                                                                 |
| `active`         | `boolean`                                                             | `true`         | When `false`, the engine is inert (no drag/snap) — e.g. to disable at a breakpoint.             |
| `draggable`      | `boolean`                                                             | `true`         | Whether pointer dragging is enabled (Embla's `watchDrag`).                                      |
| `duration`       | `number`                                                              | —              | Scroll animation duration (Embla's ease). Forced to `0` under reduced motion.                   |
| `options`        | <Code>EmblaOptionsType</Code>                                         | —              | Escape hatch: a raw Embla options object, merged last so it wins over the flat props.           |
| `autoplay`       | <Code>boolean \| AutoplayOptions & \{ resumeAfter?: number }</Code>   | —              | Enable the Autoplay plugin. `resumeAfter` (ms) restarts the timer after user interaction.       |
| `autoScroll`     | <Code>boolean \| AutoScrollOptions & \{ resumeAfter?: number }</Code> | —              | Enable continuous Auto Scroll. Mutually exclusive with `autoplay`; paused under reduced motion. |
| `autoHeight`     | <Code>boolean \| AutoHeightOptions</Code>                             | —              | Enable the Auto Height plugin; animates the viewport to each slide's height.                    |
| `fade`           | <Code>boolean \| FadeOptions</Code>                                   | —              | Enable the Fade plugin (cross-fade instead of slide). Best with one slide per view.             |
| `classNames`     | <Code>boolean \| ClassNamesOptions</Code>                             | —              | Enable the Class Names plugin, which toggles `snapped` / `inView` classes on slides.            |
| `accessibility`  | <Code>boolean \| AccessibilityOptions</Code>                          | `true`         | Keyboard/ARIA plugin for the viewport. Set `false` to opt out.                                  |
| `wheelGestures`  | <Code>boolean \| WheelGesturesOptions</Code>                          | `false`        | Enable trackpad / mouse-wheel scrolling.                                                        |
| `plugins`        | <Code>EmblaPluginType\[]</Code>                                       | —              | Additional Embla plugins to append.                                                             |
| `setApi`         | <Code>(api: CarouselApi) => void</Code>                               | —              | Receives the Embla instance once initialized — for imperative control.                          |
| `onReInit`       | <Code>(api: CarouselApi) => void</Code>                               | —              | Fires on init and whenever the engine re-initializes.                                           |
| `onSelect`       | <Code>(api: CarouselApi) => void</Code>                               | —              | Fires when the selected snap changes.                                                           |
| `onScroll`       | <Code>(api: CarouselApi) => void</Code>                               | —              | Fires continuously while scrolling.                                                             |
| `light`          | `boolean`                                                             | `false`        | Hint stored in context for light-on-dark surfaces; read via `useCarousel()`.                    |
| `aria-label`     | `string`                                                              | `'Carousel'`   | Accessible name for the region (native attribute, forwarded to the root).                       |
| `className`      | `string`                                                              | —              | Extra classes on the root, merged via `tailwind-merge`.                                         |

The root also forwards remaining native `<div>` attributes.

### CarouselContent [#carouselcontent]

The scroll viewport plus the flex track that holds the slides. Renders two nested `<div>`s. `className` lands on the inner track — a common place to set the viewport **height** for vertical carousels (e.g. `h-72`).

| Prop        | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth>      |
| ----------- | ------------------------------------------- | ------- | ------------------------------------------------------- |
| `className` | `string`                                    | —       | Extra classes on the track. Also forwards native attrs. |
| `children`  | `ReactNode`                                 | —       | The `CarouselSlide`s.                                   |

### CarouselSlide [#carouselslide]

One slide / snap point. Renders a `<div role="group">` with `basis-full` by default — override `basis-*` to change how many slides show per view.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth>              |
| ----------- | ------------------------------------------- | ------- | --------------------------------------------------------------- |
| `className` | `string`                                    | —       | Extra classes — set `basis-*` here. Also forwards native attrs. |

### CarouselPrev / CarouselNext [#carouselprev--carouselnext]

The previous/next arrows. Each renders an **unstyled** `<button>` (auto-disabled at the ends) inside a positioner. Pass your own element — usually a [`Button`](/ui/components/react/button) — through `render`.

| Prop        | <ColMinWidth width="210">Type</ColMinWidth>                    | Default    | <ColMinWidth width="220">Description</ColMinWidth>                                                    |
| ----------- | -------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| `position`  | <Code>'inside' \| 'outside' \| 'outside-half' \| 'none'</Code> | `'inside'` | Where the arrow sits relative to the viewport. `none` drops absolute positioning so you can place it. |
| `disabled`  | `boolean`                                                      | —          | Force-disable, on top of the automatic end-of-track disabling.                                        |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code>  | —          | Element to render as the arrow. `state` exposes `{ disabled, direction }`.                            |
| `className` | `string`                                                       | —          | Classes on the **positioner** (not the button). Put button styling on the `render` element.           |

Composition (`render`, `className`) is powered by [Base UI's `useRender`](https://base-ui.com/react/utils/use-render). Remaining button attributes (`onClick`, `aria-label`, …) are forwarded to the button and merged with the internal scroll handler.

### CarouselPagination [#carouselpagination]

A row (or column) of clickable bullets, one per snap point. Renders a `<div role="tablist">`; returns `null` when there's a single snap. The active bullet fills as an autoplay timer indicator while autoplay is playing.

| Prop          | <ColMinWidth width="200">Type</ColMinWidth> | Default        | <ColMinWidth width="220">Description</ColMinWidth> |
| ------------- | ------------------------------------------- | -------------- | -------------------------------------------------- |
| `orientation` | <Code>'horizontal' \| 'vertical'</Code>     | `'horizontal'` | Lay the bullets out in a row or a column.          |
| `light`       | `boolean`                                   | `false`        | Light-on-dark styling for use over imagery.        |
| `className`   | `string`                                    | —              | Extra classes. Also forwards native attrs.         |

### CarouselProgress [#carouselprogress]

A scroll/autoplay progress indicator. Renders a bar by default, or a ring with `variant="circular"`.

| Prop          | <ColMinWidth width="200">Type</ColMinWidth>   | Default        | <ColMinWidth width="220">Description</ColMinWidth>                                                    |
| ------------- | --------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| `source`      | <Code>'auto' \| 'autoplay' \| 'scroll'</Code> | `'auto'`       | What drives the fill. `'auto'` counts down autoplay while it plays, otherwise tracks scroll position. |
| `variant`     | <Code>'bar' \| 'circular'</Code>              | `'bar'`        | Straight bar or circular ring.                                                                        |
| `orientation` | <Code>'horizontal' \| 'vertical'</Code>       | `'horizontal'` | Fill direction for the bar variant.                                                                   |
| `light`       | `boolean`                                     | `false`        | Light-on-dark styling for use over imagery.                                                           |
| `className`   | `string`                                      | —              | Extra classes. Also forwards native attrs.                                                            |

### useCarousel() [#usecarousel]

Hook that returns the carousel context from inside a `Carousel`: `api` (the Embla instance), navigation callbacks (`scrollPrev`, `scrollNext`, `scrollTo`), and reactive state (`selectedIndex`, `scrollSnaps`, `canScrollPrev`, `canScrollNext`, `orientation`, `direction`, plus autoplay state). Per-frame scroll progress is exposed as a `subscribeScrollProgress` / `getScrollProgress` pair (subscribe with `useSyncExternalStore` so only readers re-render — this is what `CarouselProgress` uses); read slides in view from `api.slidesInView()`. Throws if used outside a `Carousel`.

### useLinkedCarousels(mainApi, thumbsApi) [#uselinkedcarouselsmainapi-thumbsapi]

Bidirectionally syncs two carousels' selected snaps — the classic main-plus-thumbnails pattern. Wires each engine's `select` event to `goTo` the other. Both apis may be `undefined` initially (while waiting on `setApi`); the effect re-runs once both resolve.

## Accessibility [#accessibility]

* The root is a `role="region"` with `aria-roledescription="carousel"` and an `aria-label` (native attribute, default `"Carousel"`); each slide is a `role="group"` with `aria-roledescription="slide"`.
* The Accessibility plugin (on by default) makes the viewport keyboard-operable — focus it and use the arrow keys to navigate.
* `CarouselPrev` / `CarouselNext` carry `aria-label`s (`"Previous slide"` / `"Next slide"`) and are `disabled` at the ends of a non-looping carousel. When you supply a `render` element, keep an accessible name and localize it as needed.
* `CarouselPagination` is a `role="group"` labelled `"Choose slide to display"` of bullet `<button>`s, each labelled `"Go to slide N"` with `aria-current` on the active one.
* Progress fills, the autoplay indicator, and scroll animations honour `prefers-reduced-motion` — drag snaps instantly and Auto Scroll is disabled.
* Give image slides meaningful `alt` text (or `alt=""` for purely decorative imagery).


# Checkbox (/ui/components/react/checkbox)



<Playground component="checkbox" />

## Usage [#usage]

```tsx
import { Checkbox } from '@appica/ui-react/checkbox'
```

```tsx
<label className="flex items-center gap-2">
  <Checkbox defaultChecked />
  Accept terms and conditions
</label>
```

`Checkbox` renders only the box — it has no text of its own. Wrap it and its label in a single `<label>` so clicking either toggles the box and assistive tech announces them together; no `id`/`htmlFor` wiring needed. Use it uncontrolled with `defaultChecked`, or controlled with `checked` + `onCheckedChange`. The animated check and squish are skipped when the user prefers reduced motion.

To manage several related checkboxes as one value, reach for [`CheckboxGroup`](#checkboxgroup).

## Examples [#examples]

### States [#states]

A checkbox is `unchecked`, `checked`, or `indeterminate` (a mixed state, drawn as a dash). Any of them can also be `disabled`.

```tsx
import { Checkbox } from '@appica/ui-react/checkbox'

export default function CheckboxStates() {
  return (
    <div className="flex flex-wrap items-center gap-6 text-sm select-none">
      <label className="flex items-center gap-2">
        <Checkbox />
        Unchecked
      </label>
      <label className="flex items-center gap-2">
        <Checkbox defaultChecked />
        Checked
      </label>
      <label className="flex items-center gap-2">
        <Checkbox indeterminate />
        Indeterminate
      </label>
      <label className="text-foreground-muted flex items-center gap-2">
        <Checkbox disabled />
        Disabled
      </label>
      <label className="text-foreground-muted flex items-center gap-2">
        <Checkbox disabled defaultChecked />
        Disabled checked
      </label>
      <label className="flex items-center gap-2">
        <Checkbox aria-invalid />
        Error
      </label>
    </div>
  )
}
```

### Sizing [#sizing]

`Checkbox` is sized in `em`, so it scales with the surrounding font size — set a `text-*` class on the wrapping `<label>` and the box and text grow together. It won't shrink below a 16px floor.

```tsx
import { Checkbox } from '@appica/ui-react/checkbox'

export default function CheckboxSizing() {
  return (
    <div className="flex flex-col items-start gap-4 select-none">
      <label className="flex items-center gap-2 text-base">
        <Checkbox defaultChecked />
        text-base
      </label>
      <label className="flex items-center gap-2.5 text-lg">
        <Checkbox defaultChecked />
        text-lg
      </label>
      <label className="flex items-center gap-3 text-xl">
        <Checkbox defaultChecked />
        text-xl
      </label>
    </div>
  )
}
```

### With a label and description [#with-a-label-and-description]

Put a title and supporting text beside the box. Keeping both inside the `<label>` means the whole block is one click target.

```tsx
import { Checkbox } from '@appica/ui-react/checkbox'

export default function CheckboxWithLabel() {
  return (
    <label className="flex max-w-sm items-start gap-2.5 select-none">
      <Checkbox defaultChecked className="mt-1" />
      <span className="flex flex-col">
        <span className="text-foreground-intense font-medium">Enable notifications</span>
        <span className="text-foreground-muted text-sm">
          Receive emails about new activity on your account. You can turn this off any time.
        </span>
      </span>
    </label>
  )
}
```

### Checkbox group [#checkbox-group]

`CheckboxGroup` shares a single array `value` across its children, so you read and set the whole set at once instead of tracking each box. Each child is matched to the value array by its `name`. It lays out vertically by default; pass `orientation="horizontal"` to wrap into a row.

```tsx
import { CheckboxGroup } from '@appica/ui-react/checkbox-group'
import { Checkbox } from '@appica/ui-react/checkbox'

const toppings = [
  { name: 'cheese', label: 'Extra cheese' },
  { name: 'mushrooms', label: 'Mushrooms' },
  { name: 'olives', label: 'Olives' },
  { name: 'onions', label: 'Onions' },
]

export default function CheckboxGroupExample() {
  return (
    <CheckboxGroup aria-labelledby="toppings-label" defaultValue={['cheese', 'olives']}>
      <span id="toppings-label" className="text-foreground mb-1 text-sm font-medium">
        Toppings
      </span>
      {toppings.map((topping) => (
        <label key={topping.name} className="flex items-center gap-2 text-sm select-none">
          <Checkbox name={topping.name} />
          {topping.label}
        </label>
      ))}
    </CheckboxGroup>
  )
}
```

### Select all (parent checkbox) [#select-all-parent-checkbox]

Give the group the full list of child values via `allValues` and mark one child `parent`. When some — but not all — children are checked, the group drives the parent into the `indeterminate` state automatically; ticking the parent checks every child, and clearing it unchecks them.

```tsx
'use client'

import * as React from 'react'
import { CheckboxGroup } from '@appica/ui-react/checkbox-group'
import { Checkbox } from '@appica/ui-react/checkbox'

const permissions = [
  { name: 'read', label: 'Read' },
  { name: 'write', label: 'Write' },
  { name: 'delete', label: 'Delete' },
]

const allValues = permissions.map((permission) => permission.name)

export default function CheckboxSelectAll() {
  const [value, setValue] = React.useState<string[]>(['read'])

  return (
    <CheckboxGroup aria-labelledby="permissions-label" allValues={allValues} value={value} onValueChange={setValue}>
      <label className="flex items-center gap-2 text-sm font-medium select-none">
        <Checkbox parent />
        <span id="permissions-label">Permissions</span>
      </label>
      <div className="flex flex-col gap-2 pl-6">
        {permissions.map((permission) => (
          <label key={permission.name} className="flex items-center gap-2 text-sm select-none">
            <Checkbox name={permission.name} />
            {permission.label}
          </label>
        ))}
      </div>
    </CheckboxGroup>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="checkbox" />

## API reference [#api-reference]

`Checkbox` and `CheckboxGroup` wrap [Base UI's Checkbox](https://base-ui.com/react/components/checkbox) and [CheckboxGroup](https://base-ui.com/react/components/checkbox-group). Each forwards `ref`, `aria-*`, and its native attributes; `Checkbox` exposes `data-*` state attributes (`data-checked`, `data-unchecked`, `data-indeterminate`, `data-disabled`, `data-readonly`, …) for styling and `CheckboxGroup` renders a `<div role="group">`. See the Base UI docs for the complete API.

### Checkbox [#checkbox]

| Prop              | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>                                                          |
| ----------------- | ------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `checked`         | `boolean`                                                     | —       | Controlled checked state. Pair with `onCheckedChange`.                                                      |
| `defaultChecked`  | `boolean`                                                     | `false` | Uncontrolled initial checked state.                                                                         |
| `onCheckedChange` | <Code>(checked: boolean, details) => void</Code>              | —       | Fires when the box is ticked or unticked.                                                                   |
| `indeterminate`   | `boolean`                                                     | `false` | Render the mixed state (dash). Reported to assistive tech as `aria-checked="mixed"`.                        |
| `parent`          | `boolean`                                                     | `false` | Inside a `CheckboxGroup`, makes this the "select all" box driven by the children (needs group `allValues`). |
| `name`            | `string`                                                      | —       | Field name on form submit; also how a `CheckboxGroup` matches this box to its value array.                  |
| `value`           | `string`                                                      | —       | The value submitted with the form when the box is checked.                                                  |
| `uncheckedValue`  | `string`                                                      | —       | The value submitted with the form when the box is unchecked.                                                |
| `form`            | `string`                                                      | —       | `id` of the form that owns the hidden input, when it isn't a descendant.                                    |
| `disabled`        | `boolean`                                                     | `false` | Removes the box from the tab order and ignores interaction.                                                 |
| `readOnly`        | `boolean`                                                     | `false` | Focusable but not toggleable.                                                                               |
| `required`        | `boolean`                                                     | `false` | Must be checked before its form submits.                                                                    |
| `nativeButton`    | `boolean`                                                     | `false` | Whether the element passed to `render` is a native `<button>`.                                              |
| `inputRef`        | <Code>Ref\<HTMLInputElement></Code>                           | —       | Ref to the hidden `<input>` element backing the checkbox.                                                   |
| `id`              | `string`                                                      | —       | `id` of the rendered element.                                                                               |
| `render`          | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the rendered element, or compose it with another component.                                         |
| `className`       | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes on the box, merged via `tailwind-merge`. May be a function of state.                          |
| `style`           | <Code>CSSProperties \| ((state) => CSSProperties)</Code>      | —       | Inline styles, optionally derived from state.                                                               |

### CheckboxGroup [#checkboxgroup]

Shares one value array across the checkboxes nested inside it.

| Prop            | <ColMinWidth width="200">Type</ColMinWidth>                   | Default      | <ColMinWidth width="220">Description</ColMinWidth>                                    |
| --------------- | ------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------- |
| `value`         | `string[]`                                                    | —            | Controlled array of checked child `name`s. Pair with `onValueChange`.                 |
| `defaultValue`  | `string[]`                                                    | —            | Uncontrolled initial set of checked children.                                         |
| `onValueChange` | <Code>(value: string\[], details) => void</Code>              | —            | Fires with the next array whenever a child toggles.                                   |
| `allValues`     | `string[]`                                                    | —            | Every child value — required to drive a `parent` "select all" checkbox.               |
| `orientation`   | <Code>'horizontal' \| 'vertical'</Code>                       | `'vertical'` | Stack the boxes in a column, or wrap them into a row.                                 |
| `disabled`      | `boolean`                                                     | `false`      | Disables every checkbox in the group.                                                 |
| `render`        | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —            | Replace the group element, or compose it with another component.                      |
| `className`     | <Code>string \| ((state) => string)</Code>                    | —            | Extra classes, merged via `tailwind-merge` (override the default `flex` layout here). |
| `style`         | <Code>CSSProperties \| ((state) => CSSProperties)</Code>      | —            | Inline styles, optionally derived from state.                                         |

## Accessibility [#accessibility]

* Renders with `role="checkbox"`. **Space** toggles it; **Tab** moves focus to and from it.
* A checkbox needs an accessible name — wrap it in a `<label>` together with its text (as shown above), or give it an `aria-label`.
* `indeterminate` is announced as `aria-checked="mixed"`, distinct from checked and unchecked.
* `CheckboxGroup` renders a `<div role="group">`; name it with `aria-label` or `aria-labelledby` since a group can't use a wrapping `<label>`.
* `disabled` removes the box from the tab order and exposes `data-disabled` for styling.
* The check/squish animations honour `prefers-reduced-motion`.


# Chip (/ui/components/react/chip)



<Playground component="chip" />

## Usage [#usage]

```tsx
import { Chip, ChipGroup } from '@appica/ui-react/chip'
```

```tsx
<Chip>Label</Chip>
```

`Chip` is a small, button-based pill for tags, attributes, filters, and removable tokens. It shares its look with [`Button`](/ui/components/react/button) (same `variant` palette) but comes in compact `sm` / `md` / `lg` heights. Make one removable with `dismissible` — it adds a close affordance and animates itself out when dismissed. Group several with `ChipGroup` to share `variant` / `size` and clear them all at once.

A `Chip` renders a native `<button>` by default. Swap the element with `render` (e.g. an `<a>` for a tag link), and reach for the shared `variant` palette to convey meaning.

## Examples [#examples]

### Variants [#variants]

`variant` sets the visual style, drawn from the same palette as [`Button`](/ui/components/react/button) — `soft` (default), `outline`, `primary`, `secondary`, and `destructive`.

```tsx
import { Chip } from '@appica/ui-react/chip'

const variants = ['soft', 'outline', 'primary', 'secondary', 'destructive'] as const

export default function ChipVariants() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      {variants.map((variant) => (
        <Chip key={variant} variant={variant} className="capitalize">
          {variant}
        </Chip>
      ))}
    </div>
  )
}
```

### Sizes [#sizes]

`size` scales the height, padding, text, and icon together — `sm`, `md` (default), or `lg`.

```tsx
import { Chip } from '@appica/ui-react/chip'

const sizes = [
  { size: 'sm', label: 'Small' },
  { size: 'md', label: 'Medium' },
  { size: 'lg', label: 'Large' },
] as const

export default function ChipSizes() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      {sizes.map(({ size, label }) => (
        <Chip key={size} size={size}>
          {label}
        </Chip>
      ))}
    </div>
  )
}
```

### With an icon [#with-an-icon]

Mark a leading or trailing [icon](/ui/icons) with `data-icon="start"` or `data-icon="end"` so the chip reserves the right inner spacing — the same convention as [`Button`](/ui/components/react/button).

```tsx
import { Chip } from '@appica/ui-react/chip'
import { Plus, CircleCheck, Star } from '@appica/icons-react'

export default function ChipWithIcon() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Chip variant="soft">
        <Plus data-icon="start" />
        New
      </Chip>
      <Chip variant="primary">
        <CircleCheck data-icon="start" />
        Verified
      </Chip>
      <Chip variant="outline">
        4.9
        <Star data-icon="end" />
      </Chip>
    </div>
  )
}
```

### Dismissible [#dismissible]

Add `dismissible` to render a close (✕) affordance. Clicking the chip removes it with a blur-and-scale exit animation, then fires `onDismiss` once the animation finishes — the cue to drop it from your state.

```tsx
'use client'

import * as React from 'react'
import { Chip } from '@appica/ui-react/chip'

const initial = ['Design', 'Engineering', 'Marketing', 'Sales']

export default function ChipDismissible() {
  const [tags, setTags] = React.useState(initial)

  return (
    <div className="flex min-h-8 flex-wrap items-center gap-2">
      {tags.length === 0 ? (
        <button
          type="button"
          onClick={() => setTags(initial)}
          className="text-foreground-muted hover:text-foreground text-sm"
        >
          Restore tags
        </button>
      ) : (
        tags.map((tag) => (
          <Chip
            key={tag}
            dismissible
            closeLabel={`Remove ${tag}`}
            onDismiss={() => setTags((prev) => prev.filter((t) => t !== tag))}
          >
            {tag}
          </Chip>
        ))
      )}
    </div>
  )
}
```

### Selectable filters [#selectable-filters]

A chip is a button, so it's ready for selection UIs. Drive a `selected` state yourself and swap the `variant` (and a check icon) to show which is active; set `aria-pressed` so the toggle state is announced.

```tsx
'use client'

import * as React from 'react'
import { Chip } from '@appica/ui-react/chip'
import { Check } from '@appica/icons-react'

const options = ['All', 'Active', 'Completed', 'Archived']

export default function ChipSelectable() {
  const [selected, setSelected] = React.useState('Active')

  return (
    <div className="flex flex-wrap items-center gap-2">
      {options.map((option) => {
        const isSelected = option === selected
        return (
          <Chip
            key={option}
            variant={isSelected ? 'primary' : 'outline'}
            aria-pressed={isSelected}
            onClick={() => setSelected(option)}
          >
            {isSelected && <Check data-icon="start" />}
            {option}
          </Chip>
        )
      })}
    </div>
  )
}
```

### Chip group [#chip-group]

`ChipGroup` lays chips out in a wrapping row and shares `variant` / `size` with every child through context (a chip can still override its own). Capture a ref to call `clearAll()`, which dismisses every removable chip — each animates out and fires its `onDismiss`.

```tsx
'use client'

import * as React from 'react'
import { Chip, ChipGroup, type ChipGroupHandle } from '@appica/ui-react/chip'
import { Button } from '@appica/ui-react/button'

const filters = ['React', 'TypeScript', 'Tailwind', 'Motion', 'Base UI']

export default function ChipGroupDemo() {
  const groupRef = React.useRef<ChipGroupHandle>(null)
  const [active, setActive] = React.useState(filters)

  return (
    <div className="flex flex-col items-start gap-3">
      <ChipGroup ref={groupRef} variant="outline">
        {active.map((filter) => (
          <Chip key={filter} dismissible onDismiss={() => setActive((prev) => prev.filter((f) => f !== filter))}>
            {filter}
          </Chip>
        ))}
      </ChipGroup>
      <div className="flex gap-2">
        <Button size="sm" variant="ghost" onClick={() => groupRef.current?.clearAll()} disabled={active.length === 0}>
          Clear all
        </Button>
        <Button
          size="sm"
          variant="ghost"
          onClick={() => setActive(filters)}
          disabled={active.length === filters.length}
        >
          Reset
        </Button>
      </div>
    </div>
  )
}
```

### As a link [#as-a-link]

Because chips are often navigable tags, you can render one as an `<a>` (or your router's `Link`) with the `render` prop while keeping the chip styling — the `state` is still exposed to a render callback.

```tsx
import { Chip } from '@appica/ui-react/chip'

export default function ChipAsLink() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Chip render={<a href="#design" />}>#design</Chip>
      <Chip render={<a href="#engineering" />}>#engineering</Chip>
      <Chip variant="primary" render={<a href="#featured" />}>
        #featured
      </Chip>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The chip's content, inner icon spacing, and the dismiss button all use logical properties, so they mirror to the start/end edges automatically. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="chip" />

## API reference [#api-reference]

### Chip [#chip]

A compact pill. Renders a native `<button>` by default.

| Prop           | <ColMinWidth width="200">Type</ColMinWidth>                                   | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                                                                                                             |
| -------------- | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `variant`      | <Code>'soft' \| 'outline' \| 'primary' \| 'secondary' \| 'destructive'</Code> | `'soft'`    | Visual style, from the shared [`Button`](/ui/components/react/button) palette. Inherited from `ChipGroup`.                                                                     |
| `size`         | <Code>'sm' \| 'md' \| 'lg'</Code>                                             | `'md'`      | Height, padding, text, and icon size. Inherited from `ChipGroup`.                                                                                                              |
| `dismissible`  | `boolean`                                                                     | `false`     | Render a close button; clicking the chip dismisses it with an exit animation.                                                                                                  |
| `open`         | `boolean`                                                                     | —           | Controlled visibility for a **dismissible** chip — pair with `onOpenChange` to own dismissal in your own state. (For a non-dismissible chip, render it conditionally instead.) |
| `onOpenChange` | <Code>(open: boolean) => void</Code>                                          | —           | The **intent** signal — fires with `false` the moment a dismiss is requested. Use it with `open` for controlled mode: update your state here.                                  |
| `onDismiss`    | <Code>() => void</Code>                                                       | —           | The **completion** signal — fires once the exit animation finishes. Use it in uncontrolled mode to drop the chip from state after it's animated out.                           |
| `closeLabel`   | `string`                                                                      | `'Dismiss'` | Accessible label for the dismiss action (rendered as `sr-only` text).                                                                                                          |
| `disabled`     | `boolean`                                                                     | `false`     | Disables interaction; sets `data-disabled` for styling.                                                                                                                        |
| `render`       | <Code>ReactElement \| ((props, state) => ReactElement)</Code>                 | —           | Replace the underlying element (e.g. an `<a>`), or compose it with another component.                                                                                          |
| `className`    | `string`                                                                      | —           | Extra classes, merged after the variant classes via `tailwind-merge`.                                                                                                          |

Also forwards every remaining native `<button>` prop (`onClick`, `type`, `aria-*`, `ref`, …). The `render` callback receives the chip `state`: `{ variant, size, dismissible }`.

### ChipGroup [#chipgroup]

A wrapping flex container that shares defaults with its chips and can clear them as a set.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth>               |
| ----------- | ------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `variant`   | <Code>ChipVariant</Code>                    | —       | Default `variant` for every child chip; a chip may override it.  |
| `size`      | <Code>'sm' \| 'md' \| 'lg'</Code>           | —       | Default `size` for every child chip; a chip may override it.     |
| `ref`       | <Code>Ref\<ChipGroupHandle></Code>          | —       | Exposes `clearAll()`, which dismisses every `dismissible` child. |
| `className` | `string`                                    | —       | Extra classes, merged via `tailwind-merge`.                      |

Renders a `<div>` and forwards every other prop (`id`, `aria-*`, …). `ChipGroupHandle` is `{ clearAll: () => void }`.

## Accessibility [#accessibility]

* A `Chip` is a native `<button>` (or whatever you pass to `render`), so it's focusable and in the tab order, and **Enter** / **Space** activate it.
* For a dismissible chip, the whole chip is the dismiss control; `closeLabel` provides an `sr-only` accessible name for the action — set it to something specific like `"Remove React"`.
* For selectable chips, set `aria-pressed` to expose the on/off state to assistive tech.
* `disabled` removes the chip from the tab order and sets `data-disabled` for styling.
* The dismiss exit animation is reduced to a simple fade when the user prefers reduced motion.


# Collapsible (/ui/components/react/collapsible)



<Playground component="collapsible" />

## Usage [#usage]

```tsx
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@appica/ui-react/collapsible'
```

```tsx
<Collapsible>
  <CollapsibleTrigger>What's included in the free plan?</CollapsibleTrigger>
  <CollapsibleContent>Up to three projects, 1 GB of storage, and community support.</CollapsibleContent>
</Collapsible>
```

`Collapsible` is a single show/hide disclosure — one trigger controlling one panel. Reach for it for a "read more", an inline details section, or any one-off toggle; for a set of mutually-aware sections use [`Accordion`](/ui/components/react/accordion) instead. Compose it from three parts, all under `@appica/ui-react/collapsible`:

* **`Collapsible`** — the root. Owns the open state (`open`/`defaultOpen`) and can be `disabled`.
* **`CollapsibleTrigger`** — the button that toggles the panel. It exposes `data-panel-open` and `data-disabled` for styling.
* **`CollapsibleContent`** — the panel, which animates its height open and closed. It publishes the `--collapsible-panel-height` CSS variable that powers that animation.

The parts ship almost unstyled so the collapsible inherits your layout — the examples below add the card, chevron, and spacing.

## Examples [#examples]

### Default [#default]

A trigger and a panel. The panel animates its height open and closed, and the leading chevron rotates a quarter-turn because the trigger carries `data-panel-open` while open. Pass `defaultOpen` to start expanded, as here.

```tsx
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@appica/ui-react/collapsible'
import { ChevronRight } from '@appica/icons-react'

export default function CollapsibleDefault() {
  return (
    <Collapsible defaultOpen className="w-full max-w-100">
      <CollapsibleTrigger className="group text-foreground-intense inline-flex items-start gap-2 text-start font-medium">
        <ChevronRight className="mt-0.75 size-4.5 shrink-0 stroke-2 transition-transform duration-200 group-data-panel-open:rotate-90 motion-reduce:transition-none" />
        What's included in the free plan?
      </CollapsibleTrigger>
      <CollapsibleContent>
        <p className="ps-6.5 pt-2.5 text-sm">
          The free plan includes up to three projects, 1&nbsp;GB of storage, and community support — everything you need
          to evaluate the product before upgrading.
        </p>
      </CollapsibleContent>
    </Collapsible>
  )
}
```

### File tree [#file-tree]

Nest a `Collapsible` inside another `Collapsible`'s content to build an expandable tree. Each folder is its own disclosure; files are plain rows. A recursive render keeps any depth tidy.

```tsx
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@appica/ui-react/collapsible'
import { ChevronRight, Folder, FolderOpen, File } from '@appica/icons-react'

type TreeNode = { name: string; children?: TreeNode[] }

const tree: TreeNode[] = [
  {
    name: 'src',
    children: [
      {
        name: 'app',
        children: [{ name: 'layout.tsx' }, { name: 'page.tsx' }, { name: 'globals.css' }],
      },
      {
        name: 'components',
        children: [{ name: 'site-header.tsx' }, { name: 'site-footer.tsx' }],
      },
      { name: 'lib', children: [{ name: 'utils.ts' }] },
    ],
  },
  {
    name: 'public',
    children: [{ name: 'favicon.ico' }, { name: 'logo.svg' }],
  },
  { name: 'package.json' },
  { name: 'README.md' },
]

function TreeItem({ node, defaultOpen }: { node: TreeNode; defaultOpen?: boolean }) {
  if (!node.children) {
    return (
      <span className="text-foreground-muted flex items-center gap-1.5 py-1 ps-5.5">
        <File className="size-4 shrink-0" />
        {node.name}
      </span>
    )
  }

  return (
    <Collapsible defaultOpen={defaultOpen}>
      <CollapsibleTrigger className="group inline-flex items-center gap-1.5 py-1 font-medium">
        <ChevronRight className="size-4 shrink-0 stroke-[1.75] transition-transform duration-200 group-data-panel-open:rotate-90 motion-reduce:transition-none" />
        <Folder className="text-foreground-muted size-4 shrink-0 stroke-[1.75] group-data-panel-open:hidden" />
        <FolderOpen className="text-foreground-muted hidden size-4 shrink-0 stroke-[1.75] group-data-panel-open:block" />
        {node.name}
      </CollapsibleTrigger>
      <CollapsibleContent>
        <div className="ms-2 flex flex-col border-s ps-2">
          {node.children.map((child) => (
            <TreeItem key={child.name} node={child} />
          ))}
        </div>
      </CollapsibleContent>
    </Collapsible>
  )
}

export default function CollapsibleFileTree() {
  return (
    <div className="w-full max-w-72 text-sm">
      {tree.map((node) => (
        <TreeItem key={node.name} node={node} defaultOpen={node.name === 'src'} />
      ))}
    </div>
  )
}
```

### Settings panel [#settings-panel]

Reveal extra controls only when they're needed. A single radius sets every corner; the icon-button beside it expands a per-corner panel below. The icon swaps between a maximize and minimize glyph entirely from the root's `data-open` state — no JavaScript.

```tsx
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@appica/ui-react/collapsible'
import { Button } from '@appica/ui-react/button'
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Maximize, Minimize } from '@appica/icons-react'

const px = <span className="text-foreground-muted text-xs">px</span>

function CornerField({ label, defaultValue }: { label: string; defaultValue: string }) {
  return (
    <Field>
      <FieldLabel className="text-xs font-normal">{label}</FieldLabel>
      <Input inputSize="sm" type="number" defaultValue={defaultValue} endSlot={px} />
    </Field>
  )
}

export default function CollapsibleSettingsPanel() {
  return (
    <Collapsible className="group border-border w-full max-w-82 rounded-xl border p-5">
      <div>
        <h3 className="text-foreground-intense font-semibold">Corner radius</h3>
        <p className="text-foreground-muted text-sm">Round every corner at once, or set each one.</p>
      </div>

      <div className="mt-4 flex items-center gap-3">
        <Input
          inputSize="sm"
          type="number"
          defaultValue="12"
          endSlot={px}
          className="flex-1"
          aria-label="All corners"
        />
        <CollapsibleTrigger
          className="shrink-0"
          render={<Button variant="outline" size="icon-sm" aria-label="Set each corner individually" />}
        >
          <Maximize className="group-data-open:hidden" />
          <Minimize className="hidden group-data-open:block" />
        </CollapsibleTrigger>
      </div>

      <CollapsibleContent>
        <div className="mt-4 grid grid-cols-2 gap-4 px-1.5 pb-1.5">
          <CornerField label="Top left" defaultValue="12" />
          <CornerField label="Top right" defaultValue="12" />
          <CornerField label="Bottom left" defaultValue="12" />
          <CornerField label="Bottom right" defaultValue="12" />
        </div>
      </CollapsibleContent>
    </Collapsible>
  )
}
```

### Show more [#show-more]

Because the trigger and panel are independent, the trigger can sit *below* the always-visible text as a "Show more / Show less" toggle, with the label following the open state.

```tsx
'use client'

import * as React from 'react'
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@appica/ui-react/collapsible'

export default function CollapsibleShowMore() {
  const [open, setOpen] = React.useState(false)

  return (
    <Collapsible open={open} onOpenChange={setOpen} className="max-w-100 text-sm leading-relaxed">
      <p>
        Appica UI is a headless-first component library built on Base UI and Tailwind. It ships accessible primitives
        with sensible default styling you can override class by class.
      </p>
      <CollapsibleContent>
        <p className="pt-3">
          Every component supports right-to-left layouts, honours <code>prefers-reduced-motion</code>, and forwards refs
          and native attributes to the underlying element — so it drops into your design system without fighting it.
        </p>
      </CollapsibleContent>
      <CollapsibleTrigger className="text-primary mt-2 cursor-pointer text-sm font-medium hover:underline">
        {open ? 'Show less' : 'Show more'}
      </CollapsibleTrigger>
    </Collapsible>
  )
}
```

### Controlled [#controlled]

Drive the open state yourself with `open` + `onOpenChange`. Here an external button and the header share the same state, so either one toggles the panel.

```tsx
'use client'

import * as React from 'react'
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@appica/ui-react/collapsible'
import { Button } from '@appica/ui-react/button'
import { ChevronRight } from '@appica/icons-react'

export default function CollapsibleControlled() {
  const [open, setOpen] = React.useState(false)

  return (
    <div className="flex w-full max-w-100 flex-col gap-3">
      <div className="flex items-center justify-between">
        <span className="text-foreground-muted text-sm">
          Panel is <strong className="text-foreground">{open ? 'open' : 'closed'}</strong>
        </span>
        <Button size="sm" variant="outline" onClick={() => setOpen((o) => !o)}>
          {open ? 'Collapse' : 'Expand'}
        </Button>
      </div>

      <Collapsible open={open} onOpenChange={setOpen}>
        <CollapsibleTrigger className="group text-foreground-intense inline-flex items-start gap-2 text-start font-medium">
          <ChevronRight className="mt-0.75 size-4.5 shrink-0 stroke-2 transition-transform duration-200 group-data-panel-open:rotate-90 motion-reduce:transition-none" />
          Order #4982
        </CollapsibleTrigger>
        <CollapsibleContent>
          <p className="ps-6.5 pt-2.5 text-sm">
            Two items, shipped on Aug&nbsp;30 via standard delivery. The header and the external button drive the same
            state, so either one toggles the panel.
          </p>
        </CollapsibleContent>
      </Collapsible>
    </div>
  )
}
```

### Disabled [#disabled]

Add `disabled` to the root to lock the panel shut. The trigger drops out of the tab order and exposes `data-disabled` for styling.

```tsx
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@appica/ui-react/collapsible'
import { ChevronRight } from '@appica/icons-react'

export default function CollapsibleDisabled() {
  return (
    <Collapsible disabled className="w-full max-w-100">
      <CollapsibleTrigger className="group text-foreground-intense data-disabled:text-foreground-muted inline-flex items-start gap-2 text-start font-medium">
        <ChevronRight className="mt-0.75 size-4.5 shrink-0 stroke-2 transition-transform duration-200 group-data-panel-open:rotate-90 motion-reduce:transition-none" />
        Advanced settings
      </CollapsibleTrigger>
      <CollapsibleContent>
        <p className="ps-6.5 pt-2.5 text-sm">These settings unlock on a paid plan.</p>
      </CollapsibleContent>
    </Collapsible>
  )
}
```

### Keep mounted [#keep-mounted]

By default the panel unmounts when closed. Pass `keepMounted` to leave it in the DOM so the browser's find-in-page and search-engine crawlers can still reach the hidden text.

```tsx
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@appica/ui-react/collapsible'
import { ChevronRight } from '@appica/icons-react'

export default function CollapsibleKeepMounted() {
  return (
    <Collapsible className="w-full max-w-100">
      <CollapsibleTrigger className="group text-foreground-intense inline-flex items-start gap-2 text-start font-medium">
        <ChevronRight className="mt-0.75 size-4.5 shrink-0 stroke-2 transition-transform duration-200 group-data-panel-open:rotate-90 motion-reduce:transition-none" />
        Shipping &amp; returns
      </CollapsibleTrigger>
      <CollapsibleContent keepMounted>
        <p className="ps-6.5 pt-2.5 text-sm">
          Orders ship within one business day and arrive in 3-5 days. With <code>keepMounted</code> the panel stays in
          the DOM while closed, so search engines and the browser's find-in-page can still reach this text.
        </p>
      </CollapsibleContent>
    </Collapsible>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The trigger and its panel align to the right, the panel's indent moves to the right via the logical `ps-*` padding, and the leading chevron mirrors to point toward the inline start. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="collapsible" />

## API reference [#api-reference]

`Collapsible` wraps [Base UI's Collapsible](https://base-ui.com/react/components/collapsible). Each part forwards `ref` and its remaining props to the matching Base UI primitive, so anything it accepts works here — the tables below list the most common props. The panel exposes the `--collapsible-panel-height` CSS variable that powers the height animation. See the Base UI docs for the complete API.

### Collapsible [#collapsible]

The root. Renders a `<div>` and owns the open state.

| Prop           | <ColMinWidth width="210">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth> |
| -------------- | ------------------------------------------------------------- | ------- | -------------------------------------------------- |
| `defaultOpen`  | `boolean`                                                     | `false` | Uncontrolled initial open state.                   |
| `open`         | `boolean`                                                     | —       | Controlled open state. Pair with `onOpenChange`.   |
| `onOpenChange` | <Code>(open: boolean, details) => void</Code>                 | —       | Fires when the panel opens or closes.              |
| `disabled`     | `boolean`                                                     | `false` | Disable the trigger so the panel can't toggle.     |
| `render`       | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the root element, or compose it.           |
| `className`    | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes, merged via `tailwind-merge`.        |

### CollapsibleTrigger [#collapsibletrigger]

The toggle button. Renders a `<button>` with `aria-expanded`/`aria-controls` wired to the panel, and exposes `data-panel-open` / `data-disabled`.

| Prop        | <ColMinWidth width="210">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>     |
| ----------- | ------------------------------------------------------------- | ------- | ------------------------------------------------------ |
| `children`  | `ReactNode`                                                   | —       | The trigger label and any indicator icon.              |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Render through another element (e.g. a custom button). |
| `className` | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes, merged via `tailwind-merge`.            |

### CollapsibleContent [#collapsiblecontent]

The animated panel. Renders a `<div>` and exposes `data-open` / `data-closed`.

| Prop               | <ColMinWidth width="210">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>                   |
| ------------------ | ------------------------------------------------------------- | ------- | -------------------------------------------------------------------- |
| `children`         | `ReactNode`                                                   | —       | The panel content.                                                   |
| `keepMounted`      | `boolean`                                                     | `false` | Keep the panel in the DOM while closed (find-in-page / SEO).         |
| `hiddenUntilFound` | `boolean`                                                     | `false` | Use the native `hidden="until-found"` so closed text stays findable. |
| `render`           | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the panel element.                                           |
| `className`        | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes, merged via `tailwind-merge`.                          |

## Accessibility [#accessibility]

* `CollapsibleTrigger` is a real `<button>` with `aria-expanded` reflecting the state and `aria-controls` pointing at the panel, so assistive tech announces "expanded"/"collapsed".
* **Enter** and **Space** toggle the panel while the trigger is focused; the trigger is reachable with **Tab**.
* A `disabled` collapsible removes the trigger from the tab order and marks it `data-disabled` for styling.
* Any indicator icon (the chevron in these examples) is decorative — the trigger's text label carries the meaning.
* The panel's height animation honours `prefers-reduced-motion`, collapsing instantly when the user prefers reduced motion.


# Combobox (/ui/components/react/combobox)



<Playground component="combobox" />

## Usage [#usage]

```tsx
import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'
```

```tsx
const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart']

<Combobox items={frameworks}>
  <ComboboxInput placeholder="Search a framework" />
  <ComboboxContent>
    <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item} value={item}>
          {item}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>
```

`Combobox` is a compound component. The root holds the data (`items`) and shared options (`size`, `variant`, `clearable`, `icon`, `multiple`, `grid`); the parts compose the input and the filtered popup:

* **`ComboboxInput`** — the text field, styled like [`Input`](/ui/components/react/input). It filters the list as you type. Add adornments with `startSlot` / `endSlot`.
* **`ComboboxTrigger`*&#x2A; / &#x2A;*`ComboboxValue`** — a select-style trigger (also styled like `Input`) that shows the current value and opens the popup. Use it instead of `ComboboxInput` when the search field should live **inside** the popup (see [Country select](#country-select)).
* **`ComboboxChips`*&#x2A; / &#x2A;*`ComboboxChip`** — a chip-based input for `multiple` selection, in place of `ComboboxInput`.
* **`ComboboxContent`** — the portalled, auto-positioned popup. Accepts the shared [floating props](/ui/components/react/popover).
* **`ComboboxList`** — the scrollable list. Pass a render function over the filtered items, or static `ComboboxItem`s.
* **`ComboboxItem`** — one option; its `value` is what selection reports.
* **`ComboboxEmpty`** — shown only when the filter matches nothing.

`Combobox` and [`Autocomplete`](/ui/components/react/autocomplete) are siblings built on the same Base UI primitive. Reach for `Combobox` when you're **picking a value** from a set (its chevron, clearable, chips, and grid lean toward selection); use `Autocomplete` for a leaner typeahead. For a short, known list with no search, use a [`Select`](/ui/components/react/select).

## Examples [#examples]

### Variants [#variants]

`variant` switches the input appearance between a bordered `outline` (default) and a filled `soft` field.

```tsx
'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']
const variants = ['outline', 'soft'] as const

export default function ComboboxVariants() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      {variants.map((variant) => (
        <Combobox key={variant} items={frameworks} variant={variant}>
          <ComboboxInput placeholder="Search a framework" aria-label={`Search (${variant})`} />
          <ComboboxContent>
            <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
            <ComboboxList>
              {(item: string) => (
                <ComboboxItem key={item} value={item}>
                  {item}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxContent>
        </Combobox>
      ))}
    </div>
  )
}
```

### Sizes [#sizes]

`size` on the root scales the input, popup radius, and items together — `sm`, `md` (default), or `lg`.

```tsx
'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']
const sizes = ['sm', 'md', 'lg'] as const

export default function ComboboxSizes() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      {sizes.map((size) => (
        <Combobox key={size} items={frameworks} size={size}>
          <ComboboxInput placeholder="Search a framework" aria-label={`Search (${size})`} />
          <ComboboxContent>
            <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
            <ComboboxList>
              {(item: string) => (
                <ComboboxItem key={item} value={item}>
                  {item}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxContent>
        </Combobox>
      ))}
    </div>
  )
}
```

### Clearable & chevron [#clearable--chevron]

`icon` (a chevron that toggles the popup) is **on by default**; turn it off with `icon={false}`. Set `clearable` to add a clear (✕) button once there's a value. Both render inside the input.

```tsx
'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']

export default function ComboboxClearable() {
  return (
    <div className="w-full max-w-70">
      <Combobox items={frameworks} defaultValue="Next.js" clearable>
        <ComboboxInput placeholder="Search a framework" aria-label="Search a framework" />
        <ComboboxContent>
          <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}
```

### Disabled & error states [#disabled--error-states]

`disabled` on the root greys out the input and blocks interaction. Set `aria-invalid` on the `ComboboxInput` to paint the error state — it's mirrored to `data-invalid`. Inside a [`Field`](/ui/components/react/field), the input also inherits the field's `disabled` and `invalid` state, which is the better choice when you're rendering a validation message.

```tsx
'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']

export default function ComboboxStates() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      <Combobox items={frameworks} disabled>
        <ComboboxInput placeholder="Disabled" aria-label="Disabled" />
        <ComboboxContent>
          <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>

      <Combobox items={frameworks} defaultValue="Next.js">
        <ComboboxInput aria-invalid placeholder="Search a framework" aria-label="With error" />
        <ComboboxContent>
          <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}
```

### Start & end slots [#start--end-slots]

`ComboboxInput` accepts `startSlot` and `endSlot` for adornments inside the input frame — a search icon, a shortcut hint, a unit — laid out around the field and its controls.

```tsx
'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'
import { Search } from '@appica/icons-react'

const commands = ['Open file', 'New window', 'Toggle sidebar', 'Find in files', 'Go to line', 'Command palette']

export default function ComboboxSlots() {
  return (
    <div className="w-full max-w-70">
      <Combobox items={commands} icon={false}>
        <ComboboxInput
          placeholder="Search commands"
          aria-label="Search commands"
          startSlot={<Search className="text-foreground-muted size-4.5" />}
          endSlot={<span className="text-foreground-subtle text-xs">⌘K</span>}
        />
        <ComboboxContent>
          <ComboboxEmpty>No commands found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}
```

### Country select [#country-select]

A searchable country picker with [flags](/ui/country-flags). When `items` are objects, give the root an `itemToStringLabel` so the input and filter know how to read each one; here the selected country's flag is mirrored into the input through `startSlot`. The list is long, so its `ComboboxList` is wrapped in a [`ScrollArea`](/ui/components/react/scroll-area) for a custom, themeable scrollbar (set `overflow-y-visible` on the list so the `ScrollArea` owns the scroll).

```tsx
'use client'

import * as React from 'react'
import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'
import { ScrollArea } from '@appica/ui-react/scroll-area'
import { CountryFlagRounded } from '@appica/country-flags-react'
import { World } from '@appica/icons-react'

interface Country {
  code: string
  name: string
}

const countries: Country[] = [
  { code: 'ar', name: 'Argentina' },
  { code: 'au', name: 'Australia' },
  { code: 'be', name: 'Belgium' },
  { code: 'br', name: 'Brazil' },
  { code: 'ca', name: 'Canada' },
  { code: 'cn', name: 'China' },
  { code: 'dk', name: 'Denmark' },
  { code: 'eg', name: 'Egypt' },
  { code: 'fr', name: 'France' },
  { code: 'de', name: 'Germany' },
  { code: 'in', name: 'India' },
  { code: 'it', name: 'Italy' },
  { code: 'jp', name: 'Japan' },
  { code: 'mx', name: 'Mexico' },
  { code: 'nl', name: 'Netherlands' },
  { code: 'no', name: 'Norway' },
  { code: 'pt', name: 'Portugal' },
  { code: 'kr', name: 'South Korea' },
  { code: 'es', name: 'Spain' },
  { code: 'se', name: 'Sweden' },
  { code: 'ch', name: 'Switzerland' },
  { code: 'tr', name: 'Türkiye' },
  { code: 'gb', name: 'United Kingdom' },
  { code: 'us', name: 'United States' },
]

export default function ComboboxCountry() {
  const [selected, setSelected] = React.useState<Country | null>(null)

  return (
    <div className="w-full max-w-70">
      <Combobox
        items={countries}
        value={selected}
        onValueChange={(v) => setSelected(v as Country | null)}
        itemToStringLabel={(item) => (item as Country).name}
        clearable
      >
        <ComboboxInput
          placeholder="Select a country"
          aria-label="Select a country"
          startSlot={
            selected ? (
              <CountryFlagRounded code={selected.code} aria-hidden />
            ) : (
              <World className="text-foreground-muted" />
            )
          }
        />
        <ComboboxContent>
          <ComboboxEmpty>No countries found.</ComboboxEmpty>
          <ScrollArea className="max-h-72">
            <ComboboxList className="overflow-y-visible">
              {(country: Country) => (
                <ComboboxItem key={country.code} value={country}>
                  <CountryFlagRounded code={country.code} data-icon="start" aria-hidden />
                  {country.name}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ScrollArea>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}
```

### Input inside popup and custom scroll [#input-inside-popup-and-custom-scroll]

For a select-style picker, render a `ComboboxTrigger` (showing the current `ComboboxValue`) as the field and move the search `ComboboxInput` **inside** `ComboboxContent`. Set `icon={false}` on the root so the in-popup input drops its own chevron — the trigger already has one. As with [Country select](#country-select), the long list is wrapped in a [`ScrollArea`](/ui/components/react/scroll-area) for a custom scrollbar.

```tsx
'use client'

import * as React from 'react'
import {
  Combobox,
  ComboboxTrigger,
  ComboboxValue,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'
import { ScrollArea } from '@appica/ui-react/scroll-area'

const languages = [
  'Arabic',
  'Bengali',
  'Chinese',
  'Czech',
  'Danish',
  'Dutch',
  'English',
  'Finnish',
  'French',
  'German',
  'Greek',
  'Hebrew',
  'Hindi',
  'Hungarian',
  'Indonesian',
  'Italian',
  'Japanese',
  'Korean',
  'Norwegian',
  'Polish',
  'Portuguese',
  'Romanian',
  'Russian',
  'Spanish',
  'Swedish',
  'Thai',
  'Turkish',
  'Ukrainian',
  'Vietnamese',
]

export default function ComboboxPopupSearch() {
  const [value, setValue] = React.useState<string | null>(null)

  return (
    <div className="w-full max-w-70">
      <Combobox items={languages} value={value} onValueChange={(v) => setValue(v as string | null)} icon={false}>
        <ComboboxTrigger aria-label="Select a language">
          <ComboboxValue placeholder="Select a language" />
        </ComboboxTrigger>
        <ComboboxContent>
          <div className="px-2 pb-2 group-data-empty/combobox-content:pt-2">
            <ComboboxInput placeholder="Search a language" aria-label="Search a language" />
          </div>
          <ScrollArea className="max-h-64">
            <ComboboxEmpty>No languages found.</ComboboxEmpty>
            <ComboboxList className="overflow-y-visible">
              {(item: string) => (
                <ComboboxItem key={item} value={item}>
                  {item}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ScrollArea>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}
```

### User select [#user-select]

Rich items with an [`Avatar`](/ui/components/react/avatar), a name, and a trailing role — search a directory and assign a person. The chosen avatar is echoed back into the input via `startSlot`.

```tsx
'use client'

import * as React from 'react'
import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { UserFilled } from '@appica/icons-react'

interface User {
  id: string
  name: string
  role: string
  avatar: string
  initials: string
}

const users: User[] = [
  { id: 'liam', name: 'Liam Hudson', role: 'Admin', avatar: '/avatars/01.jpg', initials: 'LH' },
  { id: 'sarah', name: 'Sarah Jenkins', role: 'User', avatar: '/avatars/02.jpg', initials: 'SJ' },
  { id: 'mateo', name: 'Mateo Rossi', role: 'User', avatar: '/avatars/03.jpg', initials: 'MR' },
  { id: 'ava', name: 'Ava Thompson', role: 'Editor', avatar: '/avatars/04.jpg', initials: 'AT' },
  { id: 'noah', name: 'Noah Patel', role: 'User', avatar: '/avatars/05.jpg', initials: 'NP' },
  { id: 'emma', name: 'Emma Garcia', role: 'User', avatar: '/avatars/06.jpg', initials: 'EG' },
  { id: 'lucas', name: 'Lucas Müller', role: 'Admin', avatar: '/avatars/07.jpg', initials: 'LM' },
  { id: 'olivia', name: 'Olivia Bennett', role: 'User', avatar: '/avatars/08.jpg', initials: 'OB' },
]

export default function ComboboxUsers() {
  const [selected, setSelected] = React.useState<User | null>(null)

  return (
    <div className="w-full max-w-70">
      <Combobox
        items={users}
        value={selected}
        onValueChange={(v) => setSelected(v as User | null)}
        itemToStringLabel={(item) => (item as User).name}
        clearable
      >
        <ComboboxInput
          placeholder="Assign to…"
          aria-label="Assign to"
          startSlot={
            <Avatar size={22}>
              {selected && <AvatarImage src={selected.avatar} alt={selected.name} />}
              <AvatarFallback>{selected ? selected.initials : <UserFilled />}</AvatarFallback>
            </Avatar>
          }
        />
        <ComboboxContent>
          <ComboboxEmpty>No people found.</ComboboxEmpty>
          <ComboboxList>
            {(user: User) => (
              <ComboboxItem key={user.id} value={user} className="[&>span:first-child]:flex-1">
                <Avatar size={22} data-icon="start">
                  <AvatarImage src={user.avatar} alt={user.name} />
                  <AvatarFallback>{user.initials}</AvatarFallback>
                </Avatar>
                {user.name}
                <span className="text-foreground-muted ms-auto ps-3 text-xs">{user.role}</span>
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}
```

### Grouped options [#grouped-options]

Pass a grouped `items` array — `{ value, items }[]` — and render each group with `ComboboxGroup` + `ComboboxLabel` + `ComboboxCollection`. The outer render function iterates groups; `ComboboxCollection` renders the items inside each. As with [Country select](#country-select), this longer list wraps its `ComboboxList` in a [`ScrollArea`](/ui/components/react/scroll-area) for a custom scrollbar.

```tsx
'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
  ComboboxGroup,
  ComboboxLabel,
  ComboboxCollection,
} from '@appica/ui-react/combobox'
import { ScrollArea } from '@appica/ui-react/scroll-area'

interface ProduceGroup {
  value: string
  items: string[]
}

const groups: ProduceGroup[] = [
  { value: 'Fruits', items: ['Apple', 'Banana', 'Cherry', 'Grapefruit', 'Mango', 'Orange', 'Strawberry'] },
  { value: 'Vegetables', items: ['Broccoli', 'Carrot', 'Cucumber', 'Lettuce', 'Potato', 'Spinach', 'Tomato'] },
  { value: 'Herbs', items: ['Basil', 'Mint', 'Oregano', 'Parsley', 'Rosemary', 'Thyme'] },
]

export default function ComboboxGrouped() {
  return (
    <div className="w-full max-w-70">
      <Combobox items={groups}>
        <ComboboxInput placeholder="Search produce" aria-label="Search produce" />
        <ComboboxContent>
          <ComboboxEmpty>No produce found.</ComboboxEmpty>
          <ScrollArea className="max-h-72">
            <ComboboxList className="overflow-y-visible">
              {(group: ProduceGroup) => (
                <ComboboxGroup key={group.value} items={group.items}>
                  <ComboboxLabel>{group.value}</ComboboxLabel>
                  <ComboboxCollection>
                    {(item: string) => (
                      <ComboboxItem key={item} value={item}>
                        {item}
                      </ComboboxItem>
                    )}
                  </ComboboxCollection>
                </ComboboxGroup>
              )}
            </ComboboxList>
          </ScrollArea>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}
```

### Grid layout [#grid-layout]

Set `grid` on the root to lay options out in a grid — arrow keys then move in two dimensions. `ComboboxList`'s `cols` controls how many items per row (defaults to 2 in grid mode); give each item `flex-1` to fill its cell.

```tsx
'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const tags = ['React', 'Vue', 'Svelte', 'Angular', 'Solid', 'Qwik', 'Preact', 'Lit', 'Alpine', 'Ember']

export default function ComboboxGrid() {
  return (
    <div className="w-full max-w-70">
      <Combobox items={tags} grid>
        <ComboboxInput placeholder="Search a library" aria-label="Search a library" />
        <ComboboxContent>
          <ComboboxEmpty>No libraries found.</ComboboxEmpty>
          <ComboboxList cols={2}>
            {(item: string) => (
              <ComboboxItem key={item} value={item} className="flex-1">
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}
```

### Multiple selection [#multiple-selection]

Set `multiple` and swap `ComboboxInput` for `ComboboxChips`: each selected value becomes a removable `ComboboxChip`, with the text field inline for adding more. The value is an array.

```tsx
'use client'

import * as React from 'react'
import {
  Combobox,
  ComboboxChips,
  ComboboxChip,
  ComboboxValue,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']

export default function ComboboxMultiple() {
  const [value, setValue] = React.useState<string[]>(['Next.js', 'Astro'])

  return (
    <div className="w-full max-w-70">
      <Combobox items={frameworks} multiple value={value} onValueChange={(v) => setValue(v as string[])}>
        <ComboboxChips placeholder="Add frameworks">
          <ComboboxValue>
            {(selected: string[]) =>
              selected.map((item) => (
                <ComboboxChip key={item} aria-label={item}>
                  {item}
                </ComboboxChip>
              ))
            }
          </ComboboxValue>
        </ComboboxChips>
        <ComboboxContent>
          <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}
```

### Creatable [#creatable]

Let users add an option that isn't in the list. Control the `items`, `value`, and `inputValue` yourself: when the typed query has no exact match, append a synthetic "create" item, and in `onValueChange` detect it to add the new entry to your data and select it. Here each created label is added to a multi-select chip field.

```tsx
'use client'

import * as React from 'react'
import {
  Combobox,
  ComboboxChips,
  ComboboxChip,
  ComboboxValue,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'
import { Plus } from '@appica/icons-react'

interface Label {
  id: string
  value: string
  creatable?: string
}

const initialLabels: Label[] = [
  { id: 'bug', value: 'bug' },
  { id: 'documentation', value: 'documentation' },
  { id: 'enhancement', value: 'enhancement' },
  { id: 'help-wanted', value: 'help wanted' },
  { id: 'good-first-issue', value: 'good first issue' },
]

export default function ComboboxCreatable() {
  const [labels, setLabels] = React.useState<Label[]>(initialLabels)
  const [selected, setSelected] = React.useState<Label[]>([])
  const [query, setQuery] = React.useState('')

  const trimmed = query.trim()
  const lowered = trimmed.toLocaleLowerCase()
  const exactExists = labels.some((label) => label.value.trim().toLocaleLowerCase() === lowered)
  const items: Label[] =
    trimmed !== '' && !exactExists
      ? [...labels, { id: `create:${lowered}`, value: `Create "${trimmed}"`, creatable: trimmed }]
      : labels

  return (
    <div className="w-full max-w-70">
      <Combobox
        items={items}
        multiple
        value={selected}
        inputValue={query}
        onInputValueChange={setQuery}
        itemToStringLabel={(item) => (item as Label).value}
        onValueChange={(next) => {
          const list = next as Label[]
          const created = list.find((item) => item.creatable && !selected.some((s) => s.id === item.id))
          if (created?.creatable) {
            const label: Label = {
              id: created.creatable.toLocaleLowerCase().replace(/\s+/g, '-'),
              value: created.creatable,
            }
            setLabels((prev) => (prev.some((l) => l.id === label.id) ? prev : [...prev, label]))
            setSelected((prev) => [...prev, label])
            setQuery('')
            return
          }
          setSelected(list.filter((item) => !item.creatable))
          setQuery('')
        }}
      >
        <ComboboxChips placeholder="Add labels…">
          <ComboboxValue>
            {(value: Label[]) =>
              value.map((label) => (
                <ComboboxChip key={label.id} aria-label={label.value}>
                  {label.value}
                </ComboboxChip>
              ))
            }
          </ComboboxValue>
        </ComboboxChips>
        <ComboboxContent>
          <ComboboxEmpty>No labels found.</ComboboxEmpty>
          <ComboboxList>
            {(item: Label) =>
              item.creatable ? (
                <ComboboxItem key={item.id} value={item}>
                  <Plus data-icon="start" />
                  Create &ldquo;{item.creatable}&rdquo;
                </ComboboxItem>
              ) : (
                <ComboboxItem key={item.id} value={item}>
                  {item.value}
                </ComboboxItem>
              )
            }
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}
```

### Controlled [#controlled]

Drive the selection yourself with `value` + `onValueChange`. The input's text is managed separately — control it too with `inputValue` + `onInputValueChange` when you need to.

```tsx
'use client'

import * as React from 'react'
import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']

export default function ComboboxControlled() {
  const [value, setValue] = React.useState<string | null>(null)

  return (
    <div className="flex w-full max-w-70 flex-col gap-3">
      <Combobox items={frameworks} value={value} onValueChange={(v) => setValue(v as string | null)} clearable>
        <ComboboxInput placeholder="Search a framework" aria-label="Choose a framework" />
        <ComboboxContent>
          <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
      <p className="text-foreground-muted text-sm">
        Selected: <span className="text-foreground font-medium">{value ?? '—'}</span>
      </p>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="combobox" />

## API reference [#api-reference]

`Combobox` wraps [Base UI's Combobox](https://base-ui.com/react/components/combobox). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### Combobox [#combobox]

The root. Holds the data and the shared styling/behavior options; renders no DOM of its own.

| Prop                 | <ColMinWidth width="180">Type</ColMinWidth>          | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                   |
| -------------------- | ---------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------ |
| `items`              | <Code>readonly T\[] \| {'{ value, items }[]'}</Code> | —           | The data to filter. A flat array, or `{ value, items }` objects for grouped options. |
| `size`               | <Code>'sm' \| 'md' \| 'lg'</Code>                    | `'md'`      | Input height, popup radius, and item sizing.                                         |
| `variant`            | <Code>'outline' \| 'soft'</Code>                     | `'outline'` | Input appearance — bordered or filled.                                               |
| `clearable`          | `boolean`                                            | `false`     | Render a clear button inside the input when a value is present.                      |
| `icon`               | `boolean`                                            | `true`      | Render a chevron button that toggles the popup.                                      |
| `grid`               | `boolean`                                            | `false`     | Lay options out as a navigable grid instead of a list.                               |
| `multiple`           | `boolean`                                            | `false`     | Allow selecting several values; the value becomes an array.                          |
| `value`              | <Code>T \| T\[] \| null</Code>                       | —           | Controlled selection. Pair with `onValueChange`.                                     |
| `defaultValue`       | <Code>T \| T\[] \| null</Code>                       | —           | Uncontrolled initial selection.                                                      |
| `onValueChange`      | <Code>(value, details) => void</Code>                | —           | Fires when the selection changes.                                                    |
| `inputValue`         | `string`                                             | —           | Controlled input text. Pair with `onInputValueChange`.                               |
| `onInputValueChange` | <Code>(value, details) => void</Code>                | —           | Fires as the typed text changes.                                                     |
| `itemToStringLabel`  | <Code>(item: T) => string</Code>                     | —           | For object items: the text the input shows and the filter matches against.           |
| `itemToStringValue`  | <Code>(item: T) => string</Code>                     | —           | For object items: the string value reported for forms.                               |
| `mode`               | <Code>'list' \| 'inline' \| 'both' \| 'none'</Code>  | `'list'`    | List filtering vs. inline autocompletion behavior.                                   |
| `autoHighlight`      | <Code>boolean \| 'always'</Code>                     | `false`     | Highlight the first matching item as you type.                                       |
| `disabled`           | `boolean`                                            | `false`     | Disable the whole control.                                                           |
| `required`           | `boolean`                                            | `false`     | Require a value before the form submits.                                             |
| `name`               | `string`                                             | —           | Field name submitted with a form.                                                    |

### ComboboxInput [#comboboxinput]

The text field. Renders Base UI's `Input` inside an `InputGroup`, styled like [`Input`](/ui/components/react/input).

| Prop           | Type                                      | Default | Description                                                    |
| -------------- | ----------------------------------------- | ------- | -------------------------------------------------------------- |
| `startSlot`    | `ReactNode`                               | —       | Adornment rendered before the field, inside the input frame.   |
| `endSlot`      | `ReactNode`                               | —       | Adornment rendered after the field, before the controls.       |
| `placeholder`  | `string`                                  | `' '`   | Placeholder text.                                              |
| `disabled`     | `boolean`                                 | `false` | Disables the field and the clear/chevron buttons.              |
| `aria-invalid` | <Code>boolean \| 'true' \| 'false'</Code> | —       | Marks the error state; mirrored to `data-invalid` for styling. |
| `className`    | `string`                                  | —       | Extra classes on the input group, merged via `tailwind-merge`. |

Also forwards every native `<input>` prop (`onChange`, `name`, `aria-*`, `ref`, …).

### ComboboxTrigger [#comboboxtrigger]

A select-style trigger button (styled like [`Input`](/ui/components/react/input)) that shows the value via `ComboboxValue` and opens the popup. Use it — instead of `ComboboxInput` as the field — when the search input should live inside `ComboboxContent`.

| Prop        | Type        | Default | Description                                           |
| ----------- | ----------- | ------- | ----------------------------------------------------- |
| `startSlot` | `ReactNode` | —       | Adornment before the value, inside the trigger frame. |
| `endSlot`   | `ReactNode` | —       | Adornment after the value, before the chevron.        |
| `children`  | `ReactNode` | —       | The trigger content — typically a `ComboboxValue`.    |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`.           |

Also forwards every native `<button>` prop (`onClick`, `disabled`, `aria-*`, `ref`, …).

### ComboboxChips [#comboboxchips]

The chip-based input for `multiple` selection — render it instead of `ComboboxInput`.

| Prop          | <ColMinWidth width="160">Type</ColMinWidth> | Default | Description                                                   |
| ------------- | ------------------------------------------- | ------- | ------------------------------------------------------------- |
| `placeholder` | `string`                                    | —       | Placeholder for the inline text field.                        |
| `inputProps`  | `object`                                    | —       | Props forwarded to the inner text `input`.                    |
| `children`    | `ReactNode`                                 | —       | A `ComboboxValue` mapping selected values to `ComboboxChip`s. |
| `className`   | `string`                                    | —       | Extra classes, merged via `tailwind-merge`.                   |

### ComboboxChip [#comboboxchip]

One removable chip representing a selected value.

| Prop        | Type        | Default | Description                                   |
| ----------- | ----------- | ------- | --------------------------------------------- |
| `children`  | `ReactNode` | —       | The chip label; a remove (✕) button is added. |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`.   |

### ComboboxContent [#comboboxcontent]

The portalled, auto-positioned popup wrapping the list. Accepts the shared floating props.

| Prop              | <ColMinWidth width="160">Type</ColMinWidth>         | Default    | Description                                                     |
| ----------------- | --------------------------------------------------- | ---------- | --------------------------------------------------------------- |
| `side`            | <Code>'top' \| 'right' \| 'bottom' \| 'left'</Code> | `'bottom'` | Preferred side of the input to open on.                         |
| `align`           | <Code>'start' \| 'center' \| 'end'</Code>           | —          | Alignment along that side.                                      |
| `sideOffset`      | `number`                                            | `6`        | Gap between the input and the popup.                            |
| `alignOffset`     | `number`                                            | —          | Shift along the alignment axis.                                 |
| `container`       | <Code>HTMLElement \| ref \| null</Code>             | —          | Portal target — render the popup into a different node.         |
| `keepMounted`     | `boolean`                                           | `false`    | Keep the popup mounted in the DOM while closed.                 |
| `positionerProps` | `object`                                            | —          | Escape hatch for the positioner element (`style`, `render`, …). |
| `portalProps`     | `object`                                            | —          | Escape hatch for the portal element (`style`, `render`, …).     |
| `className`       | `string`                                            | —          | Extra classes on the popup.                                     |

### ComboboxList [#comboboxlist]

The scrollable list container.

| Prop       | <ColMinWidth width="220">Type</ColMinWidth>          | Default | Description                                                           |
| ---------- | ---------------------------------------------------- | ------- | --------------------------------------------------------------------- |
| `cols`     | `number`                                             | —       | Items per row in grid mode (defaults to 2 when `grid` is set).        |
| `children` | <Code>ReactNode \| (item, index) => ReactNode</Code> | —       | A render function over the filtered items, or static `ComboboxItem`s. |

### ComboboxItem [#comboboxitem]

One option in the list.

| Prop        | Type      | Default | Description                                             |
| ----------- | --------- | ------- | ------------------------------------------------------- |
| `value`     | `T`       | —       | The item this option represents; reported on selection. |
| `disabled`  | `boolean` | `false` | Make the option unselectable.                           |
| `className` | `string`  | —       | Extra classes (e.g. `flex-1` to fill a grid cell).      |

### ComboboxEmpty [#comboboxempty]

Shown only when the filter matches nothing — otherwise it renders nothing.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The empty-state message.                    |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### ComboboxGroup [#comboboxgroup]

Wraps one section of a grouped list. Pass the section's `items` so a nested `ComboboxCollection` can render them, and label it with a `ComboboxLabel`.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth> | Default | Description                                          |
| ----------- | ------------------------------------------- | ------- | ---------------------------------------------------- |
| `items`     | `readonly T[]`                              | —       | The group's items, consumed by `ComboboxCollection`. |
| `children`  | `ReactNode`                                 | —       | A `ComboboxLabel` plus the group's items.            |
| `className` | `string`                                    | —       | Extra classes, merged via `tailwind-merge`.          |

### ComboboxLabel [#comboboxlabel]

The visible heading for a `ComboboxGroup`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The label text.                             |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### ComboboxCollection [#comboboxcollection]

Renders the items of the enclosing `ComboboxGroup` from a render function.

| Prop       | <ColMinWidth width="200">Type</ColMinWidth> | Default | Description                          |
| ---------- | ------------------------------------------- | ------- | ------------------------------------ |
| `children` | <Code>(item, index) => ReactNode</Code>     | —       | Render function for each group item. |

### ComboboxValue [#comboboxvalue]

Renders the current value — typically a function child mapping the selected value(s) to chips or text.

| Prop       | <ColMinWidth width="200">Type</ColMinWidth>    | Default | Description                                        |
| ---------- | ---------------------------------------------- | ------- | -------------------------------------------------- |
| `children` | <Code>ReactNode \| (value) => ReactNode</Code> | —       | Static content, or a render function of the value. |

### ComboboxSeparator [#comboboxseparator]

A thin divider between sections.

| Prop        | Type     | Default | Description                                 |
| ----------- | -------- | ------- | ------------------------------------------- |
| `className` | `string` | —       | Extra classes, merged via `tailwind-merge`. |

## Accessibility [#accessibility]

* The input has `role="combobox"`; the popup is a `listbox` (or `grid` when `grid` is set) and items are `option`/`gridcell`. Selection and active state are wired through `aria-activedescendant`.
* **↑/↓** move the highlight, **Enter** selects, **Escape** closes the popup, and typing filters the list. In `multiple` mode, **Backspace** in an empty field removes the last chip.
* The clear and chevron buttons have `aria-label`s (`Clear selection`, `Toggle popup`) and become `disabled` when the input is disabled; chip remove buttons are labelled `Remove`.
* Always give `ComboboxInput` (or `ComboboxChips`) a visible label or an `aria-label`.
* `aria-invalid` on the input is bridged to `data-invalid` so the error state styles with or without a wrapping `Field`.
* Popup enter/exit transitions are skipped when the user prefers reduced motion.


# Context Menu (/ui/components/react/context-menu)



<Playground component="context-menu" />

## Usage [#usage]

```tsx
import {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuGroupLabel,
  ContextMenuItem,
  ContextMenuSeparator,
} from '@appica/ui-react/context-menu'
```

```tsx
<ContextMenu>
  <ContextMenuTrigger className="flex h-40 w-72 items-center justify-center rounded-xl border border-dashed">
    Right-click here
  </ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuGroup>
      <ContextMenuGroupLabel>Edit</ContextMenuGroupLabel>
      <ContextMenuItem>Copy</ContextMenuItem>
      <ContextMenuItem>Cut</ContextMenuItem>
      <ContextMenuItem>Paste</ContextMenuItem>
    </ContextMenuGroup>
    <ContextMenuSeparator />
    <ContextMenuItem>Delete</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

`ContextMenu` is a compound component built on [Base UI's Context Menu](https://base-ui.com/react/components/context-menu). Unlike a menu opened from a button, its trigger is the **target area** itself:

* **`ContextMenuTrigger`** — the region that opens the menu on right-click / long-press. Renders a `div` by default; pass `className` or `render` to wrap your own content.
* **`ContextMenuContent`** — the portalled popup, positioned at the pointer. Accepts the shared [floating props](/ui/components/react/popover) (`side`, `align`, `sideOffset`, …).
* **`ContextMenuItem`** — one action. Fires `onClick` and closes the menu by default.
* **`ContextMenuGroup`*&#x2A; / &#x2A;*`ContextMenuGroupLabel`*&#x2A; / &#x2A;*`ContextMenuSeparator`** — structure for sectioned lists.
* **`ContextMenuCheckboxItem`*&#x2A; / &#x2A;*`ContextMenuRadioGroup`*&#x2A; + &#x2A;*`ContextMenuRadioItem`** — stateful options with a check indicator.
* **`ContextMenuLinkItem`** — an item that renders an `<a>` for navigation.
* **`ContextMenuSub`*&#x2A; / &#x2A;*`ContextMenuSubTrigger`*&#x2A; / &#x2A;*`ContextMenuSubContent`** — a nested submenu.

Reach for a `ContextMenu` for actions tied to a **specific object** (a file, a row, a canvas) that users invoke by right-clicking it. For a menu opened from a visible button, use a [`DropdownMenu`](/ui/components/react/dropdown-menu) instead — and consider offering both for discoverability.

## Examples [#examples]

### Basic [#basic]

Right-click the area to open a standard edit menu with leading icons and trailing [`Kbd`](/ui/components/react/kbd) shortcuts.

```tsx
import {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
} from '@appica/ui-react/context-menu'
import { Kbd } from '@appica/ui-react/kbd'
import { Copy, Scissors, Clipboard, Trash } from '@appica/icons-react'

export default function ContextMenuDefault() {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="bg-background-subtle border-border-strong flex h-40 w-72 items-center justify-center rounded-xl border border-dashed text-sm select-none">
        Right-click here
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuItem>
          <Copy data-icon="start" />
          Copy
          <Kbd size="sm" className="ms-auto">
            ⌘C
          </Kbd>
        </ContextMenuItem>
        <ContextMenuItem>
          <Scissors data-icon="start" />
          Cut
          <Kbd size="sm" className="ms-auto">
            ⌘X
          </Kbd>
        </ContextMenuItem>
        <ContextMenuItem>
          <Clipboard data-icon="start" />
          Paste
          <Kbd size="sm" className="ms-auto">
            ⌘V
          </Kbd>
        </ContextMenuItem>
        <ContextMenuSeparator />
        <ContextMenuItem className="text-error-emphasis! data-highlighted:before:bg-error-subtle!">
          <Trash data-icon="start" />
          Delete
        </ContextMenuItem>
      </ContextMenuContent>
    </ContextMenu>
  )
}
```

### On a card [#on-a-card]

The trigger can wrap any content — here a file card. Right-click it for object-specific actions, including a "Move to" submenu and a destructive delete.

```tsx
import {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuSub,
  ContextMenuSubTrigger,
  ContextMenuSubContent,
} from '@appica/ui-react/context-menu'
import { Photo, Download, Pencil, Link, Folder, Star, Trash } from '@appica/icons-react'

export default function ContextMenuCard() {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="block w-56 cursor-default text-left select-none">
        <div className="bg-background-muted text-foreground-subtle flex aspect-video items-center justify-center rounded-xl">
          <Photo className="size-8" />
        </div>
        <p className="text-foreground-intense mt-2 text-sm font-medium">cover-art.png</p>
        <p className="text-foreground-muted text-xs">1.2 MB · PNG</p>
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuItem>
          <Download data-icon="start" />
          Download
        </ContextMenuItem>
        <ContextMenuItem>
          <Pencil data-icon="start" />
          Rename
        </ContextMenuItem>
        <ContextMenuItem>
          <Link data-icon="start" />
          Copy link
        </ContextMenuItem>
        <ContextMenuSub>
          <ContextMenuSubTrigger>
            <Folder data-icon="start" />
            Move to
          </ContextMenuSubTrigger>
          <ContextMenuSubContent>
            <ContextMenuItem>Projects</ContextMenuItem>
            <ContextMenuItem>Archive</ContextMenuItem>
            <ContextMenuItem>Trash</ContextMenuItem>
          </ContextMenuSubContent>
        </ContextMenuSub>
        <ContextMenuSeparator />
        <ContextMenuItem>
          <Star data-icon="start" />
          Add to favorites
        </ContextMenuItem>
        <ContextMenuItem className="text-error-emphasis! data-highlighted:before:bg-error-subtle!">
          <Trash data-icon="start" />
          Delete
        </ContextMenuItem>
      </ContextMenuContent>
    </ContextMenu>
  )
}
```

### Checkbox & radio items [#checkbox--radio-items]

The same stateful items as `DropdownMenu`: `ContextMenuCheckboxItem` toggles booleans (and keeps the menu open), while a `ContextMenuRadioGroup` of `ContextMenuRadioItem`s picks one value.

```tsx
'use client'

import * as React from 'react'
import {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuGroupLabel,
  ContextMenuCheckboxItem,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSeparator,
} from '@appica/ui-react/context-menu'

export default function ContextMenuSelections() {
  const [showGrid, setShowGrid] = React.useState(true)
  const [showRulers, setShowRulers] = React.useState(false)
  const [zoom, setZoom] = React.useState('fit')

  return (
    <ContextMenu>
      <ContextMenuTrigger className="bg-background-subtle border-border-strong flex h-40 w-72 items-center justify-center rounded-xl border border-dashed text-sm select-none">
        Right-click the canvas
      </ContextMenuTrigger>
      <ContextMenuContent className="w-50">
        <ContextMenuGroup>
          <ContextMenuGroupLabel>View</ContextMenuGroupLabel>
          <ContextMenuCheckboxItem checked={showGrid} onCheckedChange={setShowGrid}>
            Show grid
          </ContextMenuCheckboxItem>
          <ContextMenuCheckboxItem checked={showRulers} onCheckedChange={setShowRulers}>
            Show rulers
          </ContextMenuCheckboxItem>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuRadioGroup value={zoom} onValueChange={setZoom}>
          <ContextMenuGroupLabel>Zoom</ContextMenuGroupLabel>
          <ContextMenuRadioItem value="fit">Fit to screen</ContextMenuRadioItem>
          <ContextMenuRadioItem value="100">100%</ContextMenuRadioItem>
          <ContextMenuRadioItem value="200">200%</ContextMenuRadioItem>
        </ContextMenuRadioGroup>
      </ContextMenuContent>
    </ContextMenu>
  )
}
```

### Sizes [#sizes]

`size` on the root scales the popup radius, item padding, and icon size — `sm`, `md` (default), or `lg`.

```tsx
import {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
} from '@appica/ui-react/context-menu'

const SIZES = ['sm', 'md', 'lg'] as const

export default function ContextMenuSizes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {SIZES.map((size) => (
        <ContextMenu key={size} size={size}>
          <ContextMenuTrigger className="bg-background-subtle border-border-strong flex h-24 w-32 items-center justify-center rounded-xl border border-dashed text-sm select-none">
            {size}
          </ContextMenuTrigger>
          <ContextMenuContent>
            <ContextMenuItem>Copy</ContextMenuItem>
            <ContextMenuItem>Paste</ContextMenuItem>
            <ContextMenuSeparator />
            <ContextMenuItem>Delete</ContextMenuItem>
          </ContextMenuContent>
        </ContextMenu>
      ))}
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and submenu direction — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The menu opens at the pointer and grows toward the inline-start side, with submenus and chevrons mirrored. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<Callout type="note" title="Scoped RTL needs the direction on the positioner">
  The popup portals to `<body>`, so its `start`/`end` alignment mirrors from the **document** direction (read from CSS,
  not from `DirectionProvider`) — automatic when `<html dir="rtl">`. If you instead scope RTL to a subtree of an LTR page,
  set it on the positioner so alignment still mirrors: `<ContextMenuContent positionerProps={{ dir: 'rtl' }}>`. See
  [Floating popups in a scoped RTL region](/ui/docs/react/rtl#floating-popups-in-a-scoped-rtl-region).
</Callout>

<RtlPreview component="context-menu" />

## API reference [#api-reference]

`ContextMenu` wraps [Base UI's Context Menu](https://base-ui.com/react/components/context-menu). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### ContextMenu [#contextmenu]

The root. Holds the open state and the shared `size`; renders no DOM of its own.

| Prop           | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth>        |
| -------------- | ------------------------------------------- | ------- | --------------------------------------------------------- |
| `size`         | <Code>'sm' \| 'md' \| 'lg'</Code>           | `'md'`  | Scales the popup radius, item padding, and icon size.     |
| `open`         | `boolean`                                   | —       | Controlled open state. Pair with `onOpenChange`.          |
| `defaultOpen`  | `boolean`                                   | `false` | Uncontrolled initial open state.                          |
| `onOpenChange` | <Code>(open, eventDetails) => void</Code>   | —       | Fires when the menu opens or closes.                      |
| `disabled`     | `boolean`                                   | `false` | Stop the trigger area from opening a menu.                |
| `loopFocus`    | `boolean`                                   | `true`  | Wrap keyboard focus from the last item back to the first. |

### ContextMenuTrigger [#contextmenutrigger]

The target area. Right-click or long-press inside it opens the menu at the pointer. Renders a `div` by default and forwards every native prop.

| Prop        | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                             |
| ----------- | ----------------------------------------------------------- | ------- | --------------------------------------- |
| `render`    | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render the trigger as your own element. |
| `className` | `string`                                                    | —       | Extra classes on the trigger area.      |

### ContextMenuContent [#contextmenucontent]

The portalled, pointer-positioned popup wrapping the list. Defaults to `align="start"` and `sideOffset={2}`, and accepts the shared floating props.

| Prop               | <ColMinWidth width="160">Type</ColMinWidth>         | Default    | Description                                                     |
| ------------------ | --------------------------------------------------- | ---------- | --------------------------------------------------------------- |
| `side`             | <Code>'top' \| 'right' \| 'bottom' \| 'left'</Code> | `'bottom'` | Preferred side to grow toward from the pointer.                 |
| `align`            | <Code>'start' \| 'center' \| 'end'</Code>           | `'start'`  | Alignment along that side.                                      |
| `sideOffset`       | `number`                                            | `2`        | Gap between the pointer and the popup.                          |
| `alignOffset`      | `number`                                            | —          | Shift along the alignment axis.                                 |
| `collisionPadding` | `number`                                            | `5`        | Minimum gap kept from the viewport edge when flipping/shifting. |
| `container`        | <Code>HTMLElement \| ref \| null</Code>             | —          | Portal target — render the popup into a different node.         |
| `keepMounted`      | `boolean`                                           | `false`    | Keep the popup mounted in the DOM while closed.                 |
| `positionerProps`  | `object`                                            | —          | Escape hatch for the positioner element (`style`, `render`, …). |
| `portalProps`      | `object`                                            | —          | Escape hatch for the portal element (`style`, `render`, …).     |
| `className`        | `string`                                            | —          | Extra classes on the popup.                                     |

### ContextMenuItem [#contextmenuitem]

One action in the menu.

| Prop           | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                                                    |
| -------------- | ------------------------------------------- | ------- | -------------------------------------------------------------- |
| `closeOnClick` | `boolean`                                   | `true`  | Close the menu after the item is selected.                     |
| `disabled`     | `boolean`                                   | `false` | Make the item unselectable; skipped by keyboard and typeahead. |
| `onClick`      | <Code>(event) => void</Code>                | —       | Fires when the item is selected (click or Enter/Space).        |
| `className`    | `string`                                    | —       | Extra classes, merged via `tailwind-merge`.                    |

### ContextMenuCheckboxItem [#contextmenucheckboxitem]

A toggleable item with a check indicator. Keeps the menu open on click.

| Prop              | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                                            |
| ----------------- | ------------------------------------------- | ------- | ------------------------------------------------------ |
| `checked`         | `boolean`                                   | —       | Controlled checked state. Pair with `onCheckedChange`. |
| `defaultChecked`  | `boolean`                                   | `false` | Uncontrolled initial checked state.                    |
| `onCheckedChange` | <Code>(checked) => void</Code>              | —       | Fires when the checked state changes.                  |
| `closeOnClick`    | `boolean`                                   | `false` | Close the menu when toggled.                           |
| `disabled`        | `boolean`                                   | `false` | Make the item unselectable.                            |

### ContextMenuRadioGroup [#contextmenuradiogroup]

Wraps a set of mutually exclusive `ContextMenuRadioItem`s.

| Prop            | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                                           |
| --------------- | ------------------------------------------- | ------- | ----------------------------------------------------- |
| `value`         | `string`                                    | —       | Controlled selected value. Pair with `onValueChange`. |
| `defaultValue`  | `string`                                    | —       | Uncontrolled initial value.                           |
| `onValueChange` | <Code>(value) => void</Code>                | —       | Fires when the selection changes.                     |

### ContextMenuRadioItem [#contextmenuradioitem]

One option in a `ContextMenuRadioGroup`. Keeps the menu open on click.

| Prop           | Type      | Default | Description                   |
| -------------- | --------- | ------- | ----------------------------- |
| `value`        | `string`  | —       | The value this item selects.  |
| `closeOnClick` | `boolean` | `false` | Close the menu when chosen.   |
| `disabled`     | `boolean` | `false` | Make the option unselectable. |

### ContextMenuLinkItem [#contextmenulinkitem]

An item that renders an `<a>` for navigation. Forwards every native anchor prop (`href`, `target`, `rel`, …).

| Prop        | Type     | Default | Description                                 |
| ----------- | -------- | ------- | ------------------------------------------- |
| `href`      | `string` | —       | Navigation target.                          |
| `className` | `string` | —       | Extra classes, merged via `tailwind-merge`. |

### ContextMenuGroup [#contextmenugroup]

Wraps one labelled section of items so a `ContextMenuGroupLabel` can name it.

| Prop        | Type        | Default | Description                                         |
| ----------- | ----------- | ------- | --------------------------------------------------- |
| `children`  | `ReactNode` | —       | A `ContextMenuGroupLabel` plus the section's items. |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`.         |

### ContextMenuGroupLabel [#contextmenugrouplabel]

The visible heading for a `ContextMenuGroup`. Size-aware; must be rendered inside a `ContextMenuGroup` (or `ContextMenuRadioGroup`).

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The label text.                             |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### ContextMenuSeparator [#contextmenuseparator]

A thin divider between items or groups.

| Prop        | Type     | Default | Description                                 |
| ----------- | -------- | ------- | ------------------------------------------- |
| `className` | `string` | —       | Extra classes, merged via `tailwind-merge`. |

### ContextMenuSub [#contextmenusub]

Wraps a nested submenu. Forwards Base UI's `ContextMenu.SubmenuRoot`.

| Prop          | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                           |
| ------------- | ------------------------------------------- | ------- | ------------------------------------- |
| `open`        | `boolean`                                   | —       | Controlled open state of the submenu. |
| `defaultOpen` | `boolean`                                   | `false` | Uncontrolled initial open state.      |

### ContextMenuSubTrigger [#contextmenusubtrigger]

The item that opens a submenu; renders a trailing chevron. Submenus open on hover by default.

| Prop          | Type      | Default | Description                                 |
| ------------- | --------- | ------- | ------------------------------------------- |
| `openOnHover` | `boolean` | `true`  | Open the submenu on hover (and on click).   |
| `delay`       | `number`  | `100`   | Hover-open delay in ms.                     |
| `closeDelay`  | `number`  | `0`     | Hover-close delay in ms.                    |
| `className`   | `string`  | —       | Extra classes, merged via `tailwind-merge`. |

### ContextMenuSubContent [#contextmenusubcontent]

The submenu popup. Defaults to opening on the `inline-end` side; otherwise identical to `ContextMenuContent`.

| Prop        | Type     | Default | Description                         |
| ----------- | -------- | ------- | ----------------------------------- |
| `className` | `string` | —       | Extra classes on the submenu popup. |

## Accessibility [#accessibility]

* The popup has `role="menu"`; items are `menuitem`, `menuitemcheckbox`, or `menuitemradio`.
* Opens on `contextmenu` (right-click) or long-press; **Shift + F10** and the dedicated **Menu** key open it from the keyboard when the trigger is focused.
* **↑/↓*&#x2A; move the highlight, &#x2A;*→/←** open and close submenus, **Enter** selects, **Escape** closes, and typeahead jumps to matching items.
* Focus moves into the popup on open and returns to the triggering element on close.
* `disabled` items are skipped by keyboard navigation and typeahead.
* Popup enter/exit transitions are skipped when the user prefers reduced motion.


# Copy Button (/ui/components/react/copy-button)



<Playground component="copy-button" />

## Usage [#usage]

```tsx
import { CopyButton } from '@appica/ui-react/copy-button'
```

```tsx
<CopyButton value="npm install @appica/ui-react" />
```

`CopyButton` writes `value` to the clipboard on click, then swaps its copy icon for an animated check for a couple of seconds. It's built on [`Button`](/ui/components/react/button), so it takes every Button prop (`variant`, `size`, `disabled`, …) — it just defaults to a `ghost` `icon-sm` icon button.

`value` is flexible: a **string**, a **function** returning a string (or a promise of one — handy for computing the text lazily), or a **ref** to an element, in which case its `value` (inputs/textareas) or `textContent` is copied. That makes it a natural fit in the corner of a code block or input.

## Examples [#examples]

### Variants [#variants]

`CopyButton` forwards `variant` (and any Button prop) straight through.

```tsx
import { CopyButton } from '@appica/ui-react/copy-button'

export default function CopyButtonVariants() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <CopyButton value="Ghost" variant="ghost" />
      <CopyButton value="Soft" variant="soft" />
      <CopyButton value="Outline" variant="outline" />
      <CopyButton value="Primary Outline" variant="primary-outline" />
      <CopyButton value="Primary" variant="primary" />
      <CopyButton value="Secondary" variant="secondary" />
    </div>
  )
}
```

### Sizes [#sizes]

Size comes from [`Button`](/ui/components/react/button): use the square `icon-sm` / `icon-md` / `icon-lg` for an icon-only button (the default is `icon-sm`), or `sm` / `md` / `lg` when you add a text label.

```tsx
import { CopyButton } from '@appica/ui-react/copy-button'

export default function CopyButtonSizes() {
  return (
    <div className="flex items-center gap-3">
      <CopyButton value="Small" variant="outline" size="icon-sm" />
      <CopyButton value="Medium" variant="outline" size="icon-md" />
      <CopyButton value="Large" variant="outline" size="icon-lg" />
    </div>
  )
}
```

### With a label [#with-a-label]

Pass children to show text beside the icon. A string label automatically swaps to `copiedLabel` on success, mirroring the check animation.

```tsx
import { CopyButton } from '@appica/ui-react/copy-button'

export default function CopyButtonWithLabel() {
  return (
    <CopyButton value="npm install @appica/ui-react" variant="outline" size="sm" copiedLabel="Copied!">
      Copy
    </CopyButton>
  )
}
```

### Copy from an element [#copy-from-an-element]

Give `value` a ref instead of a string to copy another element's content — here a code snippet. The button copies the element's `textContent` (or the `value` of an input/textarea).

```tsx
'use client'

import { useRef } from 'react'
import { CopyButton } from '@appica/ui-react/copy-button'

export default function CopyButtonFromElement() {
  const codeRef = useRef<HTMLElement>(null)
  return (
    <div className="border-border-muted bg-background-subtle relative w-full max-w-90 rounded-lg border py-3 ps-4 pe-12">
      <code ref={codeRef} className="text-foreground font-mono text-sm">
        npm install @appica/ui-react
      </code>
      <div className="absolute inset-e-2 top-1/2 -translate-y-1/2">
        <CopyButton value={codeRef} label="Copy command" />
      </div>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The icon and label swap sides to follow the resolved direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="copy-button" />

## API reference [#api-reference]

### CopyButton [#copybutton]

Extends [`Button`](/ui/components/react/button) — every Button prop applies. The props below are the copy-specific additions and defaults.

| Prop          | <ColMinWidth width="200">Type</ColMinWidth>                                          | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                                          |
| ------------- | ------------------------------------------------------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------- |
| `value`       | <Code>string \| RefObject\<HTMLElement> \| (() => string \| Promise\<string>)</Code> | —           | **Required.** What to copy: a string, an element ref (its value/textContent), or a (possibly async) getter. |
| `label`       | `string`                                                                             | `'Copy'`    | Accessible name (and tooltip via `title`) in the idle state.                                                |
| `copiedLabel` | `string`                                                                             | `'Copied'`  | Accessible name after a successful copy; a string child also swaps to this.                                 |
| `timeout`     | `number`                                                                             | `2000`      | How long (ms) the copied state lasts before reverting.                                                      |
| `onCopy`      | <Code>(value: string) => void</Code>                                                 | —           | Called with the copied text on success.                                                                     |
| `onCopyError` | <Code>(error: unknown) => void</Code>                                                | —           | Called if reading the value or writing to the clipboard fails.                                              |
| `variant`     | <Code>Button variant</Code>                                                          | `'ghost'`   | Inherited from `Button`; defaults to `ghost`.                                                               |
| `size`        | <Code>Button size</Code>                                                             | `'icon-sm'` | Inherited from `Button`; defaults to the small icon size.                                                   |
| `children`    | `ReactNode`                                                                          | —           | Optional visible label beside the icon.                                                                     |

`CopyButton` falls back to a hidden-`textarea` + `execCommand('copy')` when the async Clipboard API is unavailable, and exposes `data-copied` while in the copied state for styling.

## Accessibility [#accessibility]

* Renders a real `<button>` with an accessible name from `label` (and `copiedLabel` once copied), so an icon-only button is still announced.
* The copied state is conveyed by the accessible-name change, not color alone.
* `disabled` (a Button prop) blocks the copy and exposes `data-disabled` for styling.
* The icon cross-fade and check-draw animations honour `prefers-reduced-motion`.


# Countdown (/ui/components/react/countdown)



<Playground component="countdown" />

## Usage [#usage]

```tsx
import { Countdown, CountdownSegment } from '@appica/ui-react/countdown'
```

```tsx
<Countdown targetDate="2027-01-01T00:00:00Z">
  <CountdownSegment unit="days" /> <span>days</span>
  <CountdownSegment unit="hours" /> <span>hours</span>
  <CountdownSegment unit="minutes" /> <span>minutes</span>
  <CountdownSegment unit="seconds" /> <span>seconds</span>
</Countdown>
```

`Countdown` is the timing engine: give it a `targetDate` (a `Date`, epoch-ms number, or date
string) or a relative `duration` in seconds, and it ticks down once per second, breaking the
remaining time into `days` / `hours` / `minutes` / `seconds`. Each `CountdownSegment` reads one
of those units from context and renders it as **rolling digits** — every digit is a `0–9` strip
moved with a GPU `transform`, so changes slide like an odometer without thrashing layout.

It's intentionally **headless**: the root is just an `inline-flex` wrapper and the segments add no
styling of their own — they inherit the font, size, and color from your markup. There are **no
built-in labels** — you compose "Days/Hours/…" text (and any separators or boxes) yourself, styling
everything through `className`.

### Time zones [#time-zones]

`Countdown` has no `timeZone` prop, and it doesn't need one. The remaining time is `target − now`,
a subtraction of two **absolute instants** (both UTC epoch-milliseconds under the hood), so the
result is a duration — and a duration is the same everywhere. "3 hours left" is 3 hours in every
zone at once, so there is nothing for a time zone to change.

Time zones only matter when you decide *which instant* `targetDate` is — and you do that when you
construct it, before the component sees it. Pass an offset-bearing string or a real `Date`, and the
countdown is identical for every viewer:

```tsx
<Countdown targetDate="2027-01-01T00:00:00+09:00" /> // midnight in Tokyo, for everyone
<Countdown targetDate="2027-01-01T00:00:00Z" /> // midnight UTC
<Countdown targetDate={new Date(Date.UTC(2027, 0, 1))} /> // also an absolute instant
```

<Callout type="warning" title="Avoid zone-less local strings">
  A string without an offset — `"2027-01-01T00:00:00"` — is parsed in **each viewer's own** time zone, so it points at a
  different instant for everyone. Always include an offset (`+09:00`) or a trailing `Z`, or compute the instant with a
  `date-fns` time-zone helper and pass the resulting `Date`.
</Callout>

## Examples [#examples]

### Labelled countdown [#labelled-countdown]

Wrap each `CountdownSegment` with your own label and size it however you like. The digits stay
aligned because the segment uses tabular figures.

```tsx
import { Countdown, CountdownSegment } from '@appica/ui-react/countdown'

type Unit = 'days' | 'hours' | 'minutes' | 'seconds'

function Field({ unit, label }: { unit: Unit; label: string }) {
  return (
    <div className="flex flex-col items-center">
      <CountdownSegment unit={unit} className="text-foreground-intense text-4xl font-semibold" />
      <span className="text-foreground-muted mt-1 text-sm">{label}</span>
    </div>
  )
}

export default function CountdownDefault() {
  return (
    <Countdown targetDate="2027-01-01T00:00:00Z" className="gap-6" aria-label="Time until 2027">
      <Field unit="days" label="Days" />
      <Field unit="hours" label="Hours" />
      <Field unit="minutes" label="Minutes" />
      <Field unit="seconds" label="Seconds" />
    </Countdown>
  )
}
```

### Relative duration [#relative-duration]

Pass `duration` (seconds from mount) instead of `targetDate` for timers like a flash sale, and use
`onComplete` to react when it hits zero.

```tsx
'use client'

import { useState } from 'react'
import { Button } from '@appica/ui-react/button'
import { Countdown, CountdownSegment } from '@appica/ui-react/countdown'

export default function CountdownDuration() {
  const [done, setDone] = useState(false)

  if (done) {
    return (
      <div className="flex flex-col items-center gap-3">
        <p className="text-foreground-intense text-lg font-semibold">Time&apos;s up! 🎉</p>
        <Button variant="outline" size="sm" onClick={() => setDone(false)}>
          Restart
        </Button>
      </div>
    )
  }

  return (
    <Countdown
      duration={20}
      onComplete={() => setDone(true)}
      className="text-foreground-intense gap-1 text-3xl font-semibold"
      aria-label="Offer ends in"
    >
      <CountdownSegment unit="minutes" />
      <span className="text-foreground-muted">:</span>
      <CountdownSegment unit="seconds" />
    </Countdown>
  )
}
```

### Custom styling [#custom-styling]

Because every part takes a `className` (merged via `tailwind-merge`), you can box each segment, add
separators, or restyle the digits entirely.

```tsx
import { Countdown, CountdownSegment } from '@appica/ui-react/countdown'

const box =
  'bg-background-subtle text-foreground-intense rounded-lg border px-3 py-3.5 font-mono text-2xl font-semibold'

export default function CountdownStyled() {
  return (
    <Countdown targetDate="2027-01-01T00:00:00Z" className="gap-2" aria-label="Time remaining">
      <CountdownSegment unit="hours" className={box} />
      <span className="text-foreground-muted self-center text-2xl font-semibold">:</span>
      <CountdownSegment unit="minutes" className={box} />
      <span className="text-foreground-muted self-center text-2xl font-semibold">:</span>
      <CountdownSegment unit="seconds" className={box} />
    </Countdown>
  )
}
```

### Standalone rolling number [#standalone-rolling-number]

`CountdownSegment` also works on its own — pass a `value` instead of a `unit` to animate any number
you drive yourself, no timer required.

```tsx
'use client'

import { useState } from 'react'
import { Button } from '@appica/ui-react/button'
import { CountdownSegment } from '@appica/ui-react/countdown'

export default function CountdownValue() {
  const [value, setValue] = useState(8)

  return (
    <div className="flex items-center gap-5">
      <CountdownSegment value={value} className="text-foreground-intense text-5xl font-semibold" />
      <div className="flex gap-2">
        <Button variant="outline" size="sm" onClick={() => setValue((v) => Math.max(0, v - 1))}>
          -1
        </Button>
        <Button variant="outline" size="sm" onClick={() => setValue((v) => v + 1)}>
          +1
        </Button>
        <Button variant="outline" size="sm" onClick={() => setValue((v) => v + 10)}>
          +10
        </Button>
      </div>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a
container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your
tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The segments reorder to follow the resolved direction, while the digits themselves keep rolling
vertically — numbers read the same in any direction. For setup details and caveats, see the
[RTL guide](/ui/docs/react/rtl).

<RtlPreview component="countdown" />

## API reference [#api-reference]

### Countdown [#countdown]

The timing engine and headless container. Renders a `<div role="timer">` and provides the remaining
time to its `CountdownSegment` children.

| Prop         | <ColMinWidth width="200">Type</ColMinWidth>      | Default | <ColMinWidth width="220">Description</ColMinWidth>                                                      |
| ------------ | ------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------- |
| `targetDate` | <Code>Date \| number \| string</Code>            | —       | Absolute instant to count down to (a `Date`, epoch-ms, or date string).                                 |
| `duration`   | `number`                                         | —       | Relative length in **seconds** from mount. Ignored when `targetDate` is set.                            |
| `interval`   | `number`                                         | `1000`  | Tick interval in milliseconds.                                                                          |
| `onComplete` | <Code>() => void</Code>                          | —       | Fired once when the countdown reaches zero.                                                             |
| `children`   | <Code>ReactNode \| ((parts) => ReactNode)</Code> | —       | Segments and labels, or a render-prop receiving `{ days, hours, minutes, seconds, total, isComplete }`. |

Forwards `ref`, `className`, `aria-*`, and any other `<div>` attributes. Use `aria-label` to name the
timer (e.g. "Offer ends in").

### CountdownSegment [#countdownsegment]

Renders one unit as rolling digits. Use it inside a `Countdown` with `unit`, or standalone with `value`.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth>              | Default | <ColMinWidth width="220">Description</ColMinWidth>                           |
| ----------- | -------------------------------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `unit`      | <Code>'days' \| 'hours' \| 'minutes' \| 'seconds'</Code> | —       | Which unit to read from the parent `Countdown`.                              |
| `value`     | `number`                                                 | —       | Render this number directly instead of reading context (standalone display). |
| `minDigits` | `number`                                                 | `2`     | Minimum digit count; the value is zero-padded to this width.                 |

Forwards `ref`, `className`, and any other `<span>` attributes. The digit rollers honour
`prefers-reduced-motion` (snapping instantly instead of sliding).

## Accessibility [#accessibility]

* The root renders `role="timer"`; give it an `aria-label` describing what it counts down to.
* The animated digits are `aria-hidden`; each segment also renders an `sr-only` plain-text value so
  screen readers announce the number (with your adjacent label text).
* The timer does **not** announce on every tick by default (no `aria-live`), avoiding once-a-second
  spam. Add `aria-live="polite"` to the root yourself if live updates are appropriate.
* Digit rolling honours `prefers-reduced-motion` — digits update instantly without the slide.


# Data Table (/ui/components/react/data-table)



A data table isn't a single component. It's a **recipe**: you keep your own column model and feature logic in [TanStack Table](https://tanstack.com/table) — a headless, unstyled engine — and render its output with Appica UI components: [`Table`](/ui/components/react/table), [`Checkbox`](/ui/components/react/checkbox), [`Thumbnail`](/ui/components/react/thumbnail), [`Badge`](/ui/components/react/badge), [`Input`](/ui/components/react/input), [`Dropdown Menu`](/ui/components/react/dropdown-menu), and [`Scroll Area`](/ui/components/react/scroll-area).

This page is one complete, copy-pasteable example rather than a packaged component — adapt the columns and data to your own shape.

## Installation [#installation]

TanStack Table is the only extra dependency. It ships its own types, so nothing else is needed.

<InstallTabs name="@tanstack/react-table" />

## Example [#example]

A transactions table with row selection, a searchable global filter, sortable columns, a show/hide columns menu, per-row actions, and client pagination. Resize the frame down and the table scrolls horizontally instead of cramping.

```tsx
'use client'

import * as React from 'react'
import {
  type Column,
  type ColumnDef,
  type SortingState,
  type VisibilityState,
  flexRender,
  getCoreRowModel,
  getFilteredRowModel,
  getPaginationRowModel,
  getSortedRowModel,
  useReactTable,
} from '@tanstack/react-table'
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'
import { ScrollArea } from '@appica/ui-react/scroll-area'
import { Checkbox } from '@appica/ui-react/checkbox'
import { Thumbnail } from '@appica/ui-react/thumbnail'
import { Badge } from '@appica/ui-react/badge'
import { Input } from '@appica/ui-react/input'
import { Button } from '@appica/ui-react/button'
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuGroupLabel,
  DropdownMenuItem,
  DropdownMenuCheckboxItem,
  DropdownMenuSeparator,
} from '@appica/ui-react/dropdown-menu'
import {
  Search,
  LayoutColumns,
  ChevronDown,
  ChevronUp,
  ChevronsUpDown,
  ChevronLeft,
  ChevronRight,
  DotsVertical,
  BriefcaseFilled,
  BoltFilled,
  DropletHalf2Filled,
  Eye,
  Copy,
  Pencil,
  Trash,
} from '@appica/icons-react'

type Category = 'Income' | 'Entertainment' | 'Bill' | 'Medical' | 'Food & Drinks' | 'Transport'

type Transaction = {
  id: string
  date: string
  description: string
  thumb: { type: 'image'; src: string } | { type: 'icon'; icon: React.ReactNode }
  account: string
  category: Category
  status: 'Completed' | 'Pending'
  amount: number
}

const CATEGORY_DOT: Record<Category, string> = {
  Income: 'bg-lime-500',
  Entertainment: 'bg-violet-500',
  Bill: 'bg-info-emphasis',
  Medical: 'bg-success-emphasis',
  'Food & Drinks': 'bg-pink-500',
  Transport: 'bg-warning-emphasis',
}

const COLUMN_LABELS: Record<string, string> = {
  date: 'Date',
  description: 'Description',
  account: 'Account',
  category: 'Category',
  status: 'Status',
  amount: 'Amount',
}

const TRANSACTIONS: Transaction[] = [
  {
    id: 'TXN-1042',
    date: '2026-08-30T17:23:21',
    description: 'Salary - TechNova Inc.',
    thumb: { type: 'icon', icon: <BriefcaseFilled /> },
    account: '1842',
    category: 'Income',
    status: 'Completed',
    amount: 4150,
  },
  {
    id: 'TXN-1041',
    date: '2026-08-24T07:18:53',
    description: 'Netflix Subscription',
    thumb: { type: 'image', src: '/data-table/netflix.jpg' },
    account: '1842',
    category: 'Entertainment',
    status: 'Pending',
    amount: -20,
  },
  {
    id: 'TXN-1040',
    date: '2026-08-17T09:15:00',
    description: 'Utility Bill - Electricity',
    thumb: { type: 'icon', icon: <BoltFilled /> },
    account: '1842',
    category: 'Bill',
    status: 'Pending',
    amount: -186.35,
  },
  {
    id: 'TXN-1039',
    date: '2026-08-17T08:34:46',
    description: 'Utility Bill - Water',
    thumb: { type: 'icon', icon: <DropletHalf2Filled /> },
    account: '1842',
    category: 'Bill',
    status: 'Completed',
    amount: -39.78,
  },
  {
    id: 'TXN-1038',
    date: '2026-08-13T00:27:19',
    description: 'Health Insurance',
    thumb: { type: 'image', src: '/data-table/health.jpg' },
    account: '1842',
    category: 'Medical',
    status: 'Completed',
    amount: -248,
  },
  {
    id: 'TXN-1037',
    date: '2026-08-10T02:30:52',
    description: "McDonald's",
    thumb: { type: 'image', src: '/data-table/mcdonalds.jpg' },
    account: '1842',
    category: 'Food & Drinks',
    status: 'Completed',
    amount: -32.67,
  },
  {
    id: 'TXN-1034',
    date: '2026-08-07T22:50:13',
    description: 'Uber Taxi',
    thumb: { type: 'image', src: '/data-table/uber.jpg' },
    account: '1842',
    category: 'Transport',
    status: 'Completed',
    amount: -25.4,
  },
  {
    id: 'TXN-1036',
    date: '2026-08-05T04:45:21',
    description: 'Starbucks',
    thumb: { type: 'image', src: '/data-table/starbucks.jpg' },
    account: '1842',
    category: 'Food & Drinks',
    status: 'Completed',
    amount: -7.99,
  },
  {
    id: 'TXN-1035',
    date: '2026-07-30T18:19:00',
    description: 'Salary - TechNova Inc.',
    thumb: { type: 'icon', icon: <BriefcaseFilled /> },
    account: '1842',
    category: 'Income',
    status: 'Completed',
    amount: 3980,
  },
  {
    id: 'TXN-1033',
    date: '2026-07-21T15:15:40',
    description: 'Burger King',
    thumb: { type: 'image', src: '/data-table/burger-king.jpg' },
    account: '1842',
    category: 'Food & Drinks',
    status: 'Completed',
    amount: -14.99,
  },
  {
    id: 'TXN-1032',
    date: '2026-07-19T19:36:23',
    description: 'Uklon Taxi',
    thumb: { type: 'image', src: '/data-table/uklon.jpg' },
    account: '1842',
    category: 'Transport',
    status: 'Completed',
    amount: -18.5,
  },
  {
    id: 'TXN-1031',
    date: '2026-07-12T08:05:11',
    description: 'Uber Taxi',
    thumb: { type: 'image', src: '/data-table/uber.jpg' },
    account: '1842',
    category: 'Transport',
    status: 'Completed',
    amount: -31.2,
  },
  {
    id: 'TXN-1030',
    date: '2026-07-08T13:22:47',
    description: 'Starbucks',
    thumb: { type: 'image', src: '/data-table/starbucks.jpg' },
    account: '1842',
    category: 'Food & Drinks',
    status: 'Pending',
    amount: -6.45,
  },
  {
    id: 'TXN-1029',
    date: '2026-06-30T17:00:00',
    description: 'Salary - TechNova Inc.',
    thumb: { type: 'icon', icon: <BriefcaseFilled /> },
    account: '1842',
    category: 'Income',
    status: 'Completed',
    amount: 4150,
  },
]

function formatDate(iso: string) {
  const date = new Date(iso)
  const datePart = new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric', year: 'numeric' }).format(date)
  const timePart = new Intl.DateTimeFormat('en-US', {
    hour: 'numeric',
    minute: '2-digit',
    hour12: true,
  }).format(date)
  return `${datePart} ${timePart}`
}

function formatAmount(amount: number) {
  const value = Math.abs(amount).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })
  return `${amount > 0 ? '+' : '-'} $${value}`
}

function TransactionThumb({ transaction }: { transaction: Transaction }) {
  if (transaction.thumb.type === 'image') {
    return <Thumbnail size="sm" shape="circle" src={transaction.thumb.src} alt={transaction.description} />
  }
  return (
    <Thumbnail size="sm" shape="circle" variant="icon-soft">
      {transaction.thumb.icon}
    </Thumbnail>
  )
}

function SortableHeader({ column, children }: { column: Column<Transaction>; children: React.ReactNode }) {
  const sorted = column.getIsSorted()
  return (
    <button
      type="button"
      onClick={() => column.toggleSorting(sorted === 'asc')}
      className="hover:text-foreground-intense focus-visible:outline-ring rounded-3xs -mx-1 inline-flex cursor-pointer items-center gap-1 px-1 outline-offset-2 focus-visible:outline-2 [&_svg]:size-4 [&_svg]:shrink-0 [&_svg]:stroke-[1.85]"
    >
      {children}
      {sorted === 'asc' ? (
        <ChevronUp />
      ) : sorted === 'desc' ? (
        <ChevronDown />
      ) : (
        <ChevronsUpDown className="text-foreground-muted" />
      )}
    </button>
  )
}

function RowActions() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={
          <Button variant="ghost" size="icon-sm" aria-label="Open actions menu">
            <DotsVertical />
          </Button>
        }
      />
      <DropdownMenuContent align="end">
        <DropdownMenuGroup>
          <DropdownMenuItem>
            <Eye data-icon="start" />
            View details
          </DropdownMenuItem>
          <DropdownMenuItem>
            <Copy data-icon="start" />
            Copy transaction ID
          </DropdownMenuItem>
          <DropdownMenuItem>
            <Pencil data-icon="start" />
            Edit
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuItem className="text-error-emphasis! data-highlighted:before:bg-error-subtle!">
          <Trash data-icon="start" />
          Delete
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

const columns: ColumnDef<Transaction>[] = [
  {
    id: 'select',
    header: ({ table }) => (
      <Checkbox
        checked={table.getIsAllPageRowsSelected()}
        indeterminate={table.getIsSomePageRowsSelected()}
        onCheckedChange={(checked) => table.toggleAllPageRowsSelected(checked === true)}
        aria-label="Select all rows"
      />
    ),
    cell: ({ row }) => (
      <Checkbox
        checked={row.getIsSelected()}
        onCheckedChange={(checked) => row.toggleSelected(checked === true)}
        aria-label="Select row"
      />
    ),
    enableSorting: false,
    enableHiding: false,
  },
  {
    accessorKey: 'date',
    header: ({ column }) => <SortableHeader column={column}>Date</SortableHeader>,
    cell: ({ row }) => formatDate(row.original.date),
  },
  {
    accessorKey: 'description',
    header: ({ column }) => <SortableHeader column={column}>Description</SortableHeader>,
    cell: ({ row }) => (
      <div className="flex items-center gap-3">
        <TransactionThumb transaction={row.original} />
        <span className="text-foreground-intense font-medium">{row.original.description}</span>
      </div>
    ),
  },
  {
    accessorKey: 'account',
    header: ({ column }) => <SortableHeader column={column}>Account</SortableHeader>,
    cell: ({ row }) => (
      <span>
        Checking <span className="text-foreground-muted">****{row.original.account}</span>
      </span>
    ),
  },
  {
    accessorKey: 'category',
    header: ({ column }) => <SortableHeader column={column}>Category</SortableHeader>,
    cell: ({ row }) => (
      <Badge variant="outline" className="gap-1.25">
        <span className={`size-2 shrink-0 rounded-full ${CATEGORY_DOT[row.original.category]}`} />
        {row.original.category}
      </Badge>
    ),
  },
  {
    accessorKey: 'status',
    header: ({ column }) => <SortableHeader column={column}>Status</SortableHeader>,
    cell: ({ row }) => row.original.status,
  },
  {
    accessorKey: 'amount',
    header: ({ column }) => <SortableHeader column={column}>Amount</SortableHeader>,
    cell: ({ row }) => (
      <span
        className={
          row.original.status === 'Pending'
            ? 'text-foreground-muted font-semibold'
            : 'text-foreground-intense font-semibold'
        }
      >
        {formatAmount(row.original.amount)}
      </span>
    ),
  },
  {
    id: 'actions',
    cell: () => <RowActions />,
    enableSorting: false,
    enableHiding: false,
  },
]

export default function DataTableExample() {
  const [sorting, setSorting] = React.useState<SortingState>([])
  const [columnVisibility, setColumnVisibility] = React.useState<VisibilityState>({})
  const [rowSelection, setRowSelection] = React.useState({})
  const [globalFilter, setGlobalFilter] = React.useState('')

  const table = useReactTable({
    data: TRANSACTIONS,
    columns,
    state: { sorting, columnVisibility, rowSelection, globalFilter },
    onSortingChange: setSorting,
    onColumnVisibilityChange: setColumnVisibility,
    onRowSelectionChange: setRowSelection,
    onGlobalFilterChange: setGlobalFilter,
    globalFilterFn: 'includesString',
    getCoreRowModel: getCoreRowModel(),
    getSortedRowModel: getSortedRowModel(),
    getFilteredRowModel: getFilteredRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
    initialState: { pagination: { pageSize: 8 } },
  })

  const rows = table.getRowModel().rows

  return (
    <div className="flex w-full flex-col gap-4">
      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
        <Input
          placeholder="Search transactions..."
          value={globalFilter}
          onChange={(event) => setGlobalFilter(event.target.value)}
          startSlot={<Search className="text-foreground-muted size-4" />}
          clearable
          onClear={() => setGlobalFilter('')}
          className="sm:max-w-2xs"
        />
        <DropdownMenu>
          <DropdownMenuTrigger
            className="group/columns"
            render={
              <Button variant="outline">
                <LayoutColumns data-icon="start" />
                Columns
                <ChevronDown
                  data-icon="end"
                  className="transition-transform duration-200 ease-out group-data-popup-open/columns:rotate-180 motion-reduce:transition-none"
                />
              </Button>
            }
          />
          <DropdownMenuContent align="end">
            <DropdownMenuGroup>
              <DropdownMenuGroupLabel>Toggle columns</DropdownMenuGroupLabel>
              {table
                .getAllColumns()
                .filter((column) => column.getCanHide())
                .map((column) => (
                  <DropdownMenuCheckboxItem
                    key={column.id}
                    checked={column.getIsVisible()}
                    onCheckedChange={(value) => column.toggleVisibility(value === true)}
                  >
                    {COLUMN_LABELS[column.id] ?? column.id}
                  </DropdownMenuCheckboxItem>
                ))}
            </DropdownMenuGroup>
          </DropdownMenuContent>
        </DropdownMenu>
      </div>

      <ScrollArea
        orientation="horizontal"
        scrollbarVisibility="auto"
        className="[&_td]:whitespace-nowrap [&_th]:whitespace-nowrap"
      >
        <Table hoverableRows>
          <TableHeader>
            {table.getHeaderGroups().map((headerGroup) => (
              <TableRow key={headerGroup.id}>
                {headerGroup.headers.map((header) => (
                  <TableHead key={header.id} className={header.column.id === 'amount' ? 'text-end' : undefined}>
                    {header.isPlaceholder ? null : flexRender(header.column.columnDef.header, header.getContext())}
                  </TableHead>
                ))}
              </TableRow>
            ))}
          </TableHeader>
          <TableBody>
            {rows.length ? (
              rows.map((row) => (
                <TableRow key={row.id} highlighted={row.getIsSelected()}>
                  {row.getVisibleCells().map((cell) => (
                    <TableCell key={cell.id} className={cell.column.id === 'amount' ? 'text-end' : undefined}>
                      {flexRender(cell.column.columnDef.cell, cell.getContext())}
                    </TableCell>
                  ))}
                </TableRow>
              ))
            ) : (
              <TableRow>
                <TableCell colSpan={columns.length} className="text-foreground-muted h-24 text-center">
                  No results.
                </TableCell>
              </TableRow>
            )}
          </TableBody>
        </Table>
      </ScrollArea>

      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
        <p className="text-foreground-muted text-sm">
          {table.getFilteredSelectedRowModel().rows.length} of {table.getFilteredRowModel().rows.length} row(s)
          selected.
        </p>
        <div className="flex items-center gap-2">
          <span className="text-foreground-muted text-sm">
            Page {table.getState().pagination.pageIndex + 1} of {table.getPageCount()}
          </span>
          <Button
            variant="outline"
            size="sm"
            disabled={!table.getCanPreviousPage()}
            onClick={() => table.previousPage()}
          >
            <ChevronLeft data-icon="start" className="-ms-1" />
            Previous
          </Button>
          <Button variant="outline" size="sm" disabled={!table.getCanNextPage()} onClick={() => table.nextPage()}>
            Next
            <ChevronRight data-icon="end" className="-me-1" />
          </Button>
        </div>
      </div>
    </div>
  )
}
```

## How it works [#how-it-works]

TanStack Table owns the state and the row model; Appica UI owns the rendering. The bridge is `flexRender`, which turns each column's `header`/`cell` definition into React nodes that you drop straight into `Table` parts:

```tsx
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'
import { flexRender } from '@tanstack/react-table'
```

```tsx
<Table hoverableRows>
  <TableHeader>
    {table.getHeaderGroups().map((headerGroup) => (
      <TableRow key={headerGroup.id}>
        {headerGroup.headers.map((header) => (
          <TableHead key={header.id}>
            {header.isPlaceholder ? null : flexRender(header.column.columnDef.header, header.getContext())}
          </TableHead>
        ))}
      </TableRow>
    ))}
  </TableHeader>
  <TableBody>
    {table.getRowModel().rows.map((row) => (
      <TableRow key={row.id} highlighted={row.getIsSelected()}>
        {row.getVisibleCells().map((cell) => (
          <TableCell key={cell.id}>{flexRender(cell.column.columnDef.cell, cell.getContext())}</TableCell>
        ))}
      </TableRow>
    ))}
  </TableBody>
</Table>
```

Each feature is a state hook plus the matching row-model helper passed to `useReactTable`:

* **Row selection** — a `select` column whose `header` and `cell` render a [`Checkbox`](/ui/components/react/checkbox). The header checkbox wires `checked` to `getIsAllPageRowsSelected()` and `indeterminate` to `getIsSomePageRowsSelected()` for the mixed-state dash; mark the row `highlighted` when `row.getIsSelected()` to tint it.
* **Sorting** — `getSortedRowModel()` plus a `SortableHeader` button that calls `column.toggleSorting()` and swaps a `ChevronsUpDown` / `ChevronUp` / `ChevronDown` icon off `column.getIsSorted()`.
* **Global filter** — `getFilteredRowModel()` with `globalFilterFn: 'includesString'`, driven by an [`Input`](/ui/components/react/input) whose `startSlot` holds a search icon.
* **Column visibility** — a [`Dropdown Menu`](/ui/components/react/dropdown-menu) of `DropdownMenuCheckboxItem`s, one per `table.getAllColumns().filter((c) => c.getCanHide())`, each toggling `column.toggleVisibility()`.
* **Pagination** — `getPaginationRowModel()` and an `initialState.pagination.pageSize`, with `Previous` / `Next` [`Button`](/ui/components/react/button)s gated on `getCanPreviousPage()` / `getCanNextPage()`.
* **Per-row actions** — a [`Dropdown Menu`](/ui/components/react/dropdown-menu) in a trailing `actions` column. Mark it `enableSorting: false` and `enableHiding: false` so it stays put.

### Rich cells [#rich-cells]

Because a `cell` returns arbitrary JSX, you compose the same components you'd use anywhere. The description cell pairs a [`Thumbnail`](/ui/components/react/thumbnail) (an `icon-soft` variant for category icons, an image for brand logos) with an emphasized label, and the category cell renders an outline [`Badge`](/ui/components/react/badge) with a small color dot — keeping the badge neutral while the dot carries the category color:

```tsx
const CATEGORY_DOT = {
  Income: 'bg-lime-500',
  Bill: 'bg-info-emphasis',
  Medical: 'bg-success-emphasis',
  Transport: 'bg-warning-emphasis',
}
```

```tsx
<Badge variant="outline">
  <span className={`size-2 shrink-0 rounded-full ${CATEGORY_DOT[category]}`} />
  {category}
</Badge>
```

### Horizontal scroll [#horizontal-scroll]

Wrap the table in a horizontal [`Scroll Area`](/ui/components/react/scroll-area) and keep cells from wrapping with `whitespace-nowrap`, so a wide table scrolls sideways on small screens instead of squeezing its columns:

```tsx
<ScrollArea orientation="horizontal" className="[&_td]:whitespace-nowrap [&_th]:whitespace-nowrap">
  <Table hoverableRows>{/* … */}</Table>
</ScrollArea>
```

## Accessibility [#accessibility]

* The markup is a real `<table>` — `flexRender` only fills the cells, so screen readers still announce rows, columns, and headers natively. See the [`Table`](/ui/components/react/table#accessibility) notes.
* Give every selection `Checkbox` an `aria-label` (`"Select all rows"`, `"Select row"`) — the checkbox has no visible text of its own.
* Sort controls are real `<button>`s inside the `<th>`, so they're keyboard-focusable and operable with Enter/Space.
* The per-row actions trigger needs an `aria-label` (e.g. `"Open actions menu"`) since it's an icon-only button.
* Row `highlighted` is a background cue only; selection state is conveyed by the checkbox, not by color alone.


# Date Field (/ui/components/react/date-field)



<Playground component="date-field" />

## Usage [#usage]

```tsx
import { DateField } from '@appica/ui-react/date-field'
```

```tsx
<DateField value={date} onValueChange={setDate} />
```

`DateField` is a keyboard-first date entry: the `format` string is split into editable day/month/year segments, each a `spinbutton&#x60;. Type a number, paste, or press &#x2A;*↑/↓** to step a segment; focus advances automatically. The value is a native `Date` (or `null` while empty). It's not based on Base UI — it's a custom component sharing the [`Input`](/ui/components/react/input) styling.

## Examples [#examples]

### Variants [#variants]

```tsx
import { DateField } from '@appica/ui-react/date-field'

const variants = ['outline', 'soft'] as const

export default function DateFieldVariants() {
  return (
    <div className="flex max-w-50 flex-wrap items-center gap-4">
      {variants.map((variant) => (
        <DateField key={variant} defaultValue={new Date(2026, 5, 23)} variant={variant} />
      ))}
    </div>
  )
}
```

### Sizes [#sizes]

```tsx
import { DateField } from '@appica/ui-react/date-field'

const sizes = ['sm', 'md', 'lg'] as const

export default function DateFieldSizes() {
  return (
    <div className="flex max-w-50 flex-wrap items-center gap-4">
      {sizes.map((size) => (
        <DateField key={size} defaultValue={new Date(2026, 5, 23)} size={size} />
      ))}
    </div>
  )
}
```

### Formats [#formats]

The `format` string (date-fns tokens) decides which segments show and how — numeric (`MM`), abbreviated (`MMM`), or full (`MMMM`) months, 2- or 4-digit years, and any literal separators.

```tsx
import { DateField } from '@appica/ui-react/date-field'

const formats = ['MM/dd/yyyy', 'yyyy-MM-dd', 'dd.MM.yyyy', 'MMM d, yyyy']

export default function DateFieldFormats() {
  return (
    <div className="flex max-w-50 flex-wrap items-center gap-4">
      {formats.map((format) => (
        <DateField key={format} defaultValue={new Date(2026, 5, 23)} format={format} />
      ))}
    </div>
  )
}
```

### Controlled [#controlled]

Drive the value with `value` + `onValueChange`. The callback fires with a `Date` once every segment is filled, or `null` when the field is cleared.

```tsx
'use client'

import * as React from 'react'
import { DateField } from '@appica/ui-react/date-field'

export default function DateFieldControlled() {
  const [date, setDate] = React.useState<Date | null>(new Date(2026, 5, 23))

  return (
    <div className="flex w-full max-w-50 flex-col items-center gap-3">
      <DateField value={date} onValueChange={setDate} />
      <p className="text-foreground-muted w-full text-sm">
        Value: <span className="text-foreground font-medium">{date ? date.toLocaleDateString() : 'null'}</span>
      </p>
    </div>
  )
}
```

### With an icon [#with-an-icon]

Use `startSlot` / `endSlot` to render adornments inside the field frame.

```tsx
import { DateField } from '@appica/ui-react/date-field'
import { Calendar } from '@appica/icons-react'

export default function DateFieldWithIcon() {
  return <DateField className="max-w-50" defaultValue={new Date(2026, 5, 23)} startSlot={<Calendar />} />
}
```

### Disabled, read-only & error states [#disabled-read-only--error-states]

`disabled` greys out the field and blocks interaction; `readOnly` keeps it focusable and readable but prevents edits. Set `aria-invalid` to paint the error state — it's mirrored to `data-invalid`. The field also inherits `disabled` and the error state from a surrounding [`Field`](/ui/components/react/field), so wrapping it in a `Field` marked `invalid` produces the same styling and is the better choice when you're also rendering a validation message.

```tsx
import { DateField } from '@appica/ui-react/date-field'

export default function DateFieldStates() {
  return (
    <div className="flex w-full max-w-40 flex-wrap items-center gap-4">
      <DateField defaultValue={new Date(2026, 5, 23)} disabled />
      <DateField defaultValue={new Date(2026, 5, 23)} readOnly />
      <DateField defaultValue={new Date(2026, 5, 23)} aria-invalid />
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="date-field" />

## API reference [#api-reference]

| Prop                    | <ColMinWidth width="180">Type</ColMinWidth> | Default        | <ColMinWidth width="220">Description</ColMinWidth>                                     |
| ----------------------- | ------------------------------------------- | -------------- | -------------------------------------------------------------------------------------- |
| `value`                 | <Code>Date \| null</Code>                   | —              | Controlled value. Pair with `onValueChange`.                                           |
| `defaultValue`          | <Code>Date \| null</Code>                   | —              | Uncontrolled initial value.                                                            |
| `onValueChange`         | <Code>(date: Date \| null) => void</Code>   | —              | Fires with a `Date` when complete, or `null` when cleared.                             |
| `format`                | `string`                                    | `'MM/dd/yyyy'` | date-fns token string defining the segments and separators.                            |
| `variant`               | <Code>'outline' \| 'soft'</Code>            | `'outline'`    | Field appearance — bordered or filled.                                                 |
| `size`                  | <Code>'sm' \| 'md' \| 'lg'</Code>           | `'md'`         | Height, padding, and text scale.                                                       |
| `startSlot` / `endSlot` | `ReactNode`                                 | —              | Adornments rendered inside the field frame.                                            |
| `disabled`              | `boolean`                                   | `false`        | Blocks interaction and removes the segments from the tab order.                        |
| `readOnly`              | `boolean`                                   | `false`        | Segments stay focusable and readable but can't be edited.                              |
| `required`              | `boolean`                                   | `false`        | Marks the hidden form input as required (needs `name`).                                |
| `name`                  | `string`                                    | —              | Renders a hidden `<input>` with the ISO date for form submission.                      |
| `unstyled`              | `boolean`                                   | `false`        | Drop the input appearance — for composing inside another field (used by `DatePicker`). |
| `className`             | `string`                                    | —              | Extra classes on the root, merged via `tailwind-merge`.                                |

Renders a `<div role="group">` and forwards the remaining `<div>` props (`id`, `aria-*`, `ref`, …). The error styling is driven by the `data-invalid` attribute; setting `aria-invalid` marks the field invalid — it sets `data-invalid` for styling and conveys the state to assistive technology.

## Accessibility [#accessibility]

* The field is a `role="group"`; each segment is a `role="spinbutton"` with `aria-label` (day/month/year) and `aria-valuenow`/`aria-valuetext`.
* **←/→*&#x2A; move between segments, &#x2A;*↑/↓** step the focused segment, **Home/End** jump to the first/last, **Backspace/Delete** clear; typing fills and auto-advances.
* `disabled` removes the segments from the tab order; `readOnly` keeps them focusable but inert.
* Segment focus styling uses a transition wrapped in `motion-reduce:`, so it's skipped under reduced motion.


# Date Picker (/ui/components/react/date-picker)



<Playground component="date-picker" />

## Usage [#usage]

```tsx
import { DatePicker } from '@appica/ui-react/date-picker'
```

```tsx
<DatePicker mode="single" value={date} onValueChange={setDate} />
```

`DatePicker` combines a typeable [`DateField`](/ui/components/react/date-field) (and optional [`TimeField`](/ui/components/react/time-field)) with a [`Calendar`](/ui/components/react/calendar) in a [`Popover`](/ui/components/react/popover) — so a value can be typed or picked. It's a custom composition, not a Base UI primitive. The `value` shape follows `mode`: a `Date` for `single`, a `DateRange` (`{ from, to }`) for `range`, and `Date[]` for `multiple`. Leave `value`/`onValueChange` off for an uncontrolled picker.

## Examples [#examples]

### Single date [#single-date]

`mode="single"` (the default) with a `Date` value. Picking a day closes the popover.

```tsx
'use client'

import * as React from 'react'
import { DatePicker } from '@appica/ui-react/date-picker'

export default function DatePickerSingle() {
  const [date, setDate] = React.useState<Date | undefined>(new Date(2026, 5, 23))

  return <DatePicker className="max-w-50" mode="single" value={date} onValueChange={setDate} />
}
```

### Date & time [#date--time]

Add `showTime` to pair a [`TimeField`](/ui/components/react/time-field) with the date so the value carries hours and minutes. Use `timeFormat` to switch to 12-hour or drop seconds.

```tsx
'use client'

import * as React from 'react'
import { DatePicker } from '@appica/ui-react/date-picker'

export default function DatePickerWithTime() {
  const [date, setDate] = React.useState<Date | undefined>(new Date(2026, 5, 23, 9, 30, 0))

  return <DatePicker className="max-w-60" mode="single" showTime value={date} onValueChange={setDate} />
}
```

### Date range [#date-range]

`mode="range"` selects a span between two dates; the value is a `DateRange`.

```tsx
'use client'

import * as React from 'react'
import { DatePicker, type DateRange } from '@appica/ui-react/date-picker'

export default function DatePickerRange() {
  const [range, setRange] = React.useState<DateRange | undefined>({
    from: new Date(2026, 5, 10),
    to: new Date(2026, 5, 16),
  })

  return <DatePicker className="max-w-68" mode="range" value={range} onValueChange={setRange} />
}
```

### Multiple dates [#multiple-dates]

`mode="multiple"` collects an array of dates into a read-only summary field. Add `clearable` to reset, and `formatValue` to customize the summary text.

```tsx
'use client'

import * as React from 'react'
import { DatePicker } from '@appica/ui-react/date-picker'

export default function DatePickerMultiple() {
  const [days, setDays] = React.useState<Date[] | undefined>([
    new Date(2026, 5, 10),
    new Date(2026, 5, 15),
    new Date(2026, 5, 22),
  ])

  return (
    <DatePicker
      className="max-w-60"
      mode="multiple"
      clearable
      value={days}
      onValueChange={setDays}
      placeholder="Pick dates"
    />
  )
}
```

### Disabled dates [#disabled-dates]

`disabledDates` takes any react-day-picker [`Matcher`](https://daypicker.dev/api/type-aliases/Matcher) (or an array of them) — block past dates, weekends, specific days, or a predicate.

```tsx
'use client'

import * as React from 'react'
import { DatePicker } from '@appica/ui-react/date-picker'

export default function DatePickerDisabledDates() {
  const [date, setDate] = React.useState<Date | undefined>()

  return (
    <DatePicker
      className="max-w-50"
      mode="single"
      value={date}
      onValueChange={setDate}
      disabledDates={[{ before: new Date() }, { dayOfWeek: [0, 6] }]}
    />
  )
}
```

### Variants [#variants]

```tsx
import { DatePicker } from '@appica/ui-react/date-picker'

const variants = ['outline', 'soft'] as const

export default function DatePickerVariants() {
  return (
    <div className="flex max-w-50 flex-wrap items-center gap-4">
      {variants.map((variant) => (
        <DatePicker key={variant} mode="single" variant={variant} defaultValue={new Date(2026, 5, 23)} />
      ))}
    </div>
  )
}
```

### Sizes [#sizes]

```tsx
import { DatePicker } from '@appica/ui-react/date-picker'

const sizes = ['sm', 'md', 'lg'] as const

export default function DatePickerSizes() {
  return (
    <div className="flex max-w-50 flex-wrap items-center gap-4">
      {sizes.map((size) => (
        <DatePicker key={size} mode="single" size={size} defaultValue={new Date(2026, 5, 23)} />
      ))}
    </div>
  )
}
```

### Disabled & error states [#disabled--error-states]

`disabled` blocks the whole control; `aria-invalid` drives the `data-invalid` error styling and flags the field for assistive tech. The picker also inherits `disabled` and the error state from a surrounding [`Field`](/ui/components/react/field), so wrapping it in a `Field` marked `invalid` produces the same styling and is the better choice when you're also rendering a validation message.

```tsx
import { DatePicker } from '@appica/ui-react/date-picker'

export default function DatePickerStates() {
  return (
    <div className="flex w-full max-w-50 flex-col gap-4">
      <DatePicker defaultValue={new Date(2026, 5, 23)} disabled />
      <DatePicker defaultValue={new Date(2026, 5, 23)} aria-invalid />
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="date-picker" />

## API reference [#api-reference]

### Value [#value]

| Prop            | <ColMinWidth width="200">Type</ColMinWidth>    | Default    | <ColMinWidth width="200">Description</ColMinWidth>                   |
| --------------- | ---------------------------------------------- | ---------- | -------------------------------------------------------------------- |
| `mode`          | <Code>'single' \| 'range' \| 'multiple'</Code> | `'single'` | Selection behavior; determines the `value` shape.                    |
| `value`         | <Code>Date \| DateRange \| Date\[]</Code>      | —          | Controlled value; shape matches `mode`. Pair with `onValueChange`.   |
| `defaultValue`  | <Code>Date \| DateRange \| Date\[]</Code>      | —          | Uncontrolled initial value.                                          |
| `onValueChange` | <Code>(value) => void</Code>                   | —          | Fires when the selection changes; the argument shape matches `mode`. |

### Display [#display]

| Prop                    | <ColMinWidth width="200">Type</ColMinWidth>          | Default           | <ColMinWidth width="200">Description</ColMinWidth>                                                                        |
| ----------------------- | ---------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `variant`               | <Code>'outline' \| 'soft'</Code>                     | `'outline'`       | Field appearance — bordered or filled.                                                                                    |
| `size`                  | <Code>'sm' \| 'md' \| 'lg'</Code>                    | `'md'`            | Height, padding, and calendar cell scale.                                                                                 |
| `showTime`              | `boolean`                                            | `false`           | Add a `TimeField` (single/range modes).                                                                                   |
| `dateFormat`            | `string`                                             | `'MM/dd/yyyy'`    | date-fns format for the date field(s).                                                                                    |
| `timeFormat`            | `string`                                             | `'HH:mm:ss'`      | date-fns format for the time field(s).                                                                                    |
| `placeholder`           | `string`                                             | —                 | Placeholder for the multiple-mode summary field.                                                                          |
| `clearable`             | `boolean`                                            | `false`           | Show a clear button (multiple mode).                                                                                      |
| `formatValue`           | <Code>(value: Date\[] \| undefined) => string</Code> | —                 | Customize the multiple-mode summary text.                                                                                 |
| `rangeSeparator`        | `ReactNode`                                          | `'–'`             | Separator between the range's two fields.                                                                                 |
| `startSlot` / `endSlot` | `ReactNode`                                          | —                 | Adornments rendered inside the field frame.                                                                               |
| `triggerIcon`           | `ReactNode`                                          | calendar icon     | Icon for the popover trigger button.                                                                                      |
| `triggerAriaLabel`      | `string`                                             | `'Open calendar'` | Accessible label for the trigger button.                                                                                  |
| `className`             | `string`                                             | —                 | Classes on the root wrapper — use for footprint/layout (e.g. `max-w-60`). Merged via `tailwind-merge`.                    |
| `inputClassName`        | `string`                                             | —                 | Classes on the inner field box — use to override field styling (border, radius, background). Merged via `tailwind-merge`. |

### Behavior & state [#behavior--state]

| Prop            | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="200">Description</ColMinWidth>                                                                                 |
| --------------- | ------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `disabled`      | `boolean`                                   | `false` | Disable the whole control.                                                                                                         |
| `disabledDates` | <Code>Matcher \| Matcher\[]</Code>          | —       | Dates that can't be selected in the calendar.                                                                                      |
| `readOnly`      | `boolean`                                   | `false` | Make the typeable fields read-only.                                                                                                |
| `required`      | `boolean`                                   | `false` | Mark the form field as required.                                                                                                   |
| `name`          | `string`                                    | —       | Hidden input name for form submission. `range` mode emits `name[from]` / `name[to]`; with `showTime` the value is a full datetime. |
| `aria-invalid`  | `boolean`                                   | —       | Flag the field invalid — sets `data-invalid` for styling + conveys it to assistive tech.                                           |
| `closeOnSelect` | `boolean`                                   | auto    | Override auto-close. By default only single mode closes on pick; range and multiple stay open (dismiss on outside-click/Escape).   |

### Popover [#popover]

| Prop           | <ColMinWidth width="200">Type</ColMinWidth>         | Default    | <ColMinWidth width="200">Description</ColMinWidth>                                      |
| -------------- | --------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------- |
| `open`         | `boolean`                                           | —          | Controlled open state. Pair with `onOpenChange`.                                        |
| `defaultOpen`  | `boolean`                                           | `false`    | Uncontrolled initial open state.                                                        |
| `onOpenChange` | <Code>(open: boolean) => void</Code>                | —          | Fires when the popover opens or closes.                                                 |
| `side`         | <Code>'top' \| 'bottom' \| 'left' \| 'right'</Code> | `'bottom'` | Preferred popover side.                                                                 |
| `align`        | <Code>'start' \| 'center' \| 'end'</Code>           | `'end'`    | Popover alignment.                                                                      |
| `sideOffset`   | `number`                                            | `6`        | Gap between the field and the popover.                                                  |
| `popoverProps` | <Code>Partial\<PopoverContentProps></Code>          | —          | Escape hatch forwarded to the inner `PopoverContent` (collision props, `className`, …). |

`DatePicker` also forwards [`Calendar`](/ui/components/react/calendar) configuration props — `captionLayout`, `numberOfMonths`, `weekStartsOn`, `showOutsideDays`, `startMonth`/`endMonth`, and more — to the calendar inside the popover.

## Accessibility [#accessibility]

* The date/time portions are typeable segmented fields (`role="spinbutton"` per segment); the calendar is a `role="grid"` opened from a labelled trigger button (`triggerAriaLabel`).
* The popover traps focus and restores it to the trigger on close; **Escape** closes it.
* A value can be entered entirely from the keyboard via the fields, or chosen in the calendar with arrow keys — see [`DateField`](/ui/components/react/date-field) and [`Calendar`](/ui/components/react/calendar).
* `disabled` blocks the whole control; `disabledDates` prevents specific days from being chosen.
* The error styling is driven by `data-invalid`; setting `aria-invalid` flags the field invalid (sets `data-invalid`) and conveys it to assistive tech. Pass `name` to submit the value through a hidden input.


# Dialog (/ui/components/react/dialog)



<Playground component="dialog" />

## Usage [#usage]

```tsx
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogBody,
  DialogFooter,
  DialogClose,
} from '@appica/ui-react/dialog'
import { Button } from '@appica/ui-react/button'
```

```tsx
<Dialog>
  <DialogTrigger render={<Button variant="outline">Invite people</Button>} />
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Invite your team</DialogTitle>
      <DialogDescription>Send an invitation by email.</DialogDescription>
    </DialogHeader>
    <DialogBody>{/* form, content, … */}</DialogBody>
    <DialogFooter>
      <DialogClose render={<Button variant="outline">Cancel</Button>} />
      <DialogClose render={<Button>Send invites</Button>} />
    </DialogFooter>
  </DialogContent>
</Dialog>
```

`Dialog` is a compound component built on [Base UI's Dialog](https://base-ui.com/react/components/dialog). The root holds the open state; the parts compose the trigger and the portalled, centered popup. By default it's **modal** (focus trapped, page behind blocked) and dismissible (an outside click or Escape closes it), and it draws a close button in the corner:

* **`DialogTrigger`** — the button that opens the dialog. Use `render` to project it onto your own [`Button`](/ui/components/react/button) (or any element).
* **`DialogContent`** — the portalled, centered popup. It draws the card, backdrop, focus trap, and corner close button, and accepts the shared **modal props** below.
* **`DialogHeader`** — groups the title and description with consistent spacing.
* **`DialogTitle`** — an `<h2>` that labels the popup (`aria-labelledby`).
* **`DialogDescription`** — a `<p>` that describes it (`aria-describedby`).
* **`DialogBody`** — the main content region. It doesn't scroll on its own — for content taller than the viewport, wrap it in a [`ScrollArea`](#scrollable-content).
* **`DialogFooter`** — the actions; stacks on small screens and right-aligns in a row from `sm` up.
* **`DialogClose`** — a button that dismisses the dialog; project it onto your own [`Button`](/ui/components/react/button) with `render`.

Use a `Dialog` for a focused task or piece of content that should interrupt the page — a form, a confirmation with detail, a media viewer. When the action is a high-stakes confirmation, reach for an [`Alert Dialog`](/ui/components/react/alert-dialog); when the overlay should slide in from an edge (or be swipeable on touch), use a [`Drawer`](/ui/components/react/drawer); for a small, non-blocking panel anchored to a control, use a [`Popover`](/ui/components/react/popover).

## Examples [#examples]

### Form dialog [#form-dialog]

The most common shape: a header, a body of [`Field`](/ui/components/react/field)s, and a footer of actions. Lay the form out in `DialogBody` and dismiss with `DialogClose` projected onto your buttons.

```tsx
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogBody,
  DialogFooter,
  DialogClose,
} from '@appica/ui-react/dialog'
import { Button } from '@appica/ui-react/button'
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Textarea } from '@appica/ui-react/textarea'

export default function DialogForm() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline">Edit profile</Button>} />
      <DialogContent className="sm:w-110">
        <DialogHeader>
          <DialogTitle>Edit profile</DialogTitle>
          <DialogDescription>
            Update how you appear across the workspace. Changes are visible to your team.
          </DialogDescription>
        </DialogHeader>
        <DialogBody className="flex flex-col gap-4">
          <Field>
            <FieldLabel>Display name</FieldLabel>
            <Input defaultValue="Sarah Jenkins" />
          </Field>
          <Field>
            <FieldLabel>Email</FieldLabel>
            <Input type="email" defaultValue="sarah@appica.dev" />
          </Field>
          <Field>
            <FieldLabel>Bio</FieldLabel>
            <Textarea rows={3} defaultValue="Product designer focused on design systems and accessibility." />
          </Field>
        </DialogBody>
        <DialogFooter>
          <DialogClose render={<Button variant="soft">Cancel</Button>} />
          <DialogClose render={<Button>Save changes</Button>} />
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

### Sizing [#sizing]

`DialogContent` is `w-150` (600px) by default. Override the **width** with a `className` — a responsive `sm:w-100` / `sm:w-200`, a `max-w-*` cap, or a fixed `w-*`. Every dialog also carries `max-w-full`, so any width you set still shrinks to fit narrow screens. For **height**, the popup grows with its content up to the viewport; give it a fixed `h-*` only when you want a [scrollable](#scrollable-content) body that doesn't resize as content changes.

```tsx
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogBody,
  DialogFooter,
  DialogClose,
} from '@appica/ui-react/dialog'
import { Button } from '@appica/ui-react/button'

const SIZES = [
  { label: 'Small', className: 'sm:w-100', width: '400px' },
  { label: 'Default', className: undefined, width: '600px' },
  { label: 'Large', className: 'sm:w-200', width: '800px' },
] as const

export default function DialogSizing() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {SIZES.map(({ label, className, width }) => (
        <Dialog key={label}>
          <DialogTrigger render={<Button variant="outline">{label}</Button>} />
          <DialogContent className={className}>
            <DialogHeader>
              <DialogTitle>{label} dialog</DialogTitle>
              <DialogDescription>
                {className ? (
                  <>
                    Set on <code>DialogContent</code> with <code>className="{className}"</code> ({width}).
                  </>
                ) : (
                  <>The default width is {width}; no className needed.</>
                )}
              </DialogDescription>
            </DialogHeader>
            <DialogBody>
              <p>
                Widths are responsive — every dialog also carries <code>max-w-full</code>, so it shrinks to fit narrow
                screens instead of overflowing.
              </p>
            </DialogBody>
            <DialogFooter>
              <DialogClose render={<Button variant="outline">Close</Button>} />
            </DialogFooter>
          </DialogContent>
        </Dialog>
      ))}
    </div>
  )
}
```

### Scrollable content [#scrollable-content]

For content taller than the viewport, give `DialogContent` a fixed height and let a [`ScrollArea`](/ui/components/react/scroll-area) own the overflow between a pinned header and footer. The header and footer stay put while the body scrolls.

```tsx
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogFooter,
  DialogClose,
} from '@appica/ui-react/dialog'
import { Button } from '@appica/ui-react/button'
import { ScrollArea } from '@appica/ui-react/scroll-area'

const SECTIONS = [
  {
    title: '1. Acceptance of terms',
    body: 'By accessing or using the service you agree to be bound by these terms. If you are entering into this agreement on behalf of a company, you represent that you have the authority to bind that entity.',
  },
  {
    title: '2. Accounts',
    body: 'You are responsible for safeguarding the credentials you use to access the service and for any activity under your account. Notify us immediately of any unauthorized use.',
  },
  {
    title: '3. Acceptable use',
    body: 'You agree not to misuse the service: no probing, scanning, or testing the vulnerability of any system, and no interfering with or disrupting the integrity or performance of the service.',
  },
  {
    title: '4. Content',
    body: 'You retain ownership of the content you submit. By submitting content you grant us a worldwide, non-exclusive license to host and display it solely to operate and improve the service.',
  },
  {
    title: '5. Subscriptions',
    body: 'Paid plans renew automatically at the end of each billing cycle unless cancelled beforehand. Fees are non-refundable except where required by law.',
  },
  {
    title: '6. Termination',
    body: 'We may suspend or terminate your access if you breach these terms. You may stop using the service at any time; certain provisions survive termination.',
  },
  {
    title: '7. Disclaimers',
    body: 'The service is provided "as is" without warranties of any kind, whether express or implied, including merchantability, fitness for a particular purpose, and non-infringement.',
  },
  {
    title: '8. Changes',
    body: 'We may revise these terms from time to time. Material changes will be communicated in advance, and continued use after they take effect constitutes acceptance.',
  },
]

export default function DialogScrollable() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline">Review terms</Button>} />
      <DialogContent className="h-138 sm:w-130">
        <DialogHeader>
          <DialogTitle>Terms of Service</DialogTitle>
          <DialogDescription>Last updated June 27, 2026</DialogDescription>
        </DialogHeader>
        <ScrollArea className="min-h-0 flex-1">
          <div className="flex flex-col gap-5 px-6 pb-2">
            {SECTIONS.map((section) => (
              <section key={section.title} className="flex flex-col gap-1.5">
                <h3 className="text-foreground-intense font-medium">{section.title}</h3>
                <p>{section.body}</p>
              </section>
            ))}
          </div>
        </ScrollArea>
        <DialogFooter>
          <DialogClose render={<Button variant="outline">Decline</Button>} />
          <DialogClose render={<Button>Accept</Button>} />
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

### Nested dialogs [#nested-dialogs]

A dialog can open another dialog. When the child opens, the parent **retracts with the same animation as a close** and the child takes its place as a fresh dialog — keeping its frosted frame over the original backdrop — so the two never have to line up in size. Closing the child brings the parent back. Each dialog keeps its own state; just nest the markup.

```tsx
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogBody,
  DialogFooter,
  DialogClose,
} from '@appica/ui-react/dialog'
import { Button } from '@appica/ui-react/button'
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Badge } from '@appica/ui-react/badge'
import type { ReactNode } from 'react'

function SettingRow({ label, value, action }: { label: string; value: ReactNode; action?: ReactNode }) {
  return (
    <div className="border-border-muted flex items-center justify-between gap-4 border-b py-3 last:border-b-0">
      <div className="flex min-w-0 flex-col">
        <span className="text-foreground-intense font-medium">{label}</span>
        <span className="truncate text-sm">{value}</span>
      </div>
      {action}
    </div>
  )
}

export default function DialogNested() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline">Account settings</Button>} />
      <DialogContent className="sm:w-110">
        <DialogHeader>
          <DialogTitle>Account & security</DialogTitle>
          <DialogDescription>Manage how you sign in and keep your account safe.</DialogDescription>
        </DialogHeader>
        <DialogBody>
          <SettingRow label="Email" value="ada@appica.dev" />
          <SettingRow
            label="Password"
            value="Last changed 3 months ago"
            action={
              <Dialog>
                <DialogTrigger render={<Button variant="soft">Change</Button>} />
                <DialogContent className="sm:w-110">
                  <DialogHeader>
                    <DialogTitle>Change password</DialogTitle>
                    <DialogDescription>Use at least 8 characters, including a number.</DialogDescription>
                  </DialogHeader>
                  <DialogBody className="flex flex-col gap-4">
                    <Field>
                      <FieldLabel>Current password</FieldLabel>
                      <Input type="password" autoComplete="new-password" defaultValue="opensesame" />
                    </Field>
                    <Field>
                      <FieldLabel>New password</FieldLabel>
                      <Input type="password" autoComplete="new-password" defaultValue="correct-horse" />
                    </Field>
                  </DialogBody>
                  <DialogFooter>
                    <DialogClose render={<Button variant="soft">Cancel</Button>} />
                    <DialogClose render={<Button>Update password</Button>} />
                  </DialogFooter>
                </DialogContent>
              </Dialog>
            }
          />
          <SettingRow label="Two-factor auth" value={<Badge variant="success">Enabled</Badge>} />
          <SettingRow label="Active sessions" value="2 devices" />
        </DialogBody>
        <DialogFooter>
          <DialogClose render={<Button>Done</Button>} />
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

### Controlled [#controlled]

Drive the open state yourself with `open` + `onOpenChange` (or stay uncontrolled with `defaultOpen`). Owning the state is what makes a **multi-step flow** work — this create-project wizard tracks the current step, gates **Next** until the name is filled, resets itself when the dialog closes (via `onOpenChange`), and closes programmatically from **Create** rather than a `DialogClose`. The result is handed back to the page, which swaps the trigger for a project card; delete it to start over.

```tsx
'use client'

import * as React from 'react'
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogBody,
  DialogFooter,
  DialogClose,
} from '@appica/ui-react/dialog'
import { Button } from '@appica/ui-react/button'
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Textarea } from '@appica/ui-react/textarea'
import { Thumbnail } from '@appica/ui-react/thumbnail'
import { Folder, Trash } from '@appica/icons-react'

interface Project {
  name: string
  description: string
}

export default function DialogControlled() {
  const [open, setOpen] = React.useState(false)
  const [step, setStep] = React.useState(0)
  const [name, setName] = React.useState('')
  const [description, setDescription] = React.useState('')
  const [project, setProject] = React.useState<Project | null>(null)

  function handleOpenChange(next: boolean) {
    setOpen(next)
    if (!next) {
      setStep(0)
      setName('')
      setDescription('')
    }
  }

  if (project) {
    return (
      <div className="border-border bg-background flex w-full max-w-80 items-center gap-3 rounded-xl border p-3">
        <Thumbnail variant="icon-soft" size="sm">
          <Folder />
        </Thumbnail>
        <div className="flex min-w-0 flex-col">
          <span className="text-foreground-intense -mb-0.5 truncate font-medium">{project.name}</span>
          <span className="text-foreground-muted truncate text-sm">{project.description || 'No description'}</span>
        </div>
        <Button
          variant="outline"
          size="icon-sm"
          className="ms-auto shrink-0"
          aria-label={`Delete ${project.name}`}
          onClick={() => setProject(null)}
        >
          <Trash />
        </Button>
      </div>
    )
  }

  return (
    <Dialog open={open} onOpenChange={handleOpenChange}>
      <DialogTrigger render={<Button variant="outline">Create project</Button>} />
      <DialogContent className="sm:w-105">
        <DialogHeader>
          <DialogTitle>{step === 0 ? 'Name your project' : 'Add a description'}</DialogTitle>
          <DialogDescription>Step {step + 1} of 2 — you can change this later.</DialogDescription>
        </DialogHeader>
        <DialogBody>
          {step === 0 ? (
            <Field>
              <FieldLabel>Project name</FieldLabel>
              <Input autoFocus value={name} onChange={(e) => setName(e.target.value)} placeholder="Orbit" />
            </Field>
          ) : (
            <Field>
              <FieldLabel>Description</FieldLabel>
              <Textarea
                autoFocus
                rows={3}
                value={description}
                onChange={(e) => setDescription(e.target.value)}
                placeholder="What is this project about?"
              />
            </Field>
          )}
        </DialogBody>
        <DialogFooter>
          {step === 0 ? (
            <>
              <DialogClose render={<Button variant="soft">Cancel</Button>} />
              <Button disabled={!name.trim()} onClick={() => setStep(1)}>
                Next
              </Button>
            </>
          ) : (
            <>
              <Button variant="soft" onClick={() => setStep(0)}>
                Back
              </Button>
              <Button
                onClick={() => {
                  setProject({ name: name.trim(), description: description.trim() })
                  handleOpenChange(false)
                }}
              >
                Create project
              </Button>
            </>
          )}
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The header, body, and footer flip to read right-to-left, the footer's actions mirror to the leading edge, and the corner close button moves to the opposite corner. The popup portals to `<body>`, so it follows the **document** direction — when you scope RTL to a subtree of an LTR page, set `dir="rtl"` on `DialogContent` so the popup mirrors too. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="dialog" />

## API reference [#api-reference]

`Dialog` wraps [Base UI's Dialog](https://base-ui.com/react/components/dialog). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### Dialog [#dialog]

The root. Holds the open state; renders no DOM of its own.

| Prop                      | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth>            |
| ------------------------- | ------------------------------------------- | ------- | ------------------------------------------------------------- |
| `open`                    | `boolean`                                   | —       | Controlled open state. Pair with `onOpenChange`.              |
| `defaultOpen`             | `boolean`                                   | `false` | Uncontrolled initial open state.                              |
| `onOpenChange`            | <Code>(open, eventDetails) => void</Code>   | —       | Fires when the dialog opens or closes.                        |
| `modal`                   | <Code>boolean \| 'trap-focus'</Code>        | `true`  | Trap focus and block scroll/interaction with the page behind. |
| `disablePointerDismissal` | `boolean`                                   | `false` | Keep the dialog open when the backdrop is clicked.            |
| `onOpenChangeComplete`    | `(open) => void`                            | —       | Fires after the open/close transition finishes.               |
| `actionsRef`              | `RefObject`                                 | —       | Imperative handle to `close()` / `unmount()` the popup.       |

### DialogTrigger [#dialogtrigger]

The button that opens the dialog. Forwards Base UI's `Dialog.Trigger`; use `render` to project it onto your own element.

| Prop           | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                          |
| -------------- | ----------------------------------------------------------- | ------- | ---------------------------------------------------- |
| `render`       | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render the trigger as your own element (a `Button`). |
| `nativeButton` | `boolean`                                                   | `true`  | Whether the rendered element is a native `<button>`. |
| `className`    | `string`                                                    | —       | Extra classes, merged via `tailwind-merge`.          |

### DialogContent [#dialogcontent]

The portalled, centered popup. Draws the card, backdrop, focus trap, and corner close button, and maps the underlying Base UI Portal / Backdrop / Viewport so you don't have to reach into them. Shared with [`Alert Dialog`](/ui/components/react/alert-dialog) and [`Drawer`](/ui/components/react/drawer) through the **modal props**. Defaults to a `w-150` (600px) width — override with a `className`.

| Prop            | <ColMinWidth width="170">Type</ColMinWidth> | Default   | Description                                                               |
| --------------- | ------------------------------------------- | --------- | ------------------------------------------------------------------------- |
| `closeButton`   | `boolean`                                   | `true`    | Render the × button in the corner.                                        |
| `closeLabel`    | `string`                                    | `'Close'` | Accessible label for the close button.                                    |
| `backdrop`      | `boolean`                                   | `true`    | Render the dimmed, blurred backdrop behind the popup.                     |
| `initialFocus`  | `RefObject`                                 | —         | Element to focus when the dialog opens.                                   |
| `finalFocus`    | `RefObject`                                 | —         | Element to focus when it closes (defaults to the trigger).                |
| `container`     | <Code>HTMLElement \| ref \| null</Code>     | —         | Portal target — render the popup into a different node.                   |
| `keepMounted`   | `boolean`                                   | `false`   | Keep the popup mounted in the DOM while closed.                           |
| `backdropProps` | `object`                                    | —         | Escape hatch for the backdrop element (`className`, `style`, …).          |
| `viewportProps` | `object`                                    | —         | Escape hatch for the viewport element that centers the popup.             |
| `portalProps`   | `object`                                    | —         | Escape hatch for the portal element.                                      |
| `className`     | `string`                                    | —         | Extra classes on the popup card (e.g. a wider `sm:w-*` or a fixed `h-*`). |

### DialogHeader [#dialogheader]

A layout wrapper that groups the title and description with consistent padding and spacing.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | Typically the title and description.        |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### DialogTitle [#dialogtitle]

An `<h2>` that labels the popup. Rendering one sets the popup's `aria-labelledby`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The title text.                             |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### DialogDescription [#dialogdescription]

A `<p>` that describes the popup. Rendering one sets the popup's `aria-describedby`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The description text.                       |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### DialogBody [#dialogbody]

The main content region between the header and footer. Flexes to fill the available height; it doesn't scroll on its own — wrap it in a [`ScrollArea`](#scrollable-content) for content taller than the viewport.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The body content.                           |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### DialogFooter [#dialogfooter]

A layout wrapper for the actions. Stacks them vertically on small screens and lays them out in a right-aligned row from `sm` up.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The action buttons.                         |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### DialogClose [#dialogclose]

A button that closes the dialog. Forwards Base UI's `Dialog.Close`; project it onto your own element with `render`.

| Prop           | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                          |
| -------------- | ----------------------------------------------------------- | ------- | ---------------------------------------------------- |
| `render`       | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render the close control as your own element.        |
| `nativeButton` | `boolean`                                                   | `true`  | Whether the rendered element is a native `<button>`. |
| `className`    | `string`                                                    | —       | Extra classes, merged via `tailwind-merge`.          |

## Accessibility [#accessibility]

* The popup has `role="dialog"` with `aria-modal`, and `aria-labelledby` / `aria-describedby` wired automatically from `DialogTitle` and `DialogDescription` — always render a title.
* Opening **traps focus** inside the popup; **Escape** and an outside click close it (set `disablePointerDismissal` to keep it open on a backdrop click), and focus returns to the trigger.
* With `modal` (the default), scroll and interaction with the rest of the page are blocked while the dialog is open. Set `modal={false}` for a non-blocking dialog that leaves the page interactive.
* The corner close button carries an accessible label (`closeLabel`, default `"Close"`); set it when your dialog needs more specific wording.
* Popup enter/exit transitions are skipped when the user prefers reduced motion.


# Drawer (/ui/components/react/drawer)



<Playground component="drawer" />

## Usage [#usage]

```tsx
import {
  Drawer,
  DrawerTrigger,
  DrawerContent,
  DrawerHeader,
  DrawerTitle,
  DrawerDescription,
  DrawerBody,
  DrawerFooter,
  DrawerClose,
} from '@appica/ui-react/drawer'
import { Button } from '@appica/ui-react/button'
```

```tsx
<Drawer side="right">
  <DrawerTrigger render={<Button variant="outline">Open drawer</Button>} />
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle>Notifications</DrawerTitle>
      <DrawerDescription>Choose what you want to be notified about.</DrawerDescription>
    </DrawerHeader>
    <DrawerBody>{/* content */}</DrawerBody>
    <DrawerFooter>
      <DrawerClose render={<Button>Save</Button>} />
      <DrawerClose render={<Button variant="outline">Cancel</Button>} />
    </DrawerFooter>
  </DrawerContent>
</Drawer>
```

`Drawer` is a compound component built on [Base UI's Drawer](https://base-ui.com/react/components/drawer). It's a [`Dialog`](/ui/components/react/dialog) that **slides in from an edge** and can be **swiped to dismiss** — at home as a mobile bottom sheet or a desktop side panel. Pick the edge with `side`; the swipe direction follows it automatically. By default it's modal and dismissible, with a drag handle and a corner close button:

* **`DrawerTrigger`** — the button that opens the drawer. Use `render` to project it onto your own [`Button`](/ui/components/react/button) (or any element).
* **`DrawerContent`** — the portalled panel. It draws the card, backdrop, handle, focus trap, and corner close button, and accepts the shared **modal props** below.
* **`DrawerHeader`** — groups the title and description with consistent spacing.
* **`DrawerTitle`** — an `<h2>` that labels the panel (`aria-labelledby`).
* **`DrawerDescription`** — a `<p>` that describes it (`aria-describedby`).
* **`DrawerBody`** — the main content region; it owns the scroll and coordinates with the swipe gesture so scrolling doesn't dismiss the drawer.
* **`DrawerFooter`** — the actions, stacked at the bottom of the panel.
* **`DrawerClose`** — a button that dismisses the drawer; project it onto your own [`Button`](/ui/components/react/button) with `render`.

Reach for a `Drawer` when the surface should feel anchored to an edge or be swipeable on touch — navigation, filters, a detail panel, a mobile sheet. For a centered modal, use a [`Dialog`](/ui/components/react/dialog); for a high-stakes confirmation, use an [`Alert Dialog`](/ui/components/react/alert-dialog).

## Examples [#examples]

### Sides [#sides]

Set `side` to `top`, `right`, `bottom`, or `left` to choose the edge the drawer slides in from; the swipe-to-dismiss direction follows. Left and right read as side panels; top and bottom as sheets — cap the sheet's width (here `mx-auto max-w-2xl`) so it doesn't stretch edge-to-edge on a wide screen.

```tsx
import {
  Drawer,
  DrawerTrigger,
  DrawerContent,
  DrawerHeader,
  DrawerTitle,
  DrawerDescription,
  DrawerBody,
  DrawerFooter,
  DrawerClose,
} from '@appica/ui-react/drawer'
import { Button } from '@appica/ui-react/button'

const SIDES = [
  { side: 'top', label: 'Top' },
  { side: 'right', label: 'Right' },
  { side: 'bottom', label: 'Bottom' },
  { side: 'left', label: 'Left' },
] as const

export default function DrawerSides() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {SIDES.map(({ side, label }) => {
        const wide = side === 'top' || side === 'bottom'
        return (
          <Drawer key={side} side={side}>
            <DrawerTrigger render={<Button variant="outline">{label}</Button>} />
            <DrawerContent className={wide ? 'mx-auto max-w-2xl' : undefined}>
              <DrawerHeader>
                <DrawerTitle>{label} drawer</DrawerTitle>
                <DrawerDescription>This panel slides in from the {side} edge.</DrawerDescription>
              </DrawerHeader>
              <DrawerBody>
                <p>Drag the handle or swipe toward the {side} edge to dismiss it.</p>
              </DrawerBody>
              <DrawerFooter>
                <DrawerClose render={<Button variant="outline">Close</Button>} />
              </DrawerFooter>
            </DrawerContent>
          </Drawer>
        )
      })}
    </div>
  )
}
```

### Snap points [#snap-points]

Pass `snapPoints` to let a top or bottom drawer rest at intermediate heights. Each value is a fraction of the viewport (`0`–`1`), a pixel number (`> 1`), or a CSS length string (`'24rem'`). The drawer opens at the first point and the user can drag — or flick — between them; it dismisses past the smallest. Great for a bottom sheet that peeks, then expands to full height.

```tsx
import {
  Drawer,
  DrawerTrigger,
  DrawerContent,
  DrawerHeader,
  DrawerTitle,
  DrawerDescription,
} from '@appica/ui-react/drawer'
import { Button } from '@appica/ui-react/button'
import { ScrollArea } from '@appica/ui-react/scroll-area'
import { Thumbnail } from '@appica/ui-react/thumbnail'
import { Music } from '@appica/icons-react'

const TRACKS = [
  { title: 'Nightcall', artist: 'Neon Drift' },
  { title: 'Midnight City', artist: 'Violet Skies' },
  { title: 'Resonance', artist: 'Echo Theory' },
  { title: 'A Real Hero', artist: 'Pixel Horizon' },
  { title: 'Sunset Avenue', artist: 'The Lateliners' },
  { title: 'Turbo Killer', artist: 'Chrome Wolf' },
  { title: 'Afterglow', artist: 'Static Bloom' },
  { title: 'Le Castle', artist: 'Power Circuit' },
  { title: 'Tech Noir', artist: 'Ghost Signal' },
  { title: 'Crystals', artist: 'Cassette 84' },
]

export default function DrawerSnapPoints() {
  return (
    <Drawer snapPoints={[0.4, 1]}>
      <DrawerTrigger render={<Button variant="outline">Open player</Button>} />
      <DrawerContent className="mx-auto max-w-2xl">
        <DrawerHeader>
          <DrawerTitle>Up next</DrawerTitle>
          <DrawerDescription>Drag the sheet to a snap point — peek at 40% or pull it to full height.</DrawerDescription>
        </DrawerHeader>
        <ScrollArea className="min-h-0 flex-1" scrollShadow>
          <div className="flex flex-col gap-5 px-6">
            {TRACKS.map((track) => (
              <div key={track.title} className="flex items-center gap-3">
                <Thumbnail variant="icon-soft" size="sm">
                  <Music />
                </Thumbnail>
                <span className="flex min-w-0 flex-col">
                  <span className="text-foreground-intense truncate text-sm font-medium">{track.title}</span>
                  <span className="text-foreground-muted truncate text-xs">{track.artist}</span>
                </span>
              </div>
            ))}
          </div>
        </ScrollArea>
      </DrawerContent>
    </Drawer>
  )
}
```

### Scrollable content [#scrollable-content]

For content taller than the panel, let a [`ScrollArea`](/ui/components/react/scroll-area) own the overflow between a pinned header and footer. A `left`/`right` drawer is the natural fit: its swipe-to-dismiss is horizontal, so it never fights the vertical scroll.

```tsx
import {
  Drawer,
  DrawerTrigger,
  DrawerContent,
  DrawerHeader,
  DrawerTitle,
  DrawerDescription,
  DrawerFooter,
  DrawerClose,
} from '@appica/ui-react/drawer'
import { Button } from '@appica/ui-react/button'
import { ScrollArea } from '@appica/ui-react/scroll-area'

const EVENTS = [
  { who: 'Sarah Jenkins', what: 'merged pull request #482', when: '2m ago' },
  { who: 'Maya Torres', what: 'commented on “Release checklist”', when: '18m ago' },
  { who: 'Leo Martin', what: 'approved pull request #480', when: '40m ago' },
  { who: 'Daniel Reyes', what: 'closed issue #311', when: '1h ago' },
  { who: 'Priya Shah', what: 'added a label to issue #309', when: '2h ago' },
  { who: 'Emma Clarke', what: 'deployed to production', when: '3h ago' },
  { who: 'Sarah Jenkins', what: 'opened pull request #485', when: '5h ago' },
  { who: 'Tom Becker', what: 'pushed 12 commits to main', when: '6h ago' },
  { who: 'Maya Torres', what: 'requested changes on #478', when: '8h ago' },
  { who: 'Leo Martin', what: 'linked issue #312 to #485', when: '11h ago' },
  { who: 'Maya Torres', what: 'invited 2 members', when: 'Yesterday' },
  { who: 'Nina Foster', what: 'updated the roadmap', when: 'Yesterday' },
  { who: 'Priya Shah', what: 'merged pull request #476', when: 'Yesterday' },
  { who: 'Daniel Reyes', what: 'renamed the project', when: '2d ago' },
  { who: 'Emma Clarke', what: 'archived 4 tasks', when: '2d ago' },
  { who: 'Tom Becker', what: 'reverted commit 9f3c1a', when: '3d ago' },
  { who: 'Sarah Jenkins', what: 'created milestone “v2.0”', when: '3d ago' },
  { who: 'Leo Martin', what: 'closed issue #298', when: '4d ago' },
  { who: 'Nina Foster', what: 'edited the README', when: '5d ago' },
  { who: 'Priya Shah', what: 'opened pull request #470', when: '5d ago' },
  { who: 'Daniel Reyes', what: 'added 3 members', when: '6d ago' },
  { who: 'Emma Clarke', what: 'set up continuous integration', when: '1w ago' },
  { who: 'Tom Becker', what: 'imported the codebase', when: '1w ago' },
  { who: 'Sarah Jenkins', what: 'created the project', when: '2w ago' },
]

export default function DrawerScrollable() {
  return (
    <Drawer side="right">
      <DrawerTrigger render={<Button variant="outline">View activity</Button>} />
      <DrawerContent>
        <DrawerHeader>
          <DrawerTitle>Activity</DrawerTitle>
          <DrawerDescription>Everything that happened in this project.</DrawerDescription>
        </DrawerHeader>
        <ScrollArea className="min-h-0 flex-1">
          <ol className="flex flex-col gap-4 px-6 pb-2">
            {EVENTS.map((event, i) => (
              <li key={i} className="flex flex-col gap-0.5">
                <p className="text-sm">
                  <span className="text-foreground-intense font-medium">{event.who}</span> {event.what}
                </p>
                <p className="text-foreground-muted text-xs">{event.when}</p>
              </li>
            ))}
          </ol>
        </ScrollArea>
        <DrawerFooter>
          <DrawerClose render={<Button variant="outline">Close</Button>} />
        </DrawerFooter>
      </DrawerContent>
    </Drawer>
  )
}
```

### Nested drawers [#nested-drawers]

A drawer can open another drawer. Base UI keeps the parent mounted and tucks it back as the child slides in, so the stack reads as depth. The child's backdrop is suppressed automatically — just nest the markup, each drawer manages its own state.

```tsx
import {
  Drawer,
  DrawerTrigger,
  DrawerContent,
  DrawerHeader,
  DrawerTitle,
  DrawerDescription,
  DrawerBody,
  DrawerFooter,
  DrawerClose,
} from '@appica/ui-react/drawer'
import { Button } from '@appica/ui-react/button'
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Pencil } from '@appica/icons-react'

export default function DrawerNested() {
  return (
    <Drawer side="right">
      <DrawerTrigger render={<Button variant="outline">Workspace</Button>} />
      <DrawerContent>
        <DrawerHeader>
          <DrawerTitle>Workspace</DrawerTitle>
          <DrawerDescription>Manage the workspace and its members.</DrawerDescription>
        </DrawerHeader>
        <DrawerBody className="flex flex-col items-start gap-3">
          <p>Open a sub-panel to rename the workspace — the parent tucks back to show the stack.</p>
          <Drawer side="right">
            <DrawerTrigger
              render={
                <Button>
                  <Pencil data-icon="start" />
                  Rename workspace
                </Button>
              }
            />
            <DrawerContent closeButton={false}>
              <DrawerHeader>
                <DrawerTitle>Rename workspace</DrawerTitle>
                <DrawerDescription>This name is visible to everyone on the team.</DrawerDescription>
              </DrawerHeader>
              <DrawerBody>
                <Field>
                  <FieldLabel>Workspace name</FieldLabel>
                  <Input defaultValue="Appica" />
                </Field>
              </DrawerBody>
              <DrawerFooter>
                <DrawerClose render={<Button>Save</Button>} />
                <DrawerClose render={<Button variant="outline">Cancel</Button>} />
              </DrawerFooter>
            </DrawerContent>
          </Drawer>
        </DrawerBody>
      </DrawerContent>
    </Drawer>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The header, body, and footer flip to read right-to-left, and the handle and corner close button move to mirror. The panel portals to `<body>`, so it follows the **document** direction — when you scope RTL to a subtree of an LTR page, set `dir="rtl"` on `DrawerContent` so the panel mirrors too. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="drawer" />

## API reference [#api-reference]

`Drawer` wraps [Base UI's Drawer](https://base-ui.com/react/components/drawer). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### Drawer [#drawer]

The root. Holds the open state and the chosen edge; renders no DOM of its own. The swipe direction is derived from `side`, so you don't set `swipeDirection` yourself.

| Prop                      | <ColMinWidth width="200">Type</ColMinWidth>         | Default    | <ColMinWidth width="210">Description</ColMinWidth>                 |
| ------------------------- | --------------------------------------------------- | ---------- | ------------------------------------------------------------------ |
| `side`                    | <Code>'top' \| 'right' \| 'bottom' \| 'left'</Code> | `'bottom'` | The edge the drawer slides in from.                                |
| `open`                    | `boolean`                                           | —          | Controlled open state. Pair with `onOpenChange`.                   |
| `defaultOpen`             | `boolean`                                           | `false`    | Uncontrolled initial open state.                                   |
| `onOpenChange`            | <Code>(open, eventDetails) => void</Code>           | —          | Fires when the drawer opens or closes.                             |
| `modal`                   | <Code>boolean \| 'trap-focus'</Code>                | `true`     | Trap focus and block scroll/interaction with the page behind.      |
| `disablePointerDismissal` | `boolean`                                           | `false`    | Keep the drawer open when the backdrop is clicked.                 |
| `snapPoints`              | `(number \| string)[]`                              | —          | Resting heights for a top/bottom drawer (fraction, px, or length). |
| `defaultSnapPoint`        | `number \| string \| null`                          | —          | Uncontrolled initial snap point (defaults to the first).           |
| `snapPoint`               | `number \| string \| null`                          | —          | Controlled active snap point. Pair with `onSnapPointChange`.       |
| `onSnapPointChange`       | `(point) => void`                                   | —          | Fires when the active snap point changes.                          |
| `onOpenChangeComplete`    | `(open) => void`                                    | —          | Fires after the open/close transition finishes.                    |
| `actionsRef`              | `RefObject`                                         | —          | Imperative handle to `close()` / `unmount()` the panel.            |

### DrawerTrigger [#drawertrigger]

The button that opens the drawer. Forwards Base UI's `Drawer.Trigger`; use `render` to project it onto your own element.

| Prop           | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                          |
| -------------- | ----------------------------------------------------------- | ------- | ---------------------------------------------------- |
| `render`       | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render the trigger as your own element (a `Button`). |
| `nativeButton` | `boolean`                                                   | `true`  | Whether the rendered element is a native `<button>`. |
| `className`    | `string`                                                    | —       | Extra classes, merged via `tailwind-merge`.          |

### DrawerContent [#drawercontent]

The portalled panel. Draws the card, backdrop, drag handle, focus trap, and corner close button, and maps the underlying Base UI Portal / Backdrop / Viewport so you don't have to reach into them. Shared with [`Dialog`](/ui/components/react/dialog) and [`Alert Dialog`](/ui/components/react/alert-dialog) through the **modal props**.

| Prop            | <ColMinWidth width="170">Type</ColMinWidth> | Default   | Description                                                                       |
| --------------- | ------------------------------------------- | --------- | --------------------------------------------------------------------------------- |
| `closeButton`   | `boolean`                                   | `true`    | Render the × button in the corner.                                                |
| `closeLabel`    | `string`                                    | `'Close'` | Accessible label for the close button.                                            |
| `backdrop`      | `boolean`                                   | —         | Render the dimmed backdrop. Defaults to `true` at the top level, off when nested. |
| `container`     | <Code>HTMLElement \| ref \| null</Code>     | —         | Portal target — render the panel into a different node.                           |
| `keepMounted`   | `boolean`                                   | `false`   | Keep the panel mounted in the DOM while closed.                                   |
| `backdropProps` | `object`                                    | —         | Escape hatch for the backdrop element (`className`, `style`, `forceRender`, …).   |
| `viewportProps` | `object`                                    | —         | Escape hatch for the viewport element that positions the panel.                   |
| `portalProps`   | `object`                                    | —         | Escape hatch for the portal element.                                              |
| `className`     | `string`                                    | —         | Extra classes on the panel (e.g. a `max-w-*` cap or a custom `w-*`).              |

### DrawerHeader [#drawerheader]

A layout wrapper that groups the title and description with consistent padding and spacing.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | Typically the title and description.        |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### DrawerTitle [#drawertitle]

An `<h2>` that labels the panel. Rendering one sets the panel's `aria-labelledby`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The title text.                             |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### DrawerDescription [#drawerdescription]

A `<p>` that describes the panel. Rendering one sets the panel's `aria-describedby`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The description text.                       |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### DrawerBody [#drawerbody]

The main content region. Owns the scroll for overflowing content and coordinates with the swipe gesture so scrolling away from the edge doesn't dismiss the drawer.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The body content.                           |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### DrawerFooter [#drawerfooter]

A layout wrapper for the actions, stacked at the bottom of the panel.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The action buttons.                         |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### DrawerClose [#drawerclose]

A button that closes the drawer. Forwards Base UI's `Drawer.Close`; project it onto your own element with `render`.

| Prop           | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                          |
| -------------- | ----------------------------------------------------------- | ------- | ---------------------------------------------------- |
| `render`       | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render the close control as your own element.        |
| `nativeButton` | `boolean`                                                   | `true`  | Whether the rendered element is a native `<button>`. |
| `className`    | `string`                                                    | —       | Extra classes, merged via `tailwind-merge`.          |

### Indenting the page [#indenting-the-page]

Three optional parts — all from `@appica/ui-react/drawer` — produce the effect where the page scales back as a drawer opens. Wrap your app once at the root; most drawers never touch them.

| Part                     | <ColMinWidth width="260">Description</ColMinWidth>                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DrawerProvider`         | Wraps your app. Tracks every `Drawer` mounted inside it and activates the indent parts while one is open.                                               |
| `DrawerIndent`           | Wraps the page content that scales back. Place it at the top of the tree, next to `DrawerIndentBackground`.                                             |
| `DrawerIndentBackground` | The surface revealed behind the scaled page. Defaults to the body background (`bg-background`); give it a darker color for a contrasting scaled-canvas. |

```tsx
<DrawerProvider>
  <DrawerIndentBackground />
  <DrawerIndent>{/* your app — including any Drawer */}</DrawerIndent>
</DrawerProvider>
```

## Accessibility [#accessibility]

* The panel has `role="dialog"` with `aria-modal`, and `aria-labelledby` / `aria-describedby` wired automatically from `DrawerTitle` and `DrawerDescription` — always render a title.
* Opening **traps focus** inside the panel; **Escape**, an outside click, or a swipe toward the edge close it (set `disablePointerDismissal` to keep it open on a backdrop click), and focus returns to the trigger.
* With `modal` (the default), scroll and interaction with the rest of the page are blocked while the drawer is open. Set `modal={false}` to leave the page interactive.
* The corner close button carries an accessible label (`closeLabel`, default `"Close"`); set it when your drawer needs more specific wording.
* Swipe-to-dismiss, snap transitions, and enter/exit animations are skipped when the user prefers reduced motion.


# Dropdown Menu (/ui/components/react/dropdown-menu)



<Playground component="dropdown-menu" />

## Usage [#usage]

```tsx
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuGroupLabel,
  DropdownMenuItem,
  DropdownMenuSeparator,
} from '@appica/ui-react/dropdown-menu'
import { Button } from '@appica/ui-react/button'
```

```tsx
<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline">Open</Button>} />
  <DropdownMenuContent>
    <DropdownMenuGroup>
      <DropdownMenuGroupLabel>My Account</DropdownMenuGroupLabel>
      <DropdownMenuItem>Profile</DropdownMenuItem>
      <DropdownMenuItem>Billing</DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuGroup>
      <DropdownMenuItem>Team</DropdownMenuItem>
      <DropdownMenuItem>Subscription</DropdownMenuItem>
    </DropdownMenuGroup>
  </DropdownMenuContent>
</DropdownMenu>
```

Unlike a plain `<button>`, the trigger is wired to the menu through `render` — pass it your own [`Button`](/ui/components/react/button) (or any element) and the menu manages its `aria-expanded`, focus, and open/close. Every part lives in its own import under `@appica/ui-react/dropdown-menu`.

`DropdownMenu` is a compound component built on [Base UI's Menu](https://base-ui.com/react/components/menu). The root holds the open state and the shared `size`; the parts compose the trigger and the portalled popup:

* **`DropdownMenuTrigger`** — the button that toggles the menu. Use `render` to project it onto your own [`Button`](/ui/components/react/button) (or any element).
* **`DropdownMenuContent`** — the portalled, auto-positioned popup. Accepts the shared [floating props](/ui/components/react/popover) (`side`, `align`, `sideOffset`, …).
* **`DropdownMenuItem`** — one action. Fires `onClick` and closes the menu by default.
* **`DropdownMenuGroup`*&#x2A; / &#x2A;*`DropdownMenuGroupLabel`*&#x2A; / &#x2A;*`DropdownMenuSeparator`** — optional structure for sectioned lists.
* **`DropdownMenuCheckboxItem`*&#x2A; / &#x2A;*`DropdownMenuRadioGroup`*&#x2A; + &#x2A;*`DropdownMenuRadioItem`** — stateful options with a check indicator.
* **`DropdownMenuLinkItem`** — an item that renders an `<a>` for navigation.
* **`DropdownMenuSub`*&#x2A; / &#x2A;*`DropdownMenuSubTrigger`*&#x2A; / &#x2A;*`DropdownMenuSubContent`** — a nested submenu.

Put a leading icon on `data-icon="start"` so the item reserves the right padding; push a trailing badge, [`Kbd`](/ui/components/react/kbd) shortcut, or icon to the far edge with `ms-auto`.

Reach for a `DropdownMenu` for **actions** triggered from a button. To pick one value from a list of options, use a [`Select`](/ui/components/react/select); for the application command bar across the top of a window, use a [`Menubar`](/ui/components/react/menubar); to open the same menu on right-click, use a [`Context Menu`](/ui/components/react/context-menu).

## Examples [#examples]

### Account menu [#account-menu]

A complete profile menu: a header with an [`Avatar`](/ui/components/react/avatar), name, and a role [`Badge`](/ui/components/react/badge); grouped sections with count badges; a Settings submenu; an inline dark-mode [`Switch`](/ui/components/react/switch); and a sign-out action. The header is plain markup — only the rows that should be focusable are `DropdownMenuItem`s.

```tsx
'use client'

import * as React from 'react'
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuGroupLabel,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuSub,
  DropdownMenuSubTrigger,
  DropdownMenuSubContent,
} from '@appica/ui-react/dropdown-menu'
import { Button } from '@appica/ui-react/button'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { Badge } from '@appica/ui-react/badge'
import { Switch } from '@appica/ui-react/switch'
import {
  UserCircle,
  ShoppingBag,
  Heart,
  Message,
  LayoutDashboard,
  Settings,
  BellRinging,
  MoonStars,
  Logout,
  IdBadge2,
  CreditCard,
  MapPin,
} from '@appica/icons-react'

export default function DropdownMenuAccount() {
  const [darkMode, setDarkMode] = React.useState(false)

  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={
          <Button>
            <UserCircle data-icon="start" />
            My account
          </Button>
        }
      />
      <DropdownMenuContent className="min-w-64">
        <div className="flex gap-3 px-2.5 pt-2.5 pb-1.5">
          <Avatar size="sm">
            <AvatarImage src="/avatars/01.jpg" alt="Sarah Jenkins" />
            <AvatarFallback>SJ</AvatarFallback>
          </Avatar>
          <div className="min-w-0 flex-1">
            <p className="text-foreground-intense truncate text-sm font-semibold">Sarah Jenkins</p>
            <p className="text-foreground-muted truncate text-xs">sarah@appica.dev</p>
          </div>
          <Badge variant="secondary" size="sm">
            User
          </Badge>
        </div>

        <DropdownMenuGroup>
          <DropdownMenuGroupLabel>Personal</DropdownMenuGroupLabel>
          <DropdownMenuItem>
            <UserCircle data-icon="start" />
            Profile
          </DropdownMenuItem>
          <DropdownMenuItem>
            <ShoppingBag data-icon="start" />
            My Orders
            <Badge variant="outline" size="sm" className="ms-auto">
              2
            </Badge>
          </DropdownMenuItem>
          <DropdownMenuItem>
            <Heart data-icon="start" />
            Wishlist
          </DropdownMenuItem>
          <DropdownMenuItem>
            <Message data-icon="start" />
            Messages
            <Badge variant="outline" size="sm" className="ms-auto">
              5
            </Badge>
          </DropdownMenuItem>
        </DropdownMenuGroup>

        <DropdownMenuSeparator />

        <DropdownMenuGroup>
          <DropdownMenuGroupLabel>Management</DropdownMenuGroupLabel>
          <DropdownMenuItem>
            <LayoutDashboard data-icon="start" />
            Dashboard
          </DropdownMenuItem>
          <DropdownMenuSub>
            <DropdownMenuSubTrigger>
              <Settings data-icon="start" />
              Settings
            </DropdownMenuSubTrigger>
            <DropdownMenuSubContent>
              <DropdownMenuItem>
                <IdBadge2 data-icon="start" />
                Personal Info
              </DropdownMenuItem>
              <DropdownMenuItem>
                <CreditCard data-icon="start" />
                Payments
              </DropdownMenuItem>
              <DropdownMenuItem>
                <MapPin data-icon="start" />
                Addresses
              </DropdownMenuItem>
            </DropdownMenuSubContent>
          </DropdownMenuSub>
          <DropdownMenuItem>
            <BellRinging data-icon="start" />
            Notifications
          </DropdownMenuItem>
          <DropdownMenuItem closeOnClick={false} onClick={() => setDarkMode((on) => !on)}>
            <MoonStars data-icon="start" />
            Dark Mode
            <Switch checked={darkMode} readOnly tabIndex={-1} aria-hidden className="pointer-events-none ms-auto" />
          </DropdownMenuItem>
        </DropdownMenuGroup>

        <DropdownMenuSeparator />

        <DropdownMenuItem>
          <Logout data-icon="start" />
          Log Out
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Icons, shortcuts & animated chevron [#icons-shortcuts--animated-chevron]

Give items a leading icon with `data-icon="start"`, and align a trailing [`Kbd`](/ui/components/react/kbd) shortcut with `ms-auto`. The trigger carries an animated chevron: mark the trigger `group/trigger` and add `group-data-popup-open/trigger:rotate-180` to the icon so it flips while the menu is open. Paint a destructive action by overriding the item's text and highlight colors.

```tsx
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
} from '@appica/ui-react/dropdown-menu'
import { Button } from '@appica/ui-react/button'
import { Kbd } from '@appica/ui-react/kbd'
import { ChevronDown, User, Copy, Pencil, Trash } from '@appica/icons-react'

export default function DropdownMenuIcons() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        className="group/trigger"
        render={
          <Button variant="outline">
            Actions
            <ChevronDown
              data-icon="end"
              className="transition-transform duration-200 ease-out group-data-popup-open/trigger:rotate-180 motion-reduce:transition-none"
            />
          </Button>
        }
      />
      <DropdownMenuContent>
        <DropdownMenuItem>
          <User data-icon="start" />
          Profile
          <Kbd size="sm" className="ms-auto">
            ⇧⌘P
          </Kbd>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <Copy data-icon="start" />
          Duplicate
          <Kbd size="sm" className="ms-auto">
            ⌘D
          </Kbd>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <Pencil data-icon="start" />
          Rename
        </DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem className="text-error-emphasis! data-highlighted:before:bg-error-subtle!">
          <Trash data-icon="start" />
          Delete
          <Kbd size="sm" className="ms-auto">
            ⌫
          </Kbd>
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Groups & labels [#groups--labels]

Wrap related items in `DropdownMenuGroup` with a `DropdownMenuGroupLabel`, and split sections with `DropdownMenuSeparator`.

```tsx
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuGroupLabel,
  DropdownMenuItem,
  DropdownMenuSeparator,
} from '@appica/ui-react/dropdown-menu'
import { Button } from '@appica/ui-react/button'

export default function DropdownMenuGroups() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline">Open menu</Button>} />
      <DropdownMenuContent>
        <DropdownMenuGroup>
          <DropdownMenuGroupLabel>Account</DropdownMenuGroupLabel>
          <DropdownMenuItem>Profile</DropdownMenuItem>
          <DropdownMenuItem>Billing</DropdownMenuItem>
          <DropdownMenuItem>Settings</DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuGroupLabel>Team</DropdownMenuGroupLabel>
          <DropdownMenuItem>Invite members</DropdownMenuItem>
          <DropdownMenuItem>New workspace</DropdownMenuItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Scrollable [#scrollable]

For a long list, cap the height and wrap the items in a [`ScrollArea`](/ui/components/react/scroll-area) for the custom scrollbar. Pull the `ScrollArea` out to the popup edges with `-mx-2` (cancelling the popup's inner padding) and restore the item padding on the viewport (`viewportProps={{ className: 'px-2' }}`), so the scrollbar sits a hair inside the popup edge.

```tsx
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuGroupLabel,
  DropdownMenuItem,
} from '@appica/ui-react/dropdown-menu'
import { Button } from '@appica/ui-react/button'
import { ScrollArea } from '@appica/ui-react/scroll-area'
import { Avatar, AvatarFallback } from '@appica/ui-react/avatar'
import { ChevronDown } from '@appica/icons-react'

const WORKSPACES = [
  'Acme Corp',
  'Globex',
  'Initech',
  'Umbrella',
  'Stark Industries',
  'Wayne Enterprises',
  'Soylent',
  'Hooli',
  'Pied Piper',
  'Wonka Industries',
  'Cyberdyne',
  'Aperture Science',
]

export default function DropdownMenuScrollable() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        className="group/trigger"
        render={
          <Button variant="outline">
            Switch workspace
            <ChevronDown
              data-icon="end"
              className="transition-transform duration-200 ease-out group-data-popup-open/trigger:rotate-180 motion-reduce:transition-none"
            />
          </Button>
        }
      />
      <DropdownMenuContent className="min-w-60">
        <DropdownMenuGroup>
          <DropdownMenuGroupLabel>Workspaces</DropdownMenuGroupLabel>
          {/* Pull the ScrollArea out to the popup edges (cancelling the popup's
              px-2) and restore the item padding on the viewport, so the custom
              scrollbar sits 2px from the popup edge. */}
          <ScrollArea className="-mx-2 max-h-64" scrollbarVisibility="always" viewportProps={{ className: 'px-2' }}>
            <div className="flex flex-col gap-0.5">
              {WORKSPACES.map((name) => (
                <DropdownMenuItem key={name}>
                  <Avatar size="sm" data-icon="start">
                    <AvatarFallback>{name.slice(0, 1)}</AvatarFallback>
                  </Avatar>
                  {name}
                </DropdownMenuItem>
              ))}
            </div>
          </ScrollArea>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Checkbox items (controlled) [#checkbox-items-controlled]

`DropdownMenuCheckboxItem` toggles a boolean and shows a check when on. Drive it with `checked` + `onCheckedChange` (or leave it uncontrolled with `defaultChecked`); checkbox items keep the menu open so several can be toggled in one pass. A classic real-world use is **column visibility** — each item controls whether a [`Table`](/ui/components/react/table) column is shown.

```tsx
'use client'

import * as React from 'react'
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuGroupLabel,
  DropdownMenuCheckboxItem,
} from '@appica/ui-react/dropdown-menu'
import { Button } from '@appica/ui-react/button'
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'
import { ScrollArea } from '@appica/ui-react/scroll-area'
import { LayoutColumns, ChevronDown } from '@appica/icons-react'

type ColumnKey = 'email' | 'role' | 'status'

const COLUMNS: { key: ColumnKey; label: string }[] = [
  { key: 'email', label: 'Email' },
  { key: 'role', label: 'Role' },
  { key: 'status', label: 'Status' },
]

const ROWS: { name: string; email: string; role: string; status: string }[] = [
  { name: 'Sarah Jenkins', email: 'sarah@appica.dev', role: 'Admin', status: 'Active' },
  { name: 'Liam Hudson', email: 'liam@appica.dev', role: 'Editor', status: 'Invited' },
  { name: 'Mateo Rossi', email: 'mateo@appica.dev', role: 'Viewer', status: 'Active' },
]

export default function DropdownMenuCheckboxes() {
  const [visible, setVisible] = React.useState<Record<ColumnKey, boolean>>({
    email: true,
    role: true,
    status: false,
  })

  const shown = COLUMNS.filter((column) => visible[column.key])

  return (
    <div className="flex w-full max-w-125 flex-col gap-3">
      <div className="flex justify-end">
        <DropdownMenu>
          <DropdownMenuTrigger
            className="group/trigger"
            render={
              <Button variant="outline">
                <LayoutColumns data-icon="start" />
                Columns
                <ChevronDown
                  data-icon="end"
                  className="transition-transform duration-200 ease-out group-data-popup-open/trigger:rotate-180 motion-reduce:transition-none"
                />
              </Button>
            }
          />
          <DropdownMenuContent align="end">
            <DropdownMenuGroup>
              <DropdownMenuGroupLabel>Toggle columns</DropdownMenuGroupLabel>
              {COLUMNS.map((column) => (
                <DropdownMenuCheckboxItem
                  key={column.key}
                  checked={visible[column.key]}
                  onCheckedChange={(checked) => setVisible((prev) => ({ ...prev, [column.key]: checked }))}
                >
                  {column.label}
                </DropdownMenuCheckboxItem>
              ))}
            </DropdownMenuGroup>
          </DropdownMenuContent>
        </DropdownMenu>
      </div>

      <ScrollArea
        orientation="horizontal"
        scrollbarVisibility="auto"
        className="[&_td]:whitespace-nowrap [&_th]:whitespace-nowrap"
      >
        <Table hoverableRows>
          <TableHeader>
            <TableRow>
              <TableHead>Name</TableHead>
              {shown.map((column) => (
                <TableHead key={column.key}>{column.label}</TableHead>
              ))}
            </TableRow>
          </TableHeader>
          <TableBody>
            {ROWS.map((row) => (
              <TableRow key={row.email}>
                <TableCell className="text-foreground-intense font-medium">{row.name}</TableCell>
                {shown.map((column) => (
                  <TableCell key={column.key}>{row[column.key]}</TableCell>
                ))}
              </TableRow>
            ))}
          </TableBody>
        </Table>
      </ScrollArea>
    </div>
  )
}
```

### Radio items [#radio-items]

Wrap mutually exclusive options in a `DropdownMenuRadioGroup` (controlled with `value` + `onValueChange`, or uncontrolled with `defaultValue`); each `DropdownMenuRadioItem` carries the `value` it selects. Like checkbox items, radio items keep the menu open after a choice.

```tsx
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuGroupLabel,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
} from '@appica/ui-react/dropdown-menu'
import { Button } from '@appica/ui-react/button'

export default function DropdownMenuRadio() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline">Sort by</Button>} />
      <DropdownMenuContent>
        <DropdownMenuRadioGroup defaultValue="recent">
          <DropdownMenuGroupLabel>Sort order</DropdownMenuGroupLabel>
          <DropdownMenuRadioItem value="recent">Most recent</DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="popular">Most popular</DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="oldest">Oldest first</DropdownMenuRadioItem>
        </DropdownMenuRadioGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Submenus [#submenus]

Nest a `DropdownMenuSub` with its own `DropdownMenuSubTrigger` and `DropdownMenuSubContent`. The trigger shows a chevron and opens on hover or with the arrow keys; the submenu opens to the side and flips automatically near a screen edge.

```tsx
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuSub,
  DropdownMenuSubTrigger,
  DropdownMenuSubContent,
} from '@appica/ui-react/dropdown-menu'
import { Button } from '@appica/ui-react/button'
import { UserPlus, Mail, MessageCircle, Link } from '@appica/icons-react'

export default function DropdownMenuSubmenu() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline">Share</Button>} />
      <DropdownMenuContent>
        <DropdownMenuItem>Copy link</DropdownMenuItem>
        <DropdownMenuItem>Embed</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuSub>
          <DropdownMenuSubTrigger>
            <UserPlus data-icon="start" />
            Invite people
          </DropdownMenuSubTrigger>
          <DropdownMenuSubContent>
            <DropdownMenuItem>
              <Mail data-icon="start" />
              Email
            </DropdownMenuItem>
            <DropdownMenuItem>
              <MessageCircle data-icon="start" />
              Message
            </DropdownMenuItem>
            <DropdownMenuItem>
              <Link data-icon="start" />
              Invite link
            </DropdownMenuItem>
          </DropdownMenuSubContent>
        </DropdownMenuSub>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Open on hover [#open-on-hover]

Set `openOnHover` on the `DropdownMenuTrigger` to open the menu when the pointer rests on it (it still opens on click and keyboard too). Tune the timing with `delay` / `closeDelay`. Use this sparingly — hover menus aren't reachable on touch and can feel twitchy.

```tsx
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
} from '@appica/ui-react/dropdown-menu'
import { Button } from '@appica/ui-react/button'
import { ChevronDown, User, Settings, Logout } from '@appica/icons-react'

export default function DropdownMenuHover() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        className="group/trigger"
        openOnHover
        delay={100}
        render={
          <Button variant="outline">
            Hover me
            <ChevronDown
              data-icon="end"
              className="transition-transform duration-200 ease-out group-data-popup-open/trigger:rotate-180 motion-reduce:transition-none"
            />
          </Button>
        }
      />
      <DropdownMenuContent>
        <DropdownMenuItem>
          <User data-icon="start" />
          Profile
        </DropdownMenuItem>
        <DropdownMenuItem>
          <Settings data-icon="start" />
          Settings
        </DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem>
          <Logout data-icon="start" />
          Log out
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Link items [#link-items]

`DropdownMenuLinkItem` renders a real `<a>`, so it navigates (and supports `target`, modifier-clicks, and right-click "open in new tab") while staying keyboard-reachable inside the menu. For **internal** routes, project it onto your router's link via `render` — here a Next.js [`Link`](https://nextjs.org/docs/app/api-reference/components/link) (`render={<Link href="…" />}`) for client-side navigation; for **external** links, pass a plain `href` with `target="_blank"`.

```tsx
import Link from 'next/link'
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuLinkItem,
  DropdownMenuSeparator,
} from '@appica/ui-react/dropdown-menu'
import { Button } from '@appica/ui-react/button'
import { LayoutDashboard, Settings, ArrowUpRight, Book, GitBranch } from '@appica/icons-react'

export default function DropdownMenuLinks() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline">Go to</Button>} />
      <DropdownMenuContent>
        {/* Internal navigation — render through a Next.js <Link> for client-side routing. */}
        <DropdownMenuLinkItem render={<Link href="/ui/components/react/dropdown-menu" />}>
          <LayoutDashboard data-icon="start" />
          Dashboard
        </DropdownMenuLinkItem>
        <DropdownMenuLinkItem render={<Link href="/ui/components/react/dropdown-menu" />}>
          <Settings data-icon="start" />
          Settings
        </DropdownMenuLinkItem>
        <DropdownMenuSeparator />
        {/* External links — a plain href with target opens in a new tab. */}
        <DropdownMenuLinkItem href="https://base-ui.com" target="_blank" rel="noreferrer">
          <Book data-icon="start" />
          Documentation
          <ArrowUpRight data-icon="end" className="ms-auto" />
        </DropdownMenuLinkItem>
        <DropdownMenuLinkItem href="https://github.com" target="_blank" rel="noreferrer">
          <GitBranch data-icon="start" />
          Source code
          <ArrowUpRight data-icon="end" className="ms-auto" />
        </DropdownMenuLinkItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Sizes [#sizes]

`size` on the root scales the popup radius, item padding, and icon size together — `sm`, `md` (default), or `lg`.

```tsx
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
} from '@appica/ui-react/dropdown-menu'
import { Button } from '@appica/ui-react/button'

const SIZES = ['sm', 'md', 'lg'] as const

export default function DropdownMenuSizes() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      {SIZES.map((size) => (
        <DropdownMenu key={size} size={size}>
          <DropdownMenuTrigger
            render={
              <Button variant="outline" size={size}>
                {size}
              </Button>
            }
          />
          <DropdownMenuContent>
            <DropdownMenuItem>Profile</DropdownMenuItem>
            <DropdownMenuItem>Settings</DropdownMenuItem>
            <DropdownMenuSeparator />
            <DropdownMenuItem>Log out</DropdownMenuItem>
          </DropdownMenuContent>
        </DropdownMenu>
      ))}
    </div>
  )
}
```

### Side & alignment [#side--alignment]

Position the popup with `side` (`top` / `right` / `bottom` / `left`) and `align` (`start` / `center` / `end`) on `DropdownMenuContent`. It still flips and shifts automatically to stay in view.

By default a menu only flips to the opposite **same-axis** side (e.g. `right` → `left`); it won't re-place onto the other axis, since menus cap their height and scroll instead. For a side-opening (`left` / `right`) menu, pass `collisionAvoidance={{ fallbackAxisSide: 'end' }}` so it can fall back to the top/bottom axis when neither side fits — that's why the `left` and `right` triggers below set it.

```tsx
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
} from '@appica/ui-react/dropdown-menu'
import { Button } from '@appica/ui-react/button'

const PLACEMENTS = [
  { side: 'top', align: 'start' },
  { side: 'right', align: 'center' },
  { side: 'bottom', align: 'end' },
  { side: 'left', align: 'center' },
] as const

export default function DropdownMenuPlacement() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {PLACEMENTS.map(({ side, align }) => (
        <DropdownMenu key={`${side}-${align}`}>
          <DropdownMenuTrigger
            render={
              <Button variant="outline">
                {side} / {align}
              </Button>
            }
          />
          <DropdownMenuContent
            side={side}
            align={align}
            collisionAvoidance={side === 'left' || side === 'right' ? { fallbackAxisSide: 'end' } : undefined}
          >
            <DropdownMenuItem>Profile</DropdownMenuItem>
            <DropdownMenuItem>Settings</DropdownMenuItem>
            <DropdownMenuItem>Log out</DropdownMenuItem>
          </DropdownMenuContent>
        </DropdownMenu>
      ))}
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and submenu direction — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The popup anchors from the trigger's leading edge, submenus open toward the inline-start side, and the submenu chevron mirrors. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<Callout type="note" title="Scoped RTL needs the direction on the positioner">
  The popup portals to `<body>`, so its `start`/`end` alignment mirrors from the **document** direction (read from CSS,
  not from `DirectionProvider`) — automatic when `<html dir="rtl">`. If you instead scope RTL to a subtree of an LTR page,
  set it on the positioner so alignment still mirrors: `<DropdownMenuContent positionerProps={{ dir: 'rtl' }}>`. See
  [Floating popups in a scoped RTL region](/ui/docs/react/rtl#floating-popups-in-a-scoped-rtl-region).
</Callout>

<RtlPreview component="dropdown-menu" />

## API reference [#api-reference]

`DropdownMenu` wraps [Base UI's Menu](https://base-ui.com/react/components/menu). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### DropdownMenu [#dropdownmenu]

The root. Holds the open state and the shared `size`; renders no DOM of its own.

| Prop                   | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth>          |
| ---------------------- | ------------------------------------------- | ------- | ----------------------------------------------------------- |
| `size`                 | <Code>'sm' \| 'md' \| 'lg'</Code>           | `'md'`  | Scales the popup radius, item padding, and icon size.       |
| `open`                 | `boolean`                                   | —       | Controlled open state. Pair with `onOpenChange`.            |
| `defaultOpen`          | `boolean`                                   | `false` | Uncontrolled initial open state.                            |
| `onOpenChange`         | <Code>(open, eventDetails) => void</Code>   | —       | Fires when the menu opens or closes.                        |
| `modal`                | `boolean`                                   | `true`  | Trap focus and block outside scroll/interaction while open. |
| `loopFocus`            | `boolean`                                   | `true`  | Wrap keyboard focus from the last item back to the first.   |
| `disabled`             | `boolean`                                   | `false` | Disable the trigger and prevent opening.                    |
| `onOpenChangeComplete` | `() => void`                                | —       | Fires after the open/close transition finishes.             |

### DropdownMenuTrigger [#dropdownmenutrigger]

The button that toggles the menu. Forwards Base UI's `Menu.Trigger`; use `render` to project it onto your own element.

| Prop          | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                                  |
| ------------- | ----------------------------------------------------------- | ------- | ------------------------------------------------------------ |
| `render`      | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render the trigger as your own element (e.g. a `Button`).    |
| `openOnHover` | `boolean`                                                   | `false` | Open the menu when the trigger is hovered, not just clicked. |
| `delay`       | `number`                                                    | `100`   | Hover-open delay in ms (with `openOnHover`).                 |
| `closeDelay`  | `number`                                                    | `0`     | Hover-close delay in ms (with `openOnHover`).                |
| `className`   | `string`                                                    | —       | Extra classes on the trigger, merged via `tailwind-merge`.   |
| `disabled`    | `boolean`                                                   | `false` | Disable just this trigger.                                   |

### DropdownMenuContent [#dropdownmenucontent]

The portalled, auto-positioned popup wrapping the list. Defaults to `align="start"` and `sideOffset={6}`, and accepts the shared floating props.

| Prop               | <ColMinWidth width="160">Type</ColMinWidth>         | Default    | Description                                                     |
| ------------------ | --------------------------------------------------- | ---------- | --------------------------------------------------------------- |
| `side`             | <Code>'top' \| 'right' \| 'bottom' \| 'left'</Code> | `'bottom'` | Preferred side to open on.                                      |
| `align`            | <Code>'start' \| 'center' \| 'end'</Code>           | `'start'`  | Alignment along that side.                                      |
| `sideOffset`       | `number`                                            | `6`        | Gap between the trigger and the popup.                          |
| `alignOffset`      | `number`                                            | —          | Shift along the alignment axis.                                 |
| `collisionPadding` | `number`                                            | `5`        | Minimum gap kept from the viewport edge when flipping/shifting. |
| `container`        | <Code>HTMLElement \| ref \| null</Code>             | —          | Portal target — render the popup into a different node.         |
| `keepMounted`      | `boolean`                                           | `false`    | Keep the popup mounted in the DOM while closed.                 |
| `positionerProps`  | `object`                                            | —          | Escape hatch for the positioner element (`style`, `render`, …). |
| `portalProps`      | `object`                                            | —          | Escape hatch for the portal element (`style`, `render`, …).     |
| `className`        | `string`                                            | —          | Extra classes on the popup.                                     |

### DropdownMenuItem [#dropdownmenuitem]

One action in the menu.

| Prop           | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                                                    |
| -------------- | ------------------------------------------- | ------- | -------------------------------------------------------------- |
| `closeOnClick` | `boolean`                                   | `true`  | Close the menu after the item is selected.                     |
| `disabled`     | `boolean`                                   | `false` | Make the item unselectable; skipped by keyboard and typeahead. |
| `onClick`      | <Code>(event) => void</Code>                | —       | Fires when the item is selected (click or Enter/Space).        |
| `className`    | `string`                                    | —       | Extra classes, merged via `tailwind-merge`.                    |

### DropdownMenuCheckboxItem [#dropdownmenucheckboxitem]

A toggleable item with a check indicator. Keeps the menu open on click.

| Prop              | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                                            |
| ----------------- | ------------------------------------------- | ------- | ------------------------------------------------------ |
| `checked`         | `boolean`                                   | —       | Controlled checked state. Pair with `onCheckedChange`. |
| `defaultChecked`  | `boolean`                                   | `false` | Uncontrolled initial checked state.                    |
| `onCheckedChange` | <Code>(checked) => void</Code>              | —       | Fires when the checked state changes.                  |
| `closeOnClick`    | `boolean`                                   | `false` | Close the menu when toggled.                           |
| `disabled`        | `boolean`                                   | `false` | Make the item unselectable.                            |

### DropdownMenuRadioGroup [#dropdownmenuradiogroup]

Wraps a set of mutually exclusive `DropdownMenuRadioItem`s.

| Prop            | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                                           |
| --------------- | ------------------------------------------- | ------- | ----------------------------------------------------- |
| `value`         | `string`                                    | —       | Controlled selected value. Pair with `onValueChange`. |
| `defaultValue`  | `string`                                    | —       | Uncontrolled initial value.                           |
| `onValueChange` | <Code>(value) => void</Code>                | —       | Fires when the selection changes.                     |

### DropdownMenuRadioItem [#dropdownmenuradioitem]

One option in a `DropdownMenuRadioGroup`. Keeps the menu open on click.

| Prop           | Type      | Default | Description                   |
| -------------- | --------- | ------- | ----------------------------- |
| `value`        | `string`  | —       | The value this item selects.  |
| `closeOnClick` | `boolean` | `false` | Close the menu when chosen.   |
| `disabled`     | `boolean` | `false` | Make the option unselectable. |

### DropdownMenuLinkItem [#dropdownmenulinkitem]

An item that renders an `<a>` for navigation. Forwards every native anchor prop (`href`, `target`, `rel`, …).

| Prop        | Type     | Default | Description                                 |
| ----------- | -------- | ------- | ------------------------------------------- |
| `href`      | `string` | —       | Navigation target.                          |
| `className` | `string` | —       | Extra classes, merged via `tailwind-merge`. |

### DropdownMenuSub [#dropdownmenusub]

Wraps a nested submenu. Forwards Base UI's `Menu.SubmenuRoot`.

| Prop          | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                           |
| ------------- | ------------------------------------------- | ------- | ------------------------------------- |
| `open`        | `boolean`                                   | —       | Controlled open state of the submenu. |
| `defaultOpen` | `boolean`                                   | `false` | Uncontrolled initial open state.      |

### DropdownMenuSubTrigger [#dropdownmenusubtrigger]

The item that opens a submenu; renders a trailing chevron. Submenus open on hover by default.

| Prop          | Type      | Default | Description                                 |
| ------------- | --------- | ------- | ------------------------------------------- |
| `openOnHover` | `boolean` | `true`  | Open the submenu on hover (and on click).   |
| `delay`       | `number`  | `100`   | Hover-open delay in ms.                     |
| `closeDelay`  | `number`  | `0`     | Hover-close delay in ms.                    |
| `className`   | `string`  | —       | Extra classes, merged via `tailwind-merge`. |

### DropdownMenuSubContent [#dropdownmenusubcontent]

The submenu popup. Defaults to opening on the `inline-end` side; otherwise identical to `DropdownMenuContent`.

| Prop        | Type     | Default | Description                         |
| ----------- | -------- | ------- | ----------------------------------- |
| `className` | `string` | —       | Extra classes on the submenu popup. |

### DropdownMenuGroup [#dropdownmenugroup]

Wraps one labelled section of items so a `DropdownMenuGroupLabel` can name it.

| Prop        | Type        | Default | Description                                          |
| ----------- | ----------- | ------- | ---------------------------------------------------- |
| `children`  | `ReactNode` | —       | A `DropdownMenuGroupLabel` plus the section's items. |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`.          |

### DropdownMenuGroupLabel [#dropdownmenugrouplabel]

The visible heading for a `DropdownMenuGroup`. Size-aware; must be rendered inside a `DropdownMenuGroup` (or `DropdownMenuRadioGroup`).

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The label text.                             |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### DropdownMenuSeparator [#dropdownmenuseparator]

A thin divider between items or groups.

| Prop        | Type     | Default | Description                                 |
| ----------- | -------- | ------- | ------------------------------------------- |
| `className` | `string` | —       | Extra classes, merged via `tailwind-merge`. |

## Accessibility [#accessibility]

* The trigger is a `button` with `aria-haspopup="menu"` and `aria-expanded`; the popup has `role="menu"` and items are `menuitem`, `menuitemcheckbox`, or `menuitemradio`.
* **Enter / Space / ↓*&#x2A; open the menu, &#x2A;*↑/↓*&#x2A; move the highlight, &#x2A;*→*&#x2A; opens a submenu, &#x2A;*←** closes it, **Enter** selects, **Escape** closes, and typing jumps to the matching item (typeahead).
* Focus is trapped inside the open popup when `modal` (the default) and returns to the trigger on close.
* `disabled` items are skipped by keyboard navigation and typeahead.
* `DropdownMenuLinkItem` keeps native anchor semantics, so links are announced and openable in a new tab.
* Popup enter/exit transitions are skipped when the user prefers reduced motion.


# Field (/ui/components/react/field)



<Playground component="field" />

## Usage [#usage]

```tsx
import { Field, FieldLabel, FieldDescription, FieldError, FieldValidity } from '@appica/ui-react/field'
import { Fieldset, FieldsetLegend } from '@appica/ui-react/fieldset'
```

```tsx
<Field>
  <FieldLabel>Email</FieldLabel>
  <Input type="email" placeholder="you@example.com" />
  <FieldDescription>We'll send your receipt here.</FieldDescription>
</Field>
```

`Field` wires a label, description, and error message to one control without you having to juggle `id`/`htmlFor`/`aria-describedby` by hand. Drop any Appica form control inside it — [`Input`](/ui/components/react/input), [`Textarea`](/ui/components/react/textarea), [`NumberField`](/ui/components/react/number-field), [`Select`](/ui/components/react/select), [`Switch`](/ui/components/react/switch), and the rest are all Field-aware: they pick up the field's `disabled` and `invalid` state and contribute their value to validation.

Validation is built in. Give `Field` a `validate` function (or use the native constraints on the control) and render a `FieldError` to surface the message — no separate state needed. Use `Fieldset` to gather several related fields under a single legend, and to disable the whole group at once.

## Examples [#examples]

### Default [#default]

A label sits above the control and a description below it. `Field` associates all three automatically — clicking the label focuses the control, and the description is announced as the control's `aria-describedby`.

```tsx
import { Field, FieldLabel, FieldDescription } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'

export default function FieldDefault() {
  return (
    <Field className="w-full max-w-70">
      <FieldLabel>Email</FieldLabel>
      <Input type="email" placeholder="you@example.com" />
      <FieldDescription>We'll send your receipt here.</FieldDescription>
    </Field>
  )
}
```

### Validation [#validation]

Pass a `validate` callback that returns an error string (or an array of them) when the value is invalid, or `null` when it's fine. `validationMode` decides when it runs — `onBlur` here, or `onChange` / `onSubmit`. The returned message renders inside `FieldError`, and the control flips to its error styling via the field's `invalid` state.

```tsx
'use client'

import { Field, FieldLabel, FieldDescription, FieldError } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'

export default function FieldValidation() {
  return (
    <Field
      className="w-full max-w-70"
      validationMode="onBlur"
      validate={(value) => {
        const email = String(value).trim()
        if (!email) return 'Email is required'
        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) return 'Enter a valid email address'
        return null
      }}
    >
      <FieldLabel>Email</FieldLabel>
      <Input type="email" placeholder="you@example.com" />
      <FieldDescription>Validates when the field loses focus.</FieldDescription>
      <FieldError />
    </Field>
  )
}
```

### Disabled & read-only [#disabled--read-only]

Set `disabled` on the `Field` to disable the whole thing at once — it greys the control and takes it out of the tab order, propagating down to whatever control is inside. `readOnly` is a control-level concern (there's no field-wide equivalent), so set it on the input: it stays focusable and selectable but can't be edited.

```tsx
import { Field, FieldLabel, FieldDescription } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'

export default function FieldDisabled() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-5">
      <Field disabled>
        <FieldLabel>Email</FieldLabel>
        <Input type="email" defaultValue="you@example.com" />
        <FieldDescription>The whole field is disabled.</FieldDescription>
      </Field>
      <Field>
        <FieldLabel>API key</FieldLabel>
        <Input defaultValue="sk_live_8f2c91a4" readOnly />
        <FieldDescription>Focusable and selectable, but not editable.</FieldDescription>
      </Field>
    </div>
  )
}
```

### Fieldset [#fieldset]

`Fieldset` groups related fields under a `FieldsetLegend` and renders a native `<fieldset>` / `<legend>`. Setting `disabled` on the fieldset disables every control inside it in one move.

```tsx
import { Fieldset, FieldsetLegend } from '@appica/ui-react/fieldset'
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'

export default function FieldFieldset() {
  return (
    <Fieldset className="w-full max-w-70">
      <FieldsetLegend>Shipping address</FieldsetLegend>
      <Field>
        <FieldLabel>Street</FieldLabel>
        <Input placeholder="123 Main St" />
      </Field>
      <Field>
        <FieldLabel>City</FieldLabel>
        <Input placeholder="Springfield" />
      </Field>
      <Field>
        <FieldLabel>Postal code</FieldLabel>
        <Input placeholder="12345" />
      </Field>
    </Fieldset>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The label and description align to the start edge and the control follows the resolved direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="field" />

## API reference [#api-reference]

`Field` and `Fieldset` wrap [Base UI's Field](https://base-ui.com/react/components/field) and [Fieldset](https://base-ui.com/react/components/fieldset); every remaining prop is forwarded to the underlying element.

### Field [#field]

The root that provides labelling and validation context to a single control. Renders a `<div>` and exposes `data-valid` / `data-invalid` / `data-dirty` / `data-touched` / `data-filled` / `data-focused` / `data-disabled` for styling.

| Prop                     | <ColMinWidth width="200">Type</ColMinWidth>                                | Default      | <ColMinWidth width="220">Description</ColMinWidth>                              |
| ------------------------ | -------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------- |
| `name`                   | `string`                                                                   | —            | Field name on form submission; takes precedence over the control's own `name`.  |
| `validate`               | <Code>(value, formValues) => string \| string\[] \| Promise \| null</Code> | —            | Returns error message(s) when invalid, or `null` when valid. May be async.      |
| `validationMode`         | <Code>'onSubmit' \| 'onBlur' \| 'onChange'</Code>                          | `'onSubmit'` | When `validate` runs.                                                           |
| `validationDebounceTime` | `number`                                                                   | `0`          | Milliseconds to debounce `validate` in `onChange` mode.                         |
| `invalid`                | `boolean`                                                                  | —            | Force the invalid state — handy when an external library owns validation.       |
| `disabled`               | `boolean`                                                                  | `false`      | Disable the control inside; takes precedence over the control's own `disabled`. |
| `dirty`                  | `boolean`                                                                  | —            | Externally control whether the value differs from its initial value.            |
| `touched`                | `boolean`                                                                  | —            | Externally control whether the field has been interacted with.                  |
| `render`                 | <Code>ReactElement \| ((props, state) => ReactElement)</Code>              | —            | Replace the element, or compose it with another component.                      |
| `className`              | <Code>string \| ((state) => string)</Code>                                 | —            | Extra classes, merged via `tailwind-merge`. May be a function of state.         |

### FieldLabel [#fieldlabel]

The control's label. Renders a `<label>` tied to the control, so clicking it moves focus.

| Prop          | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>                                            |
| ------------- | ------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `nativeLabel` | `boolean`                                                     | `true`  | Set `false` when rendering a non-`<label>` element through `render` (e.g. labelling a group). |
| `render`      | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the element, or compose it with another component.                                    |
| `className`   | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes, merged via `tailwind-merge`.                                                   |

### FieldDescription [#fielddescription]

Supporting text for the control. Renders a `<p>` and is wired to the control's `aria-describedby`.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>         |
| ----------- | ------------------------------------------------------------- | ------- | ---------------------------------------------------------- |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the element, or compose it with another component. |
| `className` | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes, merged via `tailwind-merge`.                |

### FieldError [#fielderror]

The validation message. Renders only when the field is invalid (or `match` says so), with a height/opacity enter–exit transition that honours `prefers-reduced-motion`. With no children it shows the field's current error message; with `match` you supply custom children for a specific validity condition.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>                                              |
| ----------- | ------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `match`     | <Code>boolean \| keyof ValidityState</Code>                   | —       | `true` always shows; a `ValidityState` key (e.g. `'valueMissing'`) shows only for that failure. |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the element, or compose it with another component.                                      |
| `className` | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes, merged via `tailwind-merge`. An `svg` child is auto-sized and aligned.           |

### FieldValidity [#fieldvalidity]

A render-prop that exposes the field's live validity so you can render fully custom messaging.

| Prop       | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth>                            |
| ---------- | ------------------------------------------- | ------- | ----------------------------------------------------------------------------- |
| `children` | <Code>(state) => ReactNode</Code>           | —       | Receives `{ validity, value, error, errors }` and returns the node to render. |

### Fieldset [#fieldset-1]

Groups related fields. Renders a native `<fieldset>` (`role="group"`) laid out as a column.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>         |
| ----------- | ------------------------------------------------------------- | ------- | ---------------------------------------------------------- |
| `disabled`  | `boolean`                                                     | `false` | Disables every control inside the fieldset.                |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the element, or compose it with another component. |
| `className` | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes, merged via `tailwind-merge`.                |

### FieldsetLegend [#fieldsetlegend]

The fieldset's heading. Renders a `<legend>` that names the group.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>         |
| ----------- | ------------------------------------------------------------- | ------- | ---------------------------------------------------------- |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the element, or compose it with another component. |
| `className` | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes, merged via `tailwind-merge`.                |

## Accessibility [#accessibility]

* `FieldLabel` renders a real `<label>` bound to the control, so the label is both clickable and announced — no manual `htmlFor`/`id` wiring.
* `FieldDescription` is linked through the control's `aria-describedby`, and `FieldError` is announced when it appears.
* `Fieldset` renders a native `<fieldset>` with `role="group"` named by its `<legend>`; `disabled` on it disables every descendant control.
* The error message's enter–exit transition honours `prefers-reduced-motion`.
* To label a group of controls (a `RadioGroup`, `ToggleGroup`, or a `DateField`/`TimeField` segment group) rather than a single input, don't use `FieldLabel` — a `<label for>` doesn't associate with a `role="group"`. Name those with `aria-labelledby` pointing at a heading instead.


# Form (/ui/components/react/form)



## Usage [#usage]

```tsx
import { Form } from '@appica/ui-react/form'
import { Field, FieldLabel, FieldError } from '@appica/ui-react/field'
```

```tsx
<Form onFormSubmit={(values) => console.log(values)}>
  <Field name="email">
    <FieldLabel>Email</FieldLabel>
    <Input type="email" placeholder="you@example.com" />
    <FieldError />
  </Field>
  <Button type="submit">Subscribe</Button>
</Form>
```

`Form` renders a native `<form>` and ties together the [`Field`](/ui/components/react/field)s inside it. On submit it validates every field, focuses the first invalid one, and only calls `onFormSubmit` — with the collected `{ name: value }` map — once they all pass. `preventDefault()` is handled for you when you use `onFormSubmit`.

It also closes the loop on server-side validation: pass an `errors` object keyed by field `name` and each matching `Field` shows the message through its `FieldError`, no extra wiring. Use `validationMode` to choose when fields validate (`onSubmit`, `onBlur`, or `onChange`); a `validationMode` set on an individual `Field` wins over the form's.

## Examples [#examples]

### Default [#default]

Give each `Field` a `name` and the values arrive in `onFormSubmit` as an object keyed by those names. The form handles `preventDefault` itself.

```tsx
'use client'

import { useState } from 'react'
import { Form } from '@appica/ui-react/form'
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Button } from '@appica/ui-react/button'

export default function FormDefault() {
  const [submitted, setSubmitted] = useState<string | null>(null)

  return (
    <Form
      className="flex w-full max-w-70 flex-col gap-4"
      onFormSubmit={(values) => setSubmitted(String(values.email ?? ''))}
    >
      <Field name="name">
        <FieldLabel>Full name</FieldLabel>
        <Input placeholder="John Doe" />
      </Field>
      <Field name="email">
        <FieldLabel>Email</FieldLabel>
        <Input type="email" placeholder="you@example.com" />
      </Field>
      <Button type="submit">Subscribe</Button>
      {submitted ? <p className="text-foreground-muted text-sm">Subscribed as {submitted || 'no email'}.</p> : null}
    </Form>
  )
}
```

### Validation [#validation]

Validate on submit and reject the attempt when something's off. Here the handler builds an error map, marks each offending `Field` `invalid`, and shakes just those fields with the `animate-shake` utility so the ones needing attention nudge into view — the valid fields and the button stay put. Once a field has been flagged, it re-validates on every keystroke using the same rules — so the message clears the moment the value becomes valid (and updates if it's still wrong), instead of lingering until the next submit. `noValidate` hands validation to your code instead of the browser's native bubbles.

```tsx
'use client'

import { useState } from 'react'
import { Form } from '@appica/ui-react/form'
import { Field, FieldLabel, FieldError } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Button } from '@appica/ui-react/button'

type FormErrors = { email?: string | undefined; password?: string | undefined }
type ShakeState = { email: boolean; password: boolean }

function validateEmail(value: string): string | undefined {
  const email = value.trim()
  if (!email) return 'Email is required'
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) return 'Enter a valid email address'
  return undefined
}

function validatePassword(value: string): string | undefined {
  if (value.length < 8) return 'Use at least 8 characters'
  return undefined
}

export default function FormValidation() {
  const [errors, setErrors] = useState<FormErrors>({})
  const [shake, setShake] = useState<ShakeState>({ email: false, password: false })

  const revalidate = (field: keyof FormErrors, value: string) =>
    setErrors((prev) => {
      if (!prev[field]) return prev
      const message = field === 'email' ? validateEmail(value) : validatePassword(value)
      return { ...prev, [field]: message }
    })

  return (
    <Form
      noValidate
      className="flex w-full max-w-70 flex-col gap-4"
      onSubmit={(event) => {
        event.preventDefault()
        const data = new FormData(event.currentTarget)
        const next: FormErrors = {
          email: validateEmail(String(data.get('email') ?? '')),
          password: validatePassword(String(data.get('password') ?? '')),
        }
        setErrors(next)
        setShake({ email: Boolean(next.email), password: Boolean(next.password) })
      }}
    >
      <Field
        name="email"
        invalid={Boolean(errors.email)}
        className={shake.email ? 'animate-shake' : undefined}
        onAnimationEnd={() => setShake((prev) => ({ ...prev, email: false }))}
      >
        <FieldLabel>Email</FieldLabel>
        <Input
          type="email"
          autoComplete="off"
          placeholder="you@example.com"
          onChange={(event) => revalidate('email', event.target.value)}
        />
        <FieldError match={Boolean(errors.email)}>{errors.email}</FieldError>
      </Field>
      <Field
        name="password"
        invalid={Boolean(errors.password)}
        className={shake.password ? 'animate-shake' : undefined}
        onAnimationEnd={() => setShake((prev) => ({ ...prev, password: false }))}
      >
        <FieldLabel>Password</FieldLabel>
        <Input
          type="password"
          autoComplete="new-password"
          placeholder="••••••••"
          onChange={(event) => revalidate('password', event.target.value)}
        />
        <FieldError match={Boolean(errors.password)}>{errors.password}</FieldError>
      </Field>
      <Button type="submit">Create account</Button>
    </Form>
  )
}
```

### Server-side errors [#server-side-errors]

When validation lives on the server, pass its response to the `errors` prop keyed by field `name`. The matching `Field` renders the message through its `FieldError`, and the error clears as the user edits the field. (Submit `taken@example.com` to see it.)

```tsx
'use client'

import { useState } from 'react'
import { Form } from '@appica/ui-react/form'
import { Field, FieldLabel, FieldDescription, FieldError } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Button } from '@appica/ui-react/button'

const TAKEN = ['taken@example.com']

export default function FormServerErrors() {
  const [errors, setErrors] = useState<Record<string, string>>({})

  return (
    <Form
      errors={errors}
      className="flex w-full max-w-70 flex-col gap-4"
      onFormSubmit={(values) => {
        const email = String(values.email ?? '').trim()
        setErrors(TAKEN.includes(email) ? { email: 'This email is already registered' } : {})
      }}
    >
      <Field name="email">
        <FieldLabel>Email</FieldLabel>
        <Input type="email" placeholder="you@example.com" />
        <FieldDescription>Try taken@example.com to see a server error.</FieldDescription>
        <FieldError />
      </Field>
      <Button type="submit">Sign up</Button>
    </Form>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

Labels, controls, and messages all align to the start edge and follow the resolved direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="form" />

## API reference [#api-reference]

`Form` wraps [Base UI's Form](https://base-ui.com/react/components/form) and renders a native `<form>`, so every standard form attribute (`onSubmit`, `noValidate`, `action`, `method`, `ref`, …) passes straight through alongside the props below.

| Prop             | <ColMinWidth width="200">Type</ColMinWidth>                   | Default      | <ColMinWidth width="220">Description</ColMinWidth>                                                       |
| ---------------- | ------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------- |
| `onFormSubmit`   | <Code>(formValues, eventDetails) => void</Code>               | —            | Called on a valid submit with the collected `{ name: value }` map. `preventDefault()` is called for you. |
| `errors`         | <Code>Record\<string, string \| string\[]></Code>             | —            | External (typically server) errors keyed by field `name`; distributed to each `Field`'s `FieldError`.    |
| `validationMode` | <Code>'onSubmit' \| 'onBlur' \| 'onChange'</Code>             | `'onSubmit'` | When fields validate. A `Field`'s own `validationMode` takes precedence.                                 |
| `actionsRef`     | <Code>RefObject\<Form.Actions></Code>                         | —            | Imperative ref whose `validate(name?)` re-runs validation for all fields, or one field by `name`.        |
| `render`         | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —            | Replace the `<form>` element, or compose it with another component.                                      |
| `className`      | <Code>string \| ((state) => string)</Code>                    | —            | Extra classes, merged via `tailwind-merge`. May be a function of state.                                  |

## Accessibility [#accessibility]

* Renders a native `<form>`, so browser submit semantics (Enter to submit, `<button type="submit">`) work as expected. Name it with `aria-label` / `aria-labelledby` if it isn't already introduced by a heading.
* On an invalid submit the first invalid field receives focus, so keyboard and screen-reader users land on the problem.
* Validation messages come from each [`Field`](/ui/components/react/field)'s `FieldError`, which is wired to its control for assistive tech — see the Field page for the per-control accessibility details.
* The `animate-shake` feedback in the validation example is purely visual; it conveys nothing on its own, so the error message remains the source of truth.


# Gradient Glow (/ui/components/react/gradient-glow)



<Playground component="gradient-glow" />

## Usage [#usage]

```tsx
import { GradientGlow } from '@appica/ui-react/gradient-glow'
```

```tsx
<GradientGlow>
  <YourContent />
</GradientGlow>
```

`GradientGlow` is a `<div>` wrapper that paints a blurred, animated gradient behind its `children` —
the colored "halo" you see around AI features. The gradient slowly rotates a full turn while the glow
gently breathes in and out, so the colors drift around the element for a living, glowing feel. Tune the look with `from` / `via` / `to` (the three
gradient stops), `angle` (its resting direction), `blur` (how soft the halo is), and `speed` (seconds per
rotation).

The glow extends past the element's edges because the layer is blurred — give your `children` an opaque
surface (e.g. `bg-background`) so the halo reads as a surrounding shadow rather than washing over the
content. The decorative layers are `aria-hidden` and `pointer-events-none`, so they never reach assistive
tech or intercept clicks, and the wrapper forwards `className`, `style`, and any native `<div>` attributes.

## Examples [#examples]

### Basic glow [#basic-glow]

The default `aurora` gradient — sky blue, lilac, and warm sand — drifting behind a card. By default only
the blurred glow is rendered; the wrapper's radius (`rounded-2xl`) should match your content's radius so
the halo hugs the corners.

```tsx
import { GradientGlow } from '@appica/ui-react/gradient-glow'

export default function GradientGlowBasic() {
  return (
    <GradientGlow className="w-full max-w-80">
      <div className="bg-background text-foreground-intense flex min-h-32 w-full items-center justify-center rounded-2xl px-6 text-center text-sm font-medium">
        How can I assist you today?
      </div>
    </GradientGlow>
  )
}
```

### Animated gradient border [#animated-gradient-border]

Set `border` to add a 1px stroke that follows the same animated gradient, in sync with the glow. Tune its
thickness with `borderWidth`. Pair it with a softer, wider `blur` for a crisp edge over a diffuse halo.

```tsx
import { GradientGlow } from '@appica/ui-react/gradient-glow'

export default function GradientGlowBorder() {
  return (
    <GradientGlow border blur="xl" className="w-full max-w-80">
      <div className="bg-background text-foreground-intense flex min-h-32 w-full items-center justify-center rounded-2xl px-6 text-center text-sm font-medium">
        Smart comparison
      </div>
    </GradientGlow>
  )
}
```

### Custom colors [#custom-colors]

The three stops are fully adjustable via `from`, `via`, and `to` — pass any CSS color. Mix your own
palette to match a brand or mood.

```tsx
import { GradientGlow } from '@appica/ui-react/gradient-glow'

const PALETTES = [
  { label: 'Sunset', from: '#FCA5A5', via: '#FDC49B', to: '#FCE3A6' },
  { label: 'Ocean', from: '#9DE7D8', via: '#9CC0F9', to: '#BEB0F7' },
  { label: 'Candy', from: '#F0ABFC', via: '#C4B5FD', to: '#93C5FD' },
]

export default function GradientGlowCustomColors() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-8">
      {PALETTES.map((p) => (
        <GradientGlow key={p.label} from={p.from} via={p.via} to={p.to}>
          <div className="bg-background text-foreground-intense flex size-28 items-center justify-center rounded-2xl text-sm font-medium">
            {p.label}
          </div>
        </GradientGlow>
      ))}
    </div>
  )
}
```

### Blur / softness [#blur--softness]

`blur` controls how soft the halo is, mapped to Tailwind's `blur-*` scale (`sm` through `3xl`). Larger
values spread the glow further past the edges for a more diffuse, ambient look.

```tsx
import { GradientGlow } from '@appica/ui-react/gradient-glow'

const LEVELS = ['md', 'lg', '2xl'] as const

export default function GradientGlowBlur() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-10">
      {LEVELS.map((blur) => (
        <GradientGlow key={blur} blur={blur}>
          <div className="bg-background text-foreground-intense flex size-28 items-center justify-center rounded-2xl text-sm font-medium">
            blur=&quot;{blur}&quot;
          </div>
        </GradientGlow>
      ))}
    </div>
  )
}
```

### Reveal on interaction [#reveal-on-interaction]

Set `revealOn` to keep the glow hidden until an interaction, then fade it in (the animation resumes from
paused). Accepts `'hover'` (pointer-only, like Tailwind's `hover:` variant) and `'press'` (works on touch),
or an array to combine them. Since `'hover'` can't fire on touch, opt into `showOnTouch` to keep the glow
persistently visible there instead of hidden. Hover or press a button below.

```tsx
import { GradientGlow } from '@appica/ui-react/gradient-glow'
import { buttonVariants } from '@appica/ui-react/button'
import { cn } from '@/lib/utils'

export default function GradientGlowRevealOnInteraction() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-8">
      <GradientGlow revealOn="hover" pressScale border showOnTouch blur="md" className="rounded-full">
        <button type="button" className={cn(buttonVariants({ variant: 'outline', size: 'lg' }), 'rounded-full')}>
          Hover me
        </button>
      </GradientGlow>
      <GradientGlow revealOn="press" pressScale border blur="md" className="rounded-full">
        <button type="button" className={cn(buttonVariants({ variant: 'outline', size: 'lg' }), 'rounded-full')}>
          Press me
        </button>
      </GradientGlow>
    </div>
  )
}
```

### Controlled (loading state) [#controlled-loading-state]

For event-driven states — a request in flight, an AI task running — drive the glow with the controlled
`reveal` boolean instead. It's OR-ed with any `revealOn` interaction, so you can combine "glow on hover"
with "glow while loading". Click the button to kick off a mock request.

```tsx
'use client'

import { useRef, useState } from 'react'
import { GradientGlow } from '@appica/ui-react/gradient-glow'
import { buttonVariants } from '@appica/ui-react/button'
import { Spinner } from '@appica/ui-react/spinner'
import { Sparkle } from '@appica/icons-react'
import { cn } from '@/lib/utils'

export default function GradientGlowLoading() {
  const [loading, setLoading] = useState(false)
  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)

  function run() {
    if (timer.current) clearTimeout(timer.current)
    setLoading(true)
    timer.current = setTimeout(() => setLoading(false), 5000)
  }

  return (
    <GradientGlow reveal={loading} border blur="md" speed={3} className="rounded-full">
      <button
        type="button"
        onClick={run}
        className={cn(buttonVariants({ variant: 'outline', size: 'lg' }), 'rounded-full')}
      >
        {loading ? (
          <Spinner variant="sparkle" currentColor data-icon="start" className="text-xl" />
        ) : (
          <Sparkle data-icon="start" />
        )}
        {loading ? 'Thinking…' : 'Ask AI'}
      </button>
    </GradientGlow>
  )
}
```

## API reference [#api-reference]

| Prop          | <ColMinWidth width="210">Type</ColMinWidth>                 | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                                                         |
| ------------- | ----------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| `from`        | `string`                                                    | `'#8EC5FF'` | First gradient stop.                                                                                                       |
| `via`         | `string`                                                    | `'#EFADF7'` | Middle gradient stop.                                                                                                      |
| `to`          | `string`                                                    | `'#FFD69B'` | Last gradient stop.                                                                                                        |
| `angle`       | `number`                                                    | `95`        | Resting gradient direction in degrees; the animation rotates a full turn around it.                                        |
| `blur`        | <Code>'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl'</Code> | `'lg'`      | Softness of the glow, mapped to a Tailwind `blur-*` utility.                                                               |
| `border`      | `boolean`                                                   | `false`     | Add a 1px stroke that follows the same animated gradient.                                                                  |
| `borderWidth` | `number`                                                    | `1`         | Stroke thickness in px when `border` is on.                                                                                |
| `speed`       | `number`                                                    | `4`         | Seconds for one full rotation (and one breath) of the gradient.                                                            |
| `revealOn`    | <Code>'hover' \| 'press' \| Array</Code>                    | —           | Reveal only on interaction. `'hover'` is pointer-only; `'press'` works on touch. Combine via an array. Omit for always-on. |
| `reveal`      | `boolean`                                                   | —           | Controlled visibility for programmatic states (loading, etc.); OR-ed with `revealOn`.                                      |
| `showOnTouch` | `boolean`                                                   | `false`     | With `revealOn="hover"`, keep the glow visible on touch devices (which have no hover) instead of hidden.                   |
| `pressScale`  | `boolean`                                                   | `false`     | Scale the glow down while pressed, to track a child `Button`'s own active-press scale.                                     |
| `className`   | `string`                                                    | —           | Extra classes, merged via `tailwind-merge`. Set the radius here to match your content.                                     |
| `style`       | `CSSProperties`                                             | —           | Inline styles on the wrapper.                                                                                              |

`GradientGlow` renders a `<div>` and forwards every remaining native `<div>` attribute. The glow and
border layers are `aria-hidden` and `pointer-events-none`.

In dark mode the glow and border are automatically dimmed to 60% opacity so they don't look too bright
against dark backgrounds. Tune this via the `--gradient-glow-opacity` CSS variable, e.g.
`className="dark:[--gradient-glow-opacity:0.8]"`.

## Accessibility [#accessibility]

* The glow and border layers are `aria-hidden` and `pointer-events-none`, so they're skipped by assistive
  tech and never intercept clicks.
* Content is wrapped, not replaced — your `children` stay in the normal flow and fully accessible.
* The motion honours `prefers-reduced-motion`: the rotation and pulse only run under the `motion-safe`
  variant, so reduced-motion users see a static gradient instead of the drift.
* The glow is purely decorative — keep your content's own surface and text contrast intact so it stays
  readable regardless of the colors behind it.


# Input (/ui/components/react/input)



<Playground component="input" />

## Usage [#usage]

```tsx
import { Input } from '@appica/ui-react/input'
```

```tsx
<Input type="email" placeholder="you@example.com" />
```

`Input` is a styled text field built on [Base UI's Input](https://base-ui.com/react/components/input). Use it like a native `<input>` — every native attribute (`type`, `value`, `onChange`, `name`, …) passes straight through. Give it a label the usual way: an external `<label htmlFor>` pointing at its `id`, or an `aria-label`.

Add an icon or prefix with `startSlot` / `endSlot`, and a clear button with `clearable`. When any of those are present, `Input` renders a wrapper around the field so the adornments sit inside the same frame; otherwise it renders the bare input.

## Examples [#examples]

### Variants [#variants]

`variant` switches the appearance between a bordered `outline` (default) and a filled `soft` field.

```tsx
import { Input } from '@appica/ui-react/input'

export default function InputVariants() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      <Input variant="outline" placeholder="Outline" aria-label="Outline" />
      <Input variant="soft" placeholder="Soft" aria-label="Soft" />
    </div>
  )
}
```

### Sizes [#sizes]

`inputSize` scales the height, padding, and text — `sm`, `md` (default), or `lg`. (It's named `inputSize` so it doesn't collide with the native `size` attribute.)

```tsx
import { Input } from '@appica/ui-react/input'

export default function InputSizes() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      <Input inputSize="sm" placeholder="Small" aria-label="Small" />
      <Input inputSize="md" placeholder="Medium" aria-label="Medium" />
      <Input inputSize="lg" placeholder="Large" aria-label="Large" />
    </div>
  )
}
```

### Start & end slots [#start--end-slots]

`startSlot` and `endSlot` take any node — not just icons — and render it inside the field frame. Use them for a leading icon with a static text suffix, an [`Avatar`](/ui/components/react/avatar), or an interactive control like a password-visibility [`Button`](/ui/components/react/button).

```tsx
'use client'

import { useState } from 'react'
import { Input } from '@appica/ui-react/input'
import { Avatar, AvatarFallback } from '@appica/ui-react/avatar'
import { Button } from '@appica/ui-react/button'
import { Mail, Lock, Eye, EyeOff, UserFilled } from '@appica/icons-react'

export default function InputSlots() {
  const [show, setShow] = useState(false)
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      <Input
        startSlot={<Mail />}
        endSlot={<span className="text-foreground-muted text-sm">@example.com</span>}
        placeholder="yourname"
        aria-label="Email username"
      />
      <Input
        startSlot={
          <Avatar size="2xs">
            <AvatarFallback>
              <UserFilled />
            </AvatarFallback>
          </Avatar>
        }
        placeholder="Display name"
        aria-label="Display name"
      />
      <Input
        type={show ? 'text' : 'password'}
        startSlot={<Lock />}
        defaultValue="hidden@password"
        endSlot={
          <Button
            className="-me-1.5"
            variant="ghost"
            size="icon-sm"
            aria-label={show ? 'Hide password' : 'Show password'}
            onClick={() => setShow((v) => !v)}
          >
            {show ? <EyeOff /> : <Eye />}
          </Button>
        }
        aria-label="Password"
      />
    </div>
  )
}
```

### Clearable [#clearable]

Set `clearable` to add a clear (✕) button that appears once the field has a value and empties it on click. Pair it with `onClear` to react to the reset.

```tsx
import { Input } from '@appica/ui-react/input'
import { Search } from '@appica/icons-react'

export default function InputClearable() {
  return (
    <Input
      className="max-w-70"
      clearable
      startSlot={<Search />}
      defaultValue="Wireless headphones"
      aria-label="Search products"
    />
  )
}
```

### Disabled, read-only & error states [#disabled-read-only--error-states]

`disabled` greys out the field and blocks interaction; `readOnly` keeps it focusable and selectable but prevents edits. Set `aria-invalid` to paint the error state — it's mirrored to `data-invalid`. Inside a [`Field`](/ui/components/react/field), the input also inherits the field's `disabled` and `invalid` state, which is the better choice when you're rendering a validation message.

```tsx
import { Input } from '@appica/ui-react/input'

export default function InputStates() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      <Input placeholder="Disabled" disabled aria-label="Disabled" />
      <Input defaultValue="Read-only value" readOnly aria-label="Read-only" />
      <Input defaultValue="Input with error" aria-invalid aria-label="Input with error" />
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The text aligns to the start edge and the `startSlot`/`endSlot` adornments swap sides to follow the resolved direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="input" />

## API reference [#api-reference]

`Input` wraps [Base UI's Input](https://base-ui.com/react/components/input) and forwards every remaining native `<input>` prop (`type`, `name`, `onChange`, `aria-*`, …); the `variant`, `inputSize`, `clearable`, `startSlot`, `endSlot`, `onClear`, and `inputProps` props are Appica additions. Inside a Base UI [`Field`](/ui/components/react/field) it picks up the field's `disabled` and `invalid` state, and exposes `data-disabled` / `data-invalid` for styling.

When adornments or `clearable` are present the field renders inside a wrapper, so `className` lands on that wrapper. Use `inputProps` to reach the inner `<input>` itself (for example to give it its own `className`).

| Prop           | <ColMinWidth width="200">Type</ColMinWidth> | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                          |
| -------------- | ------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------- |
| `variant`      | <Code>'outline' \| 'soft'</Code>            | `'outline'` | Field appearance — bordered or filled.                                                      |
| `inputSize`    | <Code>'sm' \| 'md' \| 'lg'</Code>           | `'md'`      | Scales height, padding, and text. Named `inputSize` to avoid the native `size` attribute.   |
| `startSlot`    | `ReactNode`                                 | —           | Adornment rendered before the field, inside the frame.                                      |
| `endSlot`      | `ReactNode`                                 | —           | Adornment rendered after the field, inside the frame.                                       |
| `clearable`    | `boolean`                                   | `false`     | Show a clear (✕) button once the field has a value.                                         |
| `onClear`      | <Code>() => void</Code>                     | —           | Called when the clear button is pressed.                                                    |
| `inputProps`   | <Code>Omit\<InputProps, 'size'></Code>      | —           | Props for the inner `<input>` in wrapper mode (its own `className`, handlers, …).           |
| `aria-invalid` | <Code>boolean \| 'true' \| 'false'</Code>   | —           | Marks the error state; mirrored to `data-invalid`.                                          |
| `disabled`     | `boolean`                                   | `false`     | Disables the field and removes it from the tab order.                                       |
| `placeholder`  | `string`                                    | `' '`       | Placeholder text.                                                                           |
| `value`        | `string`                                    | —           | Controlled value. Pair with `onChange`.                                                     |
| `defaultValue` | `string`                                    | —           | Uncontrolled initial value.                                                                 |
| `ref`          | <Code>Ref\<HTMLInputElement></Code>         | —           | Ref to the underlying `<input>`.                                                            |
| `className`    | `string`                                    | —           | Extra classes, merged via `tailwind-merge` (lands on the wrapper when adornments are used). |

## Accessibility [#accessibility]

* Renders a native `<input>` (`role="textbox"`). Give it an accessible name — an external `<label htmlFor>` pointing at its `id`, or an `aria-label`.
* The clear button is labelled **Clear input**, kept out of the tab order (`tabIndex={-1}`), and appears only when the field has a value.
* `aria-invalid` is bridged to `data-invalid` so the error state styles with or without a wrapping `Field`.
* `disabled` removes the field from the tab order and exposes `data-disabled` for styling.


# Kbd (/ui/components/react/kbd)



<Playground component="kbd" />

## Usage [#usage]

```tsx
import { Kbd, KbdGroup } from '@appica/ui-react/kbd'
```

```tsx
<Kbd>Esc</Kbd>

<KbdGroup>
  <Kbd>⌘</Kbd>
  <Kbd>K</Kbd>
</KbdGroup>
```

`Kbd` renders a single keyboard key — a styled `<kbd>` element — for documenting shortcuts inline, in tooltips, and in menus. Two parts live under `@appica/ui-react/kbd`:

* **`Kbd`** — one key. Three `size`s; the content is whatever you pass as children (a letter, a word like `Esc`, or a glyph like `⌘`).
* **`KbdGroup`** — a wrapper that lays out a sequence of keys with even spacing and propagates a shared `size` to the `Kbd`s inside it.

It's purely presentational: it carries no shortcut behavior, so wire up the actual key handling yourself.

## Examples [#examples]

### Default [#default]

A single key sized to its content — narrow for one letter, wider for a word. The minimum width keeps single characters square.

```tsx
import { Kbd } from '@appica/ui-react/kbd'

export default function KbdDefault() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <Kbd>Esc</Kbd>
      <Kbd>Tab</Kbd>
      <Kbd>⌘</Kbd>
      <Kbd>⇧</Kbd>
      <Kbd>↵</Kbd>
      <Kbd>Space</Kbd>
    </div>
  )
}
```

### Sizes [#sizes]

Three sizes — `sm`, `md` (default), and `lg` — scale the height, padding, and text together so a key sits comfortably next to surrounding type.

```tsx
import { Kbd } from '@appica/ui-react/kbd'

const sizes = ['sm', 'md', 'lg'] as const

export default function KbdSizes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-4">
      {sizes.map((size) => (
        <Kbd key={size} size={size}>
          ⌘ K
        </Kbd>
      ))}
    </div>
  )
}
```

### Key combinations [#key-combinations]

Wrap several `Kbd`s in a `KbdGroup` to show a chord. The group spaces the keys evenly and pushes a shared `size` down to each one — and leaves any non-`Kbd` child (like a `+` separator) untouched.

```tsx
import { Kbd, KbdGroup } from '@appica/ui-react/kbd'

export default function KbdGroupExample() {
  return (
    <div className="flex flex-col items-center gap-4 text-sm">
      <KbdGroup>
        <Kbd>⌘</Kbd>
        <Kbd>⇧</Kbd>
        <Kbd>P</Kbd>
      </KbdGroup>

      <KbdGroup>
        <Kbd>Ctrl</Kbd>
        <span className="text-foreground-muted">+</span>
        <Kbd>Alt</Kbd>
        <span className="text-foreground-muted">+</span>
        <Kbd>Del</Kbd>
      </KbdGroup>

      <span className="text-foreground-muted">
        Press{' '}
        <KbdGroup size="sm">
          <Kbd>⌘</Kbd>
          <Kbd>K</Kbd>
        </KbdGroup>{' '}
        to open the command menu
      </span>
    </div>
  )
}
```

### Shortcut list [#shortcut-list]

A common layout: action on one side, its shortcut on the other. The `KbdGroup` keeps each combo aligned and consistently sized.

```tsx
import { Kbd, KbdGroup } from '@appica/ui-react/kbd'

const shortcuts = [
  { action: 'Open command menu', keys: ['⌘', 'K'] },
  { action: 'New file', keys: ['⌘', 'N'] },
  { action: 'Search', keys: ['⌘', 'F'] },
  { action: 'Toggle sidebar', keys: ['⌘', 'B'] },
]

export default function KbdShortcuts() {
  return (
    <ul className="flex w-full max-w-80 flex-col gap-0.5">
      {shortcuts.map(({ action, keys }) => (
        <li
          key={action}
          className="bg-background-subtle flex items-center justify-between gap-4 px-4 py-2.5 text-sm first:rounded-t-lg last:rounded-b-lg"
        >
          <span>{action}</span>
          <KbdGroup size="sm">
            {keys.map((key) => (
              <Kbd key={key}>{key}</Kbd>
            ))}
          </KbdGroup>
        </li>
      ))}
    </ul>
  )
}
```

### Inside a button [#inside-a-button]

Drop a `Kbd` into a [`Button`](/ui/components/react/button) as a trailing shortcut hint — a familiar pattern for search and command-menu triggers.

```tsx
import { Button } from '@appica/ui-react/button'
import { Kbd } from '@appica/ui-react/kbd'
import { Search } from '@appica/icons-react'

export default function KbdInButton() {
  return (
    <Button variant="outline" className="gap-3">
      <Search data-icon="start" />
      Search
      <Kbd size="sm" data-icon="end" className="-me-0.5">
        ⌘ K
      </Kbd>
    </Button>
  )
}
```

### Inside a tooltip [#inside-a-tooltip]

`Kbd` detects a [`Tooltip`](/ui/components/react/tooltip) surface and inverts its colors automatically, so a shortcut stays legible against the dark tooltip background with no extra styling.

```tsx
import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'
import { Button } from '@appica/ui-react/button'
import { Kbd } from '@appica/ui-react/kbd'
import { Bookmark } from '@appica/icons-react'

export default function KbdInTooltip() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger
          render={
            <Button variant="outline" size="icon-md" aria-label="Save">
              <Bookmark />
            </Button>
          }
        />
        <TooltipContent className="flex items-center gap-2">
          Save
          <Kbd size="sm">⌘ S</Kbd>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The list and its labels flip to the right, while each shortcut's keys stay in left-to-right reading order — pin the `KbdGroup` with `dir="ltr"` so a `⌘ K` combo isn't reversed into `K ⌘`. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="kbd" />

## API reference [#api-reference]

`Kbd` and `KbdGroup` are styled native elements (`<kbd>` and `<span>`) — they're not Base UI primitives. Each forwards `ref` and every remaining attribute to its underlying element.

### Kbd [#kbd]

A single key. Renders a `<kbd>`.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="240">Description</ColMinWidth>            |
| ----------- | ------------------------------------------- | ------- | ------------------------------------------------------------- |
| `size`      | <Code>'sm' \| 'md' \| 'lg'</Code>           | `'md'`  | Height, padding, and text scale. Inherited from a `KbdGroup`. |
| `children`  | `ReactNode`                                 | —       | The key label — a letter, word, or glyph.                     |
| `className` | `string`                                    | —       | Extra classes, merged via `tailwind-merge`.                   |

### KbdGroup [#kbdgroup]

A row of keys. Renders a `<span>` and forwards `size` to its `Kbd` children.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="240">Description</ColMinWidth>                   |
| ----------- | ------------------------------------------- | ------- | -------------------------------------------------------------------- |
| `size`      | <Code>'sm' \| 'md' \| 'lg'</Code>           | `'md'`  | Default size applied to each child `Kbd` that doesn't set its own.   |
| `children`  | `ReactNode`                                 | —       | The keys (and any separators). A `Kbd` with its own `size` keeps it. |
| `className` | `string`                                    | —       | Extra classes, merged via `tailwind-merge`.                          |

## Accessibility [#accessibility]

* `Kbd` renders the semantic `<kbd>` element, which assistive tech recognizes as keyboard input.
* The component is decorative documentation, not an interactive control — pair it with the real key handler, and make sure the shortcut also has a discoverable, non-keyboard way to trigger the same action.
* When a glyph alone might be ambiguous (e.g. `⌘` vs "Command"), consider an `aria-label` on the `Kbd` so it's announced clearly.
* Inside a `KbdGroup`, keys read in source order; pin the group to `dir="ltr"` under RTL so a combo isn't announced or displayed in reverse.


# Loader (/ui/components/react/loader)



<Playground component="loader" />

## Usage [#usage]

```tsx
import { Loader } from '@appica/ui-react/loader'
```

```tsx
<Loader />
```

`Loader` is an indeterminate progress indicator — it conveys "working on it" without a percentage. It comes in two shapes via `variant`: `bar` (a track with a sweeping fill, the default) and `dots` (three dots flowing left to right). Both read a little more like *progress* than a [`Spinner`](/ui/components/react/spinner), so they suit section- and status-level waits.

Like the spinner, it's **sized by font-size** — set a `text-*` class (or inherit `1em`) to scale it — and `currentColor` makes it match the surrounding text instead of the primary accent. It renders a `role="status"` element labelled "Loading".

Use `Loader` for "this area is loading", inline status text, and "load more" buttons. For a compact spinner inside a small button or icon button, reach for [`Spinner`](/ui/components/react/spinner) instead.

## Examples [#examples]

### Variants [#variants]

Two shapes: `bar` (a sweeping track) and `dots` (a flowing trio). Both loop indefinitely and honour `prefers-reduced-motion` by holding a static frame.

```tsx
import { Loader } from '@appica/ui-react/loader'

const VARIANTS = ['bar', 'dots'] as const

export default function LoaderVariants() {
  return (
    <div className="flex items-center gap-12">
      {VARIANTS.map((variant) => (
        <div key={variant} className="flex flex-col items-center gap-3">
          <Loader variant={variant} />
          <span className="text-foreground-muted text-xs">{variant}</span>
        </div>
      ))}
    </div>
  )
}
```

### Sizing [#sizing]

The loader scales with `font-size`, so a `text-*` utility resizes it — there's no `size` prop. Its width/height ratio is fixed, so it grows proportionally.

```tsx
import { Loader } from '@appica/ui-react/loader'

export default function LoaderSizing() {
  return (
    <div className="flex flex-wrap items-center gap-8">
      <Loader className="text-xl" />
      <Loader className="text-3xl" />
      <Loader className="text-5xl" />
      <Loader className="text-7xl" />
    </div>
  )
}
```

### Color [#color]

By default the loader uses the primary accent (with a soft track on the `bar`). Add `currentColor` and it adopts the surrounding text color instead.

```tsx
import { Loader } from '@appica/ui-react/loader'

export default function LoaderColor() {
  return (
    <div className="flex items-center gap-12 text-4xl">
      <Loader />
      <span className="text-violet-500">
        <Loader currentColor />
      </span>
      <span className="text-success-emphasis">
        <Loader currentColor />
      </span>
    </div>
  )
}
```

### Load more [#load-more]

A "load more" button that shows the `dots` loader while the next page fetches. `currentColor` matches the button text.

```tsx
'use client'

import * as React from 'react'
import { Button } from '@appica/ui-react/button'
import { Loader } from '@appica/ui-react/loader'

const ALL = ['Aurora', 'Borealis', 'Cosmos', 'Drift', 'Ember', 'Flux', 'Glow', 'Halo', 'Ion']

export default function LoaderButton() {
  const [count, setCount] = React.useState(3)
  const [loading, setLoading] = React.useState(false)

  const loadMore = () => {
    setLoading(true)
    setTimeout(() => {
      setCount((c) => Math.min(c + 3, ALL.length))
      setLoading(false)
    }, 1400)
  }

  return (
    <div className="flex w-56 flex-col gap-2">
      <ul className="flex flex-col gap-2">
        {ALL.slice(0, count).map((item) => (
          <li
            key={item}
            className="bg-background-subtle border-border-muted text-foreground-emphasis rounded-lg border px-4 py-3 text-sm"
          >
            {item}
          </li>
        ))}
      </ul>
      {count < ALL.length && (
        <Button onClick={loadMore} disabled={loading} className="self-center">
          {loading ? <Loader variant="dots" currentColor className="text-3xl" /> : 'Load more'}
        </Button>
      )}
    </div>
  )
}
```

### Section loading [#section-loading]

Drive a panel from your own loading state — show a centred loader while data is in flight, then swap in the content. The Refresh button re-runs it.

```tsx
'use client'

import * as React from 'react'
import { Button } from '@appica/ui-react/button'
import { Loader } from '@appica/ui-react/loader'

export default function LoaderSection() {
  const [loading, setLoading] = React.useState(true)

  const load = React.useCallback(() => {
    setLoading(true)
    const timer = setTimeout(() => setLoading(false), 1800)
    return () => clearTimeout(timer)
  }, [])

  React.useEffect(() => load(), [load])

  return (
    <div className="border-border bg-background w-80 overflow-hidden rounded-xl border">
      <div className="border-border-muted bg-background-subtle flex items-center justify-between border-b px-4 py-2.5">
        <span className="text-foreground-intense text-sm font-semibold">Revenue</span>
        <Button variant="outline" size="sm" onClick={load} disabled={loading}>
          Refresh
        </Button>
      </div>
      <div className="flex h-32 items-center justify-center p-4">
        {loading ? (
          <div className="flex flex-col items-center gap-3">
            <Loader variant="bar" className="text-4xl" />
            <span className="text-foreground-muted text-xs">Crunching the numbers…</span>
          </div>
        ) : (
          <div className="text-center">
            <p className="text-foreground-intense mb-0.5 text-3xl font-semibold">$48,250</p>
            <p className="text-success-emphasis text-sm">+12.5% this month</p>
          </div>
        )}
      </div>
    </div>
  )
}
```

### Inline status [#inline-status]

Set `currentColor` and drop a loader straight into a line of text — sized in `em`, it sits on the baseline next to a "syncing…" or "uploading…" message and takes the text's color.

```tsx
import { Loader } from '@appica/ui-react/loader'

export default function LoaderInline() {
  return (
    <div className="flex flex-col gap-4 text-sm">
      <span className="text-foreground-muted inline-flex items-center gap-2">
        Syncing your changes
        <Loader variant="dots" currentColor className="text-[1.6em]" />
      </span>
      <span className="text-secondary-emphasis inline-flex items-center gap-2">
        Uploading 3 files
        <Loader variant="bar" currentColor className="text-[1.6em]" />
      </span>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

Beside text, the loader sits on the correct side under RTL since it follows the inline flow. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="loader" />

## API reference [#api-reference]

`Loader` renders a single `<span role="status">` and forwards `ref`, `className`, and any other span attributes.

| Prop           | <ColMinWidth width="210">Type</ColMinWidth> | Default     | <ColMinWidth width="240">Description</ColMinWidth>                                                         |
| -------------- | ------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
| `variant`      | <Code>'bar' \| 'dots'</Code>                | `'bar'`     | The animated shape.                                                                                        |
| `currentColor` | `boolean`                                   | `false`     | Inherit the surrounding text color (`currentColor`) instead of the primary accent.                         |
| `aria-label`   | `string`                                    | `'Loading'` | Accessible name for the `role="status"` region.                                                            |
| `className`    | `string`                                    | —           | Extra classes, merged via `tailwind-merge`. Set a `text-*` size here — the loader scales with `font-size`. |

## Accessibility [#accessibility]

* The loader is a `role="status"` live region with a default `aria-label="Loading"`; pass a more specific label (e.g. "Uploading files") when it helps.
* When a loader replaces a section's content, keep one labelled status in the region rather than several, so screen readers announce a single "loading" state.
* A loader sitting beside text that already states the status can be marked `aria-hidden` to avoid a duplicate announcement.
* The animation is replaced by a static frame when the user prefers reduced motion.


# Menubar (/ui/components/react/menubar)



<Playground component="menubar" />

## Usage [#usage]

```tsx
import {
  Menubar,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
  MenubarItem,
  MenubarSeparator,
  MenubarSub,
  MenubarSubTrigger,
  MenubarSubContent,
} from '@appica/ui-react/menubar'
```

```tsx
<Menubar aria-label="Application">
  <MenubarMenu>
    <MenubarTrigger>File</MenubarTrigger>
    <MenubarContent>
      <MenubarItem>New file</MenubarItem>
      <MenubarItem>Open…</MenubarItem>
      <MenubarSub>
        <MenubarSubTrigger>Open recent</MenubarSubTrigger>
        <MenubarSubContent>
          <MenubarItem>project-alpha</MenubarItem>
          <MenubarItem>landing-page</MenubarItem>
        </MenubarSubContent>
      </MenubarSub>
      <MenubarSeparator />
      <MenubarItem>Save</MenubarItem>
    </MenubarContent>
  </MenubarMenu>
  <MenubarMenu>
    <MenubarTrigger>Edit</MenubarTrigger>
    <MenubarContent>
      <MenubarItem>Undo</MenubarItem>
      <MenubarItem>Redo</MenubarItem>
    </MenubarContent>
  </MenubarMenu>
</Menubar>
```

`Menubar` is a compound component built on [Base UI's Menubar](https://base-ui.com/react/components/menubar). The root is the bar that coordinates a row (or column) of menus, sharing `variant`, `size`, and `orientation` with all of them:

* **`MenubarMenu`** — wraps one menu (a menu root under the hood). It inherits the bar's `size`.
* **`MenubarTrigger`** — the top-level label that opens its menu. Once any menu is open, moving the pointer to a sibling trigger switches to it; arrow keys move focus along the bar.
* **`MenubarContent`** — the portalled popup for that menu. In a vertical bar it opens to the side automatically.
* **`MenubarItem`** — one action. Fires `onClick` and closes the menu by default.
* **`MenubarGroup`*&#x2A; / &#x2A;*`MenubarGroupLabel`*&#x2A; / &#x2A;*`MenubarSeparator`** — structure for sectioned menus.
* **`MenubarCheckboxItem`*&#x2A; / &#x2A;*`MenubarRadioGroup`*&#x2A; + &#x2A;*`MenubarRadioItem`** — stateful options with a check indicator.
* **`MenubarLinkItem`** — an item that renders an `<a>` for navigation.
* **`MenubarSub`*&#x2A; / &#x2A;*`MenubarSubTrigger`*&#x2A; / &#x2A;*`MenubarSubContent`** — a nested submenu.

Inside an item, put a leading icon on `data-icon="start"`, and push a trailing [`Kbd`](/ui/components/react/kbd) shortcut to the edge with `ms-auto`.

Reach for a `Menubar` for the persistent **command bar** of an application (File / Edit / View …). For a single menu opened from one button, use a [`DropdownMenu`](/ui/components/react/dropdown-menu); for in-page navigation with rich panels, use a [`Navigation Menu`](/ui/components/react/navigation-menu).

## Examples [#examples]

### Application menu [#application-menu]

A typical desktop-style command bar — File, Edit, and View menus with keyboard shortcuts, separators, a nested "Open recent" submenu, and a disabled item.

```tsx
import {
  Menubar,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
  MenubarItem,
  MenubarSeparator,
  MenubarSub,
  MenubarSubTrigger,
  MenubarSubContent,
} from '@appica/ui-react/menubar'
import { Kbd } from '@appica/ui-react/kbd'

export default function MenubarDefault() {
  return (
    <Menubar aria-label="Application">
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            New file
            <Kbd size="sm" className="ms-auto">
              ⌘N
            </Kbd>
          </MenubarItem>
          <MenubarItem>
            Open…
            <Kbd size="sm" className="ms-auto">
              ⌘O
            </Kbd>
          </MenubarItem>
          <MenubarSub>
            <MenubarSubTrigger>Open recent</MenubarSubTrigger>
            <MenubarSubContent>
              <MenubarItem>project-alpha</MenubarItem>
              <MenubarItem>landing-page</MenubarItem>
              <MenubarItem>design-system</MenubarItem>
            </MenubarSubContent>
          </MenubarSub>
          <MenubarSeparator />
          <MenubarItem>
            Save
            <Kbd size="sm" className="ms-auto">
              ⌘S
            </Kbd>
          </MenubarItem>
          <MenubarItem>
            Save as…
            <Kbd size="sm" className="ms-auto">
              ⇧⌘S
            </Kbd>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>

      <MenubarMenu>
        <MenubarTrigger>Edit</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            Undo
            <Kbd size="sm" className="ms-auto">
              ⌘Z
            </Kbd>
          </MenubarItem>
          <MenubarItem>
            Redo
            <Kbd size="sm" className="ms-auto">
              ⇧⌘Z
            </Kbd>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem>Cut</MenubarItem>
          <MenubarItem>Copy</MenubarItem>
          <MenubarItem>Paste</MenubarItem>
        </MenubarContent>
      </MenubarMenu>

      <MenubarMenu>
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>Zoom in</MenubarItem>
          <MenubarItem>Zoom out</MenubarItem>
          <MenubarItem>Reset zoom</MenubarItem>
          <MenubarSeparator />
          <MenubarItem disabled>Enter full screen</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  )
}
```

### Variants [#variants]

`variant` styles the triggers: `pill` (default) gives each a hover/active pill, while `line` draws an animated underline — closer to a classic desktop menu bar.

```tsx
import { Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem } from '@appica/ui-react/menubar'

const MENUS = ['File', 'Edit', 'View']

function Menus() {
  return MENUS.map((label) => (
    <MenubarMenu key={label}>
      <MenubarTrigger>{label}</MenubarTrigger>
      <MenubarContent>
        <MenubarItem>Action one</MenubarItem>
        <MenubarItem>Action two</MenubarItem>
        <MenubarItem>Action three</MenubarItem>
      </MenubarContent>
    </MenubarMenu>
  ))
}

export default function MenubarVariants() {
  return (
    <div className="flex flex-col items-center gap-8">
      <Menubar variant="pill" aria-label="Pill menubar">
        <Menus />
      </Menubar>
      <Menubar variant="line" aria-label="Line menubar">
        <Menus />
      </Menubar>
    </div>
  )
}
```

### Vertical [#vertical]

Set `orientation="vertical"` to stack the menus into a sidebar. Triggers can carry a leading icon (`data-icon="start"`), and each menu opens to the inline-end side. Menus normally only flip to the opposite same-axis side; pass `collisionAvoidance={{ fallbackAxisSide: 'end' }}` so a side-opening menu can also fall back to the top/bottom axis when it doesn't fit there.

```tsx
import {
  Menubar,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
  MenubarItem,
  MenubarSeparator,
} from '@appica/ui-react/menubar'
import { LayoutDashboard, Folder, Users, Settings } from '@appica/icons-react'

export default function MenubarVertical() {
  return (
    <Menubar orientation="vertical" aria-label="Workspace" className="w-35">
      <MenubarMenu>
        <MenubarTrigger>
          <LayoutDashboard data-icon="start" />
          Overview
        </MenubarTrigger>
        <MenubarContent collisionAvoidance={{ fallbackAxisSide: 'end' }}>
          <MenubarItem>Summary</MenubarItem>
          <MenubarItem>Activity</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>
          <Folder data-icon="start" />
          Projects
        </MenubarTrigger>
        <MenubarContent collisionAvoidance={{ fallbackAxisSide: 'end' }}>
          <MenubarItem>All projects</MenubarItem>
          <MenubarItem>New project</MenubarItem>
          <MenubarSeparator />
          <MenubarItem>Archived</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>
          <Users data-icon="start" />
          Team
        </MenubarTrigger>
        <MenubarContent collisionAvoidance={{ fallbackAxisSide: 'end' }}>
          <MenubarItem>Members</MenubarItem>
          <MenubarItem>Invitations</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>
          <Settings data-icon="start" />
          Settings
        </MenubarTrigger>
        <MenubarContent collisionAvoidance={{ fallbackAxisSide: 'end' }}>
          <MenubarItem>General</MenubarItem>
          <MenubarItem>Billing</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  )
}
```

### Submenus [#submenus]

Nest a `MenubarSub` inside a menu with its own `MenubarSubTrigger` and `MenubarSubContent`. The sub-trigger shows a chevron and opens to the side on hover or with the arrow keys, flipping automatically near a screen edge.

```tsx
import {
  Menubar,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
  MenubarItem,
  MenubarSeparator,
  MenubarSub,
  MenubarSubTrigger,
  MenubarSubContent,
} from '@appica/ui-react/menubar'
import { Kbd } from '@appica/ui-react/kbd'

export default function MenubarSubmenu() {
  return (
    <Menubar aria-label="Application">
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            New file
            <Kbd size="sm" className="ms-auto">
              ⌘N
            </Kbd>
          </MenubarItem>
          <MenubarSub>
            <MenubarSubTrigger>Open recent</MenubarSubTrigger>
            <MenubarSubContent>
              <MenubarItem>project-alpha</MenubarItem>
              <MenubarItem>landing-page</MenubarItem>
              <MenubarItem>design-system</MenubarItem>
              <MenubarSeparator />
              <MenubarItem>Clear recent</MenubarItem>
            </MenubarSubContent>
          </MenubarSub>
          <MenubarSeparator />
          <MenubarItem>
            Save
            <Kbd size="sm" className="ms-auto">
              ⌘S
            </Kbd>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>

      <MenubarMenu>
        <MenubarTrigger>Share</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>Copy link</MenubarItem>
          <MenubarSub>
            <MenubarSubTrigger>Export as</MenubarSubTrigger>
            <MenubarSubContent>
              <MenubarItem>PDF</MenubarItem>
              <MenubarItem>PNG</MenubarItem>
              <MenubarItem>SVG</MenubarItem>
            </MenubarSubContent>
          </MenubarSub>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  )
}
```

### Checkbox & radio items [#checkbox--radio-items]

Menus support the same stateful items as `DropdownMenu` — `MenubarCheckboxItem` for toggles and a `MenubarRadioGroup` of `MenubarRadioItem`s for a single choice, both grouped under a `MenubarGroupLabel`.

```tsx
'use client'

import * as React from 'react'
import {
  Menubar,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
  MenubarItem,
  MenubarGroup,
  MenubarGroupLabel,
  MenubarCheckboxItem,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSeparator,
} from '@appica/ui-react/menubar'

export default function MenubarSelections() {
  const [toolbar, setToolbar] = React.useState(true)
  const [sidebar, setSidebar] = React.useState(false)
  const [theme, setTheme] = React.useState('system')

  return (
    <Menubar aria-label="Editor">
      <MenubarMenu>
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarContent>
          <MenubarGroup>
            <MenubarGroupLabel>Panels</MenubarGroupLabel>
            <MenubarCheckboxItem checked={toolbar} onCheckedChange={setToolbar}>
              Toolbar
            </MenubarCheckboxItem>
            <MenubarCheckboxItem checked={sidebar} onCheckedChange={setSidebar}>
              Sidebar
            </MenubarCheckboxItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarRadioGroup value={theme} onValueChange={setTheme}>
            <MenubarGroupLabel>Theme</MenubarGroupLabel>
            <MenubarRadioItem value="light">Light</MenubarRadioItem>
            <MenubarRadioItem value="dark">Dark</MenubarRadioItem>
            <MenubarRadioItem value="system">System</MenubarRadioItem>
          </MenubarRadioGroup>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Help</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>Documentation</MenubarItem>
          <MenubarItem>Keyboard shortcuts</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  )
}
```

### Leading icons [#leading-icons]

Put a leading icon on the `data-icon="start"` slot, before the label — it works on both a `MenubarTrigger` and a `MenubarItem`, which reserves space and aligns every row's text. Pair an item with a trailing [`Kbd`](/ui/components/react/kbd) shortcut pushed to the edge with `ms-auto`.

```tsx
import {
  Menubar,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
  MenubarItem,
  MenubarSeparator,
} from '@appica/ui-react/menubar'
import { Kbd } from '@appica/ui-react/kbd'
import {
  FileText,
  Pencil,
  Eye,
  FilePlus,
  FolderOpen,
  Download,
  CornerUpLeft,
  CornerUpRight,
  Scissors,
  Copy,
  Clipboard,
  ZoomIn,
  ZoomOut,
  Maximize,
} from '@appica/icons-react'

export default function MenubarIcons() {
  return (
    <Menubar aria-label="Application">
      <MenubarMenu>
        <MenubarTrigger>
          <FileText data-icon="start" />
          File
        </MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            <FilePlus data-icon="start" />
            New file
            <Kbd size="sm" className="ms-auto">
              ⌘N
            </Kbd>
          </MenubarItem>
          <MenubarItem>
            <FolderOpen data-icon="start" />
            Open…
            <Kbd size="sm" className="ms-auto">
              ⌘O
            </Kbd>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem>
            <Download data-icon="start" />
            Save
            <Kbd size="sm" className="ms-auto">
              ⌘S
            </Kbd>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>

      <MenubarMenu>
        <MenubarTrigger>
          <Pencil data-icon="start" />
          Edit
        </MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            <CornerUpLeft data-icon="start" />
            Undo
          </MenubarItem>
          <MenubarItem>
            <CornerUpRight data-icon="start" />
            Redo
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem>
            <Scissors data-icon="start" />
            Cut
          </MenubarItem>
          <MenubarItem>
            <Copy data-icon="start" />
            Copy
          </MenubarItem>
          <MenubarItem>
            <Clipboard data-icon="start" />
            Paste
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>

      <MenubarMenu>
        <MenubarTrigger>
          <Eye data-icon="start" />
          View
        </MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            <ZoomIn data-icon="start" />
            Zoom in
          </MenubarItem>
          <MenubarItem>
            <ZoomOut data-icon="start" />
            Zoom out
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem>
            <Maximize data-icon="start" />
            Enter full screen
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus along the bar, popup placement, and submenu direction — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The bar lays out from the right, arrow-key focus reverses, and popups anchor and flip accordingly. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<Callout type="note" title="Scoped RTL needs the direction on the positioner">
  Each menu's popup portals to `<body>`, so its `start`/`end` alignment mirrors from the **document** direction (read from
  CSS, not from `DirectionProvider`) — automatic when `<html dir="rtl">`. If you instead scope RTL to a subtree of an LTR
  page, set it on the positioner so alignment still mirrors: `<MenubarContent positionerProps={{ dir: 'rtl' }}>`. See
  [Floating popups in a scoped RTL region](/ui/docs/react/rtl#floating-popups-in-a-scoped-rtl-region).
</Callout>

<RtlPreview component="menubar" />

## API reference [#api-reference]

`Menubar` wraps [Base UI's Menubar](https://base-ui.com/react/components/menubar) and composes a menu for each entry. Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### Menubar [#menubar]

The bar. Coordinates the menus and holds the shared styling/orientation; renders a `menubar` element.

| Prop          | <ColMinWidth width="200">Type</ColMinWidth> | Default        | <ColMinWidth width="220">Description</ColMinWidth>                |
| ------------- | ------------------------------------------- | -------------- | ----------------------------------------------------------------- |
| `variant`     | <Code>'pill' \| 'line'</Code>               | `'pill'`       | Trigger appearance — hover/active pill, or an animated underline. |
| `size`        | <Code>'sm' \| 'md' \| 'lg'</Code>           | `'md'`         | Scales the triggers, popups, and items together.                  |
| `orientation` | <Code>'horizontal' \| 'vertical'</Code>     | `'horizontal'` | Lay the bar out as a row or a column.                             |
| `modal`       | `boolean`                                   | `true`         | Trap focus and block outside interaction while a menu is open.    |
| `loopFocus`   | `boolean`                                   | `true`         | Wrap arrow-key focus from the last trigger back to the first.     |
| `disabled`    | `boolean`                                   | `false`        | Disable every menu in the bar.                                    |
| `className`   | `string`                                    | —              | Extra classes on the bar, merged via `tailwind-merge`.            |

### MenubarMenu [#menubarmenu]

Wraps one menu in the bar. Inherits the bar's `size`; forwards the rest to the underlying menu root.

| Prop           | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                           |
| -------------- | ------------------------------------------- | ------- | ------------------------------------- |
| `open`         | `boolean`                                   | —       | Controlled open state of this menu.   |
| `defaultOpen`  | `boolean`                                   | `false` | Uncontrolled initial open state.      |
| `onOpenChange` | <Code>(open, eventDetails) => void</Code>   | —       | Fires when this menu opens or closes. |

### MenubarTrigger [#menubartrigger]

The top-level label that opens its menu. Inherits the bar's `variant`, `size`, and `orientation`.

| Prop        | <ColMinWidth width="160">Type</ColMinWidth> | Default | Description                                                |
| ----------- | ------------------------------------------- | ------- | ---------------------------------------------------------- |
| `disabled`  | `boolean`                                   | `false` | Disable just this menu.                                    |
| `className` | `string`                                    | —       | Extra classes on the trigger, merged via `tailwind-merge`. |

### MenubarContent [#menubarcontent]

The portalled popup for a menu. In a vertical bar it defaults to `side="inline-end"` / `align="start"`; in a horizontal bar it opens below the trigger. Accepts the shared floating props.

| Prop               | <ColMinWidth width="160">Type</ColMinWidth>         | Default    | Description                                                     |
| ------------------ | --------------------------------------------------- | ---------- | --------------------------------------------------------------- |
| `side`             | <Code>'top' \| 'right' \| 'bottom' \| 'left'</Code> | `'bottom'` | Preferred side to open on.                                      |
| `align`            | <Code>'start' \| 'center' \| 'end'</Code>           | `'start'`  | Alignment along that side.                                      |
| `sideOffset`       | `number`                                            | `6`        | Gap between the trigger and the popup.                          |
| `alignOffset`      | `number`                                            | —          | Shift along the alignment axis.                                 |
| `collisionPadding` | `number`                                            | `5`        | Minimum gap kept from the viewport edge when flipping/shifting. |
| `container`        | <Code>HTMLElement \| ref \| null</Code>             | —          | Portal target — render the popup into a different node.         |
| `keepMounted`      | `boolean`                                           | `false`    | Keep the popup mounted in the DOM while closed.                 |
| `positionerProps`  | `object`                                            | —          | Escape hatch for the positioner element (`style`, `render`, …). |
| `portalProps`      | `object`                                            | —          | Escape hatch for the portal element (`style`, `render`, …).     |
| `className`        | `string`                                            | —          | Extra classes on the popup.                                     |

### MenubarItem [#menubaritem]

One action in a menu.

| Prop           | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                                                    |
| -------------- | ------------------------------------------- | ------- | -------------------------------------------------------------- |
| `closeOnClick` | `boolean`                                   | `true`  | Close the menu after the item is selected.                     |
| `disabled`     | `boolean`                                   | `false` | Make the item unselectable; skipped by keyboard and typeahead. |
| `onClick`      | <Code>(event) => void</Code>                | —       | Fires when the item is selected (click or Enter/Space).        |
| `className`    | `string`                                    | —       | Extra classes, merged via `tailwind-merge`.                    |

### MenubarCheckboxItem [#menubarcheckboxitem]

A toggleable item with a check indicator. Keeps the menu open on click.

| Prop              | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                                            |
| ----------------- | ------------------------------------------- | ------- | ------------------------------------------------------ |
| `checked`         | `boolean`                                   | —       | Controlled checked state. Pair with `onCheckedChange`. |
| `defaultChecked`  | `boolean`                                   | `false` | Uncontrolled initial checked state.                    |
| `onCheckedChange` | <Code>(checked) => void</Code>              | —       | Fires when the checked state changes.                  |
| `closeOnClick`    | `boolean`                                   | `false` | Close the menu when toggled.                           |
| `disabled`        | `boolean`                                   | `false` | Make the item unselectable.                            |

### MenubarRadioGroup [#menubarradiogroup]

Wraps a set of mutually exclusive `MenubarRadioItem`s.

| Prop            | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                                           |
| --------------- | ------------------------------------------- | ------- | ----------------------------------------------------- |
| `value`         | `string`                                    | —       | Controlled selected value. Pair with `onValueChange`. |
| `defaultValue`  | `string`                                    | —       | Uncontrolled initial value.                           |
| `onValueChange` | <Code>(value) => void</Code>                | —       | Fires when the selection changes.                     |

### MenubarRadioItem [#menubarradioitem]

One option in a `MenubarRadioGroup`. Keeps the menu open on click.

| Prop           | Type      | Default | Description                   |
| -------------- | --------- | ------- | ----------------------------- |
| `value`        | `string`  | —       | The value this item selects.  |
| `closeOnClick` | `boolean` | `false` | Close the menu when chosen.   |
| `disabled`     | `boolean` | `false` | Make the option unselectable. |

### MenubarLinkItem [#menubarlinkitem]

An item that renders an `<a>` for navigation. Forwards every native anchor prop (`href`, `target`, `rel`, …).

| Prop        | Type     | Default | Description                                 |
| ----------- | -------- | ------- | ------------------------------------------- |
| `href`      | `string` | —       | Navigation target.                          |
| `className` | `string` | —       | Extra classes, merged via `tailwind-merge`. |

### MenubarGroup [#menubargroup]

Wraps one labelled section of a menu so a `MenubarGroupLabel` can name it.

| Prop        | Type        | Default | Description                                     |
| ----------- | ----------- | ------- | ----------------------------------------------- |
| `children`  | `ReactNode` | —       | A `MenubarGroupLabel` plus the section's items. |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`.     |

### MenubarGroupLabel [#menubargrouplabel]

The visible heading for a `MenubarGroup`. Size-aware; must be rendered inside a `MenubarGroup` (or `MenubarRadioGroup`).

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The label text.                             |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### MenubarSeparator [#menubarseparator]

A thin divider between items or groups.

| Prop        | Type     | Default | Description                                 |
| ----------- | -------- | ------- | ------------------------------------------- |
| `className` | `string` | —       | Extra classes, merged via `tailwind-merge`. |

### MenubarSub [#menubarsub]

Wraps a nested submenu inside a menu.

| Prop          | <ColMinWidth width="180">Type</ColMinWidth> | Default | Description                           |
| ------------- | ------------------------------------------- | ------- | ------------------------------------- |
| `open`        | `boolean`                                   | —       | Controlled open state of the submenu. |
| `defaultOpen` | `boolean`                                   | `false` | Uncontrolled initial open state.      |

### MenubarSubTrigger [#menubarsubtrigger]

The item that opens a submenu; renders a trailing chevron. Submenus open on hover by default.

| Prop          | Type      | Default | Description                                 |
| ------------- | --------- | ------- | ------------------------------------------- |
| `openOnHover` | `boolean` | `true`  | Open the submenu on hover (and on click).   |
| `delay`       | `number`  | `100`   | Hover-open delay in ms.                     |
| `closeDelay`  | `number`  | `0`     | Hover-close delay in ms.                    |
| `className`   | `string`  | —       | Extra classes, merged via `tailwind-merge`. |

### MenubarSubContent [#menubarsubcontent]

The submenu popup. Defaults to opening on the `inline-end` side; otherwise identical to `MenubarContent`.

| Prop        | Type     | Default | Description                         |
| ----------- | -------- | ------- | ----------------------------------- |
| `className` | `string` | —       | Extra classes on the submenu popup. |

## Accessibility [#accessibility]

* The bar has `role="menubar"`; give it an accessible name with `aria-label`. Triggers are `menuitem`s with `aria-haspopup`, and each popup is a `menu`.
* **←/→*&#x2A; (or &#x2A;*↑/↓** when vertical) move focus between triggers; &#x2A;*Enter / Space / ↓** open a menu; **Escape** closes it back to its trigger; typeahead jumps to matching items.
* With a menu open, hovering a sibling trigger switches to its menu without an extra click.
* `disabled` triggers and items are skipped by keyboard navigation.
* Popup enter/exit transitions are skipped when the user prefers reduced motion.


# Meter (/ui/components/react/meter)



<Playground component="meter" />

## Usage [#usage]

```tsx
import { Meter, MeterLabel, MeterValue, MeterProgress } from '@appica/ui-react/meter'
```

```tsx
<Meter value={64}>
  <MeterLabel>Storage</MeterLabel>
  <MeterValue />
  <MeterProgress />
</Meter>
```

A `Meter` displays a **static measurement** inside a known range — disk usage, a score, remaining battery — as opposed to [`Progress`](/ui/components/react/progress), which tracks a task moving toward completion. Compose it from parts: `MeterLabel` names the reading, `MeterValue` prints the formatted number, and `MeterProgress` draws the track and fill. The root lays them out on a grid — label top-left, value top-right, track spanning underneath — so you can drop in only the parts you need.

By default the fill uses the primary accent. Pass the `low`, `high`, and `optimum` thresholds and the indicator recolors itself to signal whether the current reading is good, borderline, or bad — green, amber, or red.

## Examples [#examples]

### Default [#default]

A label, a formatted value, and a track. `value` is read against the default `0–100` range, and `MeterValue` renders it as a percentage out of the box.

```tsx
import { Meter, MeterLabel, MeterValue, MeterProgress } from '@appica/ui-react/meter'

export default function MeterDefault() {
  return (
    <Meter value={64} className="w-72 max-w-full">
      <MeterLabel>Storage</MeterLabel>
      <MeterValue />
      <MeterProgress />
    </Meter>
  )
}
```

### Status thresholds [#status-thresholds]

Pass `low`, `high`, and `optimum` and the indicator colors itself by zone: **optimum** (green) when the value sits on the same side as `optimum`, **suboptimum** (orange) one zone away, and **invalid** (red) at the far end. Here `optimum={10}` marks low usage as healthy, so a high reading turns red.

```tsx
import { Meter, MeterLabel, MeterValue, MeterProgress } from '@appica/ui-react/meter'

const USAGE = [
  { label: 'Operations', value: 32 },
  { label: 'Marketing', value: 64 },
  { label: 'Infrastructure', value: 94 },
]

export default function MeterStatus() {
  return (
    <div className="flex w-72 max-w-full flex-col gap-5">
      {USAGE.map((item) => (
        <Meter key={item.label} value={item.value} low={40} high={75} optimum={10}>
          <MeterLabel>{item.label}</MeterLabel>
          <MeterValue />
          <MeterProgress />
        </Meter>
      ))}
    </div>
  )
}
```

### Formatting the value [#formatting-the-value]

The root's `format` takes [`Intl.NumberFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) — render the value as currency, a unit, and so on. For full control, pass a function as `MeterValue`'s children to wrap the formatted string in your own text.

```tsx
'use client'

import { Meter, MeterLabel, MeterValue, MeterProgress } from '@appica/ui-react/meter'

export default function MeterFormatting() {
  return (
    <div className="flex w-72 max-w-full flex-col gap-6">
      <Meter value={1280} max={2000} format={{ style: 'currency', currency: 'USD' }} low={1000} high={1800} optimum={0}>
        <MeterLabel>Monthly budget</MeterLabel>
        <MeterValue />
        <MeterProgress />
      </Meter>

      <Meter value={3.4} max={8} format={{ style: 'unit', unit: 'gigabyte', maximumFractionDigits: 1 }}>
        <MeterLabel>Backup size</MeterLabel>
        <MeterValue>{(formatted) => `${formatted} of 8 GB`}</MeterValue>
        <MeterProgress />
      </Meter>
    </div>
  )
}
```

### Password strength (controlled) [#password-strength-controlled]

A real-world meter: score the input as the user types, map the score to a custom range (`max={4}`), and use the thresholds to drive the red → amber → green color. The `MeterValue` children print a word ("Fair", "Strong") instead of a number.

```tsx
'use client'

import * as React from 'react'
import { Meter, MeterValue, MeterProgress } from '@appica/ui-react/meter'
import { Input } from '@appica/ui-react/input'
import { Lock } from '@appica/icons-react'

const LEVELS = ['Too weak', 'Weak', 'Fair', 'Good', 'Strong'] as const

function scorePassword(value: string) {
  if (value.length < 3) return 0
  let score = 1
  if (value.length >= 10) score++
  if (/[A-Z]/.test(value) && /[a-z]/.test(value)) score++
  if (/[0-9]/.test(value) || /[^A-Za-z0-9]/.test(value)) score++
  return score
}

export default function MeterStrength() {
  const [password, setPassword] = React.useState('')
  const score = scorePassword(password)

  return (
    <div className="flex w-72 max-w-full flex-col gap-2">
      <Input
        startSlot={<Lock />}
        type="password"
        autoComplete="new-password"
        value={password}
        onChange={(event) => setPassword(event.target.value)}
        placeholder="Choose a password"
        aria-label="Password"
      />
      <Meter
        value={score}
        max={4}
        low={2}
        high={2}
        optimum={4}
        aria-label="Password strength"
        statusClassNames={{
          invalid: 'bg-error-emphasis',
          suboptimum: 'bg-warning-emphasis',
          optimum: 'bg-success-emphasis',
        }}
      >
        <MeterValue className="text-foreground-muted text-xs">{() => LEVELS[score]}</MeterValue>
        <MeterProgress />
      </Meter>
    </div>
  )
}
```

### Minimal [#minimal]

Drop `MeterValue` (and even `MeterLabel`) to render a bare track — handy for compact lists where the label alone carries the meaning. Restyle the track height and label with `className`.

```tsx
import { Meter, MeterLabel, MeterProgress } from '@appica/ui-react/meter'

const SKILLS = [
  { label: 'TypeScript', value: 90 },
  { label: 'React', value: 82 },
  { label: 'CSS', value: 70 },
  { label: 'Rust', value: 38 },
]

export default function MeterMinimal() {
  return (
    <div className="flex w-64 max-w-full flex-col gap-3">
      {SKILLS.map((skill) => (
        <Meter key={skill.label} value={skill.value} className="gap-1">
          <MeterLabel className="text-foreground text-xs font-normal">{skill.label}</MeterLabel>
          <MeterProgress className="h-1" />
        </Meter>
      ))}
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

Under RTL the label and value swap sides and the track fills from the right. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="meter" />

## API reference [#api-reference]

`Meter` wraps [Base UI's Meter](https://base-ui.com/react/components/meter). Each part forwards `ref` and its remaining native attributes to the matching Base UI primitive — the tables below list the Appica additions and the most common props. When any threshold is set, the root exposes `data-status` (`optimum` | `suboptimum` | `invalid`) for styling, and the indicator carries `data-slot="meter-indicator"` with the threshold-derived background class.

### Meter [#meter]

The root. Owns the `value`, the range, and the threshold logic, and provides the resolved indicator color to `MeterProgress`. Renders a `<div role="meter">`.

| Prop               | <ColMinWidth width="220">Type</ColMinWidth>                    | Default | <ColMinWidth width="220">Description</ColMinWidth>                                               |
| ------------------ | -------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `value`            | `number`                                                       | —       | **Required.** The current value.                                                                 |
| `min`              | `number`                                                       | `0`     | Lower bound of the range.                                                                        |
| `max`              | `number`                                                       | `100`   | Upper bound of the range.                                                                        |
| `low`              | `number`                                                       | —       | Upper edge of the "low" zone. Enables status coloring.                                           |
| `high`             | `number`                                                       | —       | Lower edge of the "high" zone. Enables status coloring.                                          |
| `optimum`          | `number`                                                       | —       | The ideal value; the zone it lands in becomes the green "optimum" zone. Enables status coloring. |
| `statusClassNames` | <Code>{`{ optimum?, suboptimum?, invalid?, default? }`}</Code> | —       | Override the indicator background class per status (and the no-threshold `default`).             |
| `format`           | `Intl.NumberFormatOptions`                                     | —       | Formatting passed to `Intl.NumberFormat` for the displayed value.                                |
| `locale`           | `Intl.LocalesArgument`                                         | —       | Locale used by `Intl.NumberFormat`.                                                              |
| `getAriaValueText` | <Code>(formatted: string, value: number) => string</Code>      | —       | Build the human-readable `aria-valuetext`.                                                       |
| `render`           | <Code>ReactElement \| ((props, state) => ReactElement)</Code>  | —       | Replace the rendered element, or compose it with another component.                              |
| `className`        | <Code>string \| ((state) => string)</Code>                     | —       | Extra classes, merged via `tailwind-merge`. Override the default grid layout here.               |
| `style`            | <Code>CSSProperties \| ((state) => CSSProperties)</Code>       | —       | Inline styles, optionally derived from state.                                                    |

### MeterLabel [#meterlabel]

Names the meter and is wired to the root via `aria-labelledby`. Renders a `<span>`.

| Prop        | <ColMinWidth width="220">Type</ColMinWidth>                   | Default | Description                                   |
| ----------- | ------------------------------------------------------------- | ------- | --------------------------------------------- |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace or compose the rendered element.      |
| `className` | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes, merged via `tailwind-merge`.   |
| `style`     | <Code>CSSProperties \| ((state) => CSSProperties)</Code>      | —       | Inline styles, optionally derived from state. |

### MeterValue [#metervalue]

Prints the formatted value. Renders a `<span>`.

| Prop        | <ColMinWidth width="220">Type</ColMinWidth>                            | Default | <ColMinWidth width="220">Description</ColMinWidth>                           |
| ----------- | ---------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `children`  | <Code>((formatted: string, value: number) => ReactNode) \| null</Code> | —       | Render function to fully customize the displayed text. Omit for the default. |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code>          | —       | Replace or compose the rendered element.                                     |
| `className` | <Code>string \| ((state) => string)</Code>                             | —       | Extra classes, merged via `tailwind-merge`.                                  |
| `style`     | <Code>CSSProperties \| ((state) => CSSProperties)</Code>               | —       | Inline styles, optionally derived from state.                                |

### MeterProgress [#meterprogress]

The track and fill. Wraps the `Track` and renders the `Indicator` inside it, reading the resolved color from the root. Renders a `<div>`.

| Prop        | <ColMinWidth width="220">Type</ColMinWidth>                   | Default | Description                                              |
| ----------- | ------------------------------------------------------------- | ------- | -------------------------------------------------------- |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace or compose the track element.                    |
| `className` | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes on the track, merged via `tailwind-merge`. |
| `style`     | <Code>CSSProperties \| ((state) => CSSProperties)</Code>      | —       | Inline styles, optionally derived from state.            |

## Accessibility [#accessibility]

* `Meter` renders `role="meter"` with `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` set from `value`, `min`, and `max`.
* Give every meter an accessible name — either a `MeterLabel` (wired automatically via `aria-labelledby`) or an `aria-label` on the root when you omit the visible label.
* `format` and `getAriaValueText` shape `aria-valuetext`, so screen readers announce "$1,280.00" rather than a bare number.
* Color alone shouldn't carry meaning — pair the status colors with the value or a word (as in the password-strength example) so the state is clear without color.
* The fill transition honours `prefers-reduced-motion`.


# Navigation Menu (/ui/components/react/navigation-menu)



<Playground component="navigation-menu" />

## Usage [#usage]

```tsx
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuIcon,
  NavigationMenuContent,
  NavigationMenuLink,
} from '@appica/ui-react/navigation-menu'
```

```tsx
<NavigationMenu aria-label="Main">
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>
        Products
        <NavigationMenuIcon />
      </NavigationMenuTrigger>
      <NavigationMenuContent>
        <ul className="grid w-50 gap-1">
          <li>
            <NavigationMenuLink href="/analytics">Analytics</NavigationMenuLink>
          </li>
          <li>
            <NavigationMenuLink href="/ui/components">Components</NavigationMenuLink>
          </li>
        </ul>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink href="/pricing" className="w-auto">
        Pricing
      </NavigationMenuLink>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```

`NavigationMenu` is a compound component built on [Base UI's Navigation Menu](https://base-ui.com/react/components/navigation-menu). The root coordinates the bar and shares `variant`, `size`, `orientation`, and the trigger `icon` with every item. The single popup **morphs** — moving and resizing — between items as you hover across the bar:

* **`NavigationMenuList`** — the row (or column) of items.
* **`NavigationMenuItem`** — wraps one entry: a trigger + content, or a single link.
* **`NavigationMenuTrigger`** — the label that opens an item's panel on hover or focus.
* **`NavigationMenuIcon`** — the trigger's open/close indicator; flips while open. Override its kind per-trigger or drop it with `icon={false}` on the root.
* **`NavigationMenuContent`** — the panel for a trigger. Lay your links out inside it however you like — a list, a grid, a featured card.
* **`NavigationMenuLink`** — a link, both inside a panel and as a standalone top-level item (give it `className="w-auto"` so it sizes to its label in the bar).
* **`NavigationMenuViewport`** — the surface a panel renders into. The root renders one automatically; render your own only for [inline submenus](#nested-inline-submenus).
* **`NavigationMenuPositioner`** — the portalled, auto-positioned wrapper around the popup. Rendered automatically; pass `viewport={false}` on the root to opt out.

Reach for a `NavigationMenu` for **marketing-style site navigation** with multi-column panels and descriptions. For a single menu of actions opened from a button, use a [`Dropdown Menu`](/ui/components/react/dropdown-menu); for an application command bar (File / Edit / View), use a [`Menubar`](/ui/components/react/menubar); for a flat row of section links, use [`Navigation`](/ui/components/react/navigation).

## Examples [#examples]

### Default [#default]

A bar with two panel-opening items and one plain link. Each panel is just markup inside `NavigationMenuContent` — here a grid of `NavigationMenuLink` cards with an icon, a title, and a description. The popup morphs to fit whichever panel is open.

```tsx
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuIcon,
  NavigationMenuContent,
  NavigationMenuLink,
} from '@appica/ui-react/navigation-menu'
import { DeviceDesktopAnalytics2, Cube, Bolt, Book, Code, Lifebuoy } from '@appica/icons-react'

const PRODUCTS = [
  { title: 'Analytics', description: 'Track usage and conversions in real time.', Icon: DeviceDesktopAnalytics2 },
  { title: 'Components', description: 'A composable library of UI primitives.', Icon: Cube },
  { title: 'Automation', description: 'Wire up workflows without code.', Icon: Bolt },
  { title: 'Integrations', description: 'Connect the tools your team already uses.', Icon: Code },
]

const RESOURCES = [
  { title: 'Documentation', description: 'Guides and API references.', Icon: Book },
  { title: 'Support', description: 'Reach our team for help.', Icon: Lifebuoy },
]

export default function NavigationMenuDefault() {
  return (
    <NavigationMenu aria-label="Main">
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>
            Products
            <NavigationMenuIcon />
          </NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="grid w-96 grid-cols-2 gap-0.5">
              {PRODUCTS.map(({ title, description, Icon }) => (
                <li key={title}>
                  <NavigationMenuLink href="#!" className="h-auto flex-col items-start gap-1 whitespace-normal">
                    <span className="text-foreground-intense flex items-center gap-1.5 font-medium">
                      <Icon />
                      {title}
                    </span>
                    <span className="text-foreground-muted text-xs font-normal">{description}</span>
                  </NavigationMenuLink>
                </li>
              ))}
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>

        <NavigationMenuItem>
          <NavigationMenuTrigger>
            Resources
            <NavigationMenuIcon />
          </NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="w-50 gap-0.5">
              {RESOURCES.map(({ title, description, Icon }) => (
                <li key={title}>
                  <NavigationMenuLink href="#!" className="h-auto flex-col items-start gap-1 whitespace-normal">
                    <span className="text-foreground-intense flex items-center gap-1.5 font-medium">
                      <Icon />
                      {title}
                    </span>
                    <span className="text-foreground-muted text-xs font-normal">{description}</span>
                  </NavigationMenuLink>
                </li>
              ))}
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>

        <NavigationMenuItem>
          <NavigationMenuLink href="#!">Pricing</NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  )
}
```

### Variants [#variants]

`variant` styles the triggers: `pill` (default) gives each a hover/active background, while `line` draws an animated underline.

```tsx
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuIcon,
  NavigationMenuContent,
  NavigationMenuLink,
} from '@appica/ui-react/navigation-menu'

const LINKS = ['Overview', 'Changelog', 'Roadmap', 'Releases']

function Menus() {
  return (
    <>
      <NavigationMenuItem>
        <NavigationMenuTrigger>
          Product
          <NavigationMenuIcon />
        </NavigationMenuTrigger>
        <NavigationMenuContent>
          <ul className="w-50 gap-0.5">
            {LINKS.map((label) => (
              <li key={label}>
                <NavigationMenuLink href="#!">{label}</NavigationMenuLink>
              </li>
            ))}
          </ul>
        </NavigationMenuContent>
      </NavigationMenuItem>
      <NavigationMenuItem>
        <NavigationMenuLink href="#!">Pricing</NavigationMenuLink>
      </NavigationMenuItem>
    </>
  )
}

export default function NavigationMenuVariants() {
  return (
    <div className="flex flex-col gap-8">
      <NavigationMenu aria-label="Pill" variant="pill">
        <NavigationMenuList>
          <Menus />
        </NavigationMenuList>
      </NavigationMenu>

      <NavigationMenu aria-label="Line" variant="line">
        <NavigationMenuList>
          <Menus />
        </NavigationMenuList>
      </NavigationMenu>
    </div>
  )
}
```

### Sizes [#sizes]

`size` on the root scales the triggers, popup radius, and link padding together — `sm`, `md` (default), or `lg`.

```tsx
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuIcon,
  NavigationMenuContent,
  NavigationMenuLink,
} from '@appica/ui-react/navigation-menu'

const SIZES = ['sm', 'md', 'lg'] as const

const LINKS = ['Overview', 'Analytics', 'Settings']

export default function NavigationMenuSizes() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      {SIZES.map((size) => (
        <NavigationMenu key={size} aria-label={size} size={size}>
          <NavigationMenuList>
            <NavigationMenuItem>
              <NavigationMenuTrigger>
                {size}
                <NavigationMenuIcon />
              </NavigationMenuTrigger>
              <NavigationMenuContent>
                <ul className="w-50 gap-0.5">
                  {LINKS.map((label) => (
                    <li key={label}>
                      <NavigationMenuLink href="#!">{label}</NavigationMenuLink>
                    </li>
                  ))}
                </ul>
              </NavigationMenuContent>
            </NavigationMenuItem>
          </NavigationMenuList>
        </NavigationMenu>
      ))}
    </div>
  )
}
```

### Indicator [#indicator]

`icon` on the root sets the open/close indicator next to every trigger: a `chevron` (default), a `caret`, or a `plus` that morphs into a minus. Set `icon={false}` to drop it, or override a single trigger by passing `icon` to its `NavigationMenuIcon`.

```tsx
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuIcon,
  NavigationMenuContent,
  NavigationMenuLink,
} from '@appica/ui-react/navigation-menu'

const KINDS = ['chevron', 'caret', 'plus'] as const

const LINKS = ['Dashboard', 'Reports', 'Settings']

export default function NavigationMenuIcons() {
  return (
    <div className="flex flex-wrap gap-6">
      {KINDS.map((kind) => (
        <NavigationMenu key={kind} aria-label={kind} icon={kind}>
          <NavigationMenuList>
            <NavigationMenuItem>
              <NavigationMenuTrigger>
                {kind}
                <NavigationMenuIcon />
              </NavigationMenuTrigger>
              <NavigationMenuContent>
                <ul className="w-50 gap-0.5">
                  {LINKS.map((label) => (
                    <li key={label}>
                      <NavigationMenuLink href="#!">{label}</NavigationMenuLink>
                    </li>
                  ))}
                </ul>
              </NavigationMenuContent>
            </NavigationMenuItem>
          </NavigationMenuList>
        </NavigationMenu>
      ))}
    </div>
  )
}
```

### Vertical [#vertical]

Set `orientation="vertical"` to stack the bar into a sidebar; each panel opens to the inline-end side. Give triggers `w-full justify-start` and push the indicator to the edge with `ms-auto`.

```tsx
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuIcon,
  NavigationMenuContent,
  NavigationMenuLink,
} from '@appica/ui-react/navigation-menu'
import { LayoutDashboard, Folder, Users } from '@appica/icons-react'

const MENUS = [
  { label: 'Dashboard', Icon: LayoutDashboard, links: ['Summary', 'Activity', 'Insights'] },
  { label: 'Projects', Icon: Folder, links: ['All projects', 'Archived', 'Templates'] },
  { label: 'Team', Icon: Users, links: ['Members', 'Roles', 'Invitations'] },
]

export default function NavigationMenuVertical() {
  return (
    <NavigationMenu aria-label="Sidebar" orientation="vertical" className="w-48">
      <NavigationMenuList>
        {MENUS.map(({ label, Icon, links }) => (
          <NavigationMenuItem key={label}>
            <NavigationMenuTrigger className="w-full justify-start">
              <Icon data-icon="start" />
              {label}
              <NavigationMenuIcon className="ms-auto" />
            </NavigationMenuTrigger>
            <NavigationMenuContent>
              <ul className="w-48 gap-0.5">
                {links.map((link) => (
                  <li key={link}>
                    <NavigationMenuLink href="#!">{link}</NavigationMenuLink>
                  </li>
                ))}
              </ul>
            </NavigationMenuContent>
          </NavigationMenuItem>
        ))}
      </NavigationMenuList>
    </NavigationMenu>
  )
}
```

### Backdrop [#backdrop]

Set `backdrop` to dim and blur the page behind the open panel — useful for a prominent mega-menu that should pull focus away from the page.

```tsx
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuIcon,
  NavigationMenuContent,
  NavigationMenuLink,
} from '@appica/ui-react/navigation-menu'

const PRODUCTS = [
  { title: 'Analytics', description: 'Track usage and conversions.' },
  { title: 'Components', description: 'A composable UI library.' },
  { title: 'Automation', description: 'Wire up workflows fast.' },
  { title: 'Integrations', description: 'Connect your stack.' },
]

export default function NavigationMenuBackdrop() {
  return (
    <NavigationMenu aria-label="Main" backdrop>
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>
            Products
            <NavigationMenuIcon />
          </NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="grid w-94 grid-cols-2 gap-0.5">
              {PRODUCTS.map(({ title, description }) => (
                <li key={title}>
                  <NavigationMenuLink href="#!" className="h-auto flex-col items-start gap-1 whitespace-normal">
                    <span className="text-foreground-intense font-medium">{title}</span>
                    <span className="text-foreground-muted text-xs font-normal">{description}</span>
                  </NavigationMenuLink>
                </li>
              ))}
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink href="#!">Pricing</NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  )
}
```

### Nested submenus [#nested-submenus]

Open a deeper level in its **own panel** by nesting a second `NavigationMenu` (set `orientation="vertical"`) inside a `NavigationMenuContent`. The nested menu renders its own portalled popup, opening to the side of the parent panel — just like a submenu.

```tsx
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuIcon,
  NavigationMenuContent,
  NavigationMenuLink,
} from '@appica/ui-react/navigation-menu'

const COMPANY = [
  { title: 'About', description: 'Our mission and the team behind it.' },
  { title: 'Careers', description: 'Open roles across the company.' },
  { title: 'Blog', description: 'Product news and engineering notes.' },
]

const HANDBOOK = [
  { title: 'Getting started', description: 'Set up your workspace.' },
  { title: 'Principles', description: 'How we make decisions.' },
  { title: 'Remote work', description: 'Working across time zones.' },
]

export default function NavigationMenuNestedSubmenus() {
  return (
    <NavigationMenu aria-label="Main">
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>
            Company
            <NavigationMenuIcon />
          </NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="w-58 gap-0.5">
              {COMPANY.map(({ title, description }) => (
                <li key={title}>
                  <NavigationMenuLink href="#!" className="h-auto flex-col items-start gap-1 whitespace-normal">
                    <span className="text-foreground-intense font-medium">{title}</span>
                    <span className="text-foreground-muted text-xs font-normal">{description}</span>
                  </NavigationMenuLink>
                </li>
              ))}
              <li>
                <NavigationMenu orientation="vertical">
                  <NavigationMenuList className="w-full">
                    <NavigationMenuItem className="w-full">
                      <NavigationMenuTrigger className="h-auto w-full whitespace-normal">
                        <span className="flex min-w-0 flex-1 flex-col items-start gap-0.5">
                          <span className="text-foreground-intense font-medium">Handbook</span>
                          <span className="text-foreground-muted text-xs font-normal">
                            How the team works, day to day.
                          </span>
                        </span>
                        <NavigationMenuIcon />
                      </NavigationMenuTrigger>
                      <NavigationMenuContent>
                        <ul className="w-50 gap-0.5">
                          {HANDBOOK.map(({ title, description }) => (
                            <li key={title}>
                              <NavigationMenuLink
                                href="#!"
                                className="h-auto flex-col items-start gap-1 whitespace-normal"
                              >
                                <span className="text-foreground-intense font-medium">{title}</span>
                                <span className="text-foreground-muted text-xs font-normal">{description}</span>
                              </NavigationMenuLink>
                            </li>
                          ))}
                        </ul>
                      </NavigationMenuContent>
                    </NavigationMenuItem>
                  </NavigationMenuList>
                </NavigationMenu>
              </li>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>

        <NavigationMenuItem>
          <NavigationMenuLink href="#!">Pricing</NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  )
}
```

### Nested inline submenus [#nested-inline-submenus]

To switch panels **within the same popup** — a sidebar of categories beside a detail pane — nest a `NavigationMenu` with `viewport={false}` and render your own `NavigationMenuViewport` next to its list. Use `defaultValue` to open one category on mount, and give each `NavigationMenuItem` a `value` so the list can drive the shared viewport.

```tsx
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuIcon,
  NavigationMenuContent,
  NavigationMenuLink,
  NavigationMenuViewport,
} from '@appica/ui-react/navigation-menu'

const AUDIENCES = [
  {
    value: 'developers',
    label: 'Developers',
    hint: 'Build and ship faster',
    title: 'For developers',
    description: 'APIs, SDKs, and primitives to integrate in minutes.',
    links: [
      { title: 'API reference', description: 'Every endpoint, documented.' },
      { title: 'SDKs', description: 'First-party libraries for your stack.' },
      { title: 'Examples', description: 'Copy-paste starting points.' },
    ],
  },
  {
    value: 'designers',
    label: 'Designers',
    hint: 'Design with the system',
    title: 'For designers',
    description: 'Tokens, kits, and guidelines that match the code.',
    links: [
      { title: 'Figma kit', description: 'Components mapped to production.' },
      { title: 'Design tokens', description: 'One source of truth for theming.' },
      { title: 'Guidelines', description: 'Patterns and accessibility notes.' },
    ],
  },
  {
    value: 'teams',
    label: 'Teams',
    hint: 'Scale across the org',
    title: 'For teams',
    description: 'Roles, governance, and shared workspaces.',
    links: [
      { title: 'Permissions', description: 'Granular role-based access.' },
      { title: 'Audit log', description: 'Track every change.' },
      { title: 'SSO', description: 'Single sign-on for everyone.' },
    ],
  },
]

const cardClass = 'h-auto flex-col items-start gap-0.5 whitespace-normal'

export default function NavigationMenuNestedInline() {
  return (
    <NavigationMenu aria-label="Main">
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>
            Product
            <NavigationMenuIcon />
          </NavigationMenuTrigger>
          <NavigationMenuContent className="p-0">
            <NavigationMenu orientation="vertical" defaultValue="developers" viewport={false}>
              <div className="grid w-125 grid-cols-[13rem_minmax(0,1fr)]">
                <NavigationMenuList className="border-border w-full flex-col items-stretch gap-1 border-e p-2">
                  {AUDIENCES.map((menu) => (
                    <NavigationMenuItem key={menu.value} value={menu.value} className="w-full">
                      <NavigationMenuTrigger className={`w-full ${cardClass}`}>
                        <span className="text-foreground-intense font-medium">{menu.label}</span>
                        <span className="text-foreground-muted text-xs font-normal">{menu.hint}</span>
                      </NavigationMenuTrigger>
                      <NavigationMenuContent className="p-0">
                        <div className="flex flex-col gap-3 p-2">
                          <div className="px-3 pt-1">
                            <h4 className="text-foreground-intense m-0 font-semibold">{menu.title}</h4>
                            <p className="text-foreground-muted m-0 mt-0.5 text-sm">{menu.description}</p>
                          </div>
                          <ul className="grid gap-1">
                            {menu.links.map((link) => (
                              <li key={link.title}>
                                <NavigationMenuLink href="#!" className={cardClass}>
                                  <span className="text-foreground-emphasis font-medium">{link.title}</span>
                                  <span className="text-foreground-muted text-xs font-normal">{link.description}</span>
                                </NavigationMenuLink>
                              </li>
                            ))}
                          </ul>
                        </div>
                      </NavigationMenuContent>
                    </NavigationMenuItem>
                  ))}
                </NavigationMenuList>
                <NavigationMenuViewport className="min-h-60" />
              </div>
            </NavigationMenu>
          </NavigationMenuContent>
        </NavigationMenuItem>

        <NavigationMenuItem>
          <NavigationMenuLink href="#!">Pricing</NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus along the bar, popup placement, and the morph direction — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The bar lays out from the right, arrow-key focus reverses, the panel anchors from the trigger's leading edge, and a vertical menu's panels open toward the inline-start side. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<Callout type="note" title="Scoped RTL needs the direction on the positioner">
  The popup portals to `<body>`, so its `start`/`end` alignment mirrors from the **document** direction (read from CSS,
  not from `DirectionProvider`) — automatic when `<html dir="rtl">`. If you instead scope RTL to a subtree of an LTR page,
  set `dir="rtl"` on the `NavigationMenu` root so the morphing panel still mirrors. See
  [Floating popups in a scoped RTL region](/ui/docs/react/rtl#floating-popups-in-a-scoped-rtl-region).
</Callout>

<RtlPreview component="navigation-menu" />

## API reference [#api-reference]

`NavigationMenu` wraps [Base UI's Navigation Menu](https://base-ui.com/react/components/navigation-menu). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### NavigationMenu [#navigationmenu]

The root. Coordinates the bar, owns the open state, and shares styling with every item.

| Prop            | <ColMinWidth width="210">Type</ColMinWidth>          | Default        | <ColMinWidth width="220">Description</ColMinWidth>                            |
| --------------- | ---------------------------------------------------- | -------------- | ----------------------------------------------------------------------------- |
| `variant`       | <Code>'pill' \| 'line'</Code>                        | `'pill'`       | Trigger appearance — hover/active pill, or an animated underline.             |
| `size`          | <Code>'sm' \| 'md' \| 'lg'</Code>                    | `'md'`         | Scales triggers, popup radius, and link padding.                              |
| `orientation`   | <Code>'horizontal' \| 'vertical'</Code>              | `'horizontal'` | Lay the bar out as a row or a column.                                         |
| `icon`          | <Code>'chevron' \| 'caret' \| 'plus' \| false</Code> | `'chevron'`    | The open/close indicator shown by each `NavigationMenuIcon`.                  |
| `morph`         | `boolean`                                            | `true`         | Animate the popup's size and position between items.                          |
| `backdrop`      | `boolean`                                            | `false`        | Render a dimmed, blurred backdrop behind the open panel.                      |
| `viewport`      | `boolean`                                            | `true`         | Auto-render the portalled positioner + popup. Set `false` to render your own. |
| `sideOffset`    | `number`                                             | `6`            | Gap between the trigger and the auto-rendered popup.                          |
| `value`         | `any`                                                | —              | Controlled open item. Pair with `onValueChange`.                              |
| `defaultValue`  | `any`                                                | —              | Uncontrolled initial open item.                                               |
| `onValueChange` | <Code>(value, eventDetails) => void</Code>           | —              | Fires when the open item changes.                                             |
| `delay`         | `number`                                             | `50`           | Hover-open delay in ms.                                                       |
| `closeDelay`    | `number`                                             | `50`           | Hover-close delay in ms.                                                      |
| `className`     | `string`                                             | —              | Extra classes on the bar, merged via `tailwind-merge`.                        |

### NavigationMenuList [#navigationmenulist]

The row (or column) of items.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The `NavigationMenuItem`s.                  |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### NavigationMenuItem [#navigationmenuitem]

Wraps one entry — a trigger with content, or a single link.

| Prop        | <ColMinWidth width="160">Type</ColMinWidth> | Default | Description                                                    |
| ----------- | ------------------------------------------- | ------- | -------------------------------------------------------------- |
| `value`     | `any`                                       | —       | Identifies the item — required when driving an inline submenu. |
| `children`  | `ReactNode`                                 | —       | A trigger + content pair, or a `NavigationMenuLink`.           |
| `className` | `string`                                    | —       | Extra classes, merged via `tailwind-merge`.                    |

### NavigationMenuTrigger [#navigationmenutrigger]

The label that opens an item's panel. Inherits the root's `variant`, `size`, and `orientation`.

| Prop        | Type      | Default | Description                                                |
| ----------- | --------- | ------- | ---------------------------------------------------------- |
| `disabled`  | `boolean` | `false` | Disable just this item.                                    |
| `className` | `string`  | —       | Extra classes on the trigger, merged via `tailwind-merge`. |

### NavigationMenuIcon [#navigationmenuicon]

The trigger's open/close indicator. Reads the root's `icon` kind; flips or morphs while the panel is open.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth>          | Default | Description                                 |
| ----------- | ---------------------------------------------------- | ------- | ------------------------------------------- |
| `icon`      | <Code>'chevron' \| 'caret' \| 'plus' \| false</Code> | root    | Override the indicator for this trigger.    |
| `className` | `string`                                             | —       | Extra classes, merged via `tailwind-merge`. |

### NavigationMenuContent [#navigationmenucontent]

The panel for a trigger. Renders into the active viewport; lay your links out inside it freely.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The panel's contents (lists, grids, cards). |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### NavigationMenuLink [#navigationmenulink]

A link — inside a panel or as a standalone bar item. Renders an `<a>`; use `render` to project it onto a router link. Forwards every native anchor prop (`href`, `target`, `rel`, …).

| Prop        | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                        |
| ----------- | ----------------------------------------------------------- | ------- | -------------------------------------------------- |
| `href`      | `string`                                                    | —       | Navigation target.                                 |
| `active`    | `boolean`                                                   | `false` | Mark the link as the current page.                 |
| `render`    | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render as your own element (e.g. a router `Link`). |
| `className` | `string`                                                    | —       | Extra classes, merged via `tailwind-merge`.        |

### NavigationMenuPositioner [#navigationmenupositioner]

The portalled, auto-positioned wrapper around the popup. Rendered automatically unless `viewport={false}`; render it yourself only for a fully custom popup.

| Prop               | <ColMinWidth width="200">Type</ColMinWidth>         | Default             | Description                                                  |
| ------------------ | --------------------------------------------------- | ------------------- | ------------------------------------------------------------ |
| `side`             | <Code>'top' \| 'right' \| 'bottom' \| 'left'</Code> | bottom / inline-end | Preferred side to open on (vertical defaults to inline-end). |
| `sideOffset`       | `number`                                            | `6`                 | Gap between the trigger and the popup.                       |
| `align`            | <Code>'start' \| 'center' \| 'end'</Code>           | `'start'`           | Alignment along that side.                                   |
| `alignOffset`      | `number`                                            | —                   | Shift along the alignment axis.                              |
| `collisionPadding` | `number`                                            | —                   | Minimum gap kept from the viewport edge.                     |
| `container`        | <Code>HTMLElement \| ref \| null</Code>             | —                   | Portal target for the popup.                                 |

### NavigationMenuViewport [#navigationmenuviewport]

The surface a panel renders into. The root renders one inside its popup automatically; render your own (with `viewport={false}`) only for an inline submenu.

| Prop        | Type     | Default | Description                                 |
| ----------- | -------- | ------- | ------------------------------------------- |
| `className` | `string` | —       | Extra classes, merged via `tailwind-merge`. |

## Accessibility [#accessibility]

* The bar renders a navigation landmark — give the root an `aria-label`. Triggers carry `aria-expanded` and own their panel via `aria-controls`.
* **↑/↓/←/→** move focus along the bar and into the open panel; **Enter / Space** open an item; **Escape** closes the panel back to its trigger; **Tab** moves through the panel's links.
* Panels open on hover *and* on keyboard focus, so the menu is reachable without a pointer.
* `disabled` triggers are skipped by keyboard navigation.
* The morph, panel, and backdrop transitions are all skipped when the user prefers reduced motion.


# Navigation (/ui/components/react/navigation)



<Playground component="navigation" />

## Usage [#usage]

```tsx
import { Navigation, NavigationList, NavigationItem, NavigationLink } from '@appica/ui-react/navigation'
```

```tsx
<Navigation aria-label="Main" activeLink="dashboard">
  <NavigationList>
    <NavigationItem>
      <NavigationLink href="/dashboard" value="dashboard">
        Dashboard
      </NavigationLink>
    </NavigationItem>
    <NavigationItem>
      <NavigationLink href="/projects" value="projects">
        Projects
      </NavigationLink>
    </NavigationItem>
    <NavigationItem>
      <NavigationLink href="/settings" value="settings">
        Settings
      </NavigationLink>
    </NavigationItem>
  </NavigationList>
</Navigation>
```

`Navigation` is a compound component. The root is a `<nav>` landmark that shares `variant`, `size`, and `orientation` with every link through context, and tracks which link is current via `activeLink`. The parts live under `@appica/ui-react/navigation`:

* **`Navigation`** — the `<nav>` landmark and styling context. Give it an `aria-label`.
* **`NavigationList`** — the `<ul>` that lays the links out as a row (or column).
* **`NavigationItem`** — one `<li>` wrapper.
* **`NavigationLink`** — a link. By default an `<a>`; mark it `active` (or give it a `value` matching the root's `activeLink`) to highlight the current section. Project it onto a router link with `render`.

Set the current item in one of two ways: pass `activeLink` on the root and a matching `value` on each link (handy when a route maps to a key), or set `active` directly on the one current link. A per-link `active` always wins over the root's `activeLink`.

Reach for `Navigation` to move between **distinct pages or sections**. To swap panels within a single page, use [`Tabs`](/ui/components/react/tabs); for navigation that opens rich link panels on hover, use a [`Navigation Menu`](/ui/components/react/navigation-menu); for the trail showing where you are, use a [`Breadcrumb`](/ui/components/react/breadcrumb).

## Examples [#examples]

### Basic [#basic]

A horizontal row of links with the current section highlighted. Each `NavigationLink` carries a `value`; the root's `activeLink` picks the matching one and stamps it with `aria-current="page"`.

```tsx
import { Navigation, NavigationList, NavigationItem, NavigationLink } from '@appica/ui-react/navigation'

export default function NavigationBasic() {
  return (
    <Navigation aria-label="Main" activeLink="dashboard" className="max-w-full">
      <NavigationList className="scrollbar-none overflow-x-auto [&::-webkit-scrollbar]:hidden">
        <NavigationItem>
          <NavigationLink href="#!" value="dashboard">
            Dashboard
          </NavigationLink>
        </NavigationItem>
        <NavigationItem>
          <NavigationLink href="#!" value="projects">
            Projects
          </NavigationLink>
        </NavigationItem>
        <NavigationItem>
          <NavigationLink href="#!" value="team">
            Team
          </NavigationLink>
        </NavigationItem>
        <NavigationItem>
          <NavigationLink href="#!" value="settings">
            Settings
          </NavigationLink>
        </NavigationItem>
      </NavigationList>
    </Navigation>
  )
}
```

### Variants [#variants]

`variant` sets how the active and hovered link is drawn. `pill` (default) fills a rounded background; `line` slides an underline in from the side. Both animate, and respect reduced-motion.

```tsx
import { Navigation, NavigationList, NavigationItem, NavigationLink } from '@appica/ui-react/navigation'

const ITEMS = [
  { value: 'overview', label: 'Overview' },
  { value: 'analytics', label: 'Analytics' },
  { value: 'reports', label: 'Reports' },
  { value: 'notifications', label: 'Notifications' },
]

export default function NavigationVariants() {
  return (
    <div className="flex w-full max-w-full flex-col items-center gap-8">
      <Navigation aria-label="Pill" variant="pill" activeLink="overview" className="max-w-full">
        <NavigationList className="scrollbar-none overflow-x-auto [&::-webkit-scrollbar]:hidden">
          {ITEMS.map((item) => (
            <NavigationItem key={item.value}>
              <NavigationLink href="#!" value={item.value}>
                {item.label}
              </NavigationLink>
            </NavigationItem>
          ))}
        </NavigationList>
      </Navigation>

      <Navigation aria-label="Line" variant="line" activeLink="overview" className="max-w-full">
        <NavigationList className="scrollbar-none overflow-x-auto [&::-webkit-scrollbar]:hidden">
          {ITEMS.map((item) => (
            <NavigationItem key={item.value}>
              <NavigationLink href="#!" value={item.value}>
                {item.label}
              </NavigationLink>
            </NavigationItem>
          ))}
        </NavigationList>
      </Navigation>
    </div>
  )
}
```

### Sizes [#sizes]

`size` on the root scales the link text, padding, and icon size together — `sm`, `md` (default), or `lg`.

```tsx
import { Navigation, NavigationList, NavigationItem, NavigationLink } from '@appica/ui-react/navigation'

const SIZES = ['sm', 'md', 'lg'] as const

const ITEMS = [
  { value: 'home', label: 'Home' },
  { value: 'docs', label: 'Docs' },
  { value: 'pricing', label: 'Pricing' },
]

export default function NavigationSizes() {
  return (
    <div className="flex flex-col gap-6">
      {SIZES.map((size) => (
        <Navigation key={size} aria-label={size} size={size} activeLink="home">
          <NavigationList>
            {ITEMS.map((item) => (
              <NavigationItem key={item.value}>
                <NavigationLink href="#!" value={item.value}>
                  {item.label}
                </NavigationLink>
              </NavigationItem>
            ))}
          </NavigationList>
        </Navigation>
      ))}
    </div>
  )
}
```

### With icons & badges [#with-icons--badges]

Put a leading icon on `data-icon="start"` and a trailing [`Badge`](/ui/components/react/badge) on `data-icon="end"` so the link reserves the right padding. The icon inherits the link's size.

```tsx
import { Navigation, NavigationList, NavigationItem, NavigationLink } from '@appica/ui-react/navigation'
import { Badge } from '@appica/ui-react/badge'
import { LayoutDashboard, Folder, Users, Settings } from '@appica/icons-react'

export default function NavigationIcons() {
  return (
    <Navigation aria-label="Main" activeLink="dashboard" className="max-w-full">
      <NavigationList className="scrollbar-none overflow-x-auto [&::-webkit-scrollbar]:hidden">
        <NavigationItem>
          <NavigationLink href="#!" value="dashboard">
            <LayoutDashboard data-icon="start" />
            Dashboard
          </NavigationLink>
        </NavigationItem>
        <NavigationItem>
          <NavigationLink href="#!" value="projects">
            <Folder data-icon="start" />
            Projects
          </NavigationLink>
        </NavigationItem>
        <NavigationItem>
          <NavigationLink href="#!" value="team">
            <Users data-icon="start" />
            Team
            <Badge variant="outline" size="sm" data-icon="end">
              4
            </Badge>
          </NavigationLink>
        </NavigationItem>
        <NavigationItem>
          <NavigationLink href="#!" value="settings">
            <Settings data-icon="start" />
            Settings
          </NavigationLink>
        </NavigationItem>
      </NavigationList>
    </Navigation>
  )
}
```

### Vertical sidebar [#vertical-sidebar]

Set `orientation="vertical"` to stack the links into a sidebar. Links go full-width, the active background or underline reorients, and the padding tightens for a denser column.

```tsx
import { Navigation, NavigationList, NavigationItem, NavigationLink } from '@appica/ui-react/navigation'
import { LayoutDashboard, Folder, Users, Settings } from '@appica/icons-react'

const ITEMS = [
  { value: 'dashboard', label: 'Dashboard', Icon: LayoutDashboard },
  { value: 'projects', label: 'Projects', Icon: Folder },
  { value: 'team', label: 'Team', Icon: Users },
  { value: 'settings', label: 'Settings', Icon: Settings },
]

export default function NavigationVertical() {
  return (
    <Navigation aria-label="Sidebar" orientation="vertical" variant="pill" activeLink="projects" className="w-48">
      <NavigationList>
        {ITEMS.map(({ value, label, Icon }) => (
          <NavigationItem key={value}>
            <NavigationLink href="#!" value={value} className="w-full">
              <Icon data-icon="start" />
              {label}
            </NavigationLink>
          </NavigationItem>
        ))}
      </NavigationList>
    </Navigation>
  )
}
```

### Indicator variant [#indicator-variant]

The `indicator` variant — vertical only — hides a chevron that slides in on hover or when active, a common pattern for documentation sidebars. Pass your own marker with the `indicator` prop on a link.

```tsx
import { Navigation, NavigationList, NavigationItem, NavigationLink } from '@appica/ui-react/navigation'

const ITEMS = [
  { value: 'getting-started', label: 'Getting started' },
  { value: 'installation', label: 'Installation' },
  { value: 'theming', label: 'Theming' },
  { value: 'components', label: 'Components' },
]

export default function NavigationIndicator() {
  return (
    <Navigation aria-label="Docs" orientation="vertical" variant="indicator" activeLink="theming" className="w-56">
      <NavigationList>
        {ITEMS.map(({ value, label }) => (
          <NavigationItem key={value}>
            <NavigationLink href="#!" value={value}>
              {label}
            </NavigationLink>
          </NavigationItem>
        ))}
      </NavigationList>
    </Navigation>
  )
}
```

### Controlled selection [#controlled-selection]

Drive the active item from state when the highlight follows in-page selection rather than the URL. Project each link onto a `<button>` with `render` and update `activeLink` on click.

```tsx
'use client'

import * as React from 'react'
import { Navigation, NavigationList, NavigationItem, NavigationLink } from '@appica/ui-react/navigation'

const ITEMS = [
  { value: 'account', label: 'Account' },
  { value: 'security', label: 'Security' },
  { value: 'billing', label: 'Billing' },
  { value: 'team', label: 'Team' },
]

export default function NavigationControlled() {
  const [active, setActive] = React.useState('account')

  return (
    <Navigation aria-label="Settings" variant="line" activeLink={active} className="max-w-full">
      <NavigationList className="scrollbar-none overflow-x-auto [&::-webkit-scrollbar]:hidden">
        {ITEMS.map(({ value, label }) => (
          <NavigationItem key={value}>
            <NavigationLink value={value} render={<button type="button" onClick={() => setActive(value)} />}>
              {label}
            </NavigationLink>
          </NavigationItem>
        ))}
      </NavigationList>
    </Navigation>
  )
}
```

### Router links [#router-links]

For client-side routing, project a `NavigationLink` onto your framework's link via `render` — here a Next.js [`Link`](https://nextjs.org/docs/app/api-reference/components/link). The link keeps its variant, size, and active styling. Mark an unavailable destination `disabled` to dim it and drop it from the tab order.

```tsx
import Link from 'next/link'
import { Navigation, NavigationList, NavigationItem, NavigationLink } from '@appica/ui-react/navigation'

export default function NavigationLinks() {
  return (
    <Navigation aria-label="Main" activeLink="overview">
      <NavigationList>
        <NavigationItem>
          <NavigationLink value="overview" render={<Link href="/ui/components/react/navigation" />}>
            Overview
          </NavigationLink>
        </NavigationItem>
        <NavigationItem>
          <NavigationLink value="changelog" render={<Link href="/ui/components/react/navigation" />}>
            Changelog
          </NavigationLink>
        </NavigationItem>
        <NavigationItem>
          <NavigationLink value="roadmap" disabled>
            Roadmap
          </NavigationLink>
        </NavigationItem>
      </NavigationList>
    </Navigation>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

Links lay out from the right, the `line` underline grows from the inline-start edge, and the `indicator` chevron mirrors. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="navigation" />

## API reference [#api-reference]

Navigation is a set of styled HTML elements sharing context. Each part forwards every remaining prop to its underlying element (`nav`, `ul`, `li`, `a`), so any native attribute works here — the tables below list the Appica additions and the most common props.

### Navigation [#navigation]

The `<nav>` landmark and styling context.

| Prop          | <ColMinWidth width="210">Type</ColMinWidth>  | Default        | <ColMinWidth width="220">Description</ColMinWidth>                            |
| ------------- | -------------------------------------------- | -------------- | ----------------------------------------------------------------------------- |
| `variant`     | <Code>'pill' \| 'line' \| 'indicator'</Code> | `'pill'`       | Active/hover styling. `indicator` is vertical-only.                           |
| `size`        | <Code>'sm' \| 'md' \| 'lg'</Code>            | `'md'`         | Scales link text, padding, and icons.                                         |
| `orientation` | <Code>'horizontal' \| 'vertical'</Code>      | `'horizontal'` | Lay the links out as a row or a column.                                       |
| `activeLink`  | <Code>string \| number \| null</Code>        | `null`         | The `value` of the current link. Stamps the match with `aria-current="page"`. |
| `aria-label`  | `string`                                     | —              | Accessible name for the navigation landmark.                                  |
| `className`   | `string`                                     | —              | Extra classes, merged via `tailwind-merge`.                                   |

### NavigationList [#navigationlist]

The `<ul>` that arranges the items, with orientation-aware spacing.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The `NavigationItem`s.                      |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### NavigationItem [#navigationitem]

One link's `<li>` wrapper.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | A `NavigationLink`.                         |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### NavigationLink [#navigationlink]

A navigation link. Built on Base UI's [`useRender`](https://base-ui.com/react/utils/use-render); renders an `<a>` by default. Inherits `variant`, `size`, and `orientation` from the root unless overridden per-link.

| Prop          | <ColMinWidth width="210">Type</ColMinWidth>                 | Default | Description                                                        |
| ------------- | ----------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| `value`       | <Code>string \| number</Code>                               | —       | Matched against the root's `activeLink` to mark this link current. |
| `active`      | `boolean`                                                   | —       | Force the active state, overriding `activeLink`.                   |
| `disabled`    | `boolean`                                                   | `false` | Dim the link and remove it from the tab order.                     |
| `indicator`   | `ReactNode`                                                 | chevron | Custom marker for the `indicator` variant.                         |
| `variant`     | <Code>'pill' \| 'line' \| 'indicator'</Code>                | root    | Override the root's variant for this link.                         |
| `size`        | <Code>'sm' \| 'md' \| 'lg'</Code>                           | root    | Override the root's size for this link.                            |
| `orientation` | <Code>'horizontal' \| 'vertical'</Code>                     | root    | Override the root's orientation for this link.                     |
| `render`      | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render as your own element (e.g. a router `Link` or a `<button>`). |
| `href`        | `string`                                                    | —       | Navigation target (when rendered as an `<a>`).                     |
| `className`   | `string`                                                    | —       | Extra classes, merged via `tailwind-merge`.                        |

## Accessibility [#accessibility]

* `Navigation` renders a `<nav>` landmark — always give it an `aria-label` (or `aria-labelledby`) so multiple navs on a page are distinguishable.
* The current link is stamped with `aria-current="page"`, announced as the current item without changing its role.
* A vertical navigation sets `data-orientation="vertical"` on the landmark (styling hook — `aria-orientation` isn't valid on `<nav>`).
* `disabled` links set `aria-disabled` and are removed from the tab order.
* Links are ordinary keyboard-focusable anchors (or whatever element you `render`), with a visible focus ring.
* Hover/active transitions are skipped when the user prefers reduced motion.


# Number Field (/ui/components/react/number-field)



<Playground component="number-field" />

## Usage [#usage]

```tsx
import { NumberField } from '@appica/ui-react/number-field'
```

```tsx
<NumberField defaultValue={1} min={0} max={10} />
```

`NumberField` folds the decrement button, text input, and increment button into one control — you render a single `<NumberField />`, not a set of parts. It accepts only numeric input, steps with the buttons or the ↑/↓ arrow keys, and reformats the value when you commit. Use it uncontrolled with `defaultValue`, or controlled with `value` + `onValueChange`.

Unlike a checkbox or radio, the input is a real text field, so give it a label the usual way — an external `<label htmlFor>` pointing at the field's `id`, or an `aria-label`. The rolling-digit animation on stepper presses is skipped when the user prefers reduced motion.

## Examples [#examples]

### Variants [#variants]

`variant` switches the appearance between a bordered `outline` (default) and a filled `soft` field. The stepper buttons invert their fill so they stay legible against either.

```tsx
import { NumberField } from '@appica/ui-react/number-field'

export default function NumberFieldVariants() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <NumberField variant="outline" defaultValue={3} aria-label="Outline quantity" />
      <NumberField variant="soft" defaultValue={3} aria-label="Soft quantity" />
    </div>
  )
}
```

### Sizes [#sizes]

`size` scales the field width, steppers, and text together — `sm`, `md` (default), or `lg`.

```tsx
import { NumberField } from '@appica/ui-react/number-field'

export default function NumberFieldSizes() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <NumberField size="sm" defaultValue={3} aria-label="Small quantity" />
      <NumberField size="md" defaultValue={3} aria-label="Medium quantity" />
      <NumberField size="lg" defaultValue={3} aria-label="Large quantity" />
    </div>
  )
}
```

### Min, max & step [#min-max--step]

`min` and `max` clamp the value and disable the stepper once a bound is reached; clearing the field and blurring snaps back to `min` (or `0`). `step` sets how far each press or arrow key moves the value — hold **Shift** for `largeStep` (10× by default) or **Alt** for `smallStep`.

```tsx
import { Field, FieldLabel } from '@appica/ui-react/field'
import { NumberField } from '@appica/ui-react/number-field'

export default function NumberFieldMinMaxStep() {
  return (
    <Field>
      <FieldLabel className="mb-2">Rating (0-20, step 1)</FieldLabel>
      <NumberField defaultValue={5} min={0} max={20} step={1} />
    </Field>
  )
}
```

### Formatting [#formatting]

Pass `format` — an `Intl.NumberFormatOptions` object — and an optional `locale` to display the value as currency, a percentage, units, and the like. The display reformats while the underlying value stays a plain number.

```tsx
import { NumberField } from '@appica/ui-react/number-field'

export default function NumberFieldFormatting() {
  return (
    <div className="flex flex-wrap items-end gap-6">
      <div className="flex flex-col gap-1.5">
        <label htmlFor="nf-price" className="text-foreground-intense text-sm font-medium">
          Price
        </label>
        <NumberField
          id="nf-price"
          className="w-40"
          defaultValue={19.99}
          step={0.5}
          format={{ style: 'currency', currency: 'USD' }}
          locale="en-US"
        />
      </div>
      <div className="flex flex-col gap-1.5">
        <label htmlFor="nf-rate" className="text-foreground-intense text-sm font-medium">
          Rate
        </label>
        <NumberField
          id="nf-rate"
          className="w-32"
          defaultValue={0.15}
          min={0}
          max={1}
          step={0.01}
          format={{ style: 'percent' }}
        />
      </div>
    </div>
  )
}
```

### Controlled [#controlled]

Drive the value yourself with `value` + `onValueChange`. The handler receives `null` when the field is empty, so coalesce before using the number.

```tsx
'use client'

import { useState } from 'react'
import { NumberField } from '@appica/ui-react/number-field'

export default function NumberFieldControlled() {
  const [value, setValue] = useState<number | null>(2)
  return (
    <div className="flex flex-col items-center gap-3">
      <NumberField value={value} onValueChange={setValue} min={0} aria-label="Guests" />
      <p className="text-sm">
        {value ?? 0} {value === 1 ? 'guest' : 'guests'}
      </p>
    </div>
  )
}
```

### Disabled & error states [#disabled--error-states]

`disabled` greys out the field and both steppers and blocks interaction. Set `aria-invalid` to paint the error state — it's mirrored to `data-invalid` on the field and its steppers. Wrapping the field in a [`Field`](/ui/components/react/field) marked `invalid` produces the same styling and is the better choice when you're also rendering a validation message.

```tsx
import { NumberField } from '@appica/ui-react/number-field'

export default function NumberFieldStates() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <NumberField variant="soft" defaultValue={3} disabled aria-label="Disabled quantity" />
      <NumberField variant="soft" defaultValue={3} aria-invalid aria-label="Quantity with error" />
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The decrement and increment steppers swap sides to follow the resolved direction, and a matching `locale` formats the value with that locale's own digits. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="number-field" />

## API reference [#api-reference]

A single control. The `variant`, `size`, `placeholder`, and `inputProps` props are Appica additions; every other prop is forwarded to [Base UI's NumberField.Root](https://base-ui.com/react/components/number-field).

| Prop               | <ColMinWidth width="200">Type</ColMinWidth>           | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                     |
| ------------------ | ----------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------- |
| `variant`          | <Code>'outline' \| 'soft'</Code>                      | `'outline'` | Field appearance — bordered or filled.                                                 |
| `size`             | <Code>'sm' \| 'md' \| 'lg'</Code>                     | `'md'`      | Scales field width, steppers, and text.                                                |
| `value`            | <Code>number \| null</Code>                           | —           | Controlled value (`null` when empty). Pair with `onValueChange`.                       |
| `defaultValue`     | `number`                                              | —           | Uncontrolled initial value.                                                            |
| `onValueChange`    | <Code>(value: number \| null, details) => void</Code> | —           | Fires as the value changes — typing, stepping, or scrubbing.                           |
| `onValueCommitted` | <Code>(value: number \| null, details) => void</Code> | —           | Fires when the value is finalized (blur, Enter, stepper release).                      |
| `min`              | `number`                                              | —           | Minimum allowed value; the field snaps here when cleared.                              |
| `max`              | `number`                                              | —           | Maximum allowed value.                                                                 |
| `step`             | <Code>number \| 'any'</Code>                          | `1`         | Amount each stepper press or arrow key moves the value.                                |
| `smallStep`        | `number`                                              | `0.1`       | Step taken while **Alt** is held.                                                      |
| `largeStep`        | `number`                                              | `10`        | Step taken while **Shift** is held.                                                    |
| `snapOnStep`       | `boolean`                                             | `false`     | Snap to the nearest multiple of `step` when stepping.                                  |
| `format`           | `Intl.NumberFormatOptions`                            | —           | Formatting options (currency, percent, units, …) for the displayed value.              |
| `locale`           | `Intl.LocalesArgument`                                | —           | Locale used to format and parse the value.                                             |
| `allowWheelScrub`  | `boolean`                                             | `false`     | Allow adjusting the value by scrolling the mouse wheel over the field.                 |
| `placeholder`      | `string`                                              | `' '`       | Placeholder text shown when empty.                                                     |
| `inputProps`       | <Code>ComponentProps\<'input'></Code>                 | —           | Props forwarded to the inner `<input>` (`name`, `onChange`, `aria-*`, `className`, …). |
| `name`             | `string`                                              | —           | Field name submitted with a form.                                                      |
| `disabled`         | `boolean`                                             | `false`     | Disables the input and both stepper buttons.                                           |
| `readOnly`         | `boolean`                                             | `false`     | Focusable but the value can't be changed.                                              |
| `required`         | `boolean`                                             | `false`     | Must have a value before its form submits.                                             |
| `aria-invalid`     | <Code>boolean \| 'true' \| 'false'</Code>             | —           | Marks the error state; mirrored to `data-invalid` on the field and steppers.           |
| `inputRef`         | <Code>Ref\<HTMLInputElement></Code>                   | —           | Ref to the inner `<input>` element.                                                    |
| `id`               | `string`                                              | —           | `id` of the inner `<input>` — point an external `<label htmlFor>` at it.               |
| `className`        | `string`                                              | —           | Extra classes on the field root, merged via `tailwind-merge`.                          |

`NumberField` wraps Base UI's `NumberField` (`Root`, `Input`, `Increment`, `Decrement`) and forwards every remaining Root prop. It exposes `data-*` state attributes (`data-disabled`, `data-readonly`, `data-invalid`, `data-scrubbing`, …) on the field and its parts for styling — see the Base UI docs for the full surface. When placed inside a Base UI `Field.Root` marked `invalid`, the error state (`data-invalid`) propagates to the input and both steppers automatically.

## Accessibility [#accessibility]

* The inner element is a real `<input>` with `role="spinbutton"`, exposing `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` to assistive tech.
* Give the field an accessible name — an external `<label htmlFor>` pointing at its `id`, or an `aria-label`.
* The steppers are real `<button>`s labelled **Increase value** / **Decrease value**, and become `disabled` at a bound or when the field is disabled.
* **↑/↓** step the value (with **Shift**/**Alt** for the large/small step), and typing accepts only valid numeric input.
* `disabled` blocks all interaction; `readOnly` keeps the field focusable but inert.
* `aria-invalid` is bridged to `data-invalid` so the error state can be styled without a wrapping `Field`.
* The rolling-digit animation on stepper presses honours `prefers-reduced-motion`.


# OTP Field (/ui/components/react/otp-field)



<Playground component="otp-field" />

## Usage [#usage]

```tsx
import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'
```

```tsx
<OTPField length={6} aria-label="Verification code">
  {Array.from({ length: 6 }, (_, i) => (
    <OTPFieldInput key={i} aria-label={`Digit ${i + 1} of 6`} />
  ))}
</OTPField>
```

`OTPField` is a compound component for one-time codes. The root owns the value and `length`; you render one [`OTPFieldInput`](#otpfieldinput) per slot (commonly mapped over `length`). Typing fills slots left to right and auto-advances, **Backspace** moves back, pasting a full code distributes across the slots, and `onValueComplete` fires when every slot is filled.

Give the group an accessible name with `aria-label` (or `aria-labelledby`) and label each slot — the inputs aren't tied to a single `<label>` the way a plain field is.

## Examples [#examples]

### Variants [#variants]

`variant` on the root switches every slot between a bordered `outline` (default) and a filled `soft` field.

```tsx
import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

const LENGTH = 6

export default function OTPFieldVariants() {
  return (
    <div className="flex flex-col gap-5">
      <OTPField length={LENGTH} variant="outline" aria-label="Outline code">
        {Array.from({ length: LENGTH }, (_, i) => (
          <OTPFieldInput key={i} aria-label={`Digit ${i + 1} of ${LENGTH}`} />
        ))}
      </OTPField>
      <OTPField length={LENGTH} variant="soft" aria-label="Soft code">
        {Array.from({ length: LENGTH }, (_, i) => (
          <OTPFieldInput key={i} aria-label={`Digit ${i + 1} of ${LENGTH}`} />
        ))}
      </OTPField>
    </div>
  )
}
```

### Sizes [#sizes]

`size` on the root scales all slots together — `sm`, `md` (default), or `lg`.

```tsx
import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

const LENGTH = 4

function Field({ size, label }: { size: 'sm' | 'md' | 'lg'; label: string }) {
  return (
    <OTPField length={LENGTH} size={size} aria-label={label}>
      {Array.from({ length: LENGTH }, (_, i) => (
        <OTPFieldInput key={i} aria-label={`Digit ${i + 1} of ${LENGTH}`} />
      ))}
    </OTPField>
  )
}

export default function OTPFieldSizes() {
  return (
    <div className="flex flex-col items-center gap-5">
      <Field size="sm" label="Small code" />
      <Field size="md" label="Medium code" />
      <Field size="lg" label="Large code" />
    </div>
  )
}
```

### With a separator [#with-a-separator]

Drop an [`OTPFieldSeparator`](#otpfieldseparator) between slots to break a long code into groups. It renders a dash by default; pass children to customise it.

```tsx
import { OTPField, OTPFieldInput, OTPFieldSeparator } from '@appica/ui-react/otp-field'

export default function OTPFieldWithSeparator() {
  return (
    <OTPField length={6} aria-label="Verification code">
      <OTPFieldInput aria-label="Digit 1 of 6" />
      <OTPFieldInput aria-label="Digit 2 of 6" />
      <OTPFieldInput aria-label="Digit 3 of 6" />
      <OTPFieldSeparator />
      <OTPFieldInput aria-label="Digit 4 of 6" />
      <OTPFieldInput aria-label="Digit 5 of 6" />
      <OTPFieldInput aria-label="Digit 6 of 6" />
    </OTPField>
  )
}
```

### Placeholder [#placeholder]

Give each `OTPFieldInput` a `placeholder` to hint at empty slots — a single `•` is a common choice. It shows only while a slot is empty and unfocused.

```tsx
import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

const LENGTH = 6

export default function OTPFieldPlaceholder() {
  return (
    <OTPField length={LENGTH} aria-label="Verification code">
      {Array.from({ length: LENGTH }, (_, i) => (
        <OTPFieldInput key={i} placeholder="•" aria-label={`Digit ${i + 1} of ${LENGTH}`} />
      ))}
    </OTPField>
  )
}
```

### Masked [#masked]

Set `mask` to obscure the entered characters — useful when the code is sensitive and shouldn't be shown on screen.

```tsx
import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

const LENGTH = 6

export default function OTPFieldMask() {
  return (
    <OTPField length={LENGTH} mask defaultValue="135790" aria-label="Masked code">
      {Array.from({ length: LENGTH }, (_, i) => (
        <OTPFieldInput key={i} aria-label={`Digit ${i + 1} of ${LENGTH}`} />
      ))}
    </OTPField>
  )
}
```

### Controlled & verify on complete [#controlled--verify-on-complete]

Drive the value with `value` + `onValueChange`, and use `onValueComplete` to act once all slots are filled — typically to verify or submit the code.

```tsx
'use client'

import { useState } from 'react'
import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

const LENGTH = 6
const CODE = '123456'

export default function OTPFieldControlled() {
  const [value, setValue] = useState('')
  const [status, setStatus] = useState<'idle' | 'valid' | 'invalid'>('idle')

  return (
    <div className="flex flex-col items-center gap-3">
      <OTPField
        length={LENGTH}
        value={value}
        onValueChange={(next) => {
          setValue(next)
          setStatus('idle')
        }}
        onValueComplete={(next) => setStatus(next === CODE ? 'valid' : 'invalid')}
        aria-label="Verification code"
      >
        {Array.from({ length: LENGTH }, (_, i) => (
          <OTPFieldInput key={i} aria-label={`Digit ${i + 1} of ${LENGTH}`} />
        ))}
      </OTPField>
      <p className="text-foreground-muted text-sm" aria-live="polite">
        {status === 'valid'
          ? '✓ Code verified'
          : status === 'invalid'
            ? `✗ Incorrect code (try ${CODE})`
            : `Enter the 6-digit code (${CODE})`}
      </p>
    </div>
  )
}
```

### Disabled, read-only & error states [#disabled-read-only--error-states]

`disabled` greys out every slot and blocks interaction; `readOnly` keeps the code visible and focusable but not editable. For the error state, place the field in a [`Field`](/ui/components/react/field) marked `invalid` — `data-invalid` propagates to every slot (OTP derives its invalid state from Field context, not a standalone `aria-invalid`).

```tsx
import { Field } from '@appica/ui-react/field'
import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

const LENGTH = 6

const slots = (prefix: string) =>
  Array.from({ length: LENGTH }, (_, i) => (
    <OTPFieldInput key={i} aria-label={`${prefix} digit ${i + 1} of ${LENGTH}`} />
  ))

export default function OTPFieldStates() {
  return (
    <div className="flex flex-col gap-5">
      <OTPField length={LENGTH} disabled aria-label="Disabled code">
        {slots('Disabled')}
      </OTPField>
      <OTPField length={LENGTH} readOnly defaultValue="123456" aria-label="Read-only code">
        {slots('Read-only')}
      </OTPField>
      <Field invalid>
        <OTPField length={LENGTH} defaultValue="123456" aria-label="Code with error">
          {slots('Error')}
        </OTPField>
      </Field>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The slots lay out from the right and focus advances start-to-end following the resolved direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="otp-field" />

## API reference [#api-reference]

`OTPField` wraps [Base UI's OTP Field](https://base-ui.com/react/components/otp-field). Each part forwards its remaining props to the matching Base UI primitive — the tables below list the Appica additions and the most common props.

### OTPField [#otpfield]

The root. Owns the value and the shared `variant` / `size` (cascaded to every slot); renders a `<div>`.

| Prop              | <ColMinWidth width="200">Type</ColMinWidth>                   | Default           | <ColMinWidth width="220">Description</ColMinWidth>              |
| ----------------- | ------------------------------------------------------------- | ----------------- | --------------------------------------------------------------- |
| `length`          | `number`                                                      | —                 | **Required.** Number of input slots.                            |
| `variant`         | <Code>'outline' \| 'soft'</Code>                              | `'outline'`       | Slot appearance — bordered or filled.                           |
| `size`            | <Code>'sm' \| 'md' \| 'lg'</Code>                             | `'md'`            | Scales every slot.                                              |
| `value`           | `string`                                                      | —                 | Controlled value. Pair with `onValueChange`.                    |
| `defaultValue`    | `string`                                                      | —                 | Uncontrolled initial value.                                     |
| `onValueChange`   | <Code>(value: string, details) => void</Code>                 | —                 | Fires whenever the value changes (typing, paste, clear).        |
| `onValueComplete` | <Code>(value: string, details) => void</Code>                 | —                 | Fires once every slot is filled.                                |
| `validationType`  | <Code>'numeric' \| 'alpha' \| 'alphanumeric' \| 'none'</Code> | `'numeric'`       | Which characters the slots accept.                              |
| `mask`            | `boolean`                                                     | `false`           | Obscure the entered characters.                                 |
| `autoSubmit`      | `boolean`                                                     | `false`           | Submit the owning form when the code completes.                 |
| `autoComplete`    | `string`                                                      | `'one-time-code'` | Applied to the first slot and hidden input for OS autofill.     |
| `name`            | `string`                                                      | —                 | Field name submitted with a form.                               |
| `required`        | `boolean`                                                     | `false`           | A complete value is required before the form submits.           |
| `disabled`        | `boolean`                                                     | `false`           | Disables every slot.                                            |
| `render`          | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —                 | Replace the root element, or compose it with another component. |
| `className`       | <Code>string \| ((state) => string)</Code>                    | —                 | Extra classes on the root, merged via `tailwind-merge`.         |

### OTPFieldInput [#otpfieldinput]

One slot. Inherits `variant` / `size` from the root via context; renders an `<input>`.

| Prop        | Type     | Default | Description                                             |
| ----------- | -------- | ------- | ------------------------------------------------------- |
| `className` | `string` | —       | Extra classes on the slot, merged via `tailwind-merge`. |

Also forwards every native `<input>` prop (`aria-label`, `ref`, …). It exposes `data-*` state attributes (`data-disabled`, `data-complete`, `data-filled`, …) for styling.

### OTPFieldSeparator [#otpfieldseparator]

A divider between slot groups. Renders a dash by default.

| Prop        | Type        | Default | Description                                        |
| ----------- | ----------- | ------- | -------------------------------------------------- |
| `children`  | `ReactNode` | dash    | Replace the default dash mark with custom content. |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`.        |

## Accessibility [#accessibility]

* Each slot is a native `<input>` (`role="textbox"`). Give every slot an `aria-label` (e.g. `Digit 1 of 6`) and name the whole group with `aria-label` or `aria-labelledby`.
* Typing fills slots left to right and auto-advances; **Backspace*&#x2A; clears and moves back; &#x2A;*←/→** move between slots; pasting a full code distributes it across the slots.
* `autoComplete="one-time-code"` lets the OS offer codes from SMS for autofill.
* `mask` obscures the characters for sensitive codes.
* `disabled` removes the slots from the tab order and exposes `data-disabled` for styling.


# Pagination (/ui/components/react/pagination)



<Playground component="pagination" />

## Usage [#usage]

```tsx
import {
  Pagination,
  PaginationList,
  PaginationItem,
  PaginationLink,
  PaginationEllipsis,
} from '@appica/ui-react/pagination'
```

```tsx
<Pagination>
  <PaginationList>
    <PaginationItem>
      <PaginationLink href="?page=1" active>
        1
      </PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=2">2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=10">10</PaginationLink>
    </PaginationItem>
  </PaginationList>
</Pagination>
```

`Pagination` is a set of semantic primitives — there's no hidden state, so you build the page list yourself and decide which links to show. Every part lives under `@appica/ui-react/pagination`:

* **`Pagination`** — the `<nav aria-label="pagination">` landmark that wraps the control.
* **`PaginationList`** — the `<ul>` that lays the items out in a row.
* **`PaginationItem`** — one `<li>` wrapping a link or the ellipsis.
* **`PaginationLink`** — a page link. Mark the current page with `active` (it becomes a non-interactive `aria-current="page"` element); mark out-of-range prev/next controls with `disabled`.
* **`PaginationEllipsis`** — a decorative "…" standing in for the pages collapsed out of a long range.

The `variant` (`outline` or `soft`) and `size` (`sm`/`md`/`lg`) set on the root flow to every link through context. `PaginationLink` is built on Base UI's [`useRender`](https://base-ui.com/react/utils/use-render), so you can project each link onto your router's link — e.g. a Next.js [`Link`](https://nextjs.org/docs/app/api-reference/components/link) — without losing its styling or active state.

## Examples [#examples]

### Default [#default]

A typical truncated range: an icon previous control (disabled on the first page), the current page marked `active`, an ellipsis for the gap, the last page, and an icon next control. Prev/next are chevron icons — give each an `aria-label`, and `className="px-0"` squares the link up around the lone icon.

```tsx
import {
  Pagination,
  PaginationList,
  PaginationItem,
  PaginationLink,
  PaginationEllipsis,
} from '@appica/ui-react/pagination'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

export default function PaginationDefault() {
  return (
    <Pagination>
      <PaginationList>
        <PaginationItem>
          <PaginationLink href="#!" aria-label="Go to previous page" className="px-0" disabled>
            <ChevronLeft />
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#!" active>
            1
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#!">2</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#!">3</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationEllipsis />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#!">10</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#!" aria-label="Go to next page" className="px-0">
            <ChevronRight />
          </PaginationLink>
        </PaginationItem>
      </PaginationList>
    </Pagination>
  )
}
```

### Variants [#variants]

`outline` (the default) draws a bordered button for each page; `soft` drops the borders for a lighter, fill-on-hover look. The `active` page is filled in both.

```tsx
import { Pagination, PaginationList, PaginationItem, PaginationLink } from '@appica/ui-react/pagination'

export default function PaginationVariants() {
  return (
    <div className="flex flex-col items-center gap-6">
      {(['outline', 'soft'] as const).map((variant) => (
        <Pagination key={variant} variant={variant}>
          <PaginationList>
            <PaginationItem>
              <PaginationLink href="#!" active>
                1
              </PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#!">2</PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#!">3</PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#!">4</PaginationLink>
            </PaginationItem>
          </PaginationList>
        </Pagination>
      ))}
    </div>
  )
}
```

### Sizes [#sizes]

Three sizes — `sm`, `md` (default), and `lg` — scale each link's height, minimum width, and text together.

```tsx
import { Pagination, PaginationList, PaginationItem, PaginationLink } from '@appica/ui-react/pagination'

export default function PaginationSizes() {
  return (
    <div className="flex flex-col items-center gap-6">
      {(['sm', 'md', 'lg'] as const).map((size) => (
        <Pagination key={size} size={size}>
          <PaginationList>
            <PaginationItem>
              <PaginationLink href="#!" active>
                1
              </PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#!">2</PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#!">3</PaginationLink>
            </PaginationItem>
          </PaginationList>
        </Pagination>
      ))}
    </div>
  )
}
```

### With first & last [#with-first--last]

For long ranges, flank the prev/next controls with first and last jump buttons — double-chevron [icons](/ui/icons) that skip straight to the ends. Each is icon-only, so it needs an `aria-label` and `className="px-0"`.

```tsx
import { Pagination, PaginationList, PaginationItem, PaginationLink } from '@appica/ui-react/pagination'
import { ChevronsLeft, ChevronLeft, ChevronRight, ChevronsRight } from '@appica/icons-react'

export default function PaginationFirstLast() {
  return (
    <div className="max-w-full scrollbar-none overflow-auto [&::-webkit-scrollbar]:hidden">
      <Pagination>
        <PaginationList>
          <PaginationItem>
            <PaginationLink href="#!" aria-label="Go to first page" className="px-0">
              <ChevronsLeft />
            </PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!" aria-label="Go to previous page" className="px-0">
              <ChevronLeft />
            </PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!">1</PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!">2</PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!" active>
              3
            </PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!">4</PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!">5</PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!" aria-label="Go to next page" className="px-0">
              <ChevronRight />
            </PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!" aria-label="Go to last page" className="px-0">
              <ChevronsRight />
            </PaginationLink>
          </PaginationItem>
        </PaginationList>
      </Pagination>
    </div>
  )
}
```

### Controlled [#controlled]

`Pagination` holds no state of its own, so wire it to your own page state. Here the current page lives in `useState`, each link's `onClick` updates it instead of navigating, the active page reflects state, and prev/next disable at the bounds.

```tsx
'use client'

import * as React from 'react'
import { Pagination, PaginationList, PaginationItem, PaginationLink } from '@appica/ui-react/pagination'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const TOTAL = 5

export default function PaginationControlled() {
  const [page, setPage] = React.useState(1)

  const go = (target: number) => (event: React.MouseEvent) => {
    event.preventDefault()
    setPage(Math.min(Math.max(target, 1), TOTAL))
  }

  return (
    <div className="flex flex-col items-center gap-3">
      <p className="text-foreground-muted text-sm">
        Page {page} of {TOTAL}
      </p>
      <Pagination>
        <PaginationList>
          <PaginationItem>
            <PaginationLink
              href="#!"
              aria-label="Go to previous page"
              className="px-0"
              disabled={page === 1}
              onClick={go(page - 1)}
            >
              <ChevronLeft />
            </PaginationLink>
          </PaginationItem>
          {Array.from({ length: TOTAL }, (_, index) => index + 1).map((p) => (
            <PaginationItem key={p}>
              <PaginationLink href="#!" active={p === page} aria-label={`Go to page ${p}`} onClick={go(p)}>
                {p}
              </PaginationLink>
            </PaginationItem>
          ))}
          <PaginationItem>
            <PaginationLink
              href="#!"
              aria-label="Go to next page"
              className="px-0"
              disabled={page === TOTAL}
              onClick={go(page + 1)}
            >
              <ChevronRight />
            </PaginationLink>
          </PaginationItem>
        </PaginationList>
      </Pagination>
    </div>
  )
}
```

### Router links [#router-links]

For client-side routing, project each `PaginationLink` onto your framework's link via `render` — here a Next.js [`Link`](https://nextjs.org/docs/app/api-reference/components/link). The link keeps its styling and active handling while the router owns navigation; put the `href` on the `Link` and any class overrides on the `PaginationLink` wrapper. Mark the current page `active` (no `Link` needed — it's non-interactive).

```tsx
import Link from 'next/link'
import { Pagination, PaginationList, PaginationItem, PaginationLink } from '@appica/ui-react/pagination'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

export default function PaginationRouter() {
  return (
    <Pagination>
      <PaginationList>
        <PaginationItem>
          <PaginationLink aria-label="Go to previous page" className="px-0" render={<Link href="?page=1" />}>
            <ChevronLeft />
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink render={<Link href="?page=1" />}>1</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink active>2</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink render={<Link href="?page=3" />}>3</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink aria-label="Go to next page" className="px-0" render={<Link href="?page=3" />}>
            <ChevronRight />
          </PaginationLink>
        </PaginationItem>
      </PaginationList>
    </Pagination>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The page list flows from the right, and the previous/next controls swap sides — point their chevrons the other way so they still read as "back" and "forward". For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="pagination" />

## API reference [#api-reference]

Pagination is a set of styled HTML elements. Each part forwards every remaining prop to its underlying element (`nav`, `ul`, `li`, `a`, `span`), so any native attribute works here — the tables below list the Appica additions and the most common props.

### Pagination [#pagination]

The navigation landmark. Renders a `<nav role="navigation" aria-label="pagination">` and provides the `variant`/`size` context.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth> | Default     | <ColMinWidth width="220">Description</ColMinWidth> |
| ----------- | ------------------------------------------- | ----------- | -------------------------------------------------- |
| `variant`   | <Code>'outline' \| 'soft'</Code>            | `'outline'` | Link style, shared with every link via context.    |
| `size`      | <Code>'sm' \| 'md' \| 'lg'</Code>           | `'md'`      | Link sizing, shared via context.                   |
| `children`  | `ReactNode`                                 | —           | A single `PaginationList`.                         |
| `className` | `string`                                    | —           | Extra classes, merged via `tailwind-merge`.        |

### PaginationList [#paginationlist]

The list of items. Renders a `<ul>` laying the items out in a row.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | `PaginationItem`s.                          |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### PaginationItem [#paginationitem]

One item's `<li>` wrapper.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | A `PaginationLink` or `PaginationEllipsis`. |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### PaginationLink [#paginationlink]

A page link. Built on Base UI's [`useRender`](https://base-ui.com/react/utils/use-render); renders an `<a>` unless you project it onto another element with `render`. Inherits `variant`/`size` from the root.

| Prop        | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | <ColMinWidth width="220">Description</ColMinWidth>                                          |
| ----------- | ----------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `active`    | `boolean`                                                   | `false` | Mark the current page. Renders a non-interactive, filled link with `aria-current="page"`.   |
| `disabled`  | `boolean`                                                   | `false` | Make the link non-interactive and dimmed (`aria-disabled`); used for out-of-range controls. |
| `href`      | `string`                                                    | —       | Navigation target (when rendered as an `<a>`).                                              |
| `render`    | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render as your own element (e.g. a router `Link`) or a `<button>`.                          |
| `className` | `string`                                                    | —       | Extra classes, merged via `tailwind-merge`.                                                 |

### PaginationEllipsis [#paginationellipsis]

A "…" placeholder for collapsed pages. Decorative (`aria-hidden`), with an `sr-only` "More pages" label.

| Prop        | Type        | Default       | Description                                 |
| ----------- | ----------- | ------------- | ------------------------------------------- |
| `children`  | `ReactNode` | ellipsis dots | Override the placeholder mark.              |
| `className` | `string`    | —             | Extra classes, merged via `tailwind-merge`. |

## Accessibility [#accessibility]

* `Pagination` renders a `<nav>` with `aria-label="pagination"`, so it's exposed as a named navigation landmark.
* The current page (`active`) carries `aria-current="page"` and is non-interactive, so it isn't announced as a destination.
* `disabled` links set `aria-disabled` and drop out of the tab order — the right way to express an out-of-range Previous/Next control.
* Controls without visible text — icon-only prev/next, for instance — need an `aria-label`.
* The ellipsis is `aria-hidden` and keeps an `sr-only` "More pages" label for context.


# Popover (/ui/components/react/popover)



<Playground component="popover" />

## Usage [#usage]

```tsx
import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverTitle,
  PopoverDescription,
  PopoverClose,
} from '@appica/ui-react/popover'
import { Button } from '@appica/ui-react/button'
```

```tsx
<Popover>
  <PopoverTrigger render={<Button variant="outline">Open</Button>} />
  <PopoverContent>
    <PopoverTitle>Share this page</PopoverTitle>
    <PopoverDescription>Anyone with the link can view this document.</PopoverDescription>
  </PopoverContent>
</Popover>
```

Unlike a plain `<button>`, the trigger is wired to the popup through `render` — pass it your own [`Button`](/ui/components/react/button) (or any element) and the popover manages its `aria-expanded`, focus, and open/close. Every part lives in its own import under `@appica/ui-react/popover`.

`Popover` is a compound component built on [Base UI's Popover](https://base-ui.com/react/components/popover). The root holds the open state; the parts compose the trigger and the portalled popup:

* **`PopoverTrigger`** — the button that toggles the popover. Use `render` to project it onto your own [`Button`](/ui/components/react/button) (or any element). Set `openOnHover` to open it on hover.
* **`PopoverContent`** — the portalled, auto-positioned popup. It draws the card, border, shadow, and the optional `arrow`, and accepts the shared **floating props** below.
* **`PopoverTitle`** — an `<h2>` that labels the popup (`aria-labelledby`).
* **`PopoverDescription`** — a `<p>` that describes it (`aria-describedby`).
* **`PopoverClose`** — a button that dismisses the popover; project it onto your own [`Button`](/ui/components/react/button) with `render`.

`PopoverContent` is the shared **floating surface** used across the library — `DropdownMenu`, `Tooltip`, `Select`, `Combobox`, and others reuse the same positioning props. They flatten the underlying Base UI Positioner so you can place the popup without reaching into the portal:

* `side` (`top` / `right` / `bottom` / `left`) and `align` (`start` / `center` / `end`) set the preferred placement; it still **flips and shifts** automatically to stay in view.
* `sideOffset` / `alignOffset` nudge it off the anchor; `collisionPadding` keeps a gap from the viewport edge.
* `positionerProps` / `portalProps` are escape hatches for the inner Positioner and Portal (`style`, `render`, `dir`, …); `container` re-targets the portal.

Reach for a `Popover` when you need **rich, interactive content** floating beside a control — a form, a set of settings, a share sheet. For a list of **actions**, use a [`Dropdown Menu`](/ui/components/react/dropdown-menu); for a plain text **hint**, use a [`Tooltip`](/ui/components/react/tooltip); for a hover **preview of a link**, use a [`Preview Card`](/ui/components/react/preview-card).

## Examples [#examples]

### Form in a popover [#form-in-a-popover]

Popovers can hold interactive content, including focusable form controls. Lay out [`Field`](/ui/components/react/field)s inside the popup and dismiss it with `PopoverClose` projected onto your action buttons — clicking either one closes the popover. Widen the popup past its default with a `className` (`w-72` here).

```tsx
import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverTitle,
  PopoverDescription,
  PopoverClose,
} from '@appica/ui-react/popover'
import { Button } from '@appica/ui-react/button'
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Adjustments } from '@appica/icons-react'

export default function PopoverForm() {
  return (
    <Popover>
      <PopoverTrigger
        render={
          <Button variant="outline">
            <Adjustments data-icon="start" />
            Dimensions
          </Button>
        }
      />
      <PopoverContent className="w-72">
        <PopoverTitle>Dimensions</PopoverTitle>
        <PopoverDescription>Set the size of the selected layer.</PopoverDescription>
        <div className="mt-1 grid grid-cols-2 gap-3">
          <Field>
            <FieldLabel>Width</FieldLabel>
            <Input defaultValue="320" inputMode="numeric" />
          </Field>
          <Field>
            <FieldLabel>Height</FieldLabel>
            <Input defaultValue="180" inputMode="numeric" />
          </Field>
        </div>
        <div className="mt-2 flex justify-end gap-2">
          <PopoverClose
            render={
              <Button variant="ghost" size="sm">
                Cancel
              </Button>
            }
          />
          <PopoverClose render={<Button size="sm">Apply</Button>} />
        </div>
      </PopoverContent>
    </Popover>
  )
}
```

### Controlled [#controlled]

Drive the open state yourself with `open` + `onOpenChange` (or stay uncontrolled with `defaultOpen`). Here a status picker closes the popup the moment you choose an option — `setOpen(false)` straight from the row's handler — while the trigger reflects the current selection. Owning the state is what lets you close on select, open the popover from elsewhere, or keep it in sync with the rest of your UI.

```tsx
'use client'

import * as React from 'react'
import { Popover, PopoverTrigger, PopoverContent, PopoverTitle } from '@appica/ui-react/popover'
import { NavigationLink } from '@appica/ui-react/navigation'
import { Button } from '@appica/ui-react/button'
import { Check } from '@appica/icons-react'

const PRESETS = [
  { emoji: '🟢', label: 'Active' },
  { emoji: '🗓️', label: 'In a meeting' },
  { emoji: '🎧', label: 'Focusing' },
  { emoji: '🌴', label: 'On vacation' },
  { emoji: '🤒', label: 'Out sick' },
] as const

type Status = (typeof PRESETS)[number]

export default function PopoverControlled() {
  const [open, setOpen] = React.useState(false)
  const [status, setStatus] = React.useState<Status>(PRESETS[0])

  return (
    <Popover open={open} onOpenChange={setOpen}>
      <PopoverTrigger
        render={
          <Button variant="outline">
            <span aria-hidden>{status.emoji}</span>
            {status.label}
          </Button>
        }
      />
      <PopoverContent align="start" className="w-60 gap-0.5 p-1.5">
        <PopoverTitle className="text-foreground-muted px-2 pt-1 pb-1.5 text-xs font-medium">Set a status</PopoverTitle>
        {PRESETS.map((preset) => (
          <NavigationLink
            key={preset.label}
            orientation="vertical"
            active={preset.label === status.label}
            className="w-full"
            render={
              <button
                type="button"
                onClick={() => {
                  setStatus(preset)
                  setOpen(false)
                }}
              />
            }
          >
            <span aria-hidden>{preset.emoji}</span>
            {preset.label}
            {preset.label === status.label && <Check data-icon="end" className="text-primary ms-auto" />}
          </NavigationLink>
        ))}
      </PopoverContent>
    </Popover>
  )
}
```

### Open on hover [#open-on-hover]

Set `openOnHover` on the `PopoverTrigger` to reveal the popup on pointer rest (it still opens on click and keyboard). Tune the timing with `delay` / `closeDelay`. Use it for supplementary detail like a richer-than-tooltip hint — but remember hover isn't reachable on touch, so don't hide essential actions behind it.

```tsx
import { Popover, PopoverTrigger, PopoverContent, PopoverTitle, PopoverDescription } from '@appica/ui-react/popover'
import { Button } from '@appica/ui-react/button'
import { InfoCircle } from '@appica/icons-react'

export default function PopoverHover() {
  return (
    <Popover>
      <PopoverTrigger
        openOnHover
        delay={150}
        render={
          <Button variant="ghost" size="icon-md" aria-label="Plan details">
            <InfoCircle />
          </Button>
        }
      />
      <PopoverContent side="top">
        <PopoverTitle>Pro plan</PopoverTitle>
        <PopoverDescription>
          Unlimited projects, priority support, and 100 GB of storage. Renews monthly.
        </PopoverDescription>
      </PopoverContent>
    </Popover>
  )
}
```

### Without an arrow [#without-an-arrow]

Pass `arrow={false}` to drop the pointer. The popup also pulls a little closer to the trigger and loses the thicker anchored border, for a flatter, menu-like surface.

```tsx
import { Popover, PopoverTrigger, PopoverContent, PopoverTitle, PopoverDescription } from '@appica/ui-react/popover'
import { Button } from '@appica/ui-react/button'

export default function PopoverNoArrow() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline">No arrow</Button>} />
      <PopoverContent arrow={false}>
        <PopoverTitle>Cleaner edge</PopoverTitle>
        <PopoverDescription>
          Dropping the arrow pulls the popup closer to the trigger and removes the pointer and the thicker anchored
          border.
        </PopoverDescription>
      </PopoverContent>
    </Popover>
  )
}
```

### Side & alignment [#side--alignment]

Position the popup with `side` (`top` / `right` / `bottom` / `left`) and `align` (`start` / `center` / `end`) on `PopoverContent`. Wherever you point it, it still flips and shifts automatically to stay within the viewport.

```tsx
import { Popover, PopoverTrigger, PopoverContent, PopoverTitle, PopoverDescription } from '@appica/ui-react/popover'
import { Button } from '@appica/ui-react/button'

const PLACEMENTS = [
  { side: 'top', align: 'start' },
  { side: 'right', align: 'center' },
  { side: 'bottom', align: 'end' },
  { side: 'left', align: 'center' },
] as const

export default function PopoverPlacement() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {PLACEMENTS.map(({ side, align }) => (
        <Popover key={`${side}-${align}`}>
          <PopoverTrigger
            render={
              <Button variant="outline">
                {side} / {align}
              </Button>
            }
          />
          <PopoverContent side={side} align={align}>
            <PopoverTitle>
              {side} / {align}
            </PopoverTitle>
            <PopoverDescription>The popup flips and shifts automatically to stay in view.</PopoverDescription>
          </PopoverContent>
        </Popover>
      ))}
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — popup placement and alignment — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The popup anchors from the trigger's leading edge and `start`/`end` alignment mirrors. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<Callout type="note" title="Scoped RTL needs the direction on the positioner">
  The popup portals to `<body>`, so its `start`/`end` alignment mirrors from the **document** direction (read from CSS,
  not from `DirectionProvider`) — automatic when `<html dir="rtl">`. If you instead scope RTL to a subtree of an LTR
  page, set it on the positioner so alignment still mirrors: `<PopoverContent positionerProps={{ dir: 'rtl' }}>`. See
  [Floating popups in a scoped RTL region](/ui/docs/react/rtl#floating-popups-in-a-scoped-rtl-region).
</Callout>

<RtlPreview component="popover" />

## API reference [#api-reference]

`Popover` wraps [Base UI's Popover](https://base-ui.com/react/components/popover). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### Popover [#popover]

The root. Holds the open state; renders no DOM of its own.

| Prop                   | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth>          |
| ---------------------- | ------------------------------------------- | ------- | ----------------------------------------------------------- |
| `open`                 | `boolean`                                   | —       | Controlled open state. Pair with `onOpenChange`.            |
| `defaultOpen`          | `boolean`                                   | `false` | Uncontrolled initial open state.                            |
| `onOpenChange`         | <Code>(open, eventDetails) => void</Code>   | —       | Fires when the popover opens or closes.                     |
| `modal`                | <Code>boolean \| 'trap-focus'</Code>        | `false` | Trap focus and block outside scroll/interaction while open. |
| `onOpenChangeComplete` | `(open) => void`                            | —       | Fires after the open/close transition finishes.             |
| `actionsRef`           | `RefObject`                                 | —       | Imperative handle to `close()` / `unmount()` the popup.     |

### PopoverTrigger [#popovertrigger]

The button that toggles the popover. Forwards Base UI's `Popover.Trigger`; use `render` to project it onto your own element.

| Prop           | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                                     |
| -------------- | ----------------------------------------------------------- | ------- | --------------------------------------------------------------- |
| `render`       | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render the trigger as your own element (e.g. a `Button`).       |
| `openOnHover`  | `boolean`                                                   | `false` | Open the popover when the trigger is hovered, not just clicked. |
| `delay`        | `number`                                                    | `300`   | Hover-open delay in ms (with `openOnHover`).                    |
| `closeDelay`   | `number`                                                    | `0`     | Hover-close delay in ms (with `openOnHover`).                   |
| `nativeButton` | `boolean`                                                   | `true`  | Whether the rendered element is a native `<button>`.            |
| `className`    | `string`                                                    | —       | Extra classes on the trigger, merged via `tailwind-merge`.      |

### PopoverContent [#popovercontent]

The portalled, auto-positioned popup. Draws the card and the optional arrow, and accepts the shared floating props. Defaults to `side="bottom"`, `align="center"`, and `sideOffset={10}` (or `6` without an arrow).

| Prop                | <ColMinWidth width="160">Type</ColMinWidth>         | Default    | Description                                                            |
| ------------------- | --------------------------------------------------- | ---------- | ---------------------------------------------------------------------- |
| `arrow`             | `boolean`                                           | `true`     | Render the pointer and the thicker anchored border.                    |
| `side`              | <Code>'top' \| 'right' \| 'bottom' \| 'left'</Code> | `'bottom'` | Preferred side to open on.                                             |
| `align`             | <Code>'start' \| 'center' \| 'end'</Code>           | `'center'` | Alignment along that side.                                             |
| `sideOffset`        | `number`                                            | `10`       | Gap between the trigger and the popup.                                 |
| `alignOffset`       | `number`                                            | `0`        | Shift along the alignment axis.                                        |
| `collisionPadding`  | `number`                                            | `5`        | Minimum gap kept from the viewport edge when flipping/shifting.        |
| `collisionBoundary` | `Boundary`                                          | —          | Element(s) the popup must stay within.                                 |
| `sticky`            | `boolean`                                           | `false`    | Keep the popup in view while the anchor scrolls off.                   |
| `anchor`            | <Code>Element \| ref \| VirtualElement</Code>       | —          | Anchor against a different element than the trigger.                   |
| `container`         | <Code>HTMLElement \| ref \| null</Code>             | —          | Portal target — render the popup into a different node.                |
| `keepMounted`       | `boolean`                                           | `false`    | Keep the popup mounted in the DOM while closed.                        |
| `positionerProps`   | `object`                                            | —          | Escape hatch for the positioner element (`style`, `render`, `dir`, …). |
| `portalProps`       | `object`                                            | —          | Escape hatch for the portal element (`style`, `render`, …).            |
| `className`         | `string`                                            | —          | Extra classes on the popup card.                                       |

### PopoverTitle [#popovertitle]

An `<h2>` that labels the popup. Rendering one sets the popup's `aria-labelledby`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The title text.                             |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### PopoverDescription [#popoverdescription]

A `<p>` that describes the popup. Rendering one sets the popup's `aria-describedby`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The description text.                       |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### PopoverClose [#popoverclose]

A button that closes the popover. Forwards Base UI's `Popover.Close`; project it onto your own element with `render`.

| Prop           | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                          |
| -------------- | ----------------------------------------------------------- | ------- | ---------------------------------------------------- |
| `render`       | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render the close control as your own element.        |
| `nativeButton` | `boolean`                                                   | `true`  | Whether the rendered element is a native `<button>`. |
| `className`    | `string`                                                    | —       | Extra classes, merged via `tailwind-merge`.          |

## Accessibility [#accessibility]

* The trigger is a `button` with `aria-haspopup="dialog"` and `aria-expanded`; the popup has `role="dialog"`.
* `PopoverTitle` and `PopoverDescription` wire the popup's `aria-labelledby` / `aria-describedby` automatically — prefer them over hand-rolled headings.
* **Enter / Space** open the popover from the trigger, **Escape** closes it, and focus returns to the trigger on close.
* With `modal`, focus is trapped inside the open popup and outside scroll/interaction is blocked; the default (`false`) leaves the rest of the page interactive.
* Popup enter/exit transitions are skipped when the user prefers reduced motion.


# Preview Card (/ui/components/react/preview-card)



<Playground component="preview-card" />

## Usage [#usage]

```tsx
import { PreviewCard, PreviewCardTrigger, PreviewCardContent } from '@appica/ui-react/preview-card'
```

```tsx
<PreviewCard>
  <PreviewCardTrigger href="https://appica.dev">@appica_ui</PreviewCardTrigger>
  <PreviewCardContent>
    <p className="text-foreground-intense font-semibold">Appica UI</p>
    <p className="text-sm">An accessible React component library.</p>
  </PreviewCardContent>
</PreviewCard>
```

A preview card shows a **rich preview of a link** when a sighted user hovers or focuses it — the avatar, name, and bio behind an `@mention`, or the cover image behind an article link. Unlike a [`Popover`](/ui/components/react/popover), the trigger is a real anchor: `PreviewCardTrigger` renders an `<a>`, so it still navigates on click.

`PreviewCard` is a compound component built on [Base UI's Preview Card](https://base-ui.com/react/components/preview-card):

* **`PreviewCard`** — the root. Holds the open state; opens on hover/focus of the trigger after a short `delay`.
* **`PreviewCardTrigger`** — the inline `<a>` that owns the link. Pass `href` (and `target`, `rel`, …); style it like any link in your prose.
* **`PreviewCardContent`** — the portalled, auto-positioned popup. Draws the card and the optional `arrow`, and accepts the shared [floating props](/ui/components/react/popover) (`side`, `align`, `sideOffset`, …).

<Callout type="note" title="Keep the preview supplementary">
  The popup only appears on hover/focus, so it's invisible on touch and to screen readers — it's a preview of where the
  link goes, not a place for unique or essential content. Anything important should also live on the linked page.
</Callout>

Reach for a `PreviewCard` to **preview a link's destination** inline in text. For interactive floating content from a button, use a [`Popover`](/ui/components/react/popover); for a plain hint, use a [`Tooltip`](/ui/components/react/tooltip); for a menu of actions, use a [`Dropdown Menu`](/ui/components/react/dropdown-menu).

## Examples [#examples]

### Profile preview [#profile-preview]

The classic use: an `@mention` in running text that reveals the person's or organization's profile card on hover — avatar, name, bio, follower count, and a follow action. The trigger stays a real link, so a click still navigates to the profile.

```tsx
import { PreviewCard, PreviewCardTrigger, PreviewCardContent } from '@appica/ui-react/preview-card'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { Button } from '@appica/ui-react/button'

export default function PreviewCardDefault() {
  return (
    <p className="text-foreground-muted text-center">
      Built and maintained by the team at{' '}
      <PreviewCard>
        <PreviewCardTrigger href="#!" className="text-primary font-medium underline-offset-4 hover:underline">
          @appica_ui
        </PreviewCardTrigger>
        <PreviewCardContent className="w-72">
          <div className="flex items-center justify-between">
            <Avatar>
              <AvatarImage src="/avatars/02.jpg" alt="Appica UI" />
              <AvatarFallback>AU</AvatarFallback>
            </Avatar>
            <Button size="sm">Follow</Button>
          </div>
          <div>
            <p className="text-foreground-intense font-semibold">Appica UI</p>
            <p className="text-foreground-muted text-sm">@appica_ui</p>
          </div>
          <p className="text-sm">An accessible React component library built on Base UI, Motion, and Tailwind.</p>
          <p className="text-foreground-muted text-sm">
            <span className="text-foreground-intense font-medium">2,481</span> followers
          </p>
        </PreviewCardContent>
      </PreviewCard>{' '}
      on GitHub.
    </p>
  )
}
```

### Media preview [#media-preview]

`PreviewCardContent` is just a styled container, so a card can lead with a cover image. Cancel the popup's inner padding with `p-0`, `overflow-hidden` to clip the image to the rounded corners, then pad the text block back in.

```tsx
import { PreviewCard, PreviewCardTrigger, PreviewCardContent } from '@appica/ui-react/preview-card'
import { StarFilled } from '@appica/icons-react'

export default function PreviewCardImage() {
  return (
    <p className="text-foreground-muted text-center">
      Our next offsite is at the{' '}
      <PreviewCard>
        <PreviewCardTrigger href="#!" className="text-primary font-medium underline-offset-4 hover:underline">
          Coastal House
        </PreviewCardTrigger>
        <PreviewCardContent arrow={false} className="w-72 gap-0 overflow-hidden p-0">
          <img src="/preview-card.jpg" alt="Coastal Studio" className="h-41 w-full object-cover" />
          <div className="flex flex-col gap-1 p-4">
            <div className="flex items-center justify-between">
              <p className="text-foreground-intense font-semibold">Coastal House</p>
              <span className="text-foreground-muted flex items-center gap-1 text-sm">
                <StarFilled className="text-warning-emphasis size-4" />
                4.9
              </span>
            </div>
            <p className="text-sm">A bright, open workspace overlooking the bay — room for 24.</p>
          </div>
        </PreviewCardContent>
      </PreviewCard>{' '}
      next month.
    </p>
  )
}
```

### Side & alignment [#side--alignment]

Position the card with `side` (`top` / `right` / `bottom` / `left`) and `align` (`start` / `center` / `end`) on `PreviewCardContent`. It flips and shifts automatically to stay in view.

```tsx
import { PreviewCard, PreviewCardTrigger, PreviewCardContent } from '@appica/ui-react/preview-card'

const PLACEMENTS = [
  { side: 'top', align: 'start' },
  { side: 'right', align: 'center' },
  { side: 'bottom', align: 'end' },
  { side: 'left', align: 'center' },
] as const

export default function PreviewCardPlacement() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-x-6 gap-y-3">
      {PLACEMENTS.map(({ side, align }) => (
        <PreviewCard key={`${side}-${align}`}>
          <PreviewCardTrigger href="#!" className="text-primary text-sm font-medium underline-offset-4 hover:underline">
            {side} / {align}
          </PreviewCardTrigger>
          <PreviewCardContent side={side} align={align}>
            <p className="text-foreground-intense font-semibold">
              {side} / {align}
            </p>
            <p className="text-sm">The card flips and shifts automatically to stay in view.</p>
          </PreviewCardContent>
        </PreviewCard>
      ))}
    </div>
  )
}
```

### Without an arrow [#without-an-arrow]

Pass `arrow={false}` to drop the pointer for a flatter card that sits a little closer to the link.

```tsx
import { PreviewCard, PreviewCardTrigger, PreviewCardContent } from '@appica/ui-react/preview-card'

export default function PreviewCardNoArrow() {
  return (
    <p className="text-foreground-muted text-center">
      Read more in the{' '}
      <PreviewCard>
        <PreviewCardTrigger href="#!" className="text-primary font-medium underline-offset-4 hover:underline">
          getting started
        </PreviewCardTrigger>
        <PreviewCardContent arrow={false} className="w-64">
          <p className="text-foreground-intense font-semibold">Getting started</p>
          <p className="text-sm">Install the package, import the styles, and drop your first component in.</p>
        </PreviewCardContent>
      </PreviewCard>{' '}
      guide.
    </p>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware placement follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The card anchors from the trigger's leading edge and `start`/`end` alignment mirrors. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<Callout type="note" title="Scoped RTL needs the direction on the positioner">
  The popup portals to `<body>`, so its `start`/`end` alignment mirrors from the **document** direction (read from CSS,
  not from `DirectionProvider`) — automatic when `<html dir="rtl">`. If you instead scope RTL to a subtree of an LTR
  page, set it on the positioner so alignment still mirrors: `<PreviewCardContent positionerProps={{ dir: 'rtl' }}>`.
  See [Floating popups in a scoped RTL region](/ui/docs/react/rtl#floating-popups-in-a-scoped-rtl-region).
</Callout>

<RtlPreview component="preview-card" />

## API reference [#api-reference]

`PreviewCard` wraps [Base UI's Preview Card](https://base-ui.com/react/components/preview-card). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### PreviewCard [#previewcard]

The root. Holds the open state; renders no DOM of its own.

| Prop                   | <ColMinWidth width="200">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth>     |
| ---------------------- | ------------------------------------------- | ------- | ------------------------------------------------------ |
| `open`                 | `boolean`                                   | —       | Controlled open state. Pair with `onOpenChange`.       |
| `defaultOpen`          | `boolean`                                   | `false` | Uncontrolled initial open state.                       |
| `onOpenChange`         | <Code>(open, eventDetails) => void</Code>   | —       | Fires when the card opens or closes.                   |
| `onOpenChangeComplete` | `(open) => void`                            | —       | Fires after the open/close transition finishes.        |
| `actionsRef`           | `RefObject`                                 | —       | Imperative handle to `close()` / `unmount()` the card. |

### PreviewCardTrigger [#previewcardtrigger]

The inline anchor that owns the link. Forwards Base UI's `PreviewCard.Trigger` (and every native `<a>` prop); use `render` to project it onto your router's link.

| Prop         | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                               |
| ------------ | ----------------------------------------------------------- | ------- | --------------------------------------------------------- |
| `href`       | `string`                                                    | —       | Navigation target.                                        |
| `delay`      | `number`                                                    | `600`   | Hover-open delay in ms.                                   |
| `closeDelay` | `number`                                                    | `300`   | Hover-close delay in ms.                                  |
| `render`     | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render the link as your own element (e.g. a router link). |
| `className`  | `string`                                                    | —       | Extra classes on the link, merged via `tailwind-merge`.   |

### PreviewCardContent [#previewcardcontent]

The portalled, auto-positioned popup. Draws the card and the optional arrow, and accepts the shared floating props. Defaults to `side="bottom"`, `align="center"`, and `sideOffset={10}` (or `6` without an arrow).

| Prop               | <ColMinWidth width="160">Type</ColMinWidth>         | Default    | Description                                                            |
| ------------------ | --------------------------------------------------- | ---------- | ---------------------------------------------------------------------- |
| `arrow`            | `boolean`                                           | `true`     | Render the pointer and the thicker anchored border.                    |
| `side`             | <Code>'top' \| 'right' \| 'bottom' \| 'left'</Code> | `'bottom'` | Preferred side to open on.                                             |
| `align`            | <Code>'start' \| 'center' \| 'end'</Code>           | `'center'` | Alignment along that side.                                             |
| `sideOffset`       | `number`                                            | `10`       | Gap between the link and the card.                                     |
| `alignOffset`      | `number`                                            | `0`        | Shift along the alignment axis.                                        |
| `collisionPadding` | `number`                                            | `5`        | Minimum gap kept from the viewport edge when flipping/shifting.        |
| `anchor`           | <Code>Element \| ref \| VirtualElement</Code>       | —          | Anchor against a different element than the trigger.                   |
| `container`        | <Code>HTMLElement \| ref \| null</Code>             | —          | Portal target — render the popup into a different node.                |
| `keepMounted`      | `boolean`                                           | `false`    | Keep the popup mounted in the DOM while closed.                        |
| `positionerProps`  | `object`                                            | —          | Escape hatch for the positioner element (`style`, `render`, `dir`, …). |
| `portalProps`      | `object`                                            | —          | Escape hatch for the portal element (`style`, `render`, …).            |
| `className`        | `string`                                            | —          | Extra classes on the card.                                             |

## Accessibility [#accessibility]

* The trigger is a real `<a>`, so it's keyboard-focusable and navigates on click; the preview opens on hover **and** focus.
* The popup is supplementary — it's not announced as the link's name, and it doesn't appear on touch — so don't hide unique or essential content in it.
* **Escape** closes an open card; moving focus or the pointer away closes it after `closeDelay`.
* Enter/exit transitions are skipped when the user prefers reduced motion.


# Progress (/ui/components/react/progress)



<Playground component="progress" />

## Usage [#usage]

```tsx
import { Progress, ProgressLabel, ProgressValue } from '@appica/ui-react/progress'
```

```tsx
<Progress value={60}>
  <ProgressLabel>Uploading</ProgressLabel>
  <ProgressValue />
</Progress>
```

`Progress` tracks a task **moving toward completion** — an upload, an import, an install — unlike [`Meter`](/ui/components/react/meter), which shows a static measurement. Set `value` from `0` to `100` (or pass `min`/`max` for a custom range). When you can't compute a percentage — an unknown-duration wait — reach for a [`Loader`](/ui/components/react/loader) or [`Spinner`](/ui/components/react/spinner) instead.

It comes in two layouts via `variant`: `bar` (a horizontal track, the default) with `ProgressLabel` and `ProgressValue` arranged above it, and `circular` (an SVG ring) with the value centered inside. Recolor the fill with `indicatorColor`, and tune its weight with `thickness` (plus `size` for the ring).

## Examples [#examples]

### Default [#default]

The `bar` layout: a label on the left, the percentage on the right, and the track spanning beneath. `ProgressValue` formats `value` as a percentage by default.

```tsx
import { Progress, ProgressLabel, ProgressValue } from '@appica/ui-react/progress'

export default function ProgressDefault() {
  return (
    <Progress value={60} className="w-72 max-w-full">
      <ProgressLabel>Uploading</ProgressLabel>
      <ProgressValue />
    </Progress>
  )
}
```

### Circular [#circular]

`variant="circular"` draws an SVG ring with the value in its center. Set its diameter with `size`; an optional `ProgressLabel` drops below the ring.

```tsx
import { Progress, ProgressLabel, ProgressValue } from '@appica/ui-react/progress'

export default function ProgressCircular() {
  return (
    <div className="flex items-center gap-10">
      <Progress variant="circular" value={72} size={64}>
        <ProgressValue />
      </Progress>

      <Progress variant="circular" value={40} size={64}>
        <ProgressValue />
        <ProgressLabel>Synced</ProgressLabel>
      </Progress>
    </div>
  )
}
```

### Custom color & thickness [#custom-color--thickness]

`indicatorColor` accepts any CSS color (a theme token like `var(--success-emphasis)` keeps it on-brand), and `thickness` sets the track weight in pixels — for both the bar and the ring.

```tsx
import { Progress, ProgressLabel, ProgressValue } from '@appica/ui-react/progress'

export default function ProgressCustom() {
  return (
    <div className="flex w-72 max-w-full flex-col gap-7">
      <Progress value={88} thickness={10} indicatorColor="var(--success-emphasis)">
        <ProgressLabel>Backup</ProgressLabel>
        <ProgressValue />
      </Progress>

      <Progress value={24} thickness={2} indicatorColor="var(--warning-emphasis)">
        <ProgressLabel>Storage</ProgressLabel>
        <ProgressValue />
      </Progress>

      <div className="flex justify-center">
        <Progress variant="circular" value={62} size={72} thickness={8} indicatorColor="var(--secondary-emphasis)">
          <ProgressValue />
        </Progress>
      </div>
    </div>
  )
}
```

### File upload (controlled) [#file-upload-controlled]

A real-world card driven by your own state: advance `value` as bytes arrive, swap the label to "Uploaded", and reveal an action once it completes. The fill animates smoothly between values.

```tsx
'use client'

import * as React from 'react'
import { Progress, ProgressLabel, ProgressValue } from '@appica/ui-react/progress'
import { Button } from '@appica/ui-react/button'
import { Photo } from '@appica/icons-react'
import { cn } from '@/lib/utils'

function AnimatedCheck() {
  const [drawn, setDrawn] = React.useState(false)

  React.useEffect(() => {
    const id = requestAnimationFrame(() => setDrawn(true))
    return () => cancelAnimationFrame(id)
  }, [])

  return (
    <svg viewBox="0 0 24 24" fill="none" aria-hidden="true" className="size-5">
      <path
        d="M5 12.5l4.5 4.5L19 7"
        stroke="currentColor"
        strokeWidth={2}
        strokeLinecap="round"
        strokeLinejoin="round"
        pathLength={1}
        className="transition-[stroke-dashoffset] duration-500 ease-out [stroke-dasharray:1] motion-reduce:transition-none"
        style={{ strokeDashoffset: drawn ? 0 : 1 }}
      />
    </svg>
  )
}

export default function ProgressUpload() {
  const [progress, setProgress] = React.useState(0)
  const [running, setRunning] = React.useState(true)

  React.useEffect(() => {
    if (!running) return
    const id = setInterval(() => {
      setProgress((current) => {
        if (current >= 100) {
          clearInterval(id)
          setRunning(false)
          return 100
        }
        return Math.min(100, current + 7)
      })
    }, 280)
    return () => clearInterval(id)
  }, [running])

  const done = progress >= 100

  const restart = () => {
    setProgress(0)
    setRunning(true)
  }

  return (
    <div className="border-border bg-background w-80 max-w-full rounded-xl border p-4">
      <div className="flex items-center gap-3">
        <span
          className={cn(
            'flex size-12 shrink-0 items-center justify-center rounded-lg transition-colors',
            done ? 'bg-success-subtle text-success-emphasis' : 'bg-background-muted text-foreground-muted',
          )}
        >
          {done ? <AnimatedCheck /> : <Photo className="size-5" />}
        </span>
        <div className="min-w-0 flex-1">
          <p className="text-foreground-intense truncate text-sm font-medium">cover-photo.jpg</p>
          <Progress value={progress} className="mt-1.5 gap-y-1">
            <ProgressValue className="text-foreground-muted text-xs" />
            <ProgressLabel className="text-foreground-muted text-xs font-normal">
              {done ? 'Uploaded' : 'Uploading…'}
            </ProgressLabel>
          </Progress>
        </div>
      </div>
      {done && (
        <Button variant="soft" size="sm" onClick={restart} className="mt-3 w-full">
          Upload again
        </Button>
      )}
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

Under RTL the label and value swap sides and the bar fills from the right. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="progress" />

## API reference [#api-reference]

`Progress` wraps [Base UI's Progress](https://base-ui.com/react/components/progress). Each part forwards `ref` and its remaining native attributes to the matching Base UI primitive — the tables below list the Appica additions and the most common props. The root exposes `data-complete`, `data-progressing`, and `data-variant` for styling.

### Progress [#progress]

The root. Owns the `value`, range, layout, and indicator styling, and lays out the label, value, and track. Renders a `<div role="progressbar">`.

| Prop               | <ColMinWidth width="210">Type</ColMinWidth>                   | Default       | <ColMinWidth width="220">Description</ColMinWidth>                          |
| ------------------ | ------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------- |
| `value`            | <Code>number \| null</Code>                                   | —             | Current value, from `min` to `max`. Pass `null` for an indeterminate state. |
| `variant`          | <Code>'bar' \| 'circular'</Code>                              | `'bar'`       | Horizontal track or SVG ring.                                               |
| `min`              | `number`                                                      | `0`           | Lower bound of the range.                                                   |
| `max`              | `number`                                                      | `100`         | Upper bound of the range.                                                   |
| `indicatorColor`   | `string`                                                      | primary token | Any CSS color for the fill (e.g. `var(--success-emphasis)`).                |
| `thickness`        | `number`                                                      | `6` / `4`     | Track weight in pixels. Defaults to `6` for `bar`, `4` for `circular`.      |
| `size`             | `number`                                                      | `56`          | Diameter of the ring in pixels (`circular` only).                           |
| `format`           | `Intl.NumberFormatOptions`                                    | —             | Formatting passed to `Intl.NumberFormat` for the displayed value.           |
| `locale`           | `Intl.LocalesArgument`                                        | —             | Locale used by `Intl.NumberFormat`.                                         |
| `getAriaValueText` | <Code>(formatted, value) => string</Code>                     | —             | Build the human-readable `aria-valuetext`.                                  |
| `render`           | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —             | Replace the rendered element, or compose it with another component.         |
| `className`        | <Code>string \| ((state) => string)</Code>                    | —             | Extra classes, merged via `tailwind-merge`. Set the bar width here.         |
| `style`            | <Code>CSSProperties \| ((state) => CSSProperties)</Code>      | —             | Inline styles, optionally derived from state.                               |

### ProgressLabel [#progresslabel]

Names the task and is wired to the root via `aria-labelledby`. Renders a `<span>`.

| Prop        | <ColMinWidth width="210">Type</ColMinWidth>                   | Default | Description                                   |
| ----------- | ------------------------------------------------------------- | ------- | --------------------------------------------- |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace or compose the rendered element.      |
| `className` | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes, merged via `tailwind-merge`.   |
| `style`     | <Code>CSSProperties \| ((state) => CSSProperties)</Code>      | —       | Inline styles, optionally derived from state. |

### ProgressValue [#progressvalue]

Prints the formatted value. Renders a `<span>`.

| Prop        | <ColMinWidth width="210">Type</ColMinWidth>                            | Default | <ColMinWidth width="220">Description</ColMinWidth>                     |
| ----------- | ---------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------- |
| `children`  | <Code>((formatted: string, value: number) => ReactNode) \| null</Code> | —       | Render function to customize the displayed text. Omit for the default. |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code>          | —       | Replace or compose the rendered element.                               |
| `className` | <Code>string \| ((state) => string)</Code>                             | —       | Extra classes, merged via `tailwind-merge`.                            |
| `style`     | <Code>CSSProperties \| ((state) => CSSProperties)</Code>               | —       | Inline styles, optionally derived from state.                          |

## Accessibility [#accessibility]

* `Progress` renders `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` reflecting `value`, `min`, and `max`.
* Give every progress bar an accessible name — a `ProgressLabel` (wired via `aria-labelledby`) or an `aria-label` on the root when no visible label is shown.
* The circular SVG is marked `aria-hidden`; the accessible value comes from the root's ARIA attributes, so the ring is purely visual.
* The fill animation is replaced by a static state when the user prefers reduced motion.


# Radio (/ui/components/react/radio)



<Playground component="radio" />

## Usage [#usage]

```tsx
import { RadioGroup } from '@appica/ui-react/radio-group'
import { Radio } from '@appica/ui-react/radio'
```

```tsx
<RadioGroup defaultValue="pro" aria-label="Plan">
  <label className="flex items-center gap-2">
    <Radio value="free" />
    Free
  </label>
  <label className="flex items-center gap-2">
    <Radio value="pro" />
    Pro
  </label>
  <label className="flex items-center gap-2">
    <Radio value="team" />
    Team
  </label>
</RadioGroup>
```

A `Radio` never stands alone — it only works inside a [`RadioGroup`](#radiogroup), which owns the selected `value` and the roving focus that lets arrow keys move between options. Each radio is identified by its `value`; that's what selection reports back. Wrap each radio and its text in a `<label>` so the text is clickable and announced together. The fill/squish animation is skipped when the user prefers reduced motion.

## Examples [#examples]

### Default [#default]

Set the initial selection with `defaultValue` (uncontrolled) on the group, or drive it yourself with `value` + `onValueChange`. The group lays its options out in a column by default.

```tsx
import { RadioGroup } from '@appica/ui-react/radio-group'
import { Radio } from '@appica/ui-react/radio'

const plans = [
  { value: 'free', label: 'Free' },
  { value: 'pro', label: 'Pro' },
  { value: 'team', label: 'Team' },
]

export default function RadioGroupExample() {
  return (
    <RadioGroup defaultValue="pro" aria-labelledby="plan-label">
      <span id="plan-label" className="text-foreground mb-1 text-sm font-medium">
        Plan
      </span>
      {plans.map((plan) => (
        <label key={plan.value} className="flex items-center gap-2 text-sm select-none">
          <Radio value={plan.value} />
          {plan.label}
        </label>
      ))}
    </RadioGroup>
  )
}
```

### Horizontal [#horizontal]

Pass `orientation="horizontal"` to lay the options out in a row. This also switches the arrow keys that move selection from ↑/↓ to ←/→.

```tsx
import { RadioGroup } from '@appica/ui-react/radio-group'
import { Radio } from '@appica/ui-react/radio'

const sizes = [
  { value: 's', label: 'Small' },
  { value: 'm', label: 'Medium' },
  { value: 'l', label: 'Large' },
]

export default function RadioGroupOrientation() {
  return (
    <RadioGroup orientation="horizontal" defaultValue="m" aria-label="Size">
      {sizes.map((size) => (
        <label key={size.value} className="flex items-center gap-2 text-sm select-none">
          <Radio value={size.value} />
          {size.label}
        </label>
      ))}
    </RadioGroup>
  )
}
```

### Sizing [#sizing]

`Radio` is sized in `em`, so it scales with the surrounding font size — set a `text-*` class on the wrapping `<label>` and the control and text grow together. It won't shrink below a 16px floor.

```tsx
import { RadioGroup } from '@appica/ui-react/radio-group'
import { Radio } from '@appica/ui-react/radio'

export default function RadioSizing() {
  return (
    <RadioGroup defaultValue="base" aria-label="Size" className="items-start gap-4 select-none">
      <label className="flex items-center gap-2 text-base">
        <Radio value="base" />
        text-base
      </label>
      <label className="flex items-center gap-2.5 text-lg">
        <Radio value="lg" />
        text-lg
      </label>
      <label className="flex items-center gap-3 text-xl">
        <Radio value="xl" />
        text-xl
      </label>
    </RadioGroup>
  )
}
```

### Disabled [#disabled]

Disable the whole set with `disabled` on the `RadioGroup`, or a single option with `disabled` on its `Radio`. A disabled option is skipped by arrow-key navigation.

```tsx
import { RadioGroup } from '@appica/ui-react/radio-group'
import { Radio } from '@appica/ui-react/radio'

export default function RadioGroupDisabled() {
  return (
    <div className="flex flex-col gap-8">
      <RadioGroup defaultValue="standard" aria-label="Shipping">
        <label className="flex items-center gap-2 text-sm select-none">
          <Radio value="standard" />
          Standard
        </label>
        <label className="flex items-center gap-2 text-sm select-none">
          <Radio value="express" />
          Express
        </label>
        <label className="text-foreground-muted flex items-center gap-2 text-sm select-none">
          <Radio value="overnight" disabled />
          Overnight (unavailable)
        </label>
      </RadioGroup>

      <RadioGroup defaultValue="yearly" disabled aria-label="Billing period">
        <label className="text-foreground-muted flex items-center gap-2 text-sm select-none">
          <Radio value="monthly" />
          Monthly
        </label>
        <label className="text-foreground-muted flex items-center gap-2 text-sm select-none">
          <Radio value="yearly" />
          Yearly
        </label>
      </RadioGroup>
    </div>
  )
}
```

### With descriptions [#with-descriptions]

Pair each option's label with supporting text, aligning the radio to the first line. Keeping it all inside the `<label>` makes the whole row one target.

```tsx
import { RadioGroup } from '@appica/ui-react/radio-group'
import { Radio } from '@appica/ui-react/radio'

const visibilities = [
  { value: 'public', label: 'Public', description: 'Anyone on the internet can see this project.' },
  { value: 'private', label: 'Private', description: 'Only you and people you invite can access it.' },
  { value: 'team', label: 'Team', description: 'Everyone in your organization can view and edit.' },
]

export default function RadioGroupWithDescriptions() {
  return (
    <RadioGroup defaultValue="private" aria-label="Visibility" className="max-w-md">
      {visibilities.map((visibility) => (
        <label key={visibility.value} className="flex items-start gap-2.5 select-none">
          <Radio value={visibility.value} className="mt-1" />
          <span className="flex flex-col">
            <span className="text-foreground-intense font-medium">{visibility.label}</span>
            <span className="text-foreground-muted text-sm">{visibility.description}</span>
          </span>
        </label>
      ))}
    </RadioGroup>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="radio" />

## API reference [#api-reference]

`RadioGroup` and `Radio` wrap [Base UI's Radio](https://base-ui.com/react/components/radio). The group renders a `<div role="radiogroup">` and each `Radio` a `role="radio"`; both forward `ref`, `aria-*`, and their native attributes, and expose `data-*` state attributes (`data-checked`, `data-unchecked`, `data-disabled`, `data-readonly`, …) for styling. See the Base UI docs for the complete API.

### RadioGroup [#radiogroup]

The container that owns the selected value and keyboard navigation.

| Prop            | <ColMinWidth width="200">Type</ColMinWidth>                   | Default      | <ColMinWidth width="220">Description</ColMinWidth>                                    |
| --------------- | ------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------- |
| `value`         | `string`                                                      | —            | Controlled selected value. Pair with `onValueChange`.                                 |
| `defaultValue`  | `string`                                                      | —            | Uncontrolled initial selection.                                                       |
| `onValueChange` | <Code>(value: string, details) => void</Code>                 | —            | Fires when the selection changes.                                                     |
| `orientation`   | <Code>'horizontal' \| 'vertical'</Code>                       | `'vertical'` | Lay options out in a row or column; sets which arrow keys move selection.             |
| `name`          | `string`                                                      | —            | Field name submitted with a form.                                                     |
| `disabled`      | `boolean`                                                     | `false`      | Disables every radio in the group.                                                    |
| `readOnly`      | `boolean`                                                     | `false`      | Focusable, but the selection can't be changed.                                        |
| `required`      | `boolean`                                                     | `false`      | An option must be chosen before the form submits.                                     |
| `render`        | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —            | Replace the group element, or compose it with another component.                      |
| `className`     | <Code>string \| ((state) => string)</Code>                    | —            | Extra classes, merged via `tailwind-merge` (override the default `flex` layout here). |
| `style`         | <Code>CSSProperties \| ((state) => CSSProperties)</Code>      | —            | Inline styles, optionally derived from state.                                         |

### Radio [#radio]

One option inside a `RadioGroup`.

| Prop           | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>                                   |
| -------------- | ------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `value`        | `string`                                                      | —       | **Required.** The value this option selects; reported by the group on change.        |
| `disabled`     | `boolean`                                                     | `false` | Removes this option from the tab order and skips it during arrow navigation.         |
| `readOnly`     | `boolean`                                                     | `false` | Focusable but not selectable.                                                        |
| `required`     | `boolean`                                                     | `false` | Marks this option required for form submission.                                      |
| `nativeButton` | `boolean`                                                     | `false` | Whether the element passed to `render` is a native `<button>`.                       |
| `inputRef`     | <Code>Ref\<HTMLInputElement></Code>                           | —       | Ref to the hidden `<input>` element backing the radio.                               |
| `id`           | `string`                                                      | —       | `id` of the rendered element.                                                        |
| `render`       | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the rendered element, or compose it with another component.                  |
| `className`    | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes on the radio, merged via `tailwind-merge`. May be a function of state. |
| `style`        | <Code>CSSProperties \| ((state) => CSSProperties)</Code>      | —       | Inline styles, optionally derived from state.                                        |

## Accessibility [#accessibility]

* `RadioGroup` renders a `<div role="radiogroup">` and each `Radio` a `role="radio"`. Name the group with `aria-label` or `aria-labelledby`.
* The group is a single tab stop: **Tab** moves focus into the selected option (or the first one), and the **arrow keys** move the selection between options — ↑/↓ when vertical, ←/→ when horizontal — wrapping around the ends.
* Each radio needs an accessible name — wrap it in a `<label>` together with its text, or give it an `aria-label`.
* `disabled` on a radio or the group removes the affected options from the tab order and exposes `data-disabled` for styling; disabled options are skipped during arrow navigation.
* The fill/squish animation honours `prefers-reduced-motion`.


# Scroll Area (/ui/components/react/scroll-area)



<Playground component="scroll-area" />

## Usage [#usage]

```tsx
import { ScrollArea } from '@appica/ui-react/scroll-area'
```

```tsx
<ScrollArea className="h-60 w-64 rounded-xl border">
  <div className="flex flex-col p-2">{/* overflowing content */}</div>
</ScrollArea>
```

`ScrollArea` wraps overflowing content in a native scroll container, then paints its own slim,
themeable scrollbar on top — so scrollbars look identical across macOS, Windows, and Linux instead of
inheriting the OS chrome. It scrolls only once it has a **bounded size** and content that overflows
it: give the area a height (and/or width) via `className`, and let the content inside determine the
overflow.

It's a folded single element — you render `ScrollArea` and your content, and the viewport, scrollbars,
and thumb are wired up internally. Reach the inner scroll viewport (for a `ref`, `onScroll`, or extra
classes) through the `viewportProps` escape hatch.

## Examples [#examples]

### Vertical scrolling [#vertical-scrolling]

The default `orientation`. The area fills its parent's width and scrolls vertically once the content
is taller than the set height.

```tsx
import { ScrollArea } from '@appica/ui-react/scroll-area'

const tags = [
  'React',
  'Next.js',
  'TypeScript',
  'Tailwind CSS',
  'Base UI',
  'Motion',
  'Vitest',
  'Fumadocs',
  'pnpm',
  'Radix',
  'Zod',
  'ESLint',
  'Prettier',
  'Storybook',
  'Playwright',
  'tRPC',
]

export default function ScrollAreaDefault() {
  return (
    <ScrollArea className="border-border h-58 w-full max-w-64 rounded-lg border">
      <div className="flex flex-col p-2">
        {tags.map((tag) => (
          <div key={tag} className="text-foreground rounded-md px-3 py-2 text-sm">
            {tag}
          </div>
        ))}
      </div>
    </ScrollArea>
  )
}
```

### Horizontal scrolling [#horizontal-scrolling]

Set `orientation="horizontal"` for a row of items wider than the container — carousels, tag rows, or
code blocks. The area sizes to its content's height and scrolls sideways.

```tsx
import { ScrollArea } from '@appica/ui-react/scroll-area'

export default function ScrollAreaHorizontal() {
  return (
    <ScrollArea orientation="horizontal" className="w-full max-w-md rounded-lg border">
      <div className="flex gap-3 p-4">
        {Array.from({ length: 12 }, (_, i) => (
          <div
            key={i}
            className="bg-background-muted flex size-24 shrink-0 items-center justify-center rounded-lg text-lg font-medium"
          >
            {i + 1}
          </div>
        ))}
      </div>
    </ScrollArea>
  )
}
```

### Both axes [#both-axes]

`orientation="both"` renders a scrollbar on each axis plus a corner where they meet — handy for wide
tables or grids that overflow in two directions.

```tsx
import { ScrollArea } from '@appica/ui-react/scroll-area'

export default function ScrollAreaBoth() {
  return (
    <ScrollArea orientation="both" className="h-58 w-full max-w-md rounded-lg border">
      <div className="grid w-max grid-cols-8 gap-2 p-4">
        {Array.from({ length: 96 }, (_, i) => (
          <div
            key={i}
            className="bg-background-muted text-foreground-muted flex size-14 shrink-0 items-center justify-center rounded-md text-xs"
          >
            {i + 1}
          </div>
        ))}
      </div>
    </ScrollArea>
  )
}
```

### Scroll shadow [#scroll-shadow]

Set `scrollShadow` to fade the content at whichever edges can still scroll, hinting that there's more
beyond the fold. It's a CSS mask on the viewport, so it tracks scrolling with no runtime cost and
clears once an edge is fully reached.

```tsx
import { ScrollArea } from '@appica/ui-react/scroll-area'

const paragraphs = [
  'Scroll shadows hint that there is more content beyond the visible edge. Instead of a hard cut, the text fades out where it meets the boundary of the viewport.',
  'The fade is a CSS mask applied to the viewport, so it costs nothing at runtime and follows the content as you scroll — the top edge clears once you reach the start, and the bottom clears at the end.',
  'Because it is purely visual, the mask never blocks pointer events or selection. The text underneath stays fully interactive; only its opacity near the edges is affected.',
  'Reach for it on free-flowing prose, feeds, and long lists where a visible scrollbar alone is easy to miss. Pair it with any orientation — the mask fades whichever edges can scroll.',
  'When the content fits without overflowing, the mask resolves to fully opaque, so short content is never dimmed by accident.',
]

export default function ScrollAreaShadow() {
  return (
    <ScrollArea scrollShadow className="h-56 w-full max-w-sm">
      <div className="text-foreground flex flex-col gap-3 px-1 py-2 pr-4 text-sm leading-relaxed">
        {paragraphs.map((text, i) => (
          <p key={i}>{text}</p>
        ))}
      </div>
    </ScrollArea>
  )
}
```

### Scrollbar visibility [#scrollbar-visibility]

`scrollbarVisibility` controls when the scrollbar shows: `always` (the default), `auto` to reveal it
only while hovering or scrolling, or `never` to hide it entirely while keeping the content scrollable.
This example uses `auto` — hover the area to reveal the bar.

```tsx
import { ScrollArea } from '@appica/ui-react/scroll-area'

export default function ScrollAreaVisibility() {
  return (
    <ScrollArea scrollbarVisibility="auto" className="border-border h-58 w-full max-w-64 rounded-lg border">
      <div className="flex flex-col p-2">
        {Array.from({ length: 20 }, (_, i) => (
          <div key={i} className="text-foreground rounded-md px-3 py-2 text-sm">
            Notification {i + 1}
          </div>
        ))}
      </div>
    </ScrollArea>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a
container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your
tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The vertical scrollbar moves to the start (left) edge and horizontal scrolling begins from the right,
following the resolved direction. The scroll-shadow mask mirrors to fade the matching edges. For setup
details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="scroll-area" />

## API reference [#api-reference]

`ScrollArea` wraps [Base UI's Scroll Area](https://base-ui.com/react/components/scroll-area) and forwards `ref` and remaining `ScrollArea.Root` props. Its parts carry `data-slot` attributes (`scroll-area`, `scroll-area-viewport`, `scroll-area-content`, `scroll-area-scrollbar`, `scroll-area-thumb`, `scroll-area-corner`) for targeted styling.

| Prop                  | <ColMinWidth width="200">Type</ColMinWidth>         | Default      | <ColMinWidth width="220">Description</ColMinWidth>                                         |
| --------------------- | --------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------ |
| `orientation`         | <Code>'vertical' \| 'horizontal' \| 'both'</Code>   | `'vertical'` | Which axis (or axes) gets a scrollbar. `both` also renders the corner.                     |
| `scrollShadow`        | `boolean`                                           | `false`      | Fade the content at scrollable edges via a CSS mask.                                       |
| `scrollbarVisibility` | <Code>'always' \| 'auto' \| 'never'</Code>          | `'always'`   | `auto` reveals the bar on hover/scroll; `never` hides it while keeping content scrollable. |
| `viewportProps`       | <Code>Omit\<ScrollArea.Viewport, 'children'></Code> | —            | Props forwarded to the inner scroll viewport — `ref`, `onScroll`, `className`, etc.        |
| `className`           | `string`                                            | —            | Classes on the root. **Set the size here** (`h-*` / `w-*`) so the area can overflow.       |
| `children`            | `ReactNode`                                         | —            | The scrollable content.                                                                    |

## Accessibility [#accessibility]

* Built on Base UI's Scroll Area, which keeps the content in a **native scroll container** — so mouse
  wheel, trackpad, touch, and keyboard scrolling (arrows, **Page Up/Down**, **Home/End**) all work as
  users expect; only the scrollbar's appearance is custom.
* The scroll viewport is focusable so keyboard users can scroll overflowing content, with a visible
  focus ring.
* The custom scrollbar and thumb are decorative — assistive tech navigates the content directly rather
  than the bar.
* Set a `scrollbarVisibility` other than `never` when scrolling isn't otherwise discoverable; hiding
  the bar entirely can make overflow easy to miss.


# Select (/ui/components/react/select)



<Playground component="select" />

## Usage [#usage]

```tsx
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@appica/ui-react/select'
```

```tsx
<Select>
  <SelectTrigger>
    <SelectValue placeholder="Pick a fruit" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="apple">Apple</SelectItem>
    <SelectItem value="orange">Orange</SelectItem>
  </SelectContent>
</Select>
```

`Select` is a compound component. The root holds the value and shared options (`size`, `variant`, `multiple`, `alignItemWithTrigger`); the parts compose the trigger and the portalled popup:

* **`SelectTrigger`** — the button styled like [`Input`](/ui/components/react/input). Add a clear button with `clearable`, and adornments with `startSlot` / `endSlot`.
* **`SelectValue`** — renders the current selection inside the trigger. Pass a `placeholder`, or a function child to format the value (e.g. for multi-select).
* **`SelectContent`** — the portalled, auto-positioned popup. Accepts the shared [floating props](/ui/components/react/popover) (`side`, `align`, `sideOffset`, …).
* **`SelectItem`** — one option; its `value` is what selection reports.
* **`SelectGroup`*&#x2A; / &#x2A;*`SelectGroupLabel`*&#x2A; / &#x2A;*`SelectSeparator`** — optional structure for grouped lists.

Reach for a `Select` when the options are short and known. For a long list users need to **filter by typing**, use a [`Combobox`](/ui/components/react/combobox) or [`Autocomplete`](/ui/components/react/autocomplete) instead.

## Examples [#examples]

### Variants [#variants]

`variant` switches the trigger appearance between a bordered `outline` (default) and a filled `soft` field.

```tsx
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@appica/ui-react/select'

const fruits = ['Apple', 'Banana', 'Blueberry', 'Grapes', 'Orange', 'Strawberry']
const variants = ['outline', 'soft'] as const

export default function SelectVariants() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      {variants.map((variant) => (
        <Select key={variant} variant={variant}>
          <SelectTrigger aria-label={`Pick a fruit (${variant})`}>
            <SelectValue placeholder="Pick a fruit" />
          </SelectTrigger>
          <SelectContent>
            {fruits.map((fruit) => (
              <SelectItem key={fruit} value={fruit}>
                {fruit}
              </SelectItem>
            ))}
          </SelectContent>
        </Select>
      ))}
    </div>
  )
}
```

### Sizes [#sizes]

`size` on the root scales the trigger, popup radius, and items together — `sm`, `md` (default), or `lg`.

```tsx
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@appica/ui-react/select'

const fruits = ['Apple', 'Banana', 'Blueberry', 'Grapes', 'Orange', 'Strawberry']
const sizes = ['sm', 'md', 'lg'] as const

export default function SelectSizes() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      {sizes.map((size) => (
        <Select key={size} size={size}>
          <SelectTrigger aria-label={`Pick a fruit (${size})`}>
            <SelectValue placeholder="Pick a fruit" />
          </SelectTrigger>
          <SelectContent>
            {fruits.map((fruit) => (
              <SelectItem key={fruit} value={fruit}>
                {fruit}
              </SelectItem>
            ))}
          </SelectContent>
        </Select>
      ))}
    </div>
  )
}
```

### Grouped options [#grouped-options]

Wrap related items in `SelectGroup` with a `SelectGroupLabel`, and divide groups with `SelectSeparator`. Mark an option `disabled` to make it unselectable.

```tsx
import {
  Select,
  SelectTrigger,
  SelectValue,
  SelectContent,
  SelectGroup,
  SelectGroupLabel,
  SelectItem,
  SelectSeparator,
} from '@appica/ui-react/select'

export default function SelectGrouped() {
  return (
    <div className="w-full max-w-70">
      <Select>
        <SelectTrigger aria-label="Pick a food">
          <SelectValue placeholder="Pick a food" />
        </SelectTrigger>
        <SelectContent>
          <SelectGroup>
            <SelectGroupLabel>Fruits</SelectGroupLabel>
            <SelectItem value="Apple">Apple</SelectItem>
            <SelectItem value="Banana">Banana</SelectItem>
            <SelectItem value="Orange">Orange</SelectItem>
            <SelectItem value="Strawberry">Strawberry</SelectItem>
          </SelectGroup>
          <SelectSeparator />
          <SelectGroup>
            <SelectGroupLabel>Vegetables</SelectGroupLabel>
            <SelectItem value="Carrot">Carrot</SelectItem>
            <SelectItem value="Potato">Potato</SelectItem>
            <SelectItem value="Tomato">Tomato</SelectItem>
            <SelectItem value="Broccoli" disabled>
              Broccoli
            </SelectItem>
          </SelectGroup>
        </SelectContent>
      </Select>
    </div>
  )
}
```

### Clearable [#clearable]

Set `clearable` on the trigger to add a clear (✕) button that resets the selection once a value is present.

```tsx
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@appica/ui-react/select'

const fruits = ['Apple', 'Banana', 'Blueberry', 'Grapes', 'Orange', 'Strawberry']

export default function SelectClearable() {
  return (
    <div className="w-full max-w-70">
      <Select defaultValue="Orange">
        <SelectTrigger clearable aria-label="Pick a fruit">
          <SelectValue placeholder="Pick a fruit" />
        </SelectTrigger>
        <SelectContent>
          {fruits.map((fruit) => (
            <SelectItem key={fruit} value={fruit}>
              {fruit}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </div>
  )
}
```

### Disabled & error states [#disabled--error-states]

`disabled` on the root greys out the trigger and blocks interaction. Set `aria-invalid` on the `SelectTrigger` to paint the error state — it's mirrored to `data-invalid`. Inside a [`Field`](/ui/components/react/field), the trigger also inherits the field's `disabled` and `invalid` state, which is the better choice when you're rendering a validation message.

```tsx
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@appica/ui-react/select'

const fruits = ['Apple', 'Banana', 'Blueberry', 'Grapes', 'Orange', 'Strawberry']

export default function SelectStates() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      <Select disabled>
        <SelectTrigger aria-label="Disabled">
          <SelectValue placeholder="Disabled" />
        </SelectTrigger>
        <SelectContent>
          {fruits.map((fruit) => (
            <SelectItem key={fruit} value={fruit}>
              {fruit}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>

      <Select defaultValue="Orange">
        <SelectTrigger aria-invalid aria-label="With error">
          <SelectValue placeholder="Pick a fruit" />
        </SelectTrigger>
        <SelectContent>
          {fruits.map((fruit) => (
            <SelectItem key={fruit} value={fruit}>
              {fruit}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </div>
  )
}
```

### Start & end slots [#start--end-slots]

`SelectTrigger` accepts `startSlot` and `endSlot` for adornments — an icon, a badge, a unit — rendered inside the trigger frame, around the value.

```tsx
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@appica/ui-react/select'
import { CreditCard } from '@appica/icons-react'

const methods = ['Credit card', 'PayPal', 'Bank transfer', 'Apple Pay', 'Google Pay']

export default function SelectSlots() {
  return (
    <div className="w-full max-w-70">
      <Select defaultValue="Credit card" alignItemWithTrigger={false}>
        <SelectTrigger
          aria-label="Payment method"
          startSlot={<CreditCard />}
          endSlot={<span className="text-foreground-subtle text-xs">Default</span>}
        >
          <SelectValue placeholder="Payment method" />
        </SelectTrigger>
        <SelectContent>
          {methods.map((method) => (
            <SelectItem key={method} value={method}>
              {method}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </div>
  )
}
```

<Callout type="warning" title="Disable alignItemWithTrigger when using a startSlot">
  By default `alignItemWithTrigger` overlays the selected item directly on top of the trigger when the popup opens (an
  iOS-style picker). That alignment assumes the value starts at the trigger's leading edge, so a `startSlot` throws the
  popup's horizontal position off. Whenever you add a `startSlot`, set `alignItemWithTrigger={false}` on the `Select` so
  the popup anchors below the trigger instead.
</Callout>

### Country select [#country-select]

A compact country picker: each item shows a [flag](/ui/country-flags) before the name, and the selected country's flag is mirrored into the trigger through `startSlot`. Because of that slot, the root sets `alignItemWithTrigger={false}`. For a long, searchable country list, use a [`Combobox`](/ui/components/react/combobox) instead.

```tsx
'use client'

import * as React from 'react'
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@appica/ui-react/select'
import { CountryFlagRounded } from '@appica/country-flags-react'

interface Country {
  code: string
  name: string
}

const countries: Country[] = [
  { code: 'au', name: 'Australia' },
  { code: 'br', name: 'Brazil' },
  { code: 'ca', name: 'Canada' },
  { code: 'fr', name: 'France' },
  { code: 'de', name: 'Germany' },
  { code: 'jp', name: 'Japan' },
  { code: 'gb', name: 'United Kingdom' },
  { code: 'us', name: 'United States' },
]

export default function SelectCountry() {
  const [value, setValue] = React.useState<string | null>('us')
  const selected = countries.find((country) => country.code === value)

  return (
    <div className="w-full max-w-70">
      <Select value={value} onValueChange={(v) => setValue(v as string | null)} alignItemWithTrigger={false}>
        <SelectTrigger
          aria-label="Select a country"
          startSlot={selected ? <CountryFlagRounded code={selected.code} aria-hidden /> : null}
        >
          <SelectValue placeholder="Select a country">{() => selected?.name}</SelectValue>
        </SelectTrigger>
        <SelectContent>
          {countries.map((country) => (
            <SelectItem key={country.code} value={country.code}>
              <CountryFlagRounded code={country.code} data-icon="start" aria-hidden />
              {country.name}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </div>
  )
}
```

### User select [#user-select]

Rich items with an [`Avatar`](/ui/components/react/avatar), a name, and a trailing role — a typical "assign to" picker. The chosen person's avatar is echoed into the trigger via `startSlot` (so `alignItemWithTrigger` is off here too).

```tsx
'use client'

import * as React from 'react'
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@appica/ui-react/select'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'

interface User {
  id: string
  name: string
  avatar: string
  initials: string
}

const users: User[] = [
  { id: 'sarah', name: 'Sarah Jenkins', avatar: '/avatars/01.jpg', initials: 'SJ' },
  { id: 'liam', name: 'Liam Hudson', avatar: '/avatars/02.jpg', initials: 'LH' },
  { id: 'mateo', name: 'Mateo Rossi', avatar: '/avatars/03.jpg', initials: 'MR' },
  { id: 'ava', name: 'Ava Thompson', avatar: '/avatars/04.jpg', initials: 'AT' },
  { id: 'emma', name: 'Emma Garcia', avatar: '/avatars/09.jpg', initials: 'EG' },
  { id: 'noah', name: 'Noah Patel', avatar: '/avatars/06.jpg', initials: 'NP' },
]

export default function SelectUsers() {
  const [value, setValue] = React.useState<string | null>('liam')
  const selected = users.find((user) => user.id === value)

  return (
    <div className="w-full max-w-70">
      <Select value={value} onValueChange={(v) => setValue(v as string | null)} alignItemWithTrigger={false}>
        <SelectTrigger
          aria-label="Assign to"
          startSlot={
            selected ? (
              <Avatar size={22}>
                <AvatarImage src={selected.avatar} alt={selected.name} />
                <AvatarFallback>{selected.initials}</AvatarFallback>
              </Avatar>
            ) : null
          }
        >
          <SelectValue placeholder="Assign to">{() => selected?.name}</SelectValue>
        </SelectTrigger>
        <SelectContent>
          {users.map((user) => (
            <SelectItem key={user.id} value={user.id}>
              <Avatar size={22} data-icon="start">
                <AvatarImage src={user.avatar} alt={user.name} />
                <AvatarFallback>{user.initials}</AvatarFallback>
              </Avatar>
              {user.name}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </div>
  )
}
```

### Multiple selection [#multiple-selection]

Set `multiple` on the root and the value becomes an array. Selected items keep a check, and a function child on `SelectValue` formats the trigger summary.

```tsx
'use client'

import * as React from 'react'
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@appica/ui-react/select'

const toppings = ['Pepperoni', 'Mushrooms', 'Onions', 'Olives', 'Peppers', 'Bacon', 'Pineapple']

export default function SelectMultiple() {
  const [value, setValue] = React.useState<string[]>(['Pepperoni', 'Mushrooms'])

  return (
    <div className="w-full max-w-70">
      <Select multiple value={value} onValueChange={(v) => setValue(v as string[])}>
        <SelectTrigger clearable aria-label="Choose toppings">
          <SelectValue placeholder="Choose toppings">
            {(selected: string[]) =>
              selected.length === 0
                ? 'Choose toppings'
                : selected.length === 1
                  ? selected[0]
                  : `${selected.length} toppings`
            }
          </SelectValue>
        </SelectTrigger>
        <SelectContent>
          {toppings.map((topping) => (
            <SelectItem key={topping} value={topping}>
              {topping}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </div>
  )
}
```

### Controlled [#controlled]

Drive the selection yourself with `value` + `onValueChange` — useful for syncing with form state or reacting to every change. Use `null` (or `[]` when `multiple`) for the empty value.

```tsx
'use client'

import * as React from 'react'
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@appica/ui-react/select'

const fruits = ['Apple', 'Banana', 'Blueberry', 'Grapes', 'Orange', 'Strawberry']

export default function SelectControlled() {
  const [value, setValue] = React.useState<string | null>(null)

  return (
    <div className="flex w-full max-w-70 flex-col gap-3">
      <Select value={value} onValueChange={(v) => setValue(v as string | null)}>
        <SelectTrigger clearable aria-label="Pick a fruit">
          <SelectValue placeholder="Pick a fruit" />
        </SelectTrigger>
        <SelectContent>
          {fruits.map((fruit) => (
            <SelectItem key={fruit} value={fruit}>
              {fruit}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
      <p className="text-foreground-muted text-sm">
        Current value: <span className="text-foreground font-medium">{value ?? '—'}</span>
      </p>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The trigger, popup, and check indicators all mirror to follow the resolved direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="select" />

## API reference [#api-reference]

`Select` wraps [Base UI's Select](https://base-ui.com/react/components/select). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### Select [#select]

The root. Holds the value and shared styling/behavior options; renders no DOM of its own.

| Prop                   | <ColMinWidth width="180">Type</ColMinWidth>                       | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                                 |
| ---------------------- | ----------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| `size`                 | <Code>'sm' \| 'md' \| 'lg'</Code>                                 | `'md'`      | Trigger height, popup radius, and item sizing.                                                     |
| `variant`              | <Code>'outline' \| 'soft'</Code>                                  | `'outline'` | Trigger appearance — bordered or filled.                                                           |
| `alignItemWithTrigger` | `boolean`                                                         | `true`      | Overlay the selected item over the trigger on open. &#x2A;*Set `false` when using a `startSlot`.** |
| `multiple`             | `boolean`                                                         | `false`     | Allow selecting several values; the value becomes an array.                                        |
| `value`                | <Code>Value \| Value\[] \| null</Code>                            | —           | Controlled selection. Pair with `onValueChange`.                                                   |
| `defaultValue`         | <Code>Value \| Value\[] \| null</Code>                            | —           | Uncontrolled initial selection.                                                                    |
| `onValueChange`        | <Code>(value, details) => void</Code>                             | —           | Fires when the selection changes.                                                                  |
| `open`                 | `boolean`                                                         | —           | Controlled open state of the popup. Pair with `onOpenChange`.                                      |
| `defaultOpen`          | `boolean`                                                         | `false`     | Uncontrolled initial open state.                                                                   |
| `onOpenChange`         | <Code>(open, details) => void</Code>                              | —           | Fires when the popup opens or closes.                                                              |
| `items`                | <Code>Record\<string, ReactNode> \| {'{ value, label }[]'}</Code> | —           | Value→label map so `SelectValue` can render a label without a function child.                      |
| `name`                 | `string`                                                          | —           | Field name submitted with a form.                                                                  |
| `disabled`             | `boolean`                                                         | `false`     | Disable the whole control.                                                                         |
| `required`             | `boolean`                                                         | `false`     | Require a value before the form submits.                                                           |
| `readOnly`             | `boolean`                                                         | `false`     | Focusable but not changeable.                                                                      |
| `modal`                | `boolean`                                                         | `true`      | Whether the popup traps focus and blocks outside interaction.                                      |

### SelectTrigger [#selecttrigger]

The button that opens the popup, styled like [`Input`](/ui/components/react/input).

| Prop           | <ColMinWidth width="160">Type</ColMinWidth> | Default | Description                                                           |
| -------------- | ------------------------------------------- | ------- | --------------------------------------------------------------------- |
| `clearable`    | `boolean`                                   | `false` | Render a clear button inside the trigger when a value is present.     |
| `startSlot`    | `ReactNode`                                 | —       | Adornment before the value. Pair with `alignItemWithTrigger={false}`. |
| `endSlot`      | `ReactNode`                                 | —       | Adornment after the value, before the chevron.                        |
| `aria-invalid` | <Code>boolean \| 'true' \| 'false'</Code>   | —       | Marks the error state; mirrored to `data-invalid` for styling.        |
| `className`    | `string`                                    | —       | Extra classes on the trigger, merged via `tailwind-merge`.            |

Also forwards every native `<button>` prop (`onClick`, `aria-*`, `ref`, …).

### SelectValue [#selectvalue]

Renders the current selection inside the trigger.

| Prop          | <ColMinWidth width="200">Type</ColMinWidth>    | Default | Description                                                  |
| ------------- | ---------------------------------------------- | ------- | ------------------------------------------------------------ |
| `placeholder` | `string`                                       | —       | Shown when nothing is selected.                              |
| `children`    | <Code>ReactNode \| (value) => ReactNode</Code> | —       | A function child formats the value — handy for multi-select. |

### SelectContent [#selectcontent]

The portalled, auto-positioned popup wrapping the list. Accepts the shared floating props.

| Prop                   | <ColMinWidth width="160">Type</ColMinWidth>         | Default    | Description                                                     |
| ---------------------- | --------------------------------------------------- | ---------- | --------------------------------------------------------------- |
| `alignItemWithTrigger` | `boolean`                                           | —          | Per-popup override of the root's alignment setting.             |
| `side`                 | <Code>'top' \| 'right' \| 'bottom' \| 'left'</Code> | `'bottom'` | Preferred side to open on (when not aligned with the trigger).  |
| `align`                | <Code>'start' \| 'center' \| 'end'</Code>           | —          | Alignment along that side.                                      |
| `sideOffset`           | `number`                                            | `6`        | Gap between the trigger and the popup.                          |
| `alignOffset`          | `number`                                            | —          | Shift along the alignment axis.                                 |
| `container`            | <Code>HTMLElement \| ref \| null</Code>             | —          | Portal target — render the popup into a different node.         |
| `keepMounted`          | `boolean`                                           | `false`    | Keep the popup mounted in the DOM while closed.                 |
| `positionerProps`      | `object`                                            | —          | Escape hatch for the positioner element (`style`, `render`, …). |
| `portalProps`          | `object`                                            | —          | Escape hatch for the portal element (`style`, `render`, …).     |
| `className`            | `string`                                            | —          | Extra classes on the popup.                                     |

### SelectItem [#selectitem]

One option in the list.

| Prop        | Type      | Default | Description                                             |
| ----------- | --------- | ------- | ------------------------------------------------------- |
| `value`     | `T`       | —       | The item this option represents; reported on selection. |
| `disabled`  | `boolean` | `false` | Make the option unselectable.                           |
| `className` | `string`  | —       | Extra classes, merged via `tailwind-merge`.             |

### SelectGroup [#selectgroup]

Wraps one labelled section of the list.

| Prop        | Type        | Default | Description                                  |
| ----------- | ----------- | ------- | -------------------------------------------- |
| `children`  | `ReactNode` | —       | A `SelectGroupLabel` plus its `SelectItem`s. |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`.  |

### SelectGroupLabel [#selectgrouplabel]

The visible label for a `SelectGroup`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | The label text.                             |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### SelectSeparator [#selectseparator]

A thin divider between groups.

| Prop        | Type     | Default | Description                                 |
| ----------- | -------- | ------- | ------------------------------------------- |
| `className` | `string` | —       | Extra classes, merged via `tailwind-merge`. |

## Accessibility [#accessibility]

* The trigger has `role="combobox"`; the popup is a `listbox` and items are `option`s. Selection and active state are wired through `aria-activedescendant` and `aria-selected`.
* **Space / Enter / ↓*&#x2A; open the popup, &#x2A;*↑/↓** move the highlight, **Enter** selects, **Escape** closes, and typing a letter jumps to the matching option (typeahead).
* Give the trigger an accessible name — an adjacent `<label>`, `aria-label`, or `aria-labelledby`.
* When `clearable` and a value is present, the trigger clears on **Delete** / **Backspace** (keeping focus on the trigger); the pointer ✕ affordance is decorative (`aria-hidden`).
* `disabled` removes the control from the tab order; `readOnly` keeps it focusable but inert.
* `aria-invalid` on the trigger is bridged to `data-invalid` so the error state styles with or without a wrapping `Field`.
* Popup enter/exit transitions are skipped when the user prefers reduced motion.


# Separator (/ui/components/react/separator)



<Playground component="separator" />

## Usage [#usage]

```tsx
import { Separator } from '@appica/ui-react/separator'
```

```tsx
<Separator />
```

`Separator` draws a single line between sections of related content. It's `horizontal` by default —
a full-width rule — and becomes a vertical divider with `orientation="vertical"`, stretching to the
height of its flex parent. The `variant` prop swaps the line style, from a plain `solid` rule to
decorative `wave` and `zigzag` patterns.

It renders with `role="separator"` so assistive tech announces the boundary. When a separator is
purely cosmetic (the `gradient`, `wave`, `zigzag`, and `dotted` patterns are drawn as decoration),
pass nothing else — the component already keeps it out of the way of screen readers where appropriate.

## Examples [#examples]

### Variants [#variants]

Seven line styles cover everything from a crisp hairline to playful decorative patterns. `solid`,
`dashed`, `dotted`, `double`, and `gradient` are CSS borders; `wave` and `zigzag` are drawn as a
repeating SVG path that scales with the available width.

```tsx
import { Separator } from '@appica/ui-react/separator'

const variants = ['solid', 'dashed', 'dotted', 'double', 'gradient', 'wave', 'zigzag'] as const

export default function SeparatorVariants() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-5">
      {variants.map((variant) => (
        <div key={variant} className="flex flex-col gap-2">
          <span className="text-sm capitalize">{variant}</span>
          <Separator variant={variant} />
        </div>
      ))}
    </div>
  )
}
```

### Colors [#colors]

The line is drawn with `currentColor`, so its color follows the current text color — set any
`text-*` utility on the separator (or an ancestor) to recolor it. The default is the low-emphasis
`text-border` token; reach for the stronger `text-border-strong` / `text-border-intense` shades for
more contrast, or a semantic color like `text-primary`, `text-success`, or `text-error` to tie the
divider to its surrounding state.

```tsx
import { Separator } from '@appica/ui-react/separator'

const colors = [
  { label: 'text-border (default)', className: 'text-border' },
  { label: 'text-border-strong', className: 'text-border-strong' },
  { label: 'text-border-intense', className: 'text-border-intense' },
  { label: 'text-primary', className: 'text-primary' },
  { label: 'text-secondary', className: 'text-secondary' },
  { label: 'text-error', className: 'text-error' },
  { label: 'text-success', className: 'text-success' },
  { label: 'text-warning', className: 'text-warning' },
  { label: 'text-info', className: 'text-info' },
] as const

export default function SeparatorColors() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-5">
      {colors.map(({ label, className }) => (
        <div key={className} className="flex flex-col gap-2">
          <span className="text-sm">{label}</span>
          <Separator className={className} />
        </div>
      ))}
    </div>
  )
}
```

### Vertical orientation [#vertical-orientation]

Set `orientation="vertical"` to divide inline items like toolbar actions or breadcrumb-style links.
The separator stretches to match its flex row, so give the row a height (or let its content define
one).

```tsx
import { Separator } from '@appica/ui-react/separator'

export default function SeparatorOrientation() {
  return (
    <div className="text-foreground flex h-5 items-center gap-4 text-sm">
      <span>Profile</span>
      <Separator orientation="vertical" />
      <span>Settings</span>
      <Separator orientation="vertical" />
      <span>Sign out</span>
    </div>
  )
}
```

### In context [#in-context]

Separators work in both directions within the same block — a horizontal rule between stacked
sections, and vertical rules between inline stats.

```tsx
import { Separator } from '@appica/ui-react/separator'

export default function SeparatorInContent() {
  return (
    <div className="border-border w-full max-w-sm rounded-xl border p-5">
      <div className="flex flex-col gap-1">
        <h3 className="text-foreground-intense font-medium">Mia Carter</h3>
        <p className="text-foreground-muted text-sm">Product designer based in Lisbon.</p>
      </div>
      <Separator className="my-4" />
      <div className="flex justify-between text-sm">
        <div>
          <span className="font-semibold">248</span> posts
        </div>
        <Separator orientation="vertical" className="mx-2.5" />
        <div>
          <span className="font-semibold">12.4k</span> followers
        </div>
        <Separator orientation="vertical" className="mx-2.5" />
        <div>
          <span className="font-semibold">312</span> following
        </div>
      </div>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a
container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your
tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

A horizontal separator looks the same in either direction, but the items it sits between reorder to
follow the resolved direction, so vertical dividers land in the right place automatically. For setup
details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="separator" />

## API reference [#api-reference]

`Separator` wraps [Base UI's Separator](https://base-ui.com/react/components/separator) and forwards `ref` and every remaining `<div>` attribute. It exposes `data-orientation` (`horizontal` / `vertical`) for styling.

| Prop          | <ColMinWidth width="200">Type</ColMinWidth>                                                  | Default        | <ColMinWidth width="220">Description</ColMinWidth>                            |
| ------------- | -------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------- |
| `orientation` | <Code>'horizontal' \| 'vertical'</Code>                                                      | `'horizontal'` | Direction of the line. Vertical separators stretch to their flex parent.      |
| `variant`     | <Code>'solid' \| 'dashed' \| 'dotted' \| 'double' \| 'gradient' \| 'wave' \| 'zigzag'</Code> | `'solid'`      | Line style. `gradient`, `wave`, `zigzag`, and `dotted` are decorative.        |
| `render`      | <Code>ReactElement \| ((props, state) => ReactElement)</Code>                                | —              | Replace the rendered element, or compose it with another component.           |
| `className`   | `string`                                                                                     | —              | Extra classes, merged via `tailwind-merge`. Set `text-*` to recolor the line. |
| `style`       | `CSSProperties`                                                                              | —              | Inline styles on the rendered element.                                        |

## Accessibility [#accessibility]

* Renders with `role="separator"` and an `aria-orientation` matching the `orientation` prop, so
  assistive tech announces the boundary between groups.
* Pick a color with enough contrast against its background for the divider to stay perceivable — see
  [Colors](#colors). The default `text-border` token is intentionally low-emphasis.
* A separator is non-interactive and is skipped by keyboard navigation.


# Skeleton (/ui/components/react/skeleton)



<Playground component="skeleton" />

## Usage [#usage]

```tsx
import { Skeleton } from '@appica/ui-react/skeleton'
```

```tsx
<Skeleton className="h-4 w-40" />
```

`Skeleton` is a low-level placeholder block. It has no fixed size — you give it dimensions with ordinary utility classes (`h-*`/`w-*`/`size-*`) — and a gentle default `rounded-md` you can reshape with any `rounded-*` (`rounded-full` for a dot, `rounded-[inherit]` to match a parent's shape, or `rounded-none` to square it off). This keeps it composable: build a line, a circle, an avatar, or a whole card preview by stacking `Skeleton`s, and they all inherit your design tokens automatically.

Its surface and shimmer highlight are both derived from `currentColor`, so a single `text-*` class recolors the whole placeholder coherently — the shimmer always matches the surface. By default it's a subtle tint of your foreground token.

Pick the animation with the `effect` prop — `shimmer` (default) glides a soft highlight across the block, `pulse` fades it in and out, and `none` renders a static placeholder. Both animations are skipped when the user prefers reduced motion.

## Examples [#examples]

### Default [#default]

A single `Skeleton` with a height, width, and radius. The default `shimmer` effect glides a highlight derived from your foreground token, so it reads on both light and dark surfaces.

```tsx
import { Skeleton } from '@appica/ui-react/skeleton'

export default function SkeletonDefault() {
  return <Skeleton className="h-28 w-64 rounded-xl" />
}
```

### Effects [#effects]

Switch the animation with `effect`. `shimmer` glides a highlight across the block, `pulse` fades the whole block, and `none` stays static — useful when you want the placeholder without motion.

```tsx
import { Skeleton } from '@appica/ui-react/skeleton'

export default function SkeletonEffects() {
  return (
    <div className="flex flex-wrap items-start justify-center gap-10">
      <div className="flex flex-col items-center gap-3">
        <Skeleton effect="shimmer" className="h-24 w-40 rounded-xl" />
        <span className="text-foreground-muted text-xs">shimmer</span>
      </div>
      <div className="flex flex-col items-center gap-3">
        <Skeleton effect="pulse" className="h-24 w-40 rounded-xl" />
        <span className="text-foreground-muted text-xs">pulse</span>
      </div>
      <div className="flex flex-col items-center gap-3">
        <Skeleton effect="none" className="h-24 w-40 rounded-xl" />
        <span className="text-foreground-muted text-xs">none</span>
      </div>
    </div>
  )
}
```

### Composing shapes [#composing-shapes]

There are no shape props. Reshape the same primitive with utility classes — `rounded-full` for an avatar, `size-*` for a square, a small `h-*`/`w-*` for a line.

```tsx
import { Skeleton } from '@appica/ui-react/skeleton'

export default function SkeletonShapes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-6">
      <Skeleton className="size-16 rounded-full" />
      <Skeleton className="size-16 rounded-xl" />
      <Skeleton className="h-10 w-32 rounded-lg" />
      <Skeleton className="h-4 w-40 rounded-full" />
    </div>
  )
}
```

### Text lines [#text-lines]

Stack a few full-width lines and taper the last ones with fractional widths (`w-4/5`, `w-2/3`) to mimic a paragraph.

```tsx
import { Skeleton } from '@appica/ui-react/skeleton'

export default function SkeletonText() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-2.5">
      <Skeleton className="h-4 w-full" />
      <Skeleton className="h-4 w-full" />
      <Skeleton className="h-4 w-4/5" />
      <Skeleton className="h-4 w-2/3" />
    </div>
  )
}
```

### Card [#card]

Compose placeholders into the layout you're loading — a media block, an avatar, and two text lines — so the skeleton matches the real content's footprint and there's no layout shift when it arrives.

```tsx
import { Skeleton } from '@appica/ui-react/skeleton'

export default function SkeletonCard() {
  return (
    <div className="border-border bg-background w-full max-w-sm rounded-xl border p-4">
      <Skeleton className="aspect-video w-full rounded-lg" />
      <div className="mt-4 flex items-center gap-3">
        <Skeleton className="size-10 shrink-0 rounded-full" />
        <div className="flex flex-1 flex-col gap-2">
          <Skeleton className="h-3.5 w-2/3" />
          <Skeleton className="h-3 w-1/3" />
        </div>
      </div>
    </div>
  )
}
```

### Recoloring [#recoloring]

Surface and shimmer both come from `currentColor`, so one `text-*` class tints the whole placeholder and keeps the shimmer in sync with the surface. For a shimmer color independent of the surface, set the `--skeleton-highlight` custom property directly.

```tsx
import { Skeleton } from '@appica/ui-react/skeleton'

export default function SkeletonColors() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-4">
      <Skeleton className="size-16 rounded-xl" />
      <Skeleton className="text-primary size-16 rounded-xl" />
      <Skeleton className="text-secondary-emphasis size-16 rounded-xl" />
      <Skeleton className="text-error-emphasis size-16 rounded-xl" />
      <Skeleton className="text-success-emphasis size-16 rounded-xl" />
      <Skeleton className="text-warning-emphasis size-16 rounded-xl" />
      <Skeleton className="text-info-emphasis size-16 rounded-xl" />
      <Skeleton className="size-16 rounded-xl text-violet-500" />
    </div>
  )
}
```

### Swapping in content [#swapping-in-content]

Render skeletons while content is pending, then swap them for the real elements once it arrives. Here the avatar uses its built-in [`AvatarFallback`](/ui/components/react/avatar) to show a `Skeleton` until the photo loads, and `onLoadingStatusChange` reveals the name and role at the same moment — hit **Reload** to fetch a fresh copy and replay it. Matching each skeleton to its element's size keeps the layout stable across the transition.

```tsx
'use client'

import { useState, useEffect } from 'react'
import { Skeleton } from '@appica/ui-react/skeleton'
import { Button } from '@appica/ui-react/button'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { Reload } from '@appica/icons-react'

export default function SkeletonLoading() {
  const [src, setSrc] = useState<string>()
  const [loaded, setLoaded] = useState(false)
  const [nonce, setNonce] = useState(0)

  useEffect(() => {
    setLoaded(false)
    setSrc(undefined)
    // Demo only: defer the image ~2.5s so the loading skeletons stay visible.
    const id = setTimeout(() => setSrc(`/avatars/01.jpg?reload=${nonce}`), 2500)
    return () => clearTimeout(id)
  }, [nonce])

  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <div className="flex justify-end">
        <Button size="sm" variant="outline" onClick={() => setNonce((n) => n + 1)} disabled={!loaded}>
          <Reload data-icon="start" />
          Reload
        </Button>
      </div>

      <div className="border-border bg-background flex items-center gap-3 rounded-xl border p-4">
        <Avatar size="lg" className="shrink-0 bg-transparent">
          <AvatarImage
            src={src}
            alt="Sarah Jenkins"
            onLoadingStatusChange={(status) => setLoaded(status === 'loaded')}
          />
          <AvatarFallback>
            <Skeleton className="size-full rounded-[inherit]" />
          </AvatarFallback>
        </Avatar>
        <div className="flex flex-1 flex-col gap-1.5">
          {loaded ? (
            <>
              <span className="text-foreground-intense -mb-0.5 text-sm font-semibold">Sarah Jenkins</span>
              <span className="text-foreground-muted text-xs">Product designer</span>
            </>
          ) : (
            <>
              <Skeleton className="h-4 w-2/3" />
              <Skeleton className="h-3 w-2/5" />
            </>
          )}
        </div>
      </div>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

Because skeletons are positioned with the same logical layout utilities as the content they stand in for, a placeholder card mirrors automatically — the avatar moves to the start (right) edge and the text lines follow. The `shimmer` sweep also reverses to travel right-to-left, following the reading direction.

<RtlPreview component="skeleton" />

## API reference [#api-reference]

`Skeleton` renders a `<div>`. Every other `<div>` attribute is forwarded, so `className`, `style`, and data attributes all pass straight through.

| Prop        | <ColMinWidth width="200">Type</ColMinWidth> | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                                               |
| ----------- | ------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `effect`    | <Code>'shimmer' \| 'pulse' \| 'none'</Code> | `'shimmer'` | Animation played while the placeholder is visible. All effects honor `prefers-reduced-motion`.                   |
| `className` | `string`                                    | —           | Shape, color, and radius. A `text-*` class recolors surface + shimmer; `rounded-*`/`size-*`/`h-*`/`w-*` reshape. |

The surface is `currentColor` at low opacity and the shimmer highlight is derived from `currentColor` too, so a single `text-*` class recolors both in step. The shimmer is also exposed as the `--skeleton-highlight` CSS custom property — set it on the element (e.g. `[--skeleton-highlight:var(--primary)]`) to retune the shimmer color independently of the surface.

## Accessibility [#accessibility]

* A `Skeleton` is decorative — it renders with `aria-hidden="true"` so screen readers skip the placeholder geometry rather than announcing empty boxes.
* For a loading region, announce the pending state on the **container**, not each block: set `aria-busy="true"` while data loads, and consider a polite live region (`role="status"`) that reveals the content once it arrives.
* Keep the skeleton's footprint close to the real content's so swapping it in causes no layout shift — a jump on load is its own accessibility problem.
* All animations stop under `prefers-reduced-motion: reduce` (and the library's `data-disable-animations` escape hatch), leaving a static placeholder.


# Slider (/ui/components/react/slider)



<Playground component="slider" />

## Usage [#usage]

```tsx
import { Slider } from '@appica/ui-react/slider'
```

```tsx
<Slider defaultValue={50} thumbAriaLabel="Volume" />
```

`Slider` renders the track, fill, and thumb(s) for you — you don't compose parts. The number of thumbs follows the value: a single `number` renders one thumb, an array renders one per entry (a range). Use it uncontrolled with `defaultValue`, or controlled with `value` + `onValueChange`.

A thumb has no visible text, so give it a name with `thumbAriaLabel` (a string, or a `(index) => string` function for ranges). By default a tooltip shows the current value while a thumb is hovered, focused, or dragged.

## Examples [#examples]

### Range [#range]

Pass an array `defaultValue` (or `value`) to get one thumb per entry. The fill spans between them. `thumbAriaLabel` can be a function of the thumb index to name each end.

```tsx
'use client'

import { Slider } from '@appica/ui-react/slider'

export default function SliderRange() {
  return (
    <Slider className="max-w-70" defaultValue={[25, 75]} thumbAriaLabel={(i) => (i === 0 ? 'Minimum' : 'Maximum')} />
  )
}
```

### Steps [#steps]

`step` sets the granularity; `min` and `max` set the bounds. Arrow keys move by `step`, **Shift**/**Page Up·Down** by `largeStep`.

```tsx
import { Slider } from '@appica/ui-react/slider'

export default function SliderSteps() {
  return (
    <Slider
      className="max-w-70"
      defaultValue={40}
      min={0}
      max={100}
      step={10}
      tooltipVisibility="always"
      thumbAriaLabel="Amount"
    />
  )
}
```

### Tooltip visibility [#tooltip-visibility]

`tooltipVisibility` controls the value bubble: `auto` (default — on hover/focus/drag), `always` (pinned), or `never`.

```tsx
import { Slider } from '@appica/ui-react/slider'

export default function SliderTooltip() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-8">
      <Slider defaultValue={30} tooltipVisibility="auto" thumbAriaLabel="Auto" />
      <Slider defaultValue={50} tooltipVisibility="always" thumbAriaLabel="Always" />
      <Slider defaultValue={70} tooltipVisibility="never" thumbAriaLabel="Never" />
    </div>
  )
}
```

### Vertical [#vertical]

Pass `orientation="vertical"` to lay the slider out top-to-bottom (it fills its container's height, with a sensible minimum). Works for single and range sliders.

```tsx
'use client'

import { Slider } from '@appica/ui-react/slider'

export default function SliderVertical() {
  return (
    <div className="flex h-48 items-center gap-10">
      <Slider orientation="vertical" defaultValue={60} thumbAriaLabel="Volume" />
      <Slider orientation="vertical" defaultValue={[20, 80]} thumbAriaLabel={(i) => (i === 0 ? 'Min' : 'Max')} />
    </div>
  )
}
```

### Controlled [#controlled]

Drive the value with `value` + `onValueChange` to react to every move. Here three sliders compose an RGB picker, each channel feeding a live color swatch.

```tsx
'use client'

import { useState } from 'react'
import { Slider } from '@appica/ui-react/slider'

const CHANNELS = [
  { key: 'r', label: 'R' },
  { key: 'g', label: 'G' },
  { key: 'b', label: 'B' },
] as const

export default function SliderControlled() {
  const [rgb, setRgb] = useState({ r: 99, g: 102, b: 241 })
  const color = `#${[rgb.r, rgb.g, rgb.b].map((c) => c.toString(16).padStart(2, '0')).join('')}`

  return (
    <div className="flex w-full max-w-90 items-center gap-6">
      <div className="flex w-full max-w-64 flex-col gap-4">
        {CHANNELS.map(({ key, label }) => (
          <div key={key} className="flex items-center gap-3">
            <span className="text-foreground-muted w-3 text-sm font-medium">{label}</span>
            <Slider
              className="flex-1"
              value={rgb[key]}
              onValueChange={(value) => setRgb((prev) => ({ ...prev, [key]: value as number }))}
              min={0}
              max={255}
              tooltipVisibility="never"
              thumbAriaLabel={`${label} channel`}
            />
            <span className="text-foreground-muted w-8 text-end text-sm tabular-nums">{rgb[key]}</span>
          </div>
        ))}
      </div>
      <div className="flex shrink-0 flex-col items-center gap-2">
        <div className="border-border-muted size-20 rounded-lg border" style={{ backgroundColor: color }} aria-hidden />
        <span className="text-foreground-muted font-mono text-xs uppercase">{color}</span>
      </div>
    </div>
  )
}
```

### Disabled [#disabled]

`disabled` dims the slider and blocks interaction.

```tsx
import { Slider } from '@appica/ui-react/slider'

export default function SliderDisabled() {
  return <Slider className="max-w-70" defaultValue={50} disabled thumbAriaLabel="Disabled" />
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The track fills from the end edge (right) and the arrow keys that increase the value flip with the direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="slider" />

## API reference [#api-reference]

The `tooltipVisibility` and `thumbAriaLabel` props are Appica additions; every other prop is forwarded to [Base UI's Slider.Root](https://base-ui.com/react/components/slider).

| Prop                    | <ColMinWidth width="200">Type</ColMinWidth>        | Default        | <ColMinWidth width="220">Description</ColMinWidth>                 |
| ----------------------- | -------------------------------------------------- | -------------- | ------------------------------------------------------------------ |
| `tooltipVisibility`     | <Code>'auto' \| 'always' \| 'never'</Code>         | `'auto'`       | When the value tooltip shows — on interaction, always, or never.   |
| `thumbAriaLabel`        | <Code>string \| ((index: number) => string)</Code> | —              | Accessible name for each thumb. Use a function to name range ends. |
| `value`                 | <Code>number \| number\[]</Code>                   | —              | Controlled value (array = range). Pair with `onValueChange`.       |
| `defaultValue`          | <Code>number \| number\[]</Code>                   | —              | Uncontrolled initial value; its shape sets the number of thumbs.   |
| `onValueChange`         | <Code>(value, details) => void</Code>              | —              | Fires as the value changes (drag, keyboard).                       |
| `onValueCommitted`      | <Code>(value, details) => void</Code>              | —              | Fires when the change is finalized (pointer up / blur).            |
| `min`                   | `number`                                           | `0`            | Minimum value.                                                     |
| `max`                   | `number`                                           | `100`          | Maximum value.                                                     |
| `step`                  | `number`                                           | `1`            | Stepping granularity.                                              |
| `largeStep`             | `number`                                           | `10`           | Step for **Shift**+Arrow / **Page Up·Down**.                       |
| `minStepsBetweenValues` | `number`                                           | `0`            | Minimum gap (in steps) between range thumbs.                       |
| `orientation`           | <Code>'horizontal' \| 'vertical'</Code>            | `'horizontal'` | Layout direction.                                                  |
| `disabled`              | `boolean`                                          | `false`        | Disables interaction and dims the slider.                          |
| `name`                  | `string`                                           | —              | Field name submitted with a form.                                  |
| `format`                | `Intl.NumberFormatOptions`                         | —              | Formats the tooltip/value display (currency, percent, …).          |
| `className`             | <Code>string \| ((state) => string)</Code>         | —              | Extra classes on the root, merged via `tailwind-merge`.            |

`Slider` wraps Base UI's `Slider` (`Root`, `Control`, `Track`, `Indicator`, `Thumb`, `Value`) and forwards every remaining `Root` prop. It exposes `data-*` state attributes (`data-orientation`, `data-disabled`, `data-dragging`, …) on the root and its parts for styling.

## Accessibility [#accessibility]

* Each thumb is a `role="slider"` with `aria-valuenow`/`aria-valuemin`/`aria-valuemax`. Give it a name via `thumbAriaLabel`, or an external label associated with the control.
* Keyboard: &#x2A;*←/→*&#x2A; (or &#x2A;*↑/↓**) move by `step`, **Shift**+arrow and **Page Up·Down** move by `largeStep`, **Home/End** jump to min/max.
* `disabled` blocks interaction and exposes `data-disabled` for styling.
* The tooltip and thumb-scale animations honour `prefers-reduced-motion`.


# Sparkline (/ui/components/react/sparkline)



<Playground component="sparkline" />

## Usage [#usage]

```tsx
import { Sparkline, SparklineChart, SparklineValue, SparklineLabel } from '@appica/ui-react/sparkline'
```

```tsx
<Sparkline data={[8, 14, 10, 18, 15, 22, 19, 27]}>
  <SparklineChart variant="area" />
</Sparkline>
```

A `Sparkline` distills a series into a small, word-sized chart — the trend behind a KPI, a row in a table, a card header. Pass the numbers to the root's `data`; `SparklineChart` draws them. It comes in three layouts via `variant`: `line`, `area` (solid-filled to a baseline), and `column` (bars). A plain `line` can also take a decorative gradient `fill` down to the chart's edge.

The root holds the data and the hover state and hands them to the parts, so the optional `SparklineValue` and `SparklineLabel` can sit anywhere inside — a headline above the chart, say — and update as the pointer moves. Recolor everything through a single `color` prop, and read the hovered point from `onActiveChange` to render it wherever you like.

## Examples [#examples]

### Line [#line]

The default. A crisp stroke with a hover indicator that snaps to the nearest point. The stroke stays sharp at any width because it doesn't scale with the chart.

```tsx
import { Sparkline, SparklineChart } from '@appica/ui-react/sparkline'

export default function SparklineDefault() {
  return (
    <Sparkline data={[8, 14, 10, 18, 15, 22, 19, 27, 24, 31]} className="w-64 max-w-full">
      <SparklineChart aria-label="Trend over the last 10 periods" />
    </Sparkline>
  )
}
```

### Area [#area]

`variant="area"` is a conventional area chart: it's always filled with a solid tint between the curve and a **baseline** (`0` by default). Values below the baseline fill *below* it — as in the second chart — so it reads as a signed magnitude, not just a trend. Move the reference line with `baseline`.

```tsx
import { Sparkline, SparklineChart } from '@appica/ui-react/sparkline'

export default function SparklineArea() {
  return (
    <div className="flex w-64 max-w-full flex-col gap-6">
      <Sparkline data={[6, 11, 8, 16, 13, 22, 18, 27]}>
        <SparklineChart variant="area" height={56} aria-label="Signups over 8 weeks" />
      </Sparkline>
      <Sparkline data={[3, -4, 2, 6, -2, -6, 4, 1]}>
        <SparklineChart variant="area" height={56} aria-label="Net change over 8 weeks" />
      </Sparkline>
    </div>
  )
}
```

### Filled line [#filled-line]

A plain `line` is stroke-only. Add `fill` for a gradient that fades from the line down to the chart's bottom edge — the familiar "filled trend line" without a semantic baseline. This is the right choice for values far from zero, like a revenue KPI, where a true area chart would collapse into a solid block. (For a solid, baseline-anchored fill, use `variant="area"` instead.)

```tsx
import { Sparkline, SparklineChart } from '@appica/ui-react/sparkline'

const DATA = [12, 19, 15, 24, 20, 28, 25, 33]

export default function SparklineFill() {
  return (
    <div className="flex w-64 max-w-full flex-col gap-6">
      <Sparkline data={DATA}>
        <SparklineChart height={56} aria-label="Line" />
      </Sparkline>
      <Sparkline data={DATA}>
        <SparklineChart fill height={56} aria-label="Gradient-filled line" />
      </Sparkline>
    </div>
  )
}
```

### Columns [#columns]

`variant="column"` renders bars, one per value, that pivot on a **baseline** (`0` by default): values above it grow up, values below grow *down* — the standard signed bar sparkline, as in the second chart. Hovering highlights the active column. Best for discrete buckets — visits per day, net change per period. Move the pivot with `baseline`.

```tsx
import { Sparkline, SparklineChart } from '@appica/ui-react/sparkline'

const DAYS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun', 'Mon']

export default function SparklineColumn() {
  return (
    <div className="flex w-64 max-w-full flex-col gap-6">
      <Sparkline data={[4, 9, 6, 12, 8, 15, 11, 18]} labels={DAYS}>
        <SparklineChart variant="column" height={56} tooltip aria-label="Daily visits" />
      </Sparkline>
      <Sparkline data={[6, -7, 9, -4, 8, -9, 5, -6]} labels={DAYS}>
        <SparklineChart variant="column" height={56} tooltip aria-label="Net change per day" />
      </Sparkline>
    </div>
  )
}
```

### Line smoothing [#line-smoothing]

`curve` controls how round the line is, from `0` (straight segments between points) to `1` (fully smoothed peaks). It applies to `line` and `area`.

```tsx
import { Sparkline, SparklineChart } from '@appica/ui-react/sparkline'

const DATA = [10, 24, 12, 28, 16, 30, 14, 26]

export default function SparklineCurve() {
  return (
    <div className="flex w-64 max-w-full flex-col gap-6">
      <Sparkline data={DATA}>
        <SparklineChart curve={0} aria-label="Straight segments" />
      </Sparkline>
      <Sparkline data={DATA}>
        <SparklineChart curve={1} aria-label="Fully smoothed" />
      </Sparkline>
    </div>
  )
}
```

### Line weight [#line-weight]

`strokeWidth` sets the line thickness in pixels (default `2`). The stroke never scales with the chart, so it stays exactly this weight at any width.

```tsx
import { Sparkline, SparklineChart } from '@appica/ui-react/sparkline'

const DATA = [10, 24, 12, 28, 16, 30, 14, 26]

export default function SparklineStroke() {
  return (
    <div className="flex w-64 max-w-full flex-col gap-6">
      <Sparkline data={DATA}>
        <SparklineChart strokeWidth={1} aria-label="Thin line" />
      </Sparkline>
      <Sparkline data={DATA}>
        <SparklineChart strokeWidth={3} aria-label="Thick line" />
      </Sparkline>
    </div>
  )
}
```

### Tooltip [#tooltip]

Set `tooltip` to float the value at the hovered point. When the root has `labels`, the tooltip shows the matching label alongside the value; `format` controls the number's presentation.

```tsx
import { Sparkline, SparklineChart } from '@appica/ui-react/sparkline'

export default function SparklineTooltip() {
  return (
    <Sparkline
      data={[8, 15, 11, 20, 16, 26, 22]}
      labels={['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']}
      className="w-72 max-w-full"
    >
      <SparklineChart variant="area" height={56} tooltip aria-label="Weekly requests" />
    </Sparkline>
  )
}
```

### Value headline [#value-headline]

Drop `SparklineValue` and `SparklineLabel` inside the root to print the active point — or, when nothing is hovered, the last one. Combined with `format`, this is the classic "big number over a trend" stat. Since the values sit far from zero, this uses a gradient-**filled line** rather than an area chart. Hover the chart and the headline follows.

```tsx
import { Sparkline, SparklineChart, SparklineValue, SparklineLabel } from '@appica/ui-react/sparkline'

export default function SparklineStat() {
  return (
    <Sparkline
      data={[198_120, 201_540, 199_880, 205_300, 208_770, 214_260, 222_240]}
      labels={['Nov 11', 'Nov 12', 'Nov 13', 'Nov 14', 'Nov 15', 'Nov 16', 'Nov 17']}
      className="w-72 max-w-full"
    >
      <SparklineLabel />
      <SparklineValue className="text-2xl" />
      <SparklineChart fill height={56} tooltip aria-label="Active users this week" />
    </Sparkline>
  )
}
```

### Reacting to the active point [#reacting-to-the-active-point]

For full control over where the reading appears, pass `onActiveChange`. It fires with the hovered `{ index, value, label }` (or `null` on leave), so you can render the value anywhere — outside the chart, in a sibling panel, wherever.

```tsx
'use client'

import { useState } from 'react'
import { Sparkline, SparklineChart } from '@appica/ui-react/sparkline'
import type { SparklinePoint } from '@appica/ui-react/sparkline'

const DATA = [820, 932, 901, 934, 1290, 1330, 1320]
const LABELS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']

export default function SparklineControlled() {
  const [active, setActive] = useState<SparklinePoint | null>(null)
  const point = active ?? { index: DATA.length - 1, value: DATA[DATA.length - 1]!, label: LABELS[DATA.length - 1] }

  return (
    <div className="w-72 max-w-full">
      <div className="mb-1 flex items-baseline justify-between">
        <span className="text-foreground-muted text-sm">{point.label}</span>
        <span className="text-foreground-intense text-lg font-semibold tabular-nums">
          {point.value.toLocaleString()}
        </span>
      </div>
      <Sparkline data={DATA} labels={LABELS} onActiveChange={setActive}>
        <SparklineChart height={48} aria-label="Weekly requests" />
      </Sparkline>
    </div>
  )
}
```

### Custom colors [#custom-colors]

`color` accepts any CSS color and drives the line, fill, indicator, and tooltip swatch. Reach for a theme token — `var(--success-emphasis)`, `var(--error-emphasis)` — so it tracks light and dark mode, or pass a raw value like `#a855f7` for a one-off.

```tsx
import { Sparkline, SparklineChart } from '@appica/ui-react/sparkline'

export default function SparklineColors() {
  return (
    <div className="flex w-64 max-w-full flex-col gap-5">
      <Sparkline data={[6, 12, 9, 16, 14, 22, 20, 28]} color="var(--success-emphasis)">
        <SparklineChart variant="area" aria-label="Revenue" />
      </Sparkline>
      <Sparkline data={[28, 22, 25, 16, 19, 12, 14, 8]} color="var(--error-emphasis)">
        <SparklineChart variant="area" aria-label="Churn" />
      </Sparkline>
      <Sparkline data={[10, 14, 11, 15, 13, 18, 15, 19]} color="var(--warning-emphasis)">
        <SparklineChart aria-label="Latency" />
      </Sparkline>
      <Sparkline data={[8, 16, 12, 22, 18, 26, 24, 32]} color="#a855f7">
        <SparklineChart fill aria-label="Engagement" />
      </Sparkline>
      <Sparkline data={[5, 11, 8, 14, 10, 18, 13, 21]} color="var(--info-emphasis)">
        <SparklineChart variant="column" aria-label="Orders" />
      </Sparkline>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

Under RTL the plot mirrors horizontally — the series reads right-to-left, columns stack from the right, and the hover mapping flips to match. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="sparkline" />

## API reference [#api-reference]

`Sparkline` is a compound component. The root owns the data, formatting, and hover state; `SparklineChart` draws the visualization; `SparklineValue` and `SparklineLabel` print the active-or-last point. Each part forwards `ref` and its remaining native attributes to the underlying element.

### Sparkline [#sparkline]

The root and provider. Renders a `<div>` that lays its children out in a column, and exposes the accent color as the `--sparkline-color` CSS variable.

| Prop             | <ColMinWidth width="220">Type</ColMinWidth>          | Default          | <ColMinWidth width="240">Description</ColMinWidth>                              |
| ---------------- | ---------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------- |
| `data`           | `number[]`                                           | —                | **Required.** The series to plot.                                               |
| `labels`         | `string[]`                                           | —                | Per-point labels (e.g. dates), surfaced in the tooltip and to `SparklineLabel`. |
| `color`          | `string`                                             | `var(--primary)` | Accent for the line, fill, indicator, and tooltip swatch. Any CSS color.        |
| `format`         | `Intl.NumberFormatOptions`                           | —                | Formatting for displayed values (`SparklineValue`, tooltip).                    |
| `locale`         | `Intl.LocalesArgument`                               | —                | Locale used by `Intl.NumberFormat`.                                             |
| `onActiveChange` | <Code>(point: SparklinePoint \| null) => void</Code> | —                | Fires when the hovered point changes; `null` on pointer leave.                  |
| `className`      | `string`                                             | —                | Extra classes, merged via `tailwind-merge`.                                     |

### SparklineChart [#sparklinechart]

The visualization. Renders a `<div role="img">` wrapping an SVG (line/area) or bars (column), plus the hover indicator and tooltip overlays.

| Prop            | <ColMinWidth width="220">Type</ColMinWidth>       | Default             | <ColMinWidth width="240">Description</ColMinWidth>                                            |
| --------------- | ------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------- |
| `variant`       | `'line' \| 'area' \| 'column'`                    | `'line'`            | The layout.                                                                                   |
| `curve`         | `number`                                          | `0.5`               | Line smoothing from `0` (straight) to `1` (fully rounded). Line/area only.                    |
| `fill`          | `boolean`                                         | `false`             | **`line` only.** Add a gradient fill from the line to the bottom edge. Area is always filled. |
| `baseline`      | `number`                                          | `0`                 | The pivot the fill/bars grow from; values below it render below. Area and column.             |
| `height`        | `number`                                          | `48`                | Chart height, in pixels.                                                                      |
| `strokeWidth`   | `number`                                          | `2`                 | Line thickness, in pixels. Line/area only.                                                    |
| `indicator`     | `boolean`                                         | `true`              | Show the hover indicator (dot + guide, or the active-column highlight).                       |
| `tooltip`       | `boolean`                                         | `false`             | Float a tooltip at the hovered point.                                                         |
| `renderTooltip` | <Code>(point: SparklinePoint) => ReactNode</Code> | —                   | Render custom tooltip content instead of the default swatch + value. Implies `tooltip`.       |
| `aria-label`    | `string`                                          | `'{variant} chart'` | Accessible name for the graphic. Describe the trend for screen-reader users.                  |
| `className`     | `string`                                          | —                   | Extra classes on the wrapper, merged via `tailwind-merge`.                                    |

### SparklineValue [#sparklinevalue]

Prints the hovered point's value — or the last point's when nothing is hovered — formatted with the root's `format`/`locale`. Renders a `<span>`.

| Prop        | <ColMinWidth width="220">Type</ColMinWidth>                  | Default | <ColMinWidth width="240">Description</ColMinWidth>                          |
| ----------- | ------------------------------------------------------------ | ------- | --------------------------------------------------------------------------- |
| `children`  | <Code>(formatted: string, value: number) => ReactNode</Code> | —       | Render function to fully customize the displayed text. Omit for the number. |
| `className` | `string`                                                     | —       | Extra classes, merged via `tailwind-merge`.                                 |

### SparklineLabel [#sparklinelabel]

Prints the hovered (or last) point's label from the root's `labels`. Renders nothing when no `labels` are provided. Renders a `<span>`.

| Prop        | <ColMinWidth width="220">Type</ColMinWidth>                      | Default | <ColMinWidth width="240">Description</ColMinWidth>                       |
| ----------- | ---------------------------------------------------------------- | ------- | ------------------------------------------------------------------------ |
| `children`  | <Code>(label: string, point: SparklinePoint) => ReactNode</Code> | —       | Render function to customize the displayed text. Omit for the raw label. |
| `className` | `string`                                                         | —       | Extra classes, merged via `tailwind-merge`.                              |

### SparklinePoint [#sparklinepoint]

The shape passed to `onActiveChange` and the render-function children.

| Field   | Type     | Description                                  |
| ------- | -------- | -------------------------------------------- |
| `index` | `number` | Index of the point in `data`.                |
| `value` | `number` | The point's numeric value.                   |
| `label` | `string` | The point's label, if `labels` was provided. |

## Accessibility [#accessibility]

* `SparklineChart` renders with `role="img"` and an `aria-label` (defaulting to `"{variant} chart"`). Because a sparkline is a graphic, &#x2A;*pass a descriptive `aria-label`** that summarizes the trend — e.g. `"Revenue, up 40% over 7 days"` — so screen-reader users get the meaning, not just the shape.
* The indicator and tooltip are pointer affordances layered with `pointer-events-none` and marked `aria-hidden`; they never trap focus or intercept clicks. When a value needs to be readable, surface it as text via `SparklineValue` or `onActiveChange`.
* The indicator, tooltip, and column heights animate only under `motion-safe`, so they stay still when the user prefers reduced motion.


# Spinner (/ui/components/react/spinner)



<Playground component="spinner" />

## Usage [#usage]

```tsx
import { Spinner } from '@appica/ui-react/spinner'
```

```tsx
<Spinner />
```

`Spinner` is a small, self-contained loading indicator that animates forever — use it whenever something is happening and you can't show progress. It comes in three shapes via `variant`: `circular` (the default sweep), `dots` (a ring of fading ticks), and `sparkle` (a morphing four-point star).

Two things make it drop into anything: it's **sized by font-size**, so set a `text-*` class (or inherit `1em` from a parent) to scale it, and `currentColor` makes it take the surrounding text color instead of the primary accent — which is exactly what you want inside a colored button. It renders a `role="status"` element with an `aria-label` of "Loading".

Reach for `Spinner` for compact, in-place waits — a button, an icon button, a small overlay. For a wider "this section is loading" indicator that reads more like progress, use [`Loader`](/ui/components/react/loader).

## Examples [#examples]

### Variants [#variants]

Three shapes for different personalities: `circular`, `dots`, and `sparkle`. All animate indefinitely and honour `prefers-reduced-motion` (they hold a static frame instead of spinning).

```tsx
import { Spinner } from '@appica/ui-react/spinner'

const VARIANTS = ['circular', 'dots', 'sparkle'] as const

export default function SpinnerVariants() {
  return (
    <div className="flex items-center gap-10">
      {VARIANTS.map((variant) => (
        <div key={variant} className="flex flex-col items-center gap-3">
          <Spinner variant={variant} />
          <span className="text-foreground-muted text-xs">{variant}</span>
        </div>
      ))}
    </div>
  )
}
```

### Sizing [#sizing]

The spinner is sized by `font-size`, so a `text-*` utility scales the whole thing — no `size` prop. Drop one next to text with no class and it inherits `1em`, matching the line.

```tsx
import { Spinner } from '@appica/ui-react/spinner'

export default function SpinnerSizing() {
  return (
    <div className="flex items-end gap-8">
      <Spinner className="text-xl" />
      <Spinner className="text-3xl" />
      <Spinner className="text-5xl" />
      <Spinner className="text-7xl" />
    </div>
  )
}
```

### Color [#color]

By default the spinner uses the primary accent. Add `currentColor` and it inherits the surrounding text color instead — ideal on colored surfaces or to match a status color.

```tsx
import { Spinner } from '@appica/ui-react/spinner'

export default function SpinnerColor() {
  return (
    <div className="flex items-center gap-8 text-4xl">
      <Spinner />
      <span className="text-violet-500">
        <Spinner currentColor />
      </span>
      <span className="text-success-emphasis">
        <Spinner currentColor />
      </span>
      <span className="text-error-emphasis">
        <Spinner currentColor />
      </span>
    </div>
  )
}
```

### In a button [#in-a-button]

The most common use: a submit button that shows a spinner while the action runs. Set `currentColor` so it matches the button's text, size it with `text-[1.2em]` so it scales with the button, and disable the button while loading. The second button pairs the `sparkle` variant with a [`Gradient Glow`](/ui/components/react/gradient-glow) for an "Ask AI" affordance that lights up while it thinks.

```tsx
'use client'

import * as React from 'react'
import { Button, buttonVariants } from '@appica/ui-react/button'
import { Spinner } from '@appica/ui-react/spinner'
import { GradientGlow } from '@appica/ui-react/gradient-glow'
import { Sparkle } from '@appica/icons-react'
import { cn } from '@/lib/utils'

export default function SpinnerButton() {
  const [saving, setSaving] = React.useState(false)
  const [thinking, setThinking] = React.useState(false)
  const saveTimer = React.useRef<ReturnType<typeof setTimeout> | null>(null)
  const askTimer = React.useRef<ReturnType<typeof setTimeout> | null>(null)

  const save = () => {
    if (saveTimer.current) clearTimeout(saveTimer.current)
    setSaving(true)
    saveTimer.current = setTimeout(() => setSaving(false), 1800)
  }

  const ask = () => {
    if (askTimer.current) clearTimeout(askTimer.current)
    setThinking(true)
    askTimer.current = setTimeout(() => setThinking(false), 5000)
  }

  return (
    <div className="flex flex-wrap items-center justify-center gap-4">
      <Button onClick={save} disabled={saving} className="min-w-34">
        {saving && <Spinner currentColor className="text-[1.2em]" />}
        {saving ? 'Saving…' : 'Save changes'}
      </Button>

      <GradientGlow reveal={thinking} border blur="md" speed={3} className="rounded-full">
        <button
          type="button"
          onClick={ask}
          className={cn(buttonVariants({ variant: 'outline', size: 'md' }), 'rounded-full')}
        >
          {thinking ? (
            <Spinner variant="sparkle" currentColor data-icon="start" className="text-lg" />
          ) : (
            <Sparkle data-icon="start" />
          )}
          {thinking ? 'Thinking…' : 'Ask AI'}
        </button>
      </GradientGlow>
    </div>
  )
}
```

### Refresh button [#refresh-button]

In an icon button, swap the icon for a spinner while the action is in flight — the button keeps its size, so the layout never jumps.

```tsx
'use client'

import * as React from 'react'
import { Button } from '@appica/ui-react/button'
import { Spinner } from '@appica/ui-react/spinner'
import { Refresh } from '@appica/icons-react'

export default function SpinnerRefresh() {
  const [loading, setLoading] = React.useState(false)

  const refresh = () => {
    setLoading(true)
    setTimeout(() => setLoading(false), 1500)
  }

  return (
    <Button variant="outline" size="icon-md" aria-label="Refresh data" disabled={loading} onClick={refresh}>
      {loading ? <Spinner variant="dots" currentColor className="text-[1.25em]" /> : <Refresh />}
    </Button>
  )
}
```

### Loading a panel [#loading-a-panel]

Drive a region's loading state from your own state: show a centred spinner while fetching, then swap in the content. Here a status card reloads on demand.

```tsx
'use client'

import * as React from 'react'
import { Button } from '@appica/ui-react/button'
import { Spinner } from '@appica/ui-react/spinner'
import { Refresh } from '@appica/icons-react'

export default function SpinnerPanel() {
  const [loading, setLoading] = React.useState(true)

  const reload = React.useCallback(() => {
    setLoading(true)
    const timer = setTimeout(() => setLoading(false), 1600)
    return () => clearTimeout(timer)
  }, [])

  React.useEffect(() => reload(), [reload])

  return (
    <div className="border-border bg-background w-72 rounded-xl border p-5">
      {loading ? (
        <div className="flex h-28 items-center justify-center">
          <Spinner variant="circular" className="text-4xl" />
        </div>
      ) : (
        <div className="flex h-28 flex-col justify-between">
          <div>
            <p className="text-foreground-intense font-semibold">Production</p>
            <p className="text-success-emphasis text-sm">All systems operational</p>
            <p className="text-foreground-muted mt-1 text-xs">Synced just now</p>
          </div>
          <Button variant="soft" size="sm" className="self-start" onClick={reload}>
            <Refresh data-icon="start" />
            Reload
          </Button>
        </div>
      )}
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The spinner itself is direction-agnostic; inside a button it simply leads the label, which sits on the correct side under RTL. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="spinner" />

## API reference [#api-reference]

`Spinner` renders a single `<span role="status">` and forwards `ref`, `className`, and any other span attributes.

| Prop           | <ColMinWidth width="210">Type</ColMinWidth>    | Default      | <ColMinWidth width="240">Description</ColMinWidth>                                                          |
| -------------- | ---------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------- |
| `variant`      | <Code>'circular' \| 'dots' \| 'sparkle'</Code> | `'circular'` | The animated shape.                                                                                         |
| `currentColor` | `boolean`                                      | `false`      | Inherit the surrounding text color (`currentColor`) instead of the primary accent.                          |
| `aria-label`   | `string`                                       | `'Loading'`  | Accessible name for the `role="status"` region.                                                             |
| `className`    | `string`                                       | —            | Extra classes, merged via `tailwind-merge`. Set a `text-*` size here — the spinner scales with `font-size`. |

## Accessibility [#accessibility]

* The spinner is a `role="status"` live region with a default `aria-label="Loading"`; give it a more specific label (e.g. "Saving") when the context warrants it.
* Inside a button, the button's own text ("Saving…") is the accessible name — the spinner just reinforces it visually.
* A purely decorative spinner that sits beside text already conveying the state can be hidden from assistive tech with `aria-hidden`.
* The animation is replaced by a static frame when the user prefers reduced motion.


# Switch (/ui/components/react/switch)



<Playground component="switch" />

## Usage [#usage]

```tsx
import { Switch } from '@appica/ui-react/switch'
```

```tsx
<label className="flex items-center gap-2.5">
  <Switch defaultChecked />
  Airplane mode
</label>
```

`Switch` renders only the toggle — it has no text of its own. Wrap it and its label in a single `<label>` so clicking either flips the switch and assistive tech announces them together; no `id`/`htmlFor` wiring needed. Use it uncontrolled with `defaultChecked`, or controlled with `checked` + `onCheckedChange`.

Reach for a switch when the change takes effect immediately (a setting that's on or off). For a value submitted later with a form — accepting terms, picking items — use a [`Checkbox`](/ui/components/react/checkbox) instead. The thumb slide and check animation are skipped when the user prefers reduced motion.

## Examples [#examples]

### Sizes [#sizes]

`size` scales the track and thumb together — `sm`, `md` (default), or `lg`.

```tsx
import { Switch } from '@appica/ui-react/switch'

export default function SwitchSizes() {
  return (
    <div className="flex flex-wrap items-center gap-6 text-sm select-none">
      <label className="flex items-center gap-2 text-xs">
        <Switch size="sm" defaultChecked />
        Small
      </label>
      <label className="flex items-center gap-2.5">
        <Switch size="md" defaultChecked />
        Medium
      </label>
      <label className="flex items-center gap-2.5 text-base">
        <Switch size="lg" defaultChecked />
        Large
      </label>
    </div>
  )
}
```

### States [#states]

A switch is off or on, and either state can also be `disabled`. Bridging `aria-invalid` paints the error state — useful for a required toggle that hasn't been accepted.

```tsx
import { Switch } from '@appica/ui-react/switch'

export default function SwitchStates() {
  return (
    <div className="flex flex-wrap items-center gap-6 text-sm select-none">
      <label className="flex items-center gap-2.5">
        <Switch />
        Off
      </label>
      <label className="flex items-center gap-2.5">
        <Switch defaultChecked />
        On
      </label>
      <label className="text-foreground-muted flex items-center gap-2.5">
        <Switch disabled />
        Disabled
      </label>
      <label className="text-foreground-muted flex items-center gap-2.5">
        <Switch disabled defaultChecked />
        Disabled on
      </label>
      <label className="flex items-center gap-2.5">
        <Switch aria-invalid />
        Error
      </label>
    </div>
  )
}
```

### With a label and description [#with-a-label-and-description]

A typical settings row: a title and supporting text beside the toggle. Keeping it all inside one `<label>` makes the whole row a single target.

```tsx
import { Switch } from '@appica/ui-react/switch'

export default function SwitchWithLabel() {
  return (
    <label className="border-border flex max-w-sm items-center justify-between gap-4 rounded-xl border p-5 select-none">
      <span className="flex flex-col">
        <span className="text-foreground-intense font-medium">Marketing emails</span>
        <span className="text-foreground-muted text-sm">Receive tips, product updates, and occasional offers.</span>
      </span>
      <Switch defaultChecked />
    </label>
  )
}
```

### Controlled [#controlled]

Drive the state yourself with `checked` + `onCheckedChange` to react to every toggle.

```tsx
'use client'

import { useState } from 'react'
import { Switch } from '@appica/ui-react/switch'

export default function SwitchControlled() {
  const [checked, setChecked] = useState(true)
  return (
    <label className="text-foreground flex items-center gap-2.5 text-sm select-none">
      <Switch checked={checked} onCheckedChange={setChecked} />
      Wi-Fi is {checked ? 'on' : 'off'}
    </label>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The thumb slides toward the start edge instead of the end, following the resolved direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="switch" />

## API reference [#api-reference]

`Switch` wraps [Base UI's Switch](https://base-ui.com/react/components/switch) and passes every remaining prop (`ref`, `aria-*`, and native `<button>` attributes) straight through. It exposes `data-*` state attributes (`data-checked`, `data-unchecked`, `data-disabled`, `data-readonly`, `data-invalid`, …) for styling — see the Base UI docs for the full surface.

| Prop              | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>                                   |
| ----------------- | ------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `size`            | <Code>'sm' \| 'md' \| 'lg'</Code>                             | `'md'`  | Scales the track and thumb together.                                                 |
| `checked`         | `boolean`                                                     | —       | Controlled on/off state. Pair with `onCheckedChange`.                                |
| `defaultChecked`  | `boolean`                                                     | `false` | Uncontrolled initial state.                                                          |
| `onCheckedChange` | <Code>(checked: boolean, details) => void</Code>              | —       | Fires when the switch is flipped on or off.                                          |
| `name`            | `string`                                                      | —       | Field name submitted with a form.                                                    |
| `value`           | `string`                                                      | —       | Value submitted with the form when the switch is on.                                 |
| `uncheckedValue`  | `string`                                                      | —       | Value submitted with the form when the switch is off.                                |
| `form`            | `string`                                                      | —       | `id` of the form that owns the hidden input, when it isn't a descendant.             |
| `disabled`        | `boolean`                                                     | `false` | Removes the switch from the tab order and ignores interaction.                       |
| `readOnly`        | `boolean`                                                     | `false` | Focusable but not toggleable.                                                        |
| `required`        | `boolean`                                                     | `false` | Must be on before its form submits.                                                  |
| `aria-invalid`    | <Code>boolean \| 'true' \| 'false'</Code>                     | —       | Marks the error state; mirrored to `data-invalid` for styling.                       |
| `nativeButton`    | `boolean`                                                     | `false` | Whether the element passed to `render` is a native `<button>`.                       |
| `inputRef`        | <Code>Ref\<HTMLInputElement></Code>                           | —       | Ref to the hidden `<input>` element backing the switch.                              |
| `id`              | `string`                                                      | —       | `id` of the rendered element.                                                        |
| `render`          | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the rendered element, or compose it with another component.                  |
| `className`       | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes on the track, merged via `tailwind-merge`. May be a function of state. |
| `style`           | <Code>CSSProperties \| ((state) => CSSProperties)</Code>      | —       | Inline styles, optionally derived from state.                                        |

## Accessibility [#accessibility]

* Renders with `role="switch"`. **Space** (or **Enter**) toggles it; **Tab** moves focus to and from it.
* A switch needs an accessible name — wrap it in a `<label>` together with its text (as shown above), or give it an `aria-label`.
* `disabled` removes the switch from the tab order and exposes `data-disabled` for styling; `readOnly` keeps it focusable but inert.
* `aria-invalid` is bridged to `data-invalid` so the error state can be styled without a wrapping `Field`.
* The thumb slide and check animation honour `prefers-reduced-motion`.


# Table (/ui/components/react/table)



<Playground component="table" />

## Usage [#usage]

```tsx
import { Table, TableCaption, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'
```

```tsx
<Table>
  <TableCaption>Recent transactions</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead>Date</TableHead>
      <TableHead className="text-end">Amount</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Aug 30</TableCell>
      <TableCell className="text-end">+ $4,150.00</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

`Table` is a thin, styled layer over the native table elements — it keeps the real `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, and `<td>` semantics and just adds the surface, spacing, rounded corners, and optional striping/hover. All parts live under `@appica/ui-react/table`:

* **`Table`** — the `<table>` root. Owns `size`, `borderStyle`, and the `stripedRows` / `stripedColumns` / `hoverableRows` toggles.
* **`TableHeader`*&#x2A; / &#x2A;*`TableBody`** — `<thead>` / `<tbody>` wrappers. The header gets a tinted bar; the body holds the data rows.
* **`TableRow`** — a `<tr>`. Mark one `highlighted` to call it out.
* **`TableHead`** — a `<th>` header cell (start-aligned by default).
* **`TableCell`** — a `<td>` data cell.
* **`TableCaption`** — a `<caption>` that sits above or below the table via `position`.

The rounded corners are applied automatically to the right cells, so you don't manage them by hand. Per-cell alignment (e.g. right-aligned amounts) is just a `text-end` utility on the relevant `TableHead`/`TableCell`.

## Examples [#examples]

### Default [#default]

Header, body, a caption, and a right-aligned amount column. The outer border, header bar, and corner rounding come for free.

```tsx
import { Table, TableCaption, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'

const rows = [
  { date: 'Aug 30', description: 'Salary', amount: '+ $4,150.00' },
  { date: 'Aug 24', description: 'Netflix', amount: '- $20.00' },
  { date: 'Aug 17', description: 'Electricity', amount: '- $186.35' },
  { date: 'Aug 12', description: 'Grocery store', amount: '- $74.20' },
]

export default function TableDefault() {
  return (
    <Table>
      <TableCaption>Recent transactions</TableCaption>
      <TableHeader>
        <TableRow>
          <TableHead>Date</TableHead>
          <TableHead>Description</TableHead>
          <TableHead className="text-end">Amount</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {rows.map((row) => (
          <TableRow key={row.description}>
            <TableCell>{row.date}</TableCell>
            <TableCell className="text-foreground-strong font-medium">{row.description}</TableCell>
            <TableCell className="text-end tabular-nums">{row.amount}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  )
}
```

### Sizes [#sizes]

`size` scales the cell padding, corner radius, and text together — `sm`, `md` (default), or `lg`.

```tsx
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'

const sizes = ['sm', 'md', 'lg'] as const

const rows = [
  { name: 'Starter', seats: '1–3', price: '$0' },
  { name: 'Team', seats: 'Up to 20', price: '$12' },
]

export default function TableSizes() {
  return (
    <div className="flex w-full flex-col gap-8">
      {sizes.map((size) => (
        <div key={size} className="flex flex-col gap-2">
          <span className="text-foreground-muted text-xs font-medium">size=&quot;{size}&quot;</span>
          <Table size={size}>
            <TableHeader>
              <TableRow>
                <TableHead>Plan</TableHead>
                <TableHead>Seats</TableHead>
                <TableHead className="text-end">Per month</TableHead>
              </TableRow>
            </TableHeader>
            <TableBody>
              {rows.map((row) => (
                <TableRow key={row.name}>
                  <TableCell className="text-foreground-strong font-medium">{row.name}</TableCell>
                  <TableCell>{row.seats}</TableCell>
                  <TableCell className="text-end tabular-nums">{row.price}</TableCell>
                </TableRow>
              ))}
            </TableBody>
          </Table>
        </div>
      ))}
    </div>
  )
}
```

### Striped [#striped]

`stripedRows` tints alternating rows for easier horizontal scanning; `stripedColumns` does the same down the columns. Use whichever fits the data — or neither.

```tsx
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'

const rows = [
  { region: 'North America', q3: '$48.2k', q4: '$52.9k' },
  { region: 'Europe', q3: '$31.7k', q4: '$36.4k' },
  { region: 'Asia Pacific', q3: '$22.1k', q4: '$28.8k' },
  { region: 'Latin America', q3: '$9.4k', q4: '$11.2k' },
]

export default function TableStriped() {
  return (
    <div className="flex w-full flex-col gap-8">
      <div className="flex flex-col gap-2">
        <span className="text-foreground-muted text-xs font-medium">stripedRows</span>
        <Table stripedRows>
          <TableHeader>
            <TableRow>
              <TableHead>Region</TableHead>
              <TableHead className="text-end">Q3</TableHead>
              <TableHead className="text-end">Q4</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {rows.map((row) => (
              <TableRow key={row.region}>
                <TableCell className="text-foreground-strong font-medium">{row.region}</TableCell>
                <TableCell className="text-end tabular-nums">{row.q3}</TableCell>
                <TableCell className="text-end tabular-nums">{row.q4}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </Table>
      </div>

      <div className="flex flex-col gap-2">
        <span className="text-foreground-muted text-xs font-medium">stripedColumns</span>
        <Table stripedColumns>
          <TableHeader>
            <TableRow>
              <TableHead>Region</TableHead>
              <TableHead className="text-end">Q3</TableHead>
              <TableHead className="text-end">Q4</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {rows.map((row) => (
              <TableRow key={row.region}>
                <TableCell className="text-foreground-strong font-medium">{row.region}</TableCell>
                <TableCell className="text-end tabular-nums">{row.q3}</TableCell>
                <TableCell className="text-end tabular-nums">{row.q4}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </Table>
      </div>
    </div>
  )
}
```

### Hoverable rows [#hoverable-rows]

`hoverableRows` tints a row as the pointer passes over it — handy when each row is a target you'll click or act on.

```tsx
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'

const rows = [
  { file: 'annual-report.pdf', size: '2.4 MB', modified: 'Aug 30' },
  { file: 'budget-2025.xlsx', size: '845 KB', modified: 'Aug 28' },
  { file: 'logo-final.svg', size: '12 KB', modified: 'Aug 21' },
  { file: 'roadmap.key', size: '6.1 MB', modified: 'Aug 14' },
]

export default function TableHoverable() {
  return (
    <Table hoverableRows>
      <TableHeader>
        <TableRow>
          <TableHead>File</TableHead>
          <TableHead>Size</TableHead>
          <TableHead>Modified</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {rows.map((row) => (
          <TableRow key={row.file}>
            <TableCell className="text-foreground-strong font-medium">{row.file}</TableCell>
            <TableCell className="tabular-nums">{row.size}</TableCell>
            <TableCell>{row.modified}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  )
}
```

### Border styles [#border-styles]

`borderStyle` switches the cell separators: `solid` (default), `dashed`, or `none` for a borderless, airy look.

```tsx
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'

const styles = ['solid', 'dashed', 'none'] as const

const rows = [
  { name: 'Sarah Jenkins', role: 'Engineer' },
  { name: 'Daniel Reyes', role: 'Designer' },
  { name: 'Mateo Rossi', role: 'Researcher' },
]

export default function TableBorderStyles() {
  return (
    <div className="flex w-full flex-col gap-8">
      {styles.map((borderStyle) => (
        <div key={borderStyle} className="flex flex-col gap-2">
          <span className="text-foreground-muted text-xs font-medium">borderStyle=&quot;{borderStyle}&quot;</span>
          <Table borderStyle={borderStyle}>
            <TableHeader>
              <TableRow>
                <TableHead>Name</TableHead>
                <TableHead>Role</TableHead>
              </TableRow>
            </TableHeader>
            <TableBody>
              {rows.map((row) => (
                <TableRow key={row.name}>
                  <TableCell className="text-foreground-strong font-medium">{row.name}</TableCell>
                  <TableCell>{row.role}</TableCell>
                </TableRow>
              ))}
            </TableBody>
          </Table>
        </div>
      ))}
    </div>
  )
}
```

### Highlighted row [#highlighted-row]

Mark a `TableRow` as `highlighted` to single it out — a selected row, the current plan, or a flagged entry. It keeps its background through striping and hover.

```tsx
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'

const plans = [
  { name: 'Starter', seats: '1–3', price: '$0', current: false },
  { name: 'Team', seats: 'Up to 20', price: '$12', current: true },
  { name: 'Business', seats: 'Up to 100', price: '$29', current: false },
  { name: 'Enterprise', seats: 'Unlimited', price: 'Custom', current: false },
]

export default function TableHighlighted() {
  return (
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead>Plan</TableHead>
          <TableHead>Seats</TableHead>
          <TableHead className="text-end">Per month</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {plans.map((plan) => (
          <TableRow key={plan.name} highlighted={plan.current}>
            <TableCell className="text-foreground-strong font-medium">{plan.name}</TableCell>
            <TableCell>{plan.seats}</TableCell>
            <TableCell className="text-end tabular-nums">{plan.price}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  )
}
```

### Rich content [#rich-content]

Cells take any content, so compose them with other components — an [`Avatar`](/ui/components/react/avatar) and stacked text in one cell, a [`Badge`](/ui/components/react/badge) for status in another — and pull the caption to the top with `position="top"`.

```tsx
import { Table, TableCaption, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { Badge } from '@appica/ui-react/badge'

const members = [
  { src: '/avatars/01.jpg', name: 'Sarah Jenkins', email: 'sarah@appica.dev', role: 'Owner', status: 'Active' },
  { src: '/avatars/02.jpg', name: 'Daniel Reyes', email: 'daniel@appica.dev', role: 'Editor', status: 'Active' },
  { src: '/avatars/03.jpg', name: 'Mateo Rossi', email: 'mateo@appica.dev', role: 'Viewer', status: 'Invited' },
] as const

const statusVariant = {
  Active: 'success',
  Invited: 'warning',
} as const

export default function TableRichContent() {
  return (
    <Table hoverableRows>
      <TableCaption position="top" className="text-foreground-intense text-start font-medium">
        Workspace members
      </TableCaption>
      <TableHeader>
        <TableRow>
          <TableHead>Member</TableHead>
          <TableHead>Role</TableHead>
          <TableHead className="text-end">Status</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {members.map((member) => (
          <TableRow key={member.email}>
            <TableCell>
              <div className="flex items-center gap-3">
                <Avatar size="sm">
                  <AvatarImage src={member.src} alt={member.name} />
                  <AvatarFallback>
                    {member.name
                      .split(' ')
                      .map((part) => part[0])
                      .join('')}
                  </AvatarFallback>
                </Avatar>
                <div className="flex flex-col">
                  <span className="text-foreground-emphasis font-medium">{member.name}</span>
                  <span className="text-xs">{member.email}</span>
                </div>
              </div>
            </TableCell>
            <TableCell>{member.role}</TableCell>
            <TableCell className="text-end">
              <Badge variant={statusVariant[member.status]} size="sm">
                {member.status}
              </Badge>
            </TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  )
}
```

### Scrollable [#scrollable]

For a long table, wrap it in a [`ScrollArea`](/ui/components/react/scroll-area) with a fixed height. Pin the header to the top of the viewport with `[&>thead>tr>th]:sticky [&>thead>tr>th]:top-0` so the columns stay labelled while the rows scroll.

```tsx
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'
import { ScrollArea } from '@appica/ui-react/scroll-area'

const rows = [
  { date: 'Aug 30', description: 'Salary', amount: '+ $4,150.00' },
  { date: 'Aug 28', description: 'Spotify', amount: '- $11.99' },
  { date: 'Aug 24', description: 'Netflix', amount: '- $20.00' },
  { date: 'Aug 22', description: 'Freelance invoice', amount: '+ $1,200.00' },
  { date: 'Aug 19', description: 'Coffee roasters', amount: '- $18.40' },
  { date: 'Aug 17', description: 'Electricity', amount: '- $186.35' },
  { date: 'Aug 14', description: 'Gym membership', amount: '- $39.00' },
  { date: 'Aug 12', description: 'Grocery store', amount: '- $74.20' },
  { date: 'Aug 09', description: 'Refund — returns', amount: '+ $52.10' },
  { date: 'Aug 06', description: 'Phone bill', amount: '- $45.00' },
  { date: 'Aug 03', description: 'Bookshop', amount: '- $28.75' },
  { date: 'Aug 01', description: 'Rent', amount: '- $1,650.00' },
]

export default function TableScrollable() {
  return (
    <ScrollArea className="border-border-muted h-75 w-full max-w-md rounded-lg border p-2">
      <Table className="border-0 p-0 [&>thead>tr>th]:sticky [&>thead>tr>th]:top-0">
        <TableHeader>
          <TableRow>
            <TableHead>Date</TableHead>
            <TableHead>Description</TableHead>
            <TableHead className="text-end">Amount</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {rows.map((row) => (
            <TableRow key={row.description}>
              <TableCell>{row.date}</TableCell>
              <TableCell className="text-foreground-strong font-medium">{row.description}</TableCell>
              <TableCell className="text-end tabular-nums">{row.amount}</TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </ScrollArea>
  )
}
```

### Horizontal scroll [#horizontal-scroll]

When a table has more columns than will fit, wrap it in a horizontal `ScrollArea` and keep the cells from wrapping with `whitespace-nowrap`. The columns scroll sideways instead of cramping.

```tsx
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@appica/ui-react/table'
import { ScrollArea } from '@appica/ui-react/scroll-area'

const rows = [
  {
    name: 'Sarah Jenkins',
    email: 'sarah@appica.dev',
    role: 'Owner',
    team: 'Product',
    location: 'San Francisco',
    joined: 'Jan 2021',
  },
  {
    name: 'Daniel Reyes',
    email: 'daniel@appica.dev',
    role: 'Editor',
    team: 'Engineering',
    location: 'Austin',
    joined: 'Mar 2022',
  },
  {
    name: 'Mateo Rossi',
    email: 'mateo@appica.dev',
    role: 'Viewer',
    team: 'Design',
    location: 'Milan',
    joined: 'Jul 2022',
  },
  {
    name: 'Amara Okafor',
    email: 'amara@appica.dev',
    role: 'Editor',
    team: 'Marketing',
    location: 'Lagos',
    joined: 'Nov 2023',
  },
  {
    name: 'Noah Patel',
    email: 'noah@appica.dev',
    role: 'Viewer',
    team: 'Support',
    location: 'Toronto',
    joined: 'Feb 2024',
  },
]

export default function TableWide() {
  return (
    <ScrollArea orientation="horizontal" className="w-full max-w-md">
      <Table className="whitespace-nowrap">
        <TableHeader>
          <TableRow>
            <TableHead>Name</TableHead>
            <TableHead>Email</TableHead>
            <TableHead>Role</TableHead>
            <TableHead>Team</TableHead>
            <TableHead>Location</TableHead>
            <TableHead>Joined</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {rows.map((row) => (
            <TableRow key={row.email}>
              <TableCell className="text-foreground-strong font-medium">{row.name}</TableCell>
              <TableCell>{row.email}</TableCell>
              <TableCell>{row.role}</TableCell>
              <TableCell>{row.team}</TableCell>
              <TableCell>{row.location}</TableCell>
              <TableCell>{row.joined}</TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </ScrollArea>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

Columns lay out from the right, the rounded corners mirror to the correct sides, and a `text-end` amount column moves to the left edge — all because the styling uses logical properties. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="table" />

## API reference [#api-reference]

`Table` and its parts are styled native table elements — they're not Base UI primitives. Each forwards `ref` and every remaining attribute to its underlying element, so standard table attributes (`colSpan`, `scope`, …) work as usual.

### Table [#table]

The `<table>` root. Owns the surface, sizing, and row/column treatments.

| Prop             | <ColMinWidth width="190">Type</ColMinWidth> | Default   | <ColMinWidth width="230">Description</ColMinWidth> |
| ---------------- | ------------------------------------------- | --------- | -------------------------------------------------- |
| `size`           | <Code>'sm' \| 'md' \| 'lg'</Code>           | `'md'`    | Cell padding, corner radius, and text scale.       |
| `borderStyle`    | <Code>'solid' \| 'dashed' \| 'none'</Code>  | `'solid'` | Style of the cell separators.                      |
| `stripedRows`    | `boolean`                                   | `false`   | Tint alternating rows.                             |
| `stripedColumns` | `boolean`                                   | `false`   | Tint alternating columns.                          |
| `hoverableRows`  | `boolean`                                   | `false`   | Tint a row on pointer hover.                       |
| `className`      | `string`                                    | —         | Extra classes, merged via `tailwind-merge`.        |

### TableCaption [#tablecaption]

A `<caption>` describing the table. Placed above or below.

| Prop        | <ColMinWidth width="190">Type</ColMinWidth> | Default    | <ColMinWidth width="230">Description</ColMinWidth> |
| ----------- | ------------------------------------------- | ---------- | -------------------------------------------------- |
| `position`  | <Code>'top' \| 'bottom'</Code>              | `'bottom'` | Render the caption above or below the table.       |
| `className` | `string`                                    | —          | Extra classes, merged via `tailwind-merge`.        |

### TableRow [#tablerow]

A `<tr>`. Use `highlighted` to call out a single row.

| Prop          | <ColMinWidth width="190">Type</ColMinWidth> | Default | <ColMinWidth width="230">Description</ColMinWidth>              |
| ------------- | ------------------------------------------- | ------- | --------------------------------------------------------------- |
| `highlighted` | `boolean`                                   | `false` | Apply the persistent highlight background (`data-highlighted`). |
| `className`   | `string`                                    | —       | Extra classes, merged via `tailwind-merge`.                     |

### TableHeader, TableBody, TableHead, TableCell [#tableheader-tablebody-tablehead-tablecell]

Thin wrappers over `<thead>`, `<tbody>`, `<th>`, and `<td>`. They take their native attributes plus `className` (merged via `tailwind-merge`). `TableHead` is start-aligned by default — add `text-end` (or `text-center`) for other alignments.

## Accessibility [#accessibility]

* The component renders real table semantics — `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>` — so screen readers announce rows, columns, and headers natively.
* Use `TableHead` for header cells, and add `scope="col"` (or `scope="row"` for a row header) when the relationship isn't obvious, so assistive tech maps each data cell to its header.
* A `TableCaption` gives the table an accessible name; keep it even when it's visually subtle.
* `highlighted` is a visual cue only — if the highlighted row carries meaning (e.g. "current plan"), convey that in text as well, not by color alone.
* Row hover and the highlight are background-only changes that don't affect the reading order or content.


# Tabs (/ui/components/react/tabs)



<Playground component="tabs" />

## Usage [#usage]

```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@appica/ui-react/tabs'
```

```tsx
<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">A snapshot of your workspace.</TabsContent>
  <TabsContent value="activity">Every change, newest first.</TabsContent>
  <TabsContent value="settings">Workspace name and integrations.</TabsContent>
</Tabs>
```

`Tabs` lets a single region host several panels and shows one at a time. Each `TabsTrigger` is matched to a `TabsContent` by its `value`; selecting a trigger reveals its panel and slides the active indicator across the list. Drive it uncontrolled with `defaultValue`, or controlled with `value` + `onValueChange`.

The visual style is set once on the root and flows down through context: `variant` (`pill` or `line`), `size` (`sm`/`md`/`lg`), and `orientation` (`horizontal` or `vertical`). Override any single part by passing the same prop directly to a `TabsList` or `TabsTrigger`.

Reach for `Tabs` to switch between **alternate views of the same area**. For navigating between pages or routes, use [`Navigation`](/ui/components/react/navigation) or a [`Breadcrumb`](/ui/components/react/breadcrumb) instead — tabs are for in-place content, not page navigation.

## Examples [#examples]

### Default [#default]

The `pill` variant: a filled track with a sliding white pill behind the active tab. Set the starting tab with `defaultValue` and pair every `TabsTrigger` with a `TabsContent` of the same `value`.

```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@appica/ui-react/tabs'

export default function TabsDefault() {
  return (
    <Tabs defaultValue="overview" className="w-full max-w-md">
      <TabsList>
        <TabsTrigger value="overview">Overview</TabsTrigger>
        <TabsTrigger value="activity">Activity</TabsTrigger>
        <TabsTrigger value="settings">Settings</TabsTrigger>
      </TabsList>
      <TabsContent value="overview" className="text-foreground-muted text-sm">
        A snapshot of your workspace — recent files, members, and usage.
      </TabsContent>
      <TabsContent value="activity" className="text-foreground-muted text-sm">
        Every change, comment, and deploy across the team, newest first.
      </TabsContent>
      <TabsContent value="settings" className="text-foreground-muted text-sm">
        Manage the workspace name, visibility, and connected integrations.
      </TabsContent>
    </Tabs>
  )
}
```

### Variants [#variants]

`pill` rides on a filled track; `line` drops the track for a minimal underline that slides under the active tab. Pick `line` for dense layouts or when the tabs sit directly above their content.

```tsx
import { Tabs, TabsList, TabsTrigger } from '@appica/ui-react/tabs'

export default function TabsVariants() {
  return (
    <div className="flex w-full max-w-md flex-col gap-8">
      <Tabs defaultValue="overview" variant="pill">
        <TabsList>
          <TabsTrigger value="overview">Overview</TabsTrigger>
          <TabsTrigger value="activity">Activity</TabsTrigger>
          <TabsTrigger value="settings">Settings</TabsTrigger>
        </TabsList>
      </Tabs>
      <Tabs defaultValue="overview" variant="line">
        <TabsList>
          <TabsTrigger value="overview">Overview</TabsTrigger>
          <TabsTrigger value="activity">Activity</TabsTrigger>
          <TabsTrigger value="settings">Settings</TabsTrigger>
        </TabsList>
      </Tabs>
    </div>
  )
}
```

### Sizes [#sizes]

Three sizes scale the triggers' padding and text together: `sm`, `md` (default), and `lg`. Set `size` on the root and it flows to every trigger.

```tsx
import { Tabs, TabsList, TabsTrigger } from '@appica/ui-react/tabs'

export default function TabsSizes() {
  return (
    <div className="flex flex-col items-center gap-6">
      {(['sm', 'md', 'lg'] as const).map((size) => (
        <Tabs key={size} defaultValue="overview" size={size}>
          <TabsList>
            <TabsTrigger value="overview">Overview</TabsTrigger>
            <TabsTrigger value="activity">Activity</TabsTrigger>
            <TabsTrigger value="settings">Settings</TabsTrigger>
          </TabsList>
        </Tabs>
      ))}
    </div>
  )
}
```

### Vertical [#vertical]

Set `orientation="vertical"` to stack the triggers in a column beside their panels — handy for settings screens. The arrow keys follow the axis (↑/↓), and the active indicator runs vertically.

```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@appica/ui-react/tabs'

export default function TabsVertical() {
  return (
    <Tabs defaultValue="general" orientation="vertical" className="w-full max-w-md">
      <TabsList>
        <TabsTrigger value="general">General</TabsTrigger>
        <TabsTrigger value="members">Members</TabsTrigger>
        <TabsTrigger value="billing">Billing</TabsTrigger>
      </TabsList>
      <TabsContent value="general" className="text-foreground-muted text-sm">
        Workspace name, URL slug, and default language.
      </TabsContent>
      <TabsContent value="members" className="text-foreground-muted text-sm">
        Invite teammates and manage their roles and permissions.
      </TabsContent>
      <TabsContent value="billing" className="text-foreground-muted text-sm">
        Your current plan, invoices, and payment method.
      </TabsContent>
    </Tabs>
  )
}
```

### With icons & badges [#with-icons--badges]

Drop an [icon](/ui/icons) marked `data-icon="start"` before a trigger's label and it's sized and spaced automatically. The `data-icon` attribute also tells the trigger to tighten its padding on that side. Triggers accept any children, so a trailing [`Badge`](/ui/components/react/badge) — say a count — sits inline after the label.

```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@appica/ui-react/tabs'
import { Badge } from '@appica/ui-react/badge'
import { LayoutGrid, Activity, Settings } from '@appica/icons-react'

export default function TabsIcons() {
  return (
    <Tabs defaultValue="overview" className="w-full max-w-md">
      <div className="scrollbar-none overflow-x-auto [&::-webkit-scrollbar]:hidden">
        <TabsList>
          <TabsTrigger value="overview">
            <LayoutGrid data-icon="start" />
            Overview
          </TabsTrigger>
          <TabsTrigger value="activity">
            <Activity data-icon="start" />
            Activity
            <Badge variant="outline" size="sm">
              12
            </Badge>
          </TabsTrigger>
          <TabsTrigger value="settings">
            <Settings data-icon="start" />
            Settings
          </TabsTrigger>
        </TabsList>
      </div>
      <TabsContent value="overview" className="text-foreground-muted text-sm">
        A snapshot of your workspace at a glance.
      </TabsContent>
      <TabsContent value="activity" className="text-foreground-muted text-sm">
        Every change across the team, newest first.
      </TabsContent>
      <TabsContent value="settings" className="text-foreground-muted text-sm">
        Workspace name, visibility, and integrations.
      </TabsContent>
    </Tabs>
  )
}
```

### Icon-only [#icon-only]

Give each trigger an `icon-*` size (`icon-sm`/`icon-md`/`icon-lg`) for square, label-less tabs — a compact view switcher, for instance. Pass an `aria-label` so each tab still has an accessible name.

```tsx
import { Tabs, TabsList, TabsTrigger } from '@appica/ui-react/tabs'
import { LayoutGrid, List, ChartBar } from '@appica/icons-react'

export default function TabsIconOnly() {
  return (
    <Tabs defaultValue="grid">
      <TabsList>
        <TabsTrigger value="grid" size="icon-md" aria-label="Grid view">
          <LayoutGrid />
        </TabsTrigger>
        <TabsTrigger value="list" size="icon-md" aria-label="List view">
          <List />
        </TabsTrigger>
        <TabsTrigger value="chart" size="icon-md" aria-label="Chart view">
          <ChartBar />
        </TabsTrigger>
      </TabsList>
    </Tabs>
  )
}
```

### Controlled [#controlled]

Hold the active tab in state with `value` + `onValueChange` to drive it from elsewhere — here Back/Next buttons step through a wizard while the tabs reflect the current step.

```tsx
'use client'

import * as React from 'react'
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@appica/ui-react/tabs'
import { Button } from '@appica/ui-react/button'

const STEPS = ['account', 'profile', 'review'] as const
type Step = (typeof STEPS)[number]

export default function TabsControlled() {
  const [step, setStep] = React.useState<Step>('account')
  const index = STEPS.indexOf(step)
  const goTo = (target: number) => setStep(STEPS[Math.min(Math.max(target, 0), STEPS.length - 1)]!)

  return (
    <div className="flex w-full max-w-sm flex-col gap-5">
      <Tabs value={step} onValueChange={(value) => setStep(value as Step)}>
        <TabsList>
          <TabsTrigger value="account">Account</TabsTrigger>
          <TabsTrigger value="profile">Profile</TabsTrigger>
          <TabsTrigger value="review">Review</TabsTrigger>
        </TabsList>
        <TabsContent value="account" className="text-foreground-muted text-sm">
          Step 1 — choose a username and password.
        </TabsContent>
        <TabsContent value="profile" className="text-foreground-muted text-sm">
          Step 2 — tell us a little about yourself.
        </TabsContent>
        <TabsContent value="review" className="text-foreground-muted text-sm">
          Step 3 — review everything and submit.
        </TabsContent>
      </Tabs>

      <div className="flex gap-2">
        <Button variant="outline" size="sm" disabled={index === 0} onClick={() => goTo(index - 1)}>
          Back
        </Button>
        <Button size="sm" disabled={index === STEPS.length - 1} onClick={() => goTo(index + 1)}>
          Next
        </Button>
      </div>
    </div>
  )
}
```

### Disabled [#disabled]

Add `disabled` to a `TabsTrigger` to make it non-interactive; arrow-key navigation skips over it.

```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@appica/ui-react/tabs'

export default function TabsDisabled() {
  return (
    <Tabs defaultValue="overview" className="w-full max-w-md">
      <TabsList>
        <TabsTrigger value="overview">Overview</TabsTrigger>
        <TabsTrigger value="activity">Activity</TabsTrigger>
        <TabsTrigger value="billing" disabled>
          Billing
        </TabsTrigger>
      </TabsList>
      <TabsContent value="overview" className="text-foreground-muted text-sm">
        The billing tab is disabled until you upgrade to a paid plan.
      </TabsContent>
      <TabsContent value="activity" className="text-foreground-muted text-sm">
        Every change across the team, newest first.
      </TabsContent>
    </Tabs>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, indicator placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The tabs flow from the right, the active indicator slides along the resolved direction, and ←/→ arrow keys swap roles. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="tabs" />

## API reference [#api-reference]

`Tabs` wraps [Base UI's Tabs](https://base-ui.com/react/components/tabs). The root provides the `variant`/`size`/`orientation` context; each part forwards `ref` and its remaining native attributes to the underlying element.

### Tabs [#tabs]

The root. Owns the selected value and renders a `<div>`.

| Prop            | <ColMinWidth width="200">Type</ColMinWidth>                   | Default        | <ColMinWidth width="220">Description</ColMinWidth>                                  |
| --------------- | ------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------- |
| `defaultValue`  | <Code>string \| number \| null</Code>                         | —              | The initially selected tab's `value`, for uncontrolled use.                         |
| `value`         | <Code>string \| number \| null</Code>                         | —              | The selected tab's `value`, for controlled use. Pair with `onValueChange`.          |
| `onValueChange` | <Code>(value, eventDetails) => void</Code>                    | —              | Called when the selected tab changes.                                               |
| `variant`       | <Code>'pill' \| 'line'</Code>                                 | `'pill'`       | Visual style, shared with the list and triggers via context.                        |
| `size`          | <Code>'sm' \| 'md' \| 'lg'</Code>                             | `'md'`         | Trigger sizing, shared via context.                                                 |
| `orientation`   | <Code>'horizontal' \| 'vertical'</Code>                       | `'horizontal'` | Layout axis and the direction arrow keys move focus. Exposed as `data-orientation`. |
| `render`        | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —              | Replace the rendered element, or compose it with another component.                 |
| `className`     | <Code>string \| ((state) => string)</Code>                    | —              | Extra classes, merged via `tailwind-merge`. May be a function of state.             |

### TabsList [#tabslist]

The row (or column) of triggers, with the sliding active indicator built in. Renders a `<div role="tablist">`.

| Prop              | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>                                   |
| ----------------- | ------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `variant`         | <Code>'pill' \| 'line'</Code>                                 | context | Override the root's variant for this list.                                           |
| `size`            | <Code>'sm' \| 'md' \| 'lg'</Code>                             | context | Override the root's size for this list.                                              |
| `activateOnFocus` | `boolean`                                                     | `false` | Activate a tab as soon as it's focused with the arrow keys, not only on click/Enter. |
| `loopFocus`       | `boolean`                                                     | `true`  | Whether arrow-key focus wraps from the last trigger to the first and back.           |
| `render`          | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the rendered element, or compose it with another component.                  |
| `className`       | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes, merged via `tailwind-merge`.                                          |

### TabsTrigger [#tabstrigger]

One tab button. Renders a `<button role="tab">`.

| Prop           | <ColMinWidth width="200">Type</ColMinWidth>                              | Default | <ColMinWidth width="220">Description</ColMinWidth>                  |
| -------------- | ------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------- |
| `value`        | <Code>string \| number</Code>                                            | —       | **Required.** Identifies the tab and matches it to a `TabsContent`. |
| `variant`      | <Code>'pill' \| 'line'</Code>                                            | context | Override the variant for this trigger.                              |
| `size`         | <Code>'sm' \| 'md' \| 'lg' \| 'icon-sm' \| 'icon-md' \| 'icon-lg'</Code> | context | Override the size; `icon-*` makes a square, label-less trigger.     |
| `disabled`     | `boolean`                                                                | `false` | Make the tab non-interactive and skip it during arrow navigation.   |
| `nativeButton` | `boolean`                                                                | `true`  | Whether the element passed to `render` is a native `<button>`.      |
| `render`       | <Code>ReactElement \| ((props, state) => ReactElement)</Code>            | —       | Replace the rendered element, or compose it with another component. |
| `className`    | <Code>string \| ((state) => string)</Code>                               | —       | Extra classes, merged via `tailwind-merge`.                         |

### TabsContent [#tabscontent]

The panel revealed by its matching trigger. Renders a `<div role="tabpanel">`.

| Prop          | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>                  |
| ------------- | ------------------------------------------------------------- | ------- | ------------------------------------------------------------------- |
| `value`       | <Code>string \| number</Code>                                 | —       | **Required.** Matches the trigger of the same `value`.              |
| `keepMounted` | `boolean`                                                     | `false` | Keep inactive panels mounted (hidden) instead of unmounting them.   |
| `render`      | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the rendered element, or compose it with another component. |
| `className`   | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes, merged via `tailwind-merge`.                         |

## Accessibility [#accessibility]

* The parts map to the WAI-ARIA tabs pattern: `TabsList` is a `role="tablist"`, each `TabsTrigger` a `role="tab"`, and each `TabsContent` a `role="tabpanel"` wired together with `aria-controls`/`aria-labelledby`.
* The list is a single tab stop: **Tab** moves focus into the active trigger, and the **arrow keys** move focus between triggers — ←/→ when horizontal, ↑/↓ when vertical — wrapping unless `loopFocus` is `false`.
* By default a tab activates on **Enter**/**Space**; set `activateOnFocus` to switch panels as focus moves instead.
* `disabled` triggers are removed from the tab order and skipped by arrow navigation.
* An icon-only `TabsTrigger` has no visible text, so give it an `aria-label`.
* The indicator and panel transitions honour `prefers-reduced-motion`.


# Text Animate (/ui/components/react/text-animate)



<Playground component="text-animate" />

## Usage [#usage]

```tsx
import { TextAnimate } from '@appica/ui-react/text-animate'
```

```tsx
<TextAnimate effect="typewriter">Ship beautiful interfaces, fast.</TextAnimate>
```

`TextAnimate` splits a string into **units** — characters, words, or lines — and drives every unit
from a single `progress` value (`0 → 1`). One small engine therefore covers many effects: it ships
seven presets (`typewriter`, `scramble`, `rise`, `highlight`, `wave`, `flip`, `shimmer`) and accepts
a custom function for anything else.

It is deliberately **headless and font-agnostic**: it animates only `transform`, `opacity`, and the
displayed glyphs — never `font-size`, `font-weight`, `line-height`, or `letter-spacing`. So it
inherits whatever typography you set, and multi-line text wraps and breaks naturally.

### Two ways to drive it [#two-ways-to-drive-it]

The component never listens to scroll, viewport, or page load on its own — that keeps it composable.
You either let its built-in clock play the animation, or you own the timeline:

```tsx
<TextAnimate effect="scramble">Plays itself on mount</TextAnimate>

<TextAnimate effect="highlight" autoPlay={false} progress={scrollProgress}>
  You drive this from scroll, a slider, or any state
</TextAnimate>
```

When you pass `progress`, the internal clock is disabled and the component is fully controlled — wire
it to a scroll listener, an `IntersectionObserver`, a Motion `MotionValue`, or a slider. When you
omit `progress`, an opt-in `requestAnimationFrame` clock plays it once (`duration`, `delay`) or
forever (`loop`).

## Examples [#examples]

### Typewriter [#typewriter]

The classic effect: characters reveal one-by-one with a blinking caret on the typing edge. Hidden
characters take no space, so the line grows as it types.

```tsx
'use client'

import { useState } from 'react'
import { Button } from '@appica/ui-react/button'
import { TextAnimate } from '@appica/ui-react/text-animate'

export default function TextAnimateDefault() {
  const [run, setRun] = useState(0)

  return (
    <div className="flex flex-col items-center gap-6">
      <TextAnimate
        key={run}
        effect="typewriter"
        duration={2}
        className="text-foreground-intense text-3xl font-semibold"
      >
        Ship beautiful interfaces, fast.
      </TextAnimate>
      <Button variant="outline" size="sm" onClick={() => setRun((n) => n + 1)}>
        Replay
      </Button>
    </div>
  )
}
```

### Scramble [#scramble]

Each character cycles through random glyphs before locking onto its target — the "decode" look.
Whitespace is left intact so word boundaries stay stable while the text resolves. Pairs nicely with a
monospace font.

```tsx
'use client'

import { useState } from 'react'
import { Button } from '@appica/ui-react/button'
import { TextAnimate } from '@appica/ui-react/text-animate'

export default function TextAnimateScramble() {
  const [run, setRun] = useState(0)

  return (
    <div className="flex flex-col items-center gap-6">
      <TextAnimate
        key={run}
        effect="scramble"
        duration={1.6}
        className="text-foreground-intense font-mono text-3xl font-semibold"
      >
        Decoding the signal
      </TextAnimate>
      <Button variant="outline" size="sm" onClick={() => setRun((n) => n + 1)}>
        Replay
      </Button>
    </div>
  )
}
```

### Rise [#rise]

Each unit slides up **from behind a clip edge**, so the text wipes into view from its own baseline
rather than just translating — a masked reveal that's tedious to wire up by hand. It defaults to a
per-character cascade; switch to `by="word"` or `by="line"` for a chunkier reveal.

```tsx
'use client'

import { useState } from 'react'
import { Button } from '@appica/ui-react/button'
import { TextAnimate } from '@appica/ui-react/text-animate'

export default function TextAnimateRise() {
  const [run, setRun] = useState(0)

  return (
    <div className="flex flex-col items-center gap-6">
      <TextAnimate key={run} effect="rise" duration={1.6} className="text-foreground-intense text-3xl font-semibold">
        Rising into view
      </TextAnimate>
      <Button variant="outline" size="sm" onClick={() => setRun((n) => n + 1)}>
        Replay
      </Button>
    </div>
  )
}
```

### Reveal on scroll into view [#reveal-on-scroll-into-view]

`highlight` ramps each **word** from dimmed to full. Here an `IntersectionObserver` plays the reveal
each time the paragraph scrolls into the panel (and resets it on the way out) — the observer is the
trigger, the component just animates. No animation library required.

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { ScrollArea } from '@appica/ui-react/scroll-area'
import { TextAnimate } from '@appica/ui-react/text-animate'

export default function TextAnimateHighlight() {
  const viewportRef = useRef<HTMLDivElement>(null)
  const textRef = useRef<HTMLDivElement>(null)
  const [play, setPlay] = useState(0)

  useEffect(() => {
    const root = viewportRef.current
    const target = textRef.current
    if (!root || !target) return
    const observer = new IntersectionObserver(([entry]) => setPlay((n) => (entry?.isIntersecting ? n + 1 : 0)), {
      root,
      threshold: 0.8,
    })
    observer.observe(target)
    return () => observer.disconnect()
  }, [])

  return (
    <ScrollArea className="border-border h-72 w-full max-w-md rounded-lg border" viewportProps={{ ref: viewportRef }}>
      <div className="p-6">
        <div className="h-72" />
        <div ref={textRef}>
          <TextAnimate
            key={play}
            effect="highlight"
            duration={1.4}
            className="text-foreground-intense text-xl leading-relaxed font-medium"
            {...(play > 0 ? {} : { autoPlay: false, progress: 0 })}
          >
            Scroll this paragraph into view and it reveals itself, word by word.
          </TextAnimate>
        </div>
        <div className="h-44" />
      </div>
    </ScrollArea>
  )
}
```

### Drive it yourself [#drive-it-yourself]

`progress` accepts any `0 → 1` value, so you can scrub the animation from a slider, a gesture, or app
state — wire it to a scroll position for a true scrub-as-you-scroll effect, or to any source you like.

```tsx
'use client'

import { useState } from 'react'
import { Slider } from '@appica/ui-react/slider'
import { TextAnimate } from '@appica/ui-react/text-animate'

export default function TextAnimateControlled() {
  const [progress, setProgress] = useState(0.5)

  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-8">
      <TextAnimate
        effect="flip"
        autoPlay={false}
        progress={progress}
        className="text-foreground-intense text-4xl font-semibold"
      >
        Scrub me
      </TextAnimate>
      <Slider
        className="w-full"
        value={progress}
        onValueChange={(value) => setProgress(value as number)}
        min={0}
        max={1}
        step={0.01}
        tooltipVisibility="never"
        thumbAriaLabel="Animation progress"
      />
    </div>
  )
}
```

### Continuous effects [#continuous-effects]

`wave` and `shimmer` are continuous: their presets loop the clock automatically, so they animate on
mount with no driver wiring. `wave` ripples each character vertically (amplitude in `em`, so it
scales with the font); `shimmer` sweeps a bright band along the string.

```tsx
import { TextAnimate } from '@appica/ui-react/text-animate'

export default function TextAnimateKinetic() {
  return (
    <div className="text-foreground-intense flex flex-col items-center gap-6 text-3xl font-semibold">
      <TextAnimate effect="wave">Riding the wave</TextAnimate>
      <TextAnimate effect="shimmer">Shimmering headline</TextAnimate>
    </div>
  )
}
```

### Custom effects [#custom-effects]

Pass a function instead of a preset name. It receives each unit's **local** progress and a context
object, and returns inline `style` (and/or replacement `content`). Everything the presets do, you can
do — here a per-character blur-and-rise entrance.

```tsx
'use client'

import { useState } from 'react'
import { Button } from '@appica/ui-react/button'
import { TextAnimate, type TextAnimateEffect } from '@appica/ui-react/text-animate'

const blurRise: TextAnimateEffect = (p) => ({
  style: {
    display: 'inline-block',
    opacity: p,
    filter: `blur(${((1 - p) * 6).toFixed(2)}px)`,
    transform: `translateY(${((1 - p) * 0.5).toFixed(3)}em)`,
  },
})

export default function TextAnimateCustom() {
  const [run, setRun] = useState(0)

  return (
    <div className="flex flex-col items-center gap-6">
      <TextAnimate
        key={run}
        effect={blurRise}
        by="char"
        stagger={0.5}
        duration={1.6}
        className="text-foreground-intense text-3xl font-semibold"
      >
        Roll your own effect
      </TextAnimate>
      <Button variant="outline" size="sm" onClick={() => setRun((n) => n + 1)}>
        Replay
      </Button>
    </div>
  )
}
```

For continuous effects, read `ctx.globalProgress` (the raw, un-staggered driver value) and
`ctx.index` instead of the first argument — that is how `wave` and `shimmer` phase each character.

### Multiple lines [#multiple-lines]

Use `\n` for explicit line breaks. Words still wrap within each line, and the stagger flows across
every line in reading order.

```tsx
import { TextAnimate } from '@appica/ui-react/text-animate'

export default function TextAnimateMultiline() {
  return (
    <TextAnimate
      effect="highlight"
      by="word"
      loop
      duration={4}
      className="text-foreground-intense max-w-md text-center text-xl leading-relaxed font-medium"
    >
      {'Line breaks are preserved.\nWords wrap and stagger\nacross every line you give it.'}
    </TextAnimate>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a
container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your
tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

Word and line units follow the resolved direction automatically. For setup details and caveats, see
the [RTL guide](/ui/docs/react/rtl).

<Callout type="warning" title="Use word or line splitting for cursive scripts">
  `by="char"` wraps every character in its own element, which breaks the contextual shaping of cursive scripts like
  Arabic (letters stop joining). For Arabic, Persian, and similar scripts, use `by="word"` or `by="line"` so each shaped
  unit stays intact — as the demo below does.
</Callout>

<RtlPreview component="text-animate" />

## API reference [#api-reference]

Renders a `<span>` wrapping the animated text. The full string is always present as an `sr-only` copy
for assistive tech; the animated glyphs are `aria-hidden`.

| Prop       | <ColMinWidth width="210">Type</ColMinWidth>             | Default        | <ColMinWidth width="220">Description</ColMinWidth>                                                                             |
| ---------- | ------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `children` | `string`                                                | —              | The text to animate. Use `\n` for explicit line breaks.                                                                        |
| `effect`   | <Code>TextAnimateEffectName \| TextAnimateEffect</Code> | `'typewriter'` | A preset name (`typewriter`, `scramble`, `rise`, `highlight`, `wave`, `flip`, `shimmer`) or a custom `(progress, ctx) => {…}`. |
| `by`       | <Code>'char' \| 'word' \| 'line'</Code>                 | preset's level | Segmentation level. Defaults to the preset's natural level (e.g. `word` for `highlight`).                                      |
| `progress` | `number`                                                | —              | Controlled driver value (`0 → 1`). When set, the internal clock is disabled and you own the timeline.                          |
| `autoPlay` | `boolean`                                               | `true`         | Run the built-in clock when `progress` is not provided.                                                                        |
| `loop`     | `boolean`                                               | preset's value | Loop the built-in clock. Continuous presets (`wave`, `shimmer`) default to `true`.                                             |
| `duration` | `number`                                                | `1.6`          | Built-in clock length in **seconds**.                                                                                          |
| `delay`    | `number`                                                | `0`            | Built-in clock start delay in **seconds**.                                                                                     |
| `stagger`  | `number`                                                | preset's value | How offset each unit's window is from its neighbour's, `0 → 1`. `0` = all together; `1` = fully sequential.                    |

Forwards `ref`, `className`, and any other `<span>` attributes. The root is `inline-block` — override
`display` via `className` (e.g. `block`) if you need it.

### The effect function [#the-effect-function]

A custom `effect` is `(progress, ctx) => { style?, className?, content? }`, called once per unit per
frame:

| Field                | <ColMinWidth width="180">Type</ColMinWidth> | Description                                                                                  |
| -------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `progress`           | `number`                                    | The unit's **local** progress (`0 → 1`), already staggered. Most entrance effects use this.  |
| `ctx.index`          | `number`                                    | Global unit index, in reading order.                                                         |
| `ctx.total`          | `number`                                    | Total number of units.                                                                       |
| `ctx.text`           | `string`                                    | The unit's text (a character, word, or line).                                                |
| `ctx.by`             | <Code>'char' \| 'word' \| 'line'</Code>     | The active segmentation level.                                                               |
| `ctx.globalProgress` | `number`                                    | Raw, un-staggered driver value. Use for continuous effects (wave, shimmer) plus `ctx.index`. |
| `ctx.reduced`        | `boolean`                                   | `true` when the user prefers reduced motion — return a static, legible frame.                |

Return `style`/`className` to animate the glyph and/or `content` to replace the displayed text (how
`scramble` and `typewriter` mutate characters).

## Accessibility [#accessibility]

* The complete text is always rendered as an `sr-only` copy, so screen readers announce it once, in
  full — regardless of animation state. The animated glyphs are `aria-hidden`.
* The animation honours `prefers-reduced-motion` (and `ReducedMotionProvider`): the built-in clock
  snaps straight to the final frame, the caret stops blinking, and motion-heavy presets (`wave`,
  `flip`, `shimmer`) render their static, fully-legible state.
* A controlled `progress` is **not** overridden by reduced motion — a scroll-linked reveal keeps
  working — but the motion-heavy presets still drop their transforms for those users.
* `by="char"` breaks the contextual shaping of cursive scripts (e.g. Arabic); use `by="word"` or
  `by="line"` there.
* Because every unit re-renders each frame, keep animated strings to headline/sentence length rather
  than long bodies of text.


# Textarea (/ui/components/react/textarea)



<Playground component="textarea" />

## Usage [#usage]

```tsx
import { Textarea } from '@appica/ui-react/textarea'
```

```tsx
<Textarea rows={4} placeholder="Write a message…" />
```

`Textarea` is the multi-line counterpart to [`Input`](/ui/components/react/input), sharing its appearance, variants, and sizes. Use it like a native `<textarea>` — native attributes pass straight through — and give it a label with an external `<label htmlFor>` or an `aria-label`.

`rows` seeds the initial height (and the resize floor); the field can still be dragged taller by the resize handle. Add adornments with `startSlot` / `endSlot` and a clear button with `clearable`.

## Examples [#examples]

### Variants [#variants]

`variant` switches the appearance between a bordered `outline` (default) and a filled `soft` field.

```tsx
import { Textarea } from '@appica/ui-react/textarea'

export default function TextareaVariants() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      <Textarea variant="outline" placeholder="Outline" aria-label="Outline" />
      <Textarea variant="soft" placeholder="Soft" aria-label="Soft" />
    </div>
  )
}
```

### Sizes [#sizes]

`inputSize` scales the padding and text — `sm`, `md` (default), or `lg`. (It's named `inputSize` so it doesn't collide with any native attribute.)

```tsx
import { Textarea } from '@appica/ui-react/textarea'

export default function TextareaSizes() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      <Textarea inputSize="sm" placeholder="Small" aria-label="Small" />
      <Textarea inputSize="md" placeholder="Medium" aria-label="Medium" />
      <Textarea inputSize="lg" placeholder="Large" aria-label="Large" />
    </div>
  )
}
```

### Start & end slots [#start--end-slots]

`startSlot` and `endSlot` take any node — not just icons — aligned to the first line of the field. Use them to build a compact composer: an [`Avatar`](/ui/components/react/avatar) with a send [`Button`](/ui/components/react/button), or a live character counter.

```tsx
'use client'

import { useState } from 'react'
import { Textarea } from '@appica/ui-react/textarea'
import { Avatar, AvatarFallback } from '@appica/ui-react/avatar'
import { Button } from '@appica/ui-react/button'
import { Send2, UserFilled } from '@appica/icons-react'

const LIMIT = 180

export default function TextareaSlots() {
  const [value, setValue] = useState('')
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      <Textarea
        className="*:data-[slot=textarea-end]:h-full *:data-[slot=textarea-end]:items-end"
        rows={4}
        startSlot={
          <Avatar size="2xs">
            <AvatarFallback>
              <UserFilled />
            </AvatarFallback>
          </Avatar>
        }
        endSlot={
          <Button variant="soft" size="icon-sm" aria-label="Send comment">
            <Send2 />
          </Button>
        }
        placeholder="Add a comment…"
        aria-label="Comment"
      />
      <Textarea
        rows={3}
        value={value}
        onChange={(event) => setValue(event.target.value.slice(0, LIMIT))}
        endSlot={
          <span className="text-foreground-muted text-xs tabular-nums">
            {value.length}/{LIMIT}
          </span>
        }
        placeholder="What's on your mind?"
        aria-label="Status"
      />
    </div>
  )
}
```

### Clearable [#clearable]

Set `clearable` to add a clear (✕) button that appears once the field has a value and empties it on click. Pair it with `onClear` to react to the reset.

```tsx
import { Textarea } from '@appica/ui-react/textarea'

export default function TextareaClearable() {
  return (
    <Textarea
      className="max-w-70"
      clearable
      defaultValue="The quick brown fox jumps over the lazy dog."
      aria-label="Notes"
    />
  )
}
```

### Disabled, read-only & error states [#disabled-read-only--error-states]

`disabled` greys out the field and blocks interaction; `readOnly` keeps it focusable and selectable but prevents edits. Set `aria-invalid` to paint the error state — it's mirrored to `data-invalid`.

```tsx
import { Textarea } from '@appica/ui-react/textarea'

export default function TextareaStates() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      <Textarea placeholder="Disabled" disabled aria-label="Disabled" />
      <Textarea defaultValue="Read-only content" readOnly aria-label="Read-only" />
      <Textarea defaultValue="Too short" aria-invalid aria-label="Notes with error" />
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The text aligns to the start edge, the `startSlot`/`endSlot` adornments swap sides, and the resize handle moves to the start corner to follow the resolved direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="textarea" />

## API reference [#api-reference]

The `variant`, `inputSize`, `clearable`, `startSlot`, `endSlot`, and `onClear` props are Appica additions; every other prop is forwarded to the underlying `<textarea>`.

| Prop           | <ColMinWidth width="200">Type</ColMinWidth> | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                          |
| -------------- | ------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------- |
| `variant`      | <Code>'outline' \| 'soft'</Code>            | `'outline'` | Field appearance — bordered or filled.                                                      |
| `inputSize`    | <Code>'sm' \| 'md' \| 'lg'</Code>           | `'md'`      | Scales padding and text. Named `inputSize` to avoid colliding with native attributes.       |
| `rows`         | `number`                                    | `3`         | Initial height in lines; also the resize floor.                                             |
| `startSlot`    | `ReactNode`                                 | —           | Adornment rendered before the field, aligned to the first line.                             |
| `endSlot`      | `ReactNode`                                 | —           | Adornment rendered after the field, aligned to the first line.                              |
| `clearable`    | `boolean`                                   | `false`     | Show a clear (✕) button once the field has a value.                                         |
| `onClear`      | <Code>() => void</Code>                     | —           | Called when the clear button is pressed.                                                    |
| `aria-invalid` | <Code>boolean \| 'true' \| 'false'</Code>   | —           | Marks the error state; mirrored to `data-invalid`.                                          |
| `disabled`     | `boolean`                                   | `false`     | Disables the field and removes it from the tab order.                                       |
| `placeholder`  | `string`                                    | `' '`       | Placeholder text.                                                                           |
| `value`        | `string`                                    | —           | Controlled value. Pair with `onChange`.                                                     |
| `defaultValue` | `string`                                    | —           | Uncontrolled initial value.                                                                 |
| `ref`          | <Code>Ref\<HTMLTextAreaElement></Code>      | —           | Ref to the underlying `<textarea>`.                                                         |
| `className`    | `string`                                    | —           | Extra classes, merged via `tailwind-merge` (lands on the wrapper when adornments are used). |

`Textarea` is a native `<textarea>` styled with the shared input appearance, and forwards every remaining native `<textarea>` prop (`name`, `onChange`, `maxLength`, `aria-*`, …). It exposes `data-disabled` / `data-invalid` for styling.

## Accessibility [#accessibility]

* Renders a native `<textarea>` (`role="textbox"`, multiline). Give it an accessible name — an external `<label htmlFor>` pointing at its `id`, or an `aria-label`.
* The clear button is labelled **Clear input**, kept out of the tab order (`tabIndex={-1}`), and appears only when the field has a value.
* `aria-invalid` is bridged to `data-invalid` so the error state styles correctly.
* `disabled` removes the field from the tab order and exposes `data-disabled` for styling.


# Thumbnail (/ui/components/react/thumbnail)



<Playground component="thumbnail" />

## Usage [#usage]

```tsx
import { Thumbnail } from '@appica/ui-react/thumbnail'
```

```tsx
<Thumbnail src="/thumbnail.jpg" alt="Mountain peak" />

<Thumbnail variant="icon-primary">
  <Bolt />
</Thumbnail>
```

`Thumbnail` is a compact preview tile — the small square you see beside a file, a list row, or a media item. A single component covers both jobs:

* **Image** (`variant="image"`, the default) — shows `src` cropped to fill, preloading it like an [`Avatar`](/ui/components/react/avatar) and dropping to a placeholder icon if the image is missing or fails.
* **Icon** (`variant="icon-*"`) — a colored tile that frames an icon you pass as `children`, in soft, outline, primary, and the semantic accent colors.

Everything is sized in `em` from a single `size`, so the tile and its icon scale together. Use a preset (`2xs`–`2xl`) or a pixel number, and pick a `rounded` square or a full `circle` with `shape`.

## Examples [#examples]

### Default [#default]

The image variant. The `src` is cropped to fill the square; give it an `alt` that describes the picture.

```tsx
import { Thumbnail } from '@appica/ui-react/thumbnail'

export default function ThumbnailDefault() {
  return <Thumbnail size="xl" src="/thumbnail.jpg" alt="Snow-capped mountain peak at sunset" />
}
```

### Sizes [#sizes]

Seven presets run from `2xs` to `2xl`. Because the tile is sized in `em`, a fallback or icon inside scales right along with it.

```tsx
import { Thumbnail } from '@appica/ui-react/thumbnail'

const sizes = ['2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'] as const

export default function ThumbnailSizes() {
  return (
    <div className="flex flex-wrap items-end justify-center gap-4">
      {sizes.map((size) => (
        <Thumbnail key={size} size={size} src="/thumbnail.jpg" alt="Mountain peak" />
      ))}
    </div>
  )
}
```

### Custom size [#custom-size]

Pass a number to `size` for an exact pixel dimension when a preset doesn't fit — it drives the tile's `font-size`, so everything inside stays proportional.

```tsx
import { Thumbnail } from '@appica/ui-react/thumbnail'

export default function ThumbnailCustomSize() {
  return (
    <div className="flex items-end gap-4">
      <Thumbnail size={40} src="/thumbnail.jpg" alt="Mountain peak" />
      <Thumbnail size={56} src="/thumbnail.jpg" alt="Mountain peak" />
      <Thumbnail size={88} src="/thumbnail.jpg" alt="Mountain peak" />
    </div>
  )
}
```

### Shape [#shape]

`shape="rounded"` (the default) is a squircle-style rounded square; `shape="circle"` clips the image to a full circle.

```tsx
import { Thumbnail } from '@appica/ui-react/thumbnail'

export default function ThumbnailShape() {
  return (
    <div className="flex items-center gap-4">
      <Thumbnail size="xl" shape="rounded" src="/thumbnail.jpg" alt="Mountain peak" />
      <Thumbnail size="xl" shape="circle" src="/thumbnail.jpg" alt="Mountain peak" />
    </div>
  )
}
```

### Icon variants [#icon-variants]

The `icon-*` variants drop the image and frame an icon child instead — `icon-soft` and `icon-outline` for neutral tiles, `icon-primary` and `icon-primary-outline` for the brand color, and `icon-secondary` / `icon-error` / `icon-success` / `icon-warning` / `icon-info` for the semantic accents.

```tsx
import { Thumbnail } from '@appica/ui-react/thumbnail'
import { Folder, ImageSquareRounded, Bolt, Heart, Star, Trash, Check, Bell, Mail } from '@appica/icons-react'

const variants = [
  { variant: 'icon-soft', icon: <Folder /> },
  { variant: 'icon-outline', icon: <ImageSquareRounded /> },
  { variant: 'icon-primary', icon: <Bolt /> },
  { variant: 'icon-primary-outline', icon: <Heart /> },
  { variant: 'icon-secondary', icon: <Star /> },
  { variant: 'icon-error', icon: <Trash /> },
  { variant: 'icon-success', icon: <Check /> },
  { variant: 'icon-warning', icon: <Bell /> },
  { variant: 'icon-info', icon: <Mail /> },
] as const

export default function ThumbnailIconVariants() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-4">
      {variants.map(({ variant, icon }) => (
        <Thumbnail key={variant} variant={variant} size="lg">
          {icon}
        </Thumbnail>
      ))}
    </div>
  )
}
```

### Fallback [#fallback]

When the image is missing or fails to load, the image variant falls back to a built-in placeholder icon — no broken-image glyph ever flashes.

```tsx
import { Thumbnail } from '@appica/ui-react/thumbnail'

export default function ThumbnailFallback() {
  return <Thumbnail size="xl" src="/thumbnail-does-not-exist.jpg" alt="Unavailable image" />
}
```

### Media list [#media-list]

Thumbnails shine next to text. Mix an image tile with icon tiles down a list so files, folders, and media share one consistent rhythm.

```tsx
import { Thumbnail } from '@appica/ui-react/thumbnail'
import { Folder, Layout2, Music } from '@appica/icons-react'

const items = [
  {
    thumb: <Thumbnail size="md" src="/thumbnail.jpg" alt="Mountain peak" />,
    title: 'Summit.jpg',
    meta: 'Image · 2.4 MB',
  },
  {
    thumb: (
      <Thumbnail size="md" variant="icon-soft">
        <Folder />
      </Thumbnail>
    ),
    title: 'Field notes',
    meta: 'Folder · 18 items',
  },
  {
    thumb: (
      <Thumbnail size="md" variant="icon-primary">
        <Music />
      </Thumbnail>
    ),
    title: 'Trailhead.mp3',
    meta: 'Audio · 3:42',
  },
  {
    thumb: (
      <Thumbnail size="md" variant="icon-secondary">
        <Layout2 />
      </Thumbnail>
    ),
    title: 'Moodboard',
    meta: 'Album · 24 photos',
  },
]

export default function ThumbnailMediaList() {
  return (
    <ul className="divide-border border-border w-full max-w-90 divide-y rounded-xl border">
      {items.map((item) => (
        <li key={item.title} className="flex items-center gap-3 px-4 py-3">
          {item.thumb}
          <div className="flex flex-col">
            <span className="text-foreground-intense text-sm font-medium">{item.title}</span>
            <span className="text-foreground-muted text-xs">{item.meta}</span>
          </div>
        </li>
      ))}
    </ul>
  )
}
```

### Next.js Image [#nextjs-image]

To serve an optimized image, pass a Next.js `<Image>` to the `render` prop. The wrapper lifts the `src` so the preloader still drives the fallback, and applies its own `object-cover` and rounded-corner classes. Give the `Image` a `width`/`height` matching the tile's pixel size.

```tsx
import Image from 'next/image'
import { Thumbnail } from '@appica/ui-react/thumbnail'

export default function ThumbnailNextImage() {
  return (
    <Thumbnail
      size="2xl"
      render={<Image src="/thumbnail.jpg" alt="Snow-capped mountain peak at sunset" width={80} height={80} />}
    />
  )
}
```

### Loading [#loading]

`onLoadingStatusChange` reports the image's lifecycle, so you can overlay a [`Skeleton`](/ui/components/react/skeleton) while it loads and drop it once the photo arrives. Press **Reload** to fetch a fresh copy and watch it again.

```tsx
'use client'

import { useState, useEffect } from 'react'
import { Thumbnail } from '@appica/ui-react/thumbnail'
import { Skeleton } from '@appica/ui-react/skeleton'
import { Button } from '@appica/ui-react/button'

export default function ThumbnailLoading() {
  const [src, setSrc] = useState<string>()
  const [loaded, setLoaded] = useState(false)
  const [nonce, setNonce] = useState(0)

  useEffect(() => {
    setSrc(undefined)
    setLoaded(false)
    // Demo only: defer the image ~2.5s so the loading skeleton stays visible.
    const id = setTimeout(() => setSrc(`/thumbnail.jpg?reload=${nonce}`), 2500)
    return () => clearTimeout(id)
  }, [nonce])

  return (
    <div className="flex flex-col items-center gap-4">
      <div className="relative inline-flex">
        <Thumbnail
          size="2xl"
          alt="Mountain peak"
          onLoadingStatusChange={(status) => setLoaded(status === 'loaded')}
          {...(src ? { src } : {})}
        />
        {!loaded && <Skeleton className="absolute inset-0 rounded-[calc(tan(atan2(var(--radius-md),2.5rem))*100%)]" />}
      </div>
      <Button variant="outline" size="sm" onClick={() => setNonce((n) => n + 1)} disabled={!src}>
        Reload
      </Button>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The tile itself is symmetric, so it looks the same in either direction; what flips is the surrounding layout — in a media row the thumbnail moves to the right and the text to its left. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="thumbnail" />

## API reference [#api-reference]

`Thumbnail` is a single component. For the image variant it builds on [Base UI's Avatar](https://base-ui.com/react/components/avatar) to preload the source and manage the fallback; the icon variants render a plain tile. It forwards `ref` and remaining attributes to the root element.

| Prop                    | <ColMinWidth width="210">Type</ColMinWidth>                                                                                                                                              | Default     | <ColMinWidth width="210">Description</ColMinWidth>                                 |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------- |
| `variant`               | <Code>'image' \| 'icon-soft' \| 'icon-outline' \| 'icon-primary' \| 'icon-primary-outline' \| 'icon-secondary' \| 'icon-error' \| 'icon-success' \| 'icon-warning' \| 'icon-info'</Code> | `'image'`   | Image tile, or a colored icon tile.                                                |
| `size`                  | <Code>'2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| number</Code>                                                                                                            | `'md'`      | A preset scale, or a pixel number for an exact size.                               |
| `shape`                 | <Code>'rounded' \| 'circle'</Code>                                                                                                                                                       | `'rounded'` | Rounded square or full circle.                                                     |
| `src`                   | `string`                                                                                                                                                                                 | —           | Image URL (image variant). Lifted from `render` when omitted.                      |
| `alt`                   | `string`                                                                                                                                                                                 | `''`        | Alternative text describing the image. Defaults to `""` (decorative) when omitted. |
| `children`              | `ReactNode`                                                                                                                                                                              | —           | The icon to frame (icon variants).                                                 |
| `render`                | <Code>ReactElement \| ((props, state) => ReactElement)</Code>                                                                                                                            | —           | Swap the `<img>` for another element — e.g. a Next.js `<Image>`.                   |
| `onLoadingStatusChange` | <Code>(status: 'idle' \| 'loading' \| 'loaded' \| 'error') => void</Code>                                                                                                                | —           | Fires as the image moves through its loading lifecycle.                            |
| `className`             | `string`                                                                                                                                                                                 | —           | Extra classes, merged via `tailwind-merge`.                                        |

## Accessibility [#accessibility]

* For a meaningful image, give it an `alt` that describes the picture; for a purely decorative thumbnail, use `alt=""`.
* The icon variants are decorative tiles — the icon child carries no accessible name on its own, so make sure the surrounding context (a filename, a label) names what the thumbnail represents.
* The built-in fallback icon is marked `aria-hidden`; the `alt` text is what's announced when the image can't load.
* Pass an explicit `width`/`height` to a `render`ed Next.js `<Image>` so the layout doesn't shift while the image loads.


# Time Field (/ui/components/react/time-field)



<Playground component="time-field" />

## Usage [#usage]

```tsx
import { TimeField } from '@appica/ui-react/time-field'
```

```tsx
<TimeField value={time} onValueChange={setTime} />
```

`TimeField` is the time counterpart to [`DateField`](/ui/components/react/date-field): the `format` string is split into editable hour/minute/second (and optional AM/PM) segments, each a `spinbutton`. The value is always a 24-hour `HH:mm` or `HH:mm:ss` string (or `null` while empty), even when displayed in 12-hour form. It's a custom component — not based on Base UI — sharing the [`Input`](/ui/components/react/input) styling.

## Examples [#examples]

### Variants [#variants]

```tsx
import { TimeField } from '@appica/ui-react/time-field'

const variants = ['outline', 'soft'] as const

export default function TimeFieldVariants() {
  return (
    <div className="flex w-full max-w-40 flex-wrap items-center gap-4">
      {variants.map((variant) => (
        <TimeField key={variant} defaultValue="09:30" variant={variant} />
      ))}
    </div>
  )
}
```

### Sizes [#sizes]

```tsx
import { TimeField } from '@appica/ui-react/time-field'

const sizes = ['sm', 'md', 'lg'] as const

export default function TimeFieldSizes() {
  return (
    <div className="flex w-full max-w-40 flex-wrap items-center gap-4">
      {sizes.map((size) => (
        <TimeField key={size} defaultValue="09:30" size={size} />
      ))}
    </div>
  )
}
```

### Formats [#formats]

Choose 24-hour (`HH`) or 12-hour (`hh` with an `a` period segment), and add `ss` for seconds. The stored value stays 24-hour regardless of display.

```tsx
import { TimeField } from '@appica/ui-react/time-field'

const formats = ['HH:mm', 'HH:mm:ss', 'hh:mm a', 'hh:mm:ss a']

export default function TimeFieldFormats() {
  return (
    <div className="flex w-full max-w-40 flex-wrap items-center gap-4">
      {formats.map((format) => (
        <TimeField key={format} defaultValue="13:45:30" format={format} />
      ))}
    </div>
  )
}
```

### Controlled [#controlled]

Drive the value with `value` + `onValueChange`. The callback fires with a `"HH:mm"`/`"HH:mm:ss"` string once the required segments are filled, or `null` when cleared.

```tsx
'use client'

import * as React from 'react'
import { TimeField } from '@appica/ui-react/time-field'

export default function TimeFieldControlled() {
  const [time, setTime] = React.useState<string | null>('09:30')

  return (
    <div className="flex w-full max-w-40 flex-col gap-3">
      <TimeField value={time} onValueChange={setTime} />
      <p className="text-foreground-muted text-sm">
        Value: <span className="text-foreground font-medium">{time ?? 'null'}</span>
      </p>
    </div>
  )
}
```

### With an icon [#with-an-icon]

Use `startSlot` / `endSlot` to render adornments inside the field frame.

```tsx
import { TimeField } from '@appica/ui-react/time-field'
import { Clock } from '@appica/icons-react'

export default function TimeFieldWithIcon() {
  return <TimeField className="max-w-40" defaultValue="09:30" startSlot={<Clock />} />
}
```

### Disabled, read-only & error states [#disabled-read-only--error-states]

`disabled` greys out the field and blocks interaction; `readOnly` keeps it focusable and readable but prevents edits. Set `aria-invalid` to paint the error state — it's mirrored to `data-invalid`. The field also inherits `disabled` and the error state from a surrounding [`Field`](/ui/components/react/field), so wrapping it in a `Field` marked `invalid` produces the same styling and is the better choice when you're also rendering a validation message.

```tsx
import { TimeField } from '@appica/ui-react/time-field'

export default function TimeFieldStates() {
  return (
    <div className="flex w-full max-w-40 flex-wrap items-center gap-4">
      <TimeField defaultValue="09:30" disabled />
      <TimeField defaultValue="09:30" readOnly />
      <TimeField defaultValue="09:30" aria-invalid />
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="time-field" />

## API reference [#api-reference]

| Prop                    | <ColMinWidth width="180">Type</ColMinWidth> | Default     | <ColMinWidth width="220">Description</ColMinWidth>                                     |
| ----------------------- | ------------------------------------------- | ----------- | -------------------------------------------------------------------------------------- |
| `value`                 | <Code>string \| null</Code>                 | —           | Controlled value, a 24-hour `"HH:mm[:ss]"` string. Pair with `onValueChange`.          |
| `defaultValue`          | <Code>string \| null</Code>                 | —           | Uncontrolled initial value.                                                            |
| `onValueChange`         | <Code>(time: string \| null) => void</Code> | —           | Fires with the time string when complete, or `null` when cleared.                      |
| `format`                | `string`                                    | `'HH:mm'`   | date-fns token string — `H`/`HH`, `h`/`hh`, `m`/`mm`, `s`/`ss`, `a`.                   |
| `variant`               | <Code>'outline' \| 'soft'</Code>            | `'outline'` | Field appearance — bordered or filled.                                                 |
| `size`                  | <Code>'sm' \| 'md' \| 'lg'</Code>           | `'md'`      | Height, padding, and text scale.                                                       |
| `startSlot` / `endSlot` | `ReactNode`                                 | —           | Adornments rendered inside the field frame.                                            |
| `disabled`              | `boolean`                                   | `false`     | Blocks interaction and removes the segments from the tab order.                        |
| `readOnly`              | `boolean`                                   | `false`     | Segments stay focusable and readable but can't be edited.                              |
| `required`              | `boolean`                                   | `false`     | Marks the hidden form input as required (needs `name`).                                |
| `name`                  | `string`                                    | —           | Renders a hidden `<input>` with the time value for form submission.                    |
| `unstyled`              | `boolean`                                   | `false`     | Drop the input appearance — for composing inside another field (used by `DatePicker`). |
| `className`             | `string`                                    | —           | Extra classes on the root, merged via `tailwind-merge`.                                |

Renders a `<div role="group">` and forwards the remaining `<div>` props (`id`, `aria-*`, `ref`, …). The error styling is driven by the `data-invalid` attribute; setting `aria-invalid` marks the field invalid — it sets `data-invalid` for styling and conveys the state to assistive technology.

## Accessibility [#accessibility]

* The field is a `role="group"`; each segment is a `role="spinbutton"` with an `aria-label` (hour/minute/second/period) and `aria-valuenow`/`aria-valuetext`.
* **←/→*&#x2A; move between segments, &#x2A;*↑/↓** step the focused segment (toggling AM/PM on the period), **Home/End** jump to the first/last, **Backspace/Delete** clear; typing fills and auto-advances. The period segment also accepts **a**/**p**.
* `disabled` removes the segments from the tab order; `readOnly` keeps them focusable but inert.
* Segment focus styling uses a transition wrapped in `motion-reduce:`, so it's skipped under reduced motion.


# Toast (/ui/components/react/toast)



<Playground component="toast" />

## Usage [#usage]

```tsx
import { ToastProvider, Toaster, useToastManager } from '@appica/ui-react/toast'
```

Mount `ToastProvider` near the root of your app and render `Toaster` once inside it — that's the portal-anchored viewport every toast appears in. Then call `useToastManager().add(...)` from anywhere below the provider to fire one.

```tsx
function App() {
  return (
    <ToastProvider>
      <YourApp />
      <Toaster />
    </ToastProvider>
  )
}

function SaveButton() {
  const toast = useToastManager()
  return <Button onClick={() => toast.add({ title: 'Changes saved' })}>Save</Button>
}
```

A toast is **imperative**: you describe it as data (`title`, `description`, an optional icon, an action button) and the `Toaster` renders, stacks, and animates it for you. Each one auto-dismisses after `timeout` (5s by default), can be swiped away, and exposes a close button. `Toaster` accepts a `position` to pin the stack to any corner or edge.

<Callout>
  In the examples below, triggers fire real toasts that appear in their fixed corner of the page — scroll up if you
  don't see one land.
</Callout>

## Examples [#examples]

### Default [#default]

Fire a toast with a `title` and `description` from a `useToastManager().add(...)` call. It slides in, waits, and dismisses itself.

```tsx
'use client'

import { useToastManager } from '@appica/ui-react/toast'
import { Button } from '@appica/ui-react/button'
import { ToastSandbox } from './sandbox'

function Demo() {
  const toast = useToastManager()
  return (
    <Button
      onClick={() =>
        toast.add({
          title: 'Changes saved',
          description: 'Your preferences have been updated.',
        })
      }
    >
      Show toast
    </Button>
  )
}

export default function ToastDefault() {
  return (
    <ToastSandbox>
      <Demo />
    </ToastSandbox>
  )
}
```

### With an icon [#with-an-icon]

Pass a leading icon through the toast's typed `data` (`useToastManager<{ icon?: ReactNode }>()`). A filled, color-matched glyph signals success, error, or another state at a glance while the surface stays neutral.

```tsx
'use client'

import { useToastManager } from '@appica/ui-react/toast'
import { Button } from '@appica/ui-react/button'
import { CircleCheckFilled, CircleXFilled, AlertTriangleFilled, InfoCircleFilled } from '@appica/icons-react'
import { ToastSandbox } from './sandbox'

function Demo() {
  const toast = useToastManager<{ icon?: React.ReactNode }>()
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Payment received',
            description: 'Invoice #1024 has been settled.',
            data: { icon: <CircleCheckFilled className="text-success-emphasis" /> },
          })
        }
      >
        Success
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Upload failed',
            description: 'The file exceeds the 25 MB limit.',
            data: { icon: <CircleXFilled className="text-error-emphasis" /> },
          })
        }
      >
        Error
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Storage almost full',
            description: 'You have used 92% of your quota.',
            data: { icon: <AlertTriangleFilled className="text-warning-emphasis" /> },
          })
        }
      >
        Warning
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Heads up',
            description: 'Maintenance is scheduled for Sunday.',
            data: { icon: <InfoCircleFilled className="text-info-emphasis" /> },
          })
        }
      >
        Info
      </Button>
    </div>
  )
}

export default function ToastIconExample() {
  return (
    <ToastSandbox>
      <Demo />
    </ToastSandbox>
  )
}
```

### With a thumbnail [#with-a-thumbnail]

For more prominence, wrap the icon in a [`Thumbnail`](/ui/components/react/thumbnail) (`size="sm"`) with an `icon-*` variant — a tinted badge that pairs a soft background with the state color.

```tsx
'use client'

import { useToastManager } from '@appica/ui-react/toast'
import { Thumbnail } from '@appica/ui-react/thumbnail'
import { Button } from '@appica/ui-react/button'
import { Bell, CircleCheck, CircleX } from '@appica/icons-react'
import { ToastSandbox } from './sandbox'

function Demo() {
  const toast = useToastManager<{ icon?: React.ReactNode }>()
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'New notification',
            description: 'You have 3 unread messages.',
            data: {
              icon: (
                <Thumbnail variant="icon-soft" size="sm">
                  <Bell />
                </Thumbnail>
              ),
            },
          })
        }
      >
        Default
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Payment received',
            description: 'Invoice #1024 has been settled.',
            data: {
              icon: (
                <Thumbnail variant="icon-success" size="sm">
                  <CircleCheck />
                </Thumbnail>
              ),
            },
          })
        }
      >
        Success
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Upload failed',
            description: 'The file exceeds the 25 MB limit.',
            data: {
              icon: (
                <Thumbnail variant="icon-error" size="sm">
                  <CircleX />
                </Thumbnail>
              ),
            },
          })
        }
      >
        Error
      </Button>
    </div>
  )
}

export default function ToastThumbnailExample() {
  return (
    <ToastSandbox>
      <Demo />
    </ToastSandbox>
  )
}
```

### With an action [#with-an-action]

Add `actionProps` for an inline button — an "Undo", "Retry", or "View". Its `onClick` runs your handler; here it fires a follow-up toast.

```tsx
'use client'

import { useToastManager } from '@appica/ui-react/toast'
import { Button } from '@appica/ui-react/button'
import { ToastSandbox } from './sandbox'

function Demo() {
  const toast = useToastManager()
  return (
    <Button
      variant="outline"
      onClick={() =>
        toast.add({
          title: 'Message archived',
          actionProps: {
            children: 'Undo',
            onClick: () => toast.add({ title: 'Message restored' }),
          },
        })
      }
    >
      Archive message
    </Button>
  )
}

export default function ToastAction() {
  return (
    <ToastSandbox>
      <Demo />
    </ToastSandbox>
  )
}
```

### Promise [#promise]

Hand `toast.promise(...)` a promise plus `loading` / `success` / `error` states and it swaps the content as the promise settles — ideal for saves and uploads. (This demo fails at random to show both outcomes.)

```tsx
'use client'

import { useToastManager } from '@appica/ui-react/toast'
import { Thumbnail } from '@appica/ui-react/thumbnail'
import { Button } from '@appica/ui-react/button'
import { Spinner } from '@appica/ui-react/spinner'
import { CircleCheck, CircleX } from '@appica/icons-react'
import { ToastSandbox } from './sandbox'

function save() {
  return new Promise<{ name: string }>((resolve, reject) => {
    setTimeout(() => (Math.random() > 0.3 ? resolve({ name: 'report.pdf' }) : reject(new Error('Network error'))), 2000)
  })
}

function Demo() {
  const toast = useToastManager<{ icon?: React.ReactNode }>()
  return (
    <Button
      onClick={() =>
        toast.promise(save(), {
          loading: {
            title: 'Saving…',
            data: {
              icon: (
                <Thumbnail variant="icon-soft" size="sm">
                  <Spinner currentColor className="text-base" />
                </Thumbnail>
              ),
            },
          },
          success: {
            title: 'Saved',
            description: 'report.pdf is ready to share.',
            data: {
              icon: (
                <Thumbnail variant="icon-success" size="sm">
                  <CircleCheck />
                </Thumbnail>
              ),
            },
          },
          error: {
            title: 'Could not save',
            description: 'Check your connection and try again.',
            data: {
              icon: (
                <Thumbnail variant="icon-error" size="sm">
                  <CircleX />
                </Thumbnail>
              ),
            },
          },
        })
      }
    >
      Save document
    </Button>
  )
}

export default function ToastPromise() {
  return (
    <ToastSandbox>
      <Demo />
    </ToastSandbox>
  )
}
```

### Positions [#positions]

Set `position` on `Toaster` to anchor the stack: any of the six corners and edges. Toasts swipe toward their nearest edge to dismiss.

```tsx
'use client'

import * as React from 'react'
import { ToastProvider, Toaster, useToastManager, type ToastPosition } from '@appica/ui-react/toast'
import { Button } from '@appica/ui-react/button'

const POSITIONS: ToastPosition[] = [
  'top-left',
  'top-center',
  'top-right',
  'bottom-left',
  'bottom-center',
  'bottom-right',
]

function Picker({ onPosition }: { onPosition: (position: ToastPosition) => void }) {
  const toast = useToastManager()
  const show = (position: ToastPosition) => {
    onPosition(position)
    toast.add({ title: 'Notification', description: `Anchored ${position}.` })
  }
  return (
    <div className="grid grid-cols-3 gap-2">
      {POSITIONS.map((position) => (
        <Button key={position} variant="outline" size="sm" onClick={() => show(position)}>
          {position}
        </Button>
      ))}
    </div>
  )
}

export default function ToastPositions() {
  const [position, setPosition] = React.useState<ToastPosition>('bottom-right')
  return (
    <ToastProvider>
      <Picker onPosition={setPosition} />
      <Toaster position={position} />
    </ToastProvider>
  )
}
```

### Timeout & progress [#timeout--progress]

`timeout` controls how long a toast lingers — pass `timeout: 0` for a sticky toast that stays until dismissed. Progress is **opt-in**: set `progress` on the `Toaster` to draw a thin bar counting down on any auto-dismissing toast (including ones that use the default 5s). When you do, set `timeout` on the `Toaster` to match a custom `ToastProvider` timeout so the bar's duration lines up.

```tsx
'use client'

import { useToastManager } from '@appica/ui-react/toast'
import { Button } from '@appica/ui-react/button'
import { ToastSandbox } from './sandbox'

function Demo() {
  const toast = useToastManager()
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Auto-dismiss',
            description: 'This toast closes in 6 seconds.',
            timeout: 6000,
          })
        }
      >
        Timed (6s)
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            title: 'Stays put',
            description: 'Set timeout to 0 to keep a toast until dismissed.',
            timeout: 0,
          })
        }
      >
        Persistent
      </Button>
    </div>
  )
}

export default function ToastTimeout() {
  return (
    <ToastSandbox progress>
      <Demo />
    </ToastSandbox>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

Under RTL the toast's layout mirrors — the icon leads from the right, the close button moves to the left — and the countdown progress bar drains in the reading direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="toast" />

## API reference [#api-reference]

Toast wraps [Base UI's Toast](https://base-ui.com/react/components/toast). Each part forwards its remaining props to the matching Base UI primitive and carries a `data-slot` for styling — the tables below list the Appica additions and the most common props.

### ToastProvider [#toastprovider]

Holds the toast queue and timing config. Wrap your app (or the subtree that fires toasts) in it. Renders no DOM of its own.

| Prop           | <ColMinWidth width="190">Type</ColMinWidth> | Default | <ColMinWidth width="230">Description</ColMinWidth>                         |
| -------------- | ------------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `timeout`      | `number`                                    | `5000`  | Default auto-dismiss delay (ms) for toasts that don't set their own.       |
| `limit`        | `number`                                    | `3`     | Maximum toasts shown at once; the rest queue and surface as room frees up. |
| `toastManager` | `ToastManager`                              | —       | A manager from `createToastManager()` to drive toasts from outside React.  |
| `children`     | `ReactNode`                                 | —       | Your app subtree.                                                          |

### Toaster [#toaster]

The viewport: portals to the body and renders the live stack. Render exactly one per provider.

| Prop          | <ColMinWidth width="190">Type</ColMinWidth>                                                                  | Default          | <ColMinWidth width="230">Description</ColMinWidth>                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `position`    | <Code>'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'</Code> | `'bottom-right'` | Where the stack is anchored; also sets the default swipe-to-dismiss directions.                                                            |
| `progress`    | `boolean`                                                                                                    | `false`          | Opt in to a countdown progress bar on auto-dismissing toasts.                                                                              |
| `timeout`     | `number`                                                                                                     | `5000`           | Provider default (ms) used to size the progress bar for toasts that don't set their own `timeout`. Match your `ToastProvider`'s `timeout`. |
| `container`   | <Code>HTMLElement \| Ref \| null</Code>                                                                      | `document.body`  | Portal target — scope the toasts to a specific element.                                                                                    |
| `portalProps` | <Code>Toast.Portal props</Code>                                                                              | —                | Escape hatch forwarded to the underlying `Toast.Portal`.                                                                                   |
| `className`   | <Code>string \| ((state) => string)</Code>                                                                   | —                | Extra classes on the viewport, merged via `tailwind-merge`.                                                                                |

`Toaster` reads the live `toasts` from the manager and renders each as a `Toast` with its title, description, optional `data.icon`, and `actionProps`.

### useToastManager [#usetoastmanager]

A hook returning the manager used to create and control toasts. Must be called under a `ToastProvider`.

| Method    | <ColMinWidth width="260">Signature</ColMinWidth> | Description                                                   |
| --------- | ------------------------------------------------ | ------------------------------------------------------------- |
| `add`     | <Code>(options) => string</Code>                 | Show a toast; returns its id.                                 |
| `update`  | <Code>(id, options) => void</Code>               | Patch an existing toast in place.                             |
| `close`   | <Code>(id) => void</Code>                        | Dismiss a toast by id.                                        |
| `promise` | <Code>(promise, states) => Promise</Code>        | Drive a toast through `loading` / `success` / `error` states. |
| `toasts`  | <Code>ToastObject\[]</Code>                      | The current live toasts (consumed by `Toaster`).              |

`createToastManager()` returns the same control surface (minus the reactive `toasts`) for firing toasts outside the React tree — pass it to `ToastProvider`'s `toastManager`.

#### `add` / `update` options [#add--update-options]

| Option        | <ColMinWidth width="170">Type</ColMinWidth> | Default | <ColMinWidth width="230">Description</ColMinWidth>                         |
| ------------- | ------------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `title`       | `string`                                    | —       | The toast heading.                                                         |
| `description` | `string`                                    | —       | Supporting body text.                                                      |
| `timeout`     | `number`                                    | `5000`  | Auto-dismiss delay (ms). `0` keeps it until dismissed.                     |
| `type`        | `string`                                    | —       | A free-form category, also surfaced as `data-type` for styling.            |
| `priority`    | <Code>'low' \| 'high'</Code>                | `'low'` | `'high'` interrupts screen readers (use for errors).                       |
| `data`        | `T`                                         | —       | Your typed payload — the `Toaster` reads `data.icon` for the leading icon. |
| `actionProps` | <Code>button props</Code>                   | —       | Renders an inline action button (`children`, `onClick`, …).                |
| `onClose`     | <Code>() => void</Code>                     | —       | Fired when the toast is removed.                                           |

### Toast and its parts [#toast-and-its-parts]

`Toaster` assembles these for you, but they're exported for manual composition (custom layouts, extra parts): `Toast`, `ToastIcon`, `ToastTitle`, `ToastDescription`, `ToastActions`, `ToastAction`, `ToastClose`, `ToastProgress`, and the lower-level `ToastViewport` / `ToastPortal`.

| Prop               | Component              | <ColMinWidth width="150">Type</ColMinWidth> | Default          | Description                                                              |
| ------------------ | ---------------------- | ------------------------------------------- | ---------------- | ------------------------------------------------------------------------ |
| `toast`            | `Toast`                | `ToastObject`                               | —                | **Required.** The toast data from `toasts`.                              |
| `position`         | `Toast`                | `ToastPosition`                             | inherited        | Override the anchor/animation for a single toast.                        |
| `dismissible`      | `Toast`                | `boolean`                                   | `true`           | Render the close button.                                                 |
| `progress`         | `Toast`                | `boolean`                                   | `false`          | Show the countdown progress bar (when `timeout > 0`).                    |
| `swipeDirection`   | `Toast`                | <Code>axis \| axis\[]</Code>                | by position      | Allowed swipe-to-dismiss directions.                                     |
| `closeLabel`       | `Toast` / `ToastClose` | `string`                                    | `'Dismiss'`      | Accessible label for the close button.                                   |
| `variant` / `size` | `ToastAction`          | `buttonVariants`                            | `primary` / `sm` | Styles the action button like a [`Button`](/ui/components/react/button). |

## Accessibility [#accessibility]

* The `Toaster` viewport is a labelled landmark (an `aria-live` region); press **F6** to jump to it from anywhere on the page.
* New toasts are announced politely by default. Set `priority: 'high'` on important ones (errors, warnings) to interrupt and announce immediately.
* The close button carries an accessible label (`closeLabel`, default "Dismiss"); it's hidden from the a11y tree until the stack is hovered or focused, then revealed.
* Keep toast text short and self-contained — they disappear, so don't put the only copy of critical information in one.
* All enter/exit, stacking, and swipe animations honour `prefers-reduced-motion`, and the countdown progress bar is hidden under reduced motion.


# Table of Content (TOC) (/ui/components/react/toc)



<Playground component="toc" />

## Usage [#usage]

```tsx
import { Toc, TocList, TocItem, TocLink } from '@appica/ui-react/toc'
```

```tsx
<Toc aria-label="On this page">
  <TocList>
    <TocItem>
      <TocLink href="#installation">Installation</TocLink>
    </TocItem>
    <TocItem>
      <TocLink href="#usage">Usage</TocLink>
    </TocItem>
    <TocItem>
      <TocLink href="#configuration" depth={3}>
        Configuration
      </TocLink>
    </TocItem>
    <TocItem>
      <TocLink href="#faq">FAQ</TocLink>
    </TocItem>
  </TocList>
</Toc>
```

`Toc` is an "on this page" sidebar that watches the document and highlights the link whose heading is currently in view. Each `TocLink`'s `href` points at a heading's `id` (`href="#installation"` → `<h2 id="installation">`); the component registers those targets, observes them with an `IntersectionObserver`, and marks the visible ones `data-active`. When several headings share the screen the indicator stretches to cover the whole span, and `aria-current` lands on the topmost one.

It's purely compositional — no list data is passed in. Lay out the items yourself (typically generated from your page's headings) and set each link's `depth` to match its heading level so deeper headings indent. Everything is driven by the real DOM, so the headings just need matching `id`s.

Because scroll-spy needs a scroll position to track, the live examples below put the article in a self-contained scrolling panel — scroll inside it to watch the active link follow along. They also intercept link clicks to scroll that panel rather than the page; on a real page where the TOC tracks the document, you'd skip that and let the anchor jump the page natively.

## Examples [#examples]

### Default [#default]

A flat list of top-level headings. As you scroll the article, the link tracking the visible heading lights up and the indicator slides to it.

```tsx
'use client'

import { type MouseEvent } from 'react'
import { Toc, TocList, TocItem, TocLink } from '@appica/ui-react/toc'

const SECTIONS = [
  {
    id: 'toc-demo-getting-started',
    title: 'Getting started',
    body: 'Install the package with your favourite package manager and import the component you need. Every component ships from its own subpath, so your bundler only pulls in what you actually use and tree-shaking does the rest. There is no global stylesheet to wire up beyond the theme layer — the components bring their own styles, so a fresh install renders correctly with nothing else configured. A component behaves identically on the server and the client, so you can drop it anywhere in a React tree without reaching for a "use client" boundary unless your own code needs one. Sensible defaults mean most components look right immediately, and every visual choice can be overridden through props or class names. Once you are comfortable with one component the rest follow the same composition-first API, so there is very little new to learn as you reach for more of them across a project.',
  },
  {
    id: 'toc-demo-theming',
    title: 'Theming',
    body: 'Colors, radii, and motion are driven entirely by CSS variables. Override them at any level of the tree to retheme a single section or the whole application, with no build step or configuration. Light and dark modes are just two sets of the same variables, so a theme toggle is a single class on a parent element. Because everything resolves at runtime, you can even let users tweak the palette live.',
  },
  {
    id: 'toc-demo-accessibility',
    title: 'Accessibility',
    body: 'Components follow the WAI-ARIA patterns out of the box — roving focus, correct roles, and labelled landmarks — so keyboard and screen-reader support comes for free. Focus is trapped and restored where it should be, and every interactive element is reachable by keyboard. We test the primitives against axe to catch regressions early. You are still responsible for naming your own instances, but the wiring underneath is handled.',
  },
  {
    id: 'toc-demo-rtl',
    title: 'Right-to-left',
    body: 'Logical properties and a direction provider mean every component mirrors cleanly under dir="rtl" without any extra work on your part. Padding, borders, and animations all flip to follow the reading direction. Arrow-key navigation and popup placement respect the resolved direction too. Switching a whole app to RTL is a single attribute on the html element plus the provider.',
  },
]

// Demo only: scrolls within this panel instead of the page so the example stays put.
// A page-level TOC needs none of this — let the anchor jump the page natively.
function scrollWithinPanel(event: MouseEvent<HTMLElement>) {
  const link = (event.target as HTMLElement).closest('a[href^="#"]')
  if (!link) return
  const id = decodeURIComponent(link.getAttribute('href')!.slice(1))
  const heading = document.getElementById(id)
  const panel = heading?.closest('[data-scroll-panel]')
  if (!heading || !panel) return
  event.preventDefault()
  const gap = parseFloat(getComputedStyle(heading).scrollMarginTop) || 0
  const top = heading.getBoundingClientRect().top - panel.getBoundingClientRect().top + panel.scrollTop - gap
  panel.scrollTo({ top, behavior: 'smooth' })
}

export default function TocDefault() {
  return (
    <div className="flex w-full max-w-xl gap-4">
      <div
        data-scroll-panel
        className="border-border h-64 flex-1 scrollbar-none overflow-auto rounded-lg border p-4 [&::-webkit-scrollbar]:hidden"
      >
        {SECTIONS.map((section) => (
          <section key={section.id} className="mb-6 last:mb-0">
            <h3 id={section.id} className="text-foreground-intense mb-2 scroll-mt-6 font-semibold">
              {section.title}
            </h3>
            <p className="text-sm leading-relaxed">{section.body}</p>
          </section>
        ))}
      </div>

      <Toc className="w-38 shrink-0" onClick={scrollWithinPanel}>
        <TocList>
          {SECTIONS.map((section) => (
            <TocItem key={section.id}>
              <TocLink href={`#${section.id}`}>{section.title}</TocLink>
            </TocItem>
          ))}
        </TocList>
      </Toc>
    </div>
  )
}
```

### Nested headings [#nested-headings]

Give each `TocLink` a `depth` (2–6) matching its heading level and deeper entries indent automatically — the typical `<h2>`/`<h3>` outline. The active indicator runs down the shared left rail regardless of depth.

```tsx
'use client'

import { type MouseEvent } from 'react'
import { Toc, TocList, TocItem, TocLink } from '@appica/ui-react/toc'

const HEADINGS = [
  {
    id: 'toc-nested-install',
    title: 'Installation',
    depth: 2,
    body: 'Add the package to your project before importing anything. It has a single peer dependency on React and works with any bundler that understands ES modules, so there is no special configuration to add and nothing to register globally. Pick the package manager your team already uses — the install command is the only thing that differs between them, and the resulting dependency is identical. In a monorepo, add it to the package that actually renders UI rather than the workspace root, so each app pins the version it depends on and upgrades stay scoped. Commit your lockfile afterwards so every environment, including CI, resolves exactly the same build of the library. Once it is installed you can import any component from its own subpath and start composing immediately, with no build step and no global stylesheet to wire up first.',
  },
  {
    id: 'toc-nested-pnpm',
    title: 'pnpm',
    depth: 3,
    body: 'Run pnpm add to install it into the current workspace. In a monorepo, scope it to the package that renders UI rather than the root so versions stay explicit per app.',
  },
  {
    id: 'toc-nested-npm',
    title: 'npm',
    depth: 3,
    body: 'npm install works identically and writes the dependency to your package.json. Commit the lockfile so every environment resolves the same version of the library.',
  },
  {
    id: 'toc-nested-usage',
    title: 'Usage',
    depth: 2,
    body: 'Import the parts you need and compose them. Components are designed to be assembled rather than configured through long prop lists, so most screens are just JSX. The pieces share a styling context, so a variant set once flows down.',
  },
  {
    id: 'toc-nested-import',
    title: 'Importing',
    depth: 3,
    body: 'Each component lives at its own subpath, so import from there rather than a barrel. This keeps your bundle lean and makes it obvious which parts a file actually depends on.',
  },
  {
    id: 'toc-nested-compose',
    title: 'Composing',
    depth: 3,
    body: 'Nest the sub-components to build the shape you want, and reach for the render prop when you need to project a part onto your own element. Composition is the primary extension point across the whole library.',
  },
  {
    id: 'toc-nested-faq',
    title: 'FAQ',
    depth: 2,
    body: 'Answers to the questions that come up most often, from server-component support to bundle size and theming. If something is missing here, the per-component pages go deeper.',
  },
]

// Demo only: scrolls within this panel instead of the page so the example stays put.
// A page-level TOC needs none of this — let the anchor jump the page natively.
function scrollWithinPanel(event: MouseEvent<HTMLElement>) {
  const link = (event.target as HTMLElement).closest('a[href^="#"]')
  if (!link) return
  const id = decodeURIComponent(link.getAttribute('href')!.slice(1))
  const heading = document.getElementById(id)
  const panel = heading?.closest('[data-scroll-panel]')
  if (!heading || !panel) return
  event.preventDefault()
  const gap = parseFloat(getComputedStyle(heading).scrollMarginTop) || 0
  const top = heading.getBoundingClientRect().top - panel.getBoundingClientRect().top + panel.scrollTop - gap
  panel.scrollTo({ top, behavior: 'smooth' })
}

export default function TocNested() {
  return (
    <div className="flex w-full max-w-xl gap-4">
      <div
        data-scroll-panel
        className="border-border h-64 flex-1 scrollbar-none overflow-auto rounded-lg border p-4 [&::-webkit-scrollbar]:hidden"
      >
        {HEADINGS.map((heading) => (
          <section key={heading.id} className="mb-6 last:mb-0">
            {heading.depth === 2 ? (
              <h3 id={heading.id} className="text-foreground-intense mb-2 scroll-mt-6 font-semibold">
                {heading.title}
              </h3>
            ) : (
              <h4 id={heading.id} className="text-foreground-intense mb-2 scroll-mt-6 text-sm font-medium">
                {heading.title}
              </h4>
            )}
            <p className="text-sm leading-relaxed">{heading.body}</p>
          </section>
        ))}
      </div>

      <Toc className="w-38 shrink-0" onClick={scrollWithinPanel}>
        <TocList>
          {HEADINGS.map((heading) => (
            <TocItem key={heading.id}>
              <TocLink href={`#${heading.id}`} depth={heading.depth}>
                {heading.title}
              </TocLink>
            </TocItem>
          ))}
        </TocList>
      </Toc>
    </div>
  )
}
```

### With icons [#with-icons]

`TocLink` takes arbitrary children, so you can prefix each entry with an [icon](/ui/icons). Set the link to `flex` and size the SVG; the icon inherits the link's color, so it brightens along with the label when active.

```tsx
'use client'

import { type MouseEvent } from 'react'
import { Toc, TocList, TocItem, TocLink } from '@appica/ui-react/toc'
import { Rocket, Palette, Accessible, TextDirectionRtl } from '@appica/icons-react'

const SECTIONS = [
  {
    id: 'toc-icons-getting-started',
    title: 'Getting started',
    icon: Rocket,
    body: 'Install the package and import the component you need from its own subpath. There is nothing global to configure — components bring their own styles, so you can drop one into a page and it renders correctly straight away, with no provider or stylesheet to register first. Tree-shaking keeps your bundle to only the parts you import, and there is no runtime style injection to worry about. A component works the same whether it is rendered on the server or the client, so you can use it anywhere in a React tree without a "use client" boundary unless your own code needs one. Sensible defaults mean it looks right immediately, and you can override any of it through props or class names. Once you are comfortable with one component the rest follow the same composition-first API, so there is very little new to learn as you reach for more of them.',
  },
  {
    id: 'toc-icons-theming',
    title: 'Theming',
    icon: Palette,
    body: 'Colors, radii, and motion are driven by CSS variables you can override anywhere in the tree. Light and dark are two sets of the same variables, so a theme switch is a single class on a parent. There is no build step involved, and values resolve live at runtime.',
  },
  {
    id: 'toc-icons-accessibility',
    title: 'Accessibility',
    icon: Accessible,
    body: 'Components follow the WAI-ARIA patterns out of the box, so keyboard support and screen-reader semantics come for free. Focus management, roles, and labelled landmarks are handled by the primitives. You still name your own instances, but the wiring underneath is done for you.',
  },
  {
    id: 'toc-icons-rtl',
    title: 'Right-to-left',
    icon: TextDirectionRtl,
    body: 'Logical properties mean every component mirrors cleanly under dir="rtl". Padding, borders, focus order, and popup placement all flip to follow the reading direction. Switching the whole app is a single attribute plus the direction provider.',
  },
]

// Demo only: scrolls within this panel instead of the page so the example stays put.
// A page-level TOC needs none of this — let the anchor jump the page natively.
function scrollWithinPanel(event: MouseEvent<HTMLElement>) {
  const link = (event.target as HTMLElement).closest('a[href^="#"]')
  if (!link) return
  const id = decodeURIComponent(link.getAttribute('href')!.slice(1))
  const heading = document.getElementById(id)
  const panel = heading?.closest('[data-scroll-panel]')
  if (!heading || !panel) return
  event.preventDefault()
  const gap = parseFloat(getComputedStyle(heading).scrollMarginTop) || 0
  const top = heading.getBoundingClientRect().top - panel.getBoundingClientRect().top + panel.scrollTop - gap
  panel.scrollTo({ top, behavior: 'smooth' })
}

export default function TocWithIcons() {
  return (
    <div className="flex w-full max-w-xl gap-4">
      <div
        data-scroll-panel
        className="border-border h-64 flex-1 scrollbar-none overflow-auto rounded-lg border p-4 [&::-webkit-scrollbar]:hidden"
      >
        {SECTIONS.map((section) => (
          <section key={section.id} className="mb-6 last:mb-0">
            <h3 id={section.id} className="text-foreground-intense mb-2 scroll-mt-6 font-semibold">
              {section.title}
            </h3>
            <p className="text-sm leading-relaxed">{section.body}</p>
          </section>
        ))}
      </div>

      <Toc className="w-38 shrink-0" onClick={scrollWithinPanel}>
        <TocList>
          {SECTIONS.map((section) => (
            <TocItem key={section.id}>
              <TocLink href={`#${section.id}`} className="flex items-center gap-2 [&_svg]:size-4 [&_svg]:shrink-0">
                <section.icon />
                {section.title}
              </TocLink>
            </TocItem>
          ))}
        </TocList>
      </Toc>
    </div>
  )
}
```

## Scroll offset [#scroll-offset]

On a real page with a sticky header, headings become "current" a little too early — they're technically in view but hidden behind the header. Pass `rootMargin` to `Toc` to shrink the observer's viewport from the top by the header's height, so a heading only counts as active once it clears it:

```tsx
<Toc rootMargin="-80px 0px 0px 0px">{/* … */}</Toc>
```

The value is a standard [`IntersectionObserver` `rootMargin`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver#rootmargin) string (`top right bottom left`). A negative top inset pulls the active boundary down below your header.

## Router links [#router-links]

`TocLink` is built on Base UI's [`useRender`](https://base-ui.com/react/utils/use-render), so you can project it onto your framework's link with `render` while keeping the scroll-spy wiring and active styling:

```tsx
<TocLink href="#usage" render={<Link href="#usage" />}>
  Usage
</TocLink>
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The list's rail and active indicator move to the right edge and the depth indentation flips, since both are built from CSS logical properties. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="toc" />

## API reference [#api-reference]

Each part forwards every remaining prop to its underlying element (`nav`, `ul`, `li`, `a`). The tables below list the Appica additions and the most common props.

### Toc [#toc]

The navigation landmark and scroll-spy provider. Renders a `<nav aria-label="Table of contents">`.

| Prop         | <ColMinWidth width="200">Type</ColMinWidth> | Default               | <ColMinWidth width="240">Description</ColMinWidth>                                                                    |
| ------------ | ------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `rootMargin` | `string`                                    | `'0px'`               | `IntersectionObserver` `rootMargin` (`top right bottom left`) — offset the active boundary, e.g. for a sticky header. |
| `aria-label` | `string`                                    | `'Table of contents'` | Accessible name for the navigation landmark.                                                                          |
| `children`   | `ReactNode`                                 | —                     | Usually a `TocList` (with an optional heading above it).                                                              |
| `className`  | `string`                                    | —                     | Extra classes, merged via `tailwind-merge`.                                                                           |

### TocList [#toclist]

The list of entries, carrying the shared rail and sliding active indicator. Renders a `<ul role="list">`.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | `TocItem`s.                                 |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### TocItem [#tocitem]

One entry's `<li>` wrapper.

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | —       | A `TocLink`.                                |
| `className` | `string`    | —       | Extra classes, merged via `tailwind-merge`. |

### TocLink [#toclink]

A link to one heading. Registers its target for scroll-spy and reflects the active state. Built on Base UI's [`useRender`](https://base-ui.com/react/utils/use-render); renders an `<a>` unless you project it with `render`.

| Prop        | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | <ColMinWidth width="220">Description</ColMinWidth>                                               |
| ----------- | ----------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `href`      | `string`                                                    | —       | **Required.** The target heading, as a hash (`#id`). The `id` after `#` is the heading observed. |
| `depth`     | `number`                                                    | `2`     | Heading level (2–6); controls the indentation. Higher = deeper indent.                           |
| `render`    | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render as your own element (e.g. a router `Link`). The `state` exposes `active`.                 |
| `className` | <Code>string \| ((state) => string)</Code>                  | —       | Extra classes, merged via `tailwind-merge`. May be a function of the `{ active }` state.         |

The link exposes `data-active` while its heading is in view and `aria-current="true"` on the topmost active link — both available for styling.

## Accessibility [#accessibility]

* `Toc` renders a `<nav>` with a default `aria-label="Table of contents"`; override it (e.g. `"On this page"`) to suit the surrounding page. The list is a `role="list"` of plain links.
* The topmost in-view link carries `aria-current="true"`, so assistive tech announces the reader's current position.
* Links are ordinary anchors, fully keyboard-focusable, and activating one jumps to its heading — pair headings with `scroll-mt-*` so they aren't hidden under a sticky header on arrival.
* The active indicator and link transitions honour `prefers-reduced-motion`.
* Scroll-spy is presentational: it only updates `data-active`/`aria-current`, never moving focus or scrolling on its own.


# Toggle Group (/ui/components/react/toggle-group)



## Usage [#usage]

```tsx
import { ToggleGroup } from '@appica/ui-react/toggle-group'
import { Toggle } from '@appica/ui-react/toggle'
import { Button } from '@appica/ui-react/button'
```

```tsx
<ToggleGroup aria-label="Text alignment" defaultValue={['center']}>
  <Toggle
    value="left"
    aria-label="Align left"
    render={
      <Button variant="ghost" size="icon-md">
        <AlignLeft />
      </Button>
    }
  />
  <Toggle
    value="center"
    aria-label="Align center"
    render={
      <Button variant="ghost" size="icon-md">
        <AlignCenter />
      </Button>
    }
  />
  <Toggle
    value="right"
    aria-label="Align right"
    render={
      <Button variant="ghost" size="icon-md">
        <AlignRight />
      </Button>
    }
  />
</ToggleGroup>
```

`ToggleGroup` lays out a row of [`Toggle`](/ui/components/react/toggle)s and tracks which ones are pressed as a string array of their `value`s. It's single-select by default — pressing one toggle releases the previous — and becomes multi-select with the `multiple` prop, where any number of toggles can stay pressed at once. Drive it uncontrolled with `defaultValue`, or controlled with `value` + `onValueChange`.

`Toggle` ships no styling of its own, so give each one a look by composing it with [`Button`](/ui/components/react/button) through `render={<Button … />}` — `Button` already reacts to `data-pressed`, so the pressed state comes for free. Because a toggle group is a `role="group"` rather than a labelable form control, name it with `aria-label` or `aria-labelledby` — never with a `<Field>`/`FieldLabel`.

## Examples [#examples]

### Single selection [#single-selection]

By default the group is single-select: pressing a toggle releases whichever one was pressed before, so exactly one stays active.

```tsx
import { Button } from '@appica/ui-react/button'
import { Toggle } from '@appica/ui-react/toggle'
import { ToggleGroup } from '@appica/ui-react/toggle-group'
import { AlignLeft, AlignCenter, AlignRight } from '@appica/icons-react'

export default function ToggleGroupSingle() {
  return (
    <ToggleGroup aria-label="Text alignment" defaultValue={['center']}>
      <Toggle
        value="left"
        aria-label="Align left"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignLeft />
          </Button>
        }
      />
      <Toggle
        value="center"
        aria-label="Align center"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignCenter />
          </Button>
        }
      />
      <Toggle
        value="right"
        aria-label="Align right"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignRight />
          </Button>
        }
      />
    </ToggleGroup>
  )
}
```

### Multiple selection [#multiple-selection]

Add `multiple` to let several toggles stay pressed at once — handy for independent formatting options like bold, italic, and underline.

```tsx
import { Button } from '@appica/ui-react/button'
import { Toggle } from '@appica/ui-react/toggle'
import { ToggleGroup } from '@appica/ui-react/toggle-group'
import { Bold, Italic, Underline } from '@appica/icons-react'

export default function ToggleGroupMultiple() {
  return (
    <ToggleGroup aria-label="Text formatting" multiple defaultValue={['bold']}>
      <Toggle
        value="bold"
        aria-label="Bold"
        render={
          <Button variant="ghost" size="icon-md">
            <Bold />
          </Button>
        }
      />
      <Toggle
        value="italic"
        aria-label="Italic"
        render={
          <Button variant="ghost" size="icon-md">
            <Italic />
          </Button>
        }
      />
      <Toggle
        value="underline"
        aria-label="Underline"
        render={
          <Button variant="ghost" size="icon-md">
            <Underline />
          </Button>
        }
      />
    </ToggleGroup>
  )
}
```

### Vertical orientation [#vertical-orientation]

Set `orientation="vertical"` to stack the toggles in a column. Arrow-key focus follows the same axis.

```tsx
import { Button } from '@appica/ui-react/button'
import { Toggle } from '@appica/ui-react/toggle'
import { ToggleGroup } from '@appica/ui-react/toggle-group'
import { AlignLeft, AlignCenter, AlignRight } from '@appica/icons-react'

export default function ToggleGroupVertical() {
  return (
    <ToggleGroup aria-label="Text alignment" orientation="vertical" defaultValue={['left']}>
      <Toggle
        value="left"
        aria-label="Align left"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignLeft />
          </Button>
        }
      />
      <Toggle
        value="center"
        aria-label="Align center"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignCenter />
          </Button>
        }
      />
      <Toggle
        value="right"
        aria-label="Align right"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignRight />
          </Button>
        }
      />
    </ToggleGroup>
  )
}
```

### Disabled [#disabled]

Set `disabled` on the group to disable every toggle inside it at once.

```tsx
import { Button } from '@appica/ui-react/button'
import { Toggle } from '@appica/ui-react/toggle'
import { ToggleGroup } from '@appica/ui-react/toggle-group'
import { AlignLeft, AlignCenter, AlignRight } from '@appica/icons-react'

export default function ToggleGroupDisabled() {
  return (
    <ToggleGroup aria-label="Text alignment" disabled defaultValue={['center']}>
      <Toggle
        value="left"
        aria-label="Align left"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignLeft />
          </Button>
        }
      />
      <Toggle
        value="center"
        aria-label="Align center"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignCenter />
          </Button>
        }
      />
      <Toggle
        value="right"
        aria-label="Align right"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignRight />
          </Button>
        }
      />
    </ToggleGroup>
  )
}
```

### Color swatches (controlled) [#color-swatches-controlled]

A controlled single-select group, used as a color picker. Here the toggles aren't button-shaped, so they're styled directly rather than composed with `Button` — each bare `Toggle` is a 16px circular swatch carrying its color, and the pressed one gets an offset `border-inverse` ring. Driving it with `value` + `onValueChange` keeps the selection in state, which the label above reads to name the current color.

```tsx
'use client'

import * as React from 'react'
import { Toggle } from '@appica/ui-react/toggle'
import { ToggleGroup } from '@appica/ui-react/toggle-group'

const SWATCHES = [
  { value: 'sage', name: 'Sage', color: '#8fb478' },
  { value: 'terracotta', name: 'Terracotta', color: '#cc8259' },
  { value: 'sand', name: 'Sand', color: '#d9ba6e' },
  { value: 'blush', name: 'Blush', color: '#db9385' },
  { value: 'denim', name: 'Denim', color: '#7e9cc9' },
]

export default function ToggleGroupSwatches() {
  const [value, setValue] = React.useState(['sage'])
  const selected = SWATCHES.find((swatch) => swatch.value === value[0])

  return (
    <div className="flex flex-col items-start gap-3">
      <span className="text-foreground-muted text-sm">
        Color - <span className="text-foreground-intense font-medium">{selected?.name}</span>
      </span>
      <ToggleGroup
        aria-label="Swatch color"
        className="gap-3"
        value={value}
        onValueChange={(next) => next.length > 0 && setValue(next)}
      >
        {SWATCHES.map((swatch) => (
          <Toggle
            key={swatch.value}
            value={swatch.value}
            aria-label={swatch.name}
            style={{ backgroundColor: swatch.color }}
            className="after:ring-border-inverse outline-ring relative size-4 rounded-full outline-offset-2 transition-transform after:pointer-events-none after:absolute after:-inset-0.5 after:scale-50 after:rounded-full after:opacity-0 after:ring-1 after:transition after:duration-200 after:ease-[cubic-bezier(0.175,0.885,0.32,1.5)] active:scale-90 data-pressed:after:scale-100 data-pressed:after:opacity-100 motion-reduce:transition-none motion-reduce:after:transition-none"
          />
        ))}
      </ToggleGroup>
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The toggles align to the start edge and arrow-key focus follows the resolved direction, so the first toggle sits on the right under RTL. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="toggle-group" />

## API reference [#api-reference]

`ToggleGroup` wraps [Base UI's Toggle Group](https://base-ui.com/react/components/toggle-group), renders with `role="group"`, and forwards `ref` and every remaining `<div>` attribute. Its children are [`Toggle`](/ui/components/react/toggle)s — each needs a `value` and an accessible name. To present a standalone toolbar, pass `role="toolbar"` yourself (don't nest one inside [`Toolbar`](/ui/components/react/toolbar), which is already a toolbar).

| Prop            | <ColMinWidth width="200">Type</ColMinWidth>                   | Default        | <ColMinWidth width="220">Description</ColMinWidth>                                                             |
| --------------- | ------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------- |
| `value`         | `string[]`                                                    | —              | The pressed toggles' `value`s, for controlled use. Pair with `onValueChange`.                                  |
| `defaultValue`  | `string[]`                                                    | —              | The initially pressed toggles, for uncontrolled use.                                                           |
| `onValueChange` | <Code>(value: string\[], eventDetails) => void</Code>         | —              | Called when the pressed set changes, with the new array of `value`s.                                           |
| `multiple`      | `boolean`                                                     | `false`        | Allow several toggles to be pressed at once. When `false`, pressing one releases the previous (single-select). |
| `orientation`   | <Code>'horizontal' \| 'vertical'</Code>                       | `'horizontal'` | Layout axis and the direction arrow keys move focus. Exposed as `data-orientation`.                            |
| `loopFocus`     | `boolean`                                                     | `true`         | Whether arrow-key focus wraps around from the last toggle to the first and back.                               |
| `disabled`      | `boolean`                                                     | `false`        | Disable every toggle in the group.                                                                             |
| `render`        | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —              | Replace the rendered element, or compose it with another component.                                            |
| `className`     | <Code>string \| ((state) => string)</Code>                    | —              | Extra classes, merged via `tailwind-merge`. May be a function of state.                                        |

## Accessibility [#accessibility]

* The group renders as a `role="group"`, so name it with `aria-label` or `aria-labelledby` — not a `<Field>`/`FieldLabel`, whose `<label for>` doesn't associate with a group.
* Arrow keys move focus between toggles via roving tabindex (the row has a single tab stop), following the group's `orientation`; `loopFocus` controls whether focus wraps at the ends.
* Space or Enter toggles the focused button, which exposes its pressed state through `aria-pressed`.
* Setting `disabled` on the group disables all of its toggles, removing them from the tab order.


# Toggle (/ui/components/react/toggle)



<Playground component="toggle" />

## Usage [#usage]

```tsx
import { Toggle } from '@appica/ui-react/toggle'
import { Button } from '@appica/ui-react/button'
```

```tsx
<Toggle
  aria-label="Bold"
  render={
    <Button variant="outline" size="icon-md">
      B
    </Button>
  }
/>
```

`Toggle` is a behavior primitive — it renders a `<button aria-pressed>` and ships **no visual styling of its own**. To make it look like anything, compose it with our [`Button`](/ui/components/react/button) through `render={<Button …/>}` (or apply `buttonVariants({ variant, size })` as `className`). `Button` already reacts to the pressed state via `data-pressed`, so the pressed look comes for free.

Use it uncontrolled with `defaultPressed`, or controlled with `pressed` + `onPressedChange`. Every toggle needs an accessible name: give an icon-only toggle an `aria-label`, or use visible text children. To build a set of mutually-exclusive or multi-select toggles, group them in a [`ToggleGroup`](/ui/components/react/toggle-group), where each `Toggle` carries a `value`.

## Examples [#examples]

### Composing with Button [#composing-with-button]

A toolbar of icon toggles, each rendered as an `outline` `Button`. The pressed state is styled automatically through `data-pressed`; the first toggle starts on with `defaultPressed`.

```tsx
import { Button } from '@appica/ui-react/button'
import { Toggle } from '@appica/ui-react/toggle'
import { Bold, Italic, Underline } from '@appica/icons-react'

export default function ToggleWithButton() {
  return (
    <div className="flex items-center gap-2">
      <Toggle
        defaultPressed
        aria-label="Bold"
        render={
          <Button variant="outline" size="icon-md">
            <Bold />
          </Button>
        }
      />
      <Toggle
        aria-label="Italic"
        render={
          <Button variant="outline" size="icon-md">
            <Italic />
          </Button>
        }
      />
      <Toggle
        aria-label="Underline"
        render={
          <Button variant="outline" size="icon-md">
            <Underline />
          </Button>
        }
      />
    </div>
  )
}
```

### States [#states]

A toggle is off or on, and either state can also be `disabled`. `disabled` removes it from the tab order and exposes `data-disabled` for styling.

```tsx
import { Button } from '@appica/ui-react/button'
import { Toggle } from '@appica/ui-react/toggle'

export default function ToggleStates() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Toggle
        aria-label="Off"
        render={
          <Button variant="outline" size="md">
            Off
          </Button>
        }
      />
      <Toggle
        defaultPressed
        aria-label="Pressed"
        render={
          <Button variant="outline" size="md">
            Pressed
          </Button>
        }
      />
      <Toggle
        disabled
        aria-label="Disabled"
        render={
          <Button variant="outline" size="md">
            Disabled
          </Button>
        }
      />
    </div>
  )
}
```

### Controlled [#controlled]

Hold the state yourself with `pressed` + `onPressedChange`, then derive the rest of the UI from it. Here a single boolean drives the whole row — the bell icon, the button's `variant`, the accessible label, and the helper text all follow the toggle's value.

```tsx
'use client'

import { useState } from 'react'
import { Button } from '@appica/ui-react/button'
import { Toggle } from '@appica/ui-react/toggle'
import { Bell, BellOff } from '@appica/icons-react'

export default function ToggleControlled() {
  const [enabled, setEnabled] = useState(true)
  return (
    <div className="flex w-full max-w-74 items-center justify-between gap-4 rounded-xl border p-4">
      <div className="flex flex-col gap-0.5">
        <span className="text-foreground-intense text-sm font-medium">Notifications</span>
        <span className="text-foreground-muted text-xs">
          {enabled ? "You'll be notified about new activity" : 'All notifications are paused'}
        </span>
      </div>
      <Toggle
        pressed={enabled}
        onPressedChange={setEnabled}
        aria-label={enabled ? 'Mute notifications' : 'Enable notifications'}
        render={
          <Button variant={enabled ? 'primary' : 'soft'} size="icon-md">
            {enabled ? <Bell /> : <BellOff />}
          </Button>
        }
      />
    </div>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

A row of toggles reorders from the start edge, following the resolved direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="toggle" />

## API reference [#api-reference]

`Toggle` wraps [Base UI's Toggle](https://base-ui.com/react/components/toggle) and passes every remaining prop (`ref`, `aria-*`, and native `<button>` attributes) straight through. It exposes `data-pressed` and `data-disabled` state attributes for styling — see the Base UI docs for the full surface.

| Prop              | <ColMinWidth width="200">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>                                    |
| ----------------- | ------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `pressed`         | `boolean`                                                     | —       | Controlled pressed state. Pair with `onPressedChange`.                                |
| `defaultPressed`  | `boolean`                                                     | `false` | Uncontrolled initial pressed state.                                                   |
| `onPressedChange` | <Code>(pressed: boolean, details) => void</Code>              | —       | Fires when the toggle is pressed or unpressed.                                        |
| `value`           | `string`                                                      | —       | Identity within a `ToggleGroup`; meaningless on a standalone toggle.                  |
| `disabled`        | `boolean`                                                     | `false` | Removes the toggle from the tab order and ignores interaction.                        |
| `nativeButton`    | `boolean`                                                     | `true`  | Whether the element passed to `render` is a native `<button>`.                        |
| `render`          | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Replace the rendered element, or compose it with another component (e.g. `Button`).   |
| `className`       | <Code>string \| ((state) => string)</Code>                    | —       | Extra classes on the button, merged via `tailwind-merge`. May be a function of state. |
| `style`           | <Code>CSSProperties \| ((state) => CSSProperties)</Code>      | —       | Inline styles, optionally derived from state.                                         |

## Accessibility [#accessibility]

* Renders a `<button>` with `aria-pressed` reflecting the current state. **Space** (or **Enter**) toggles it; **Tab** moves focus to and from it.
* A toggle needs an accessible name — give an icon-only toggle an `aria-label`, or use visible text children.
* `disabled` removes the toggle from the tab order and exposes `data-disabled` for styling.
* The pressed state is exposed as both `aria-pressed` (for assistive tech) and `data-pressed` (for styling) — `Button` uses the latter to paint its pressed look.


# Toolbar (/ui/components/react/toolbar)



## Usage [#usage]

```tsx
import { Toolbar, ToolbarButton, ToolbarGroup, ToolbarSeparator, ToolbarLink } from '@appica/ui-react/toolbar'
import { Button } from '@appica/ui-react/button'
```

```tsx
<Toolbar aria-label="Formatting">
  <ToolbarGroup aria-label="Text style">
    <ToolbarButton render={<Button variant="ghost">Bold</Button>} />
    <ToolbarButton render={<Button variant="ghost">Italic</Button>} />
  </ToolbarGroup>
  <ToolbarSeparator />
  <ToolbarLink href="#help">Help</ToolbarLink>
</Toolbar>
```

`Toolbar` is a `role="toolbar"` strip with a roving tabindex: the toolbar holds a single tab stop, and the arrow keys move focus between its items (with `Home`/`End` jumping to the ends). This keeps the whole group to one stop in the page's tab order while still letting keyboard users reach every control. Set `orientation="vertical"` to stack items and switch the arrow keys to the vertical axis; `disabled` disables every item at once.

The items are composed, not bespoke: `ToolbarButton` renders any button you pass to `render` — most often a ghost [`Button`](/ui/components/react/button) — so the toolbar inherits your existing styles while the toolbar wiring (focus order, `disabled`) is added on top. `ToolbarSeparator` always renders **perpendicular** to the toolbar (a horizontal toolbar gets vertical dividers, and vice-versa), so you never set its orientation by hand. Give the toolbar an accessible name with `aria-label`, and name each `ToolbarGroup` the same way.

A toolbar never reflows: its items keep their size, and when there isn't room the bar caps to the available width and scrolls along its axis instead (the scrollbar is hidden — the clipped edge already hints there's more). That's built in, so you don't wrap it yourself.

## Examples [#examples]

### Default [#default]

A table toolbar that mixes the part types: a `ToolbarInput` search box (rendered as an [`Input`](/ui/components/react/input)), a `ToolbarGroup` holding a ghost-[`Button`](/ui/components/react/button) `Filter` action, and an `Export` `ToolbarLink`. Each lands in the same roving-focus order, so one **Tab** reaches the strip and the arrow keys walk from the search box through to the link. On a narrow screen the bar scrolls sideways rather than reflowing — no wrapper needed.

```tsx
import { Search, Filter, SortAscending, Download } from '@appica/icons-react'
import { Button, buttonVariants } from '@appica/ui-react/button'
import { Input } from '@appica/ui-react/input'
import {
  Toolbar,
  ToolbarButton,
  ToolbarGroup,
  ToolbarInput,
  ToolbarLink,
  ToolbarSeparator,
} from '@appica/ui-react/toolbar'

export default function ToolbarDefault() {
  return (
    <Toolbar aria-label="Table actions">
      <ToolbarInput
        className="w-44"
        render={<Input startSlot={<Search />} placeholder="Search tasks…" aria-label="Search tasks" />}
      />

      <ToolbarGroup aria-label="Refine">
        <ToolbarButton
          render={
            <Button variant="ghost">
              <Filter data-icon="start" />
              Filter
            </Button>
          }
        />
      </ToolbarGroup>

      <ToolbarSeparator />

      <ToolbarLink href="#export" className={buttonVariants({ variant: 'ghost' })}>
        <Download data-icon="start" />
        Export
      </ToolbarLink>
    </Toolbar>
  )
}
```

### With a toggle group [#with-a-toggle-group]

A rich-text editing toolbar. The undo/redo `ToolbarGroup` and a font [`Select`](/ui/components/react/select) sit beside a true single-select alignment [`ToggleGroup`](/ui/components/react/toggle-group) — built by wrapping each `ToolbarButton render={<Toggle …/>}` in a `ToggleGroup`, so the toggles share one pressed value (picking an alignment releases the previous one) while still taking part in the toolbar's roving focus. The selection state is the group's own — no extra wiring.

```tsx
'use client'

import { ArrowBackUp, ArrowForwardUp, AlignLeft, AlignCenter, AlignRight, Typography } from '@appica/icons-react'
import { Button } from '@appica/ui-react/button'
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@appica/ui-react/select'
import { Toggle } from '@appica/ui-react/toggle'
import { ToggleGroup } from '@appica/ui-react/toggle-group'
import { Toolbar, ToolbarButton, ToolbarGroup, ToolbarSeparator } from '@appica/ui-react/toolbar'

export default function ToolbarWithToggles() {
  return (
    <Toolbar aria-label="Text formatting">
      <ToolbarGroup aria-label="History">
        <ToolbarButton
          render={
            <Button variant="ghost" size="icon-md" aria-label="Undo">
              <ArrowBackUp />
            </Button>
          }
        />
        <ToolbarButton
          render={
            <Button variant="ghost" size="icon-md" aria-label="Redo">
              <ArrowForwardUp />
            </Button>
          }
        />
      </ToolbarGroup>

      <ToolbarSeparator />

      <Select defaultValue="Inter" alignItemWithTrigger={false}>
        <ToolbarButton
          className="w-36"
          render={
            <SelectTrigger startSlot={<Typography />} aria-label="Font">
              <SelectValue />
            </SelectTrigger>
          }
        />
        <SelectContent>
          <SelectItem value="Geist">Geist</SelectItem>
          <SelectItem value="Inter">Inter</SelectItem>
          <SelectItem value="Georgia">Figrtree</SelectItem>
          <SelectItem value="Urbanist">Urbanist</SelectItem>
        </SelectContent>
      </Select>

      <ToolbarSeparator />

      <ToggleGroup defaultValue={['left']} aria-label="Alignment">
        <ToolbarButton
          render={
            <Toggle
              value="left"
              aria-label="Align left"
              render={
                <Button variant="ghost" size="icon-md">
                  <AlignLeft />
                </Button>
              }
            />
          }
        />
        <ToolbarButton
          render={
            <Toggle
              value="center"
              aria-label="Align center"
              render={
                <Button variant="ghost" size="icon-md">
                  <AlignCenter />
                </Button>
              }
            />
          }
        />
        <ToolbarButton
          render={
            <Toggle
              value="right"
              aria-label="Align right"
              render={
                <Button variant="ghost" size="icon-md">
                  <AlignRight />
                </Button>
              }
            />
          }
        />
      </ToggleGroup>
    </Toolbar>
  )
}
```

### Vertical orientation [#vertical-orientation]

Set `orientation="vertical"` to stack the items into a column — here a formatting group and a clipboard group. The arrow keys follow the vertical axis and the `ToolbarSeparator` between the groups flips to a horizontal divider automatically.

```tsx
import { Bold, Italic, Underline, Copy, Scissors } from '@appica/icons-react'
import { Button } from '@appica/ui-react/button'
import { Toolbar, ToolbarButton, ToolbarGroup, ToolbarSeparator } from '@appica/ui-react/toolbar'

export default function ToolbarVertical() {
  return (
    <Toolbar aria-label="Formatting" orientation="vertical">
      <ToolbarGroup aria-label="Text style">
        <ToolbarButton
          render={
            <Button variant="ghost" size="icon-md" aria-label="Bold">
              <Bold />
            </Button>
          }
        />
        <ToolbarButton
          render={
            <Button variant="ghost" size="icon-md" aria-label="Italic">
              <Italic />
            </Button>
          }
        />
        <ToolbarButton
          render={
            <Button variant="ghost" size="icon-md" aria-label="Underline">
              <Underline />
            </Button>
          }
        />
      </ToolbarGroup>

      <ToolbarSeparator />

      <ToolbarGroup aria-label="Clipboard">
        <ToolbarButton
          render={
            <Button variant="ghost" size="icon-md" aria-label="Copy">
              <Copy />
            </Button>
          }
        />
        <ToolbarButton
          render={
            <Button variant="ghost" size="icon-md" aria-label="Cut">
              <Scissors />
            </Button>
          }
        />
      </ToolbarGroup>
    </Toolbar>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

Items and groups align to the start edge and the arrow-key focus order follows the resolved direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<RtlPreview component="toolbar" />

## API reference [#api-reference]

`Toolbar` wraps [Base UI's Toolbar](https://base-ui.com/react/components/toolbar). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the most common props.

### Toolbar [#toolbar]

The root strip. Renders a `role="toolbar"` `<div>` and exposes `data-orientation`.

| Prop          | <ColMinWidth width="180">Type</ColMinWidth>                   | Default        | <ColMinWidth width="220">Description</ColMinWidth>                      |
| ------------- | ------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------- |
| `orientation` | <Code>'horizontal' \| 'vertical'</Code>                       | `'horizontal'` | Layout axis; also the axis the arrow keys move focus along.             |
| `disabled`    | `boolean`                                                     | `false`        | Disable every item in the toolbar at once.                              |
| `loopFocus`   | `boolean`                                                     | `true`         | Wrap focus to the other end when arrowing past the first or last item.  |
| `render`      | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —              | Replace the `<div>`, or compose it with another component.              |
| `className`   | <Code>string \| ((state) => string)</Code>                    | —              | Extra classes, merged via `tailwind-merge`. May be a function of state. |

Also forwards `ref` and every remaining native `<div>` attribute.

### ToolbarButton [#toolbarbutton]

A toolbar item button, usually composed with a [`Button`](/ui/components/react/button) via `render`.

| Prop                    | <ColMinWidth width="180">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>                 |
| ----------------------- | ------------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| `disabled`              | `boolean`                                                     | `false` | Disable just this item.                                            |
| `focusableWhenDisabled` | `boolean`                                                     | `true`  | Keep a disabled item reachable by the roving focus.                |
| `render`                | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Render-as: pass your own button (e.g. `<Button variant="ghost">`). |
| `className`             | `string`                                                      | —       | Extra classes, merged via `tailwind-merge`.                        |

### ToolbarLink [#toolbarlink]

A link item (`<a href>`, `role="link"`) that joins the roving focus order.

| Prop        | <ColMinWidth width="180">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>            |
| ----------- | ------------------------------------------------------------- | ------- | ------------------------------------------------------------- |
| `href`      | `string`                                                      | —       | The link target.                                              |
| `render`    | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Render-as: compose with a framework `<Link>` or other anchor. |
| `className` | `string`                                                      | —       | Extra classes, merged via `tailwind-merge`.                   |

### ToolbarInput [#toolbarinput]

An input item that lives in the toolbar's focus order — a search box or inline value field.

| Prop                    | <ColMinWidth width="180">Type</ColMinWidth>                   | Default | <ColMinWidth width="220">Description</ColMinWidth>                |
| ----------------------- | ------------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| `disabled`              | `boolean`                                                     | `false` | Disable just this item.                                           |
| `focusableWhenDisabled` | `boolean`                                                     | `true`  | Keep a disabled input reachable by the roving focus.              |
| `render`                | <Code>ReactElement \| ((props, state) => ReactElement)</Code> | —       | Render-as: compose with an [`Input`](/ui/components/react/input). |
| `className`             | `string`                                                      | —       | Extra classes, merged via `tailwind-merge`.                       |

### ToolbarGroup [#toolbargroup]

Groups related items under a single `role="group"`. Lay out as a flex row (or column under `data-orientation=vertical`).

| Prop         | <ColMinWidth width="180">Type</ColMinWidth> | Default | <ColMinWidth width="220">Description</ColMinWidth> |
| ------------ | ------------------------------------------- | ------- | -------------------------------------------------- |
| `disabled`   | `boolean`                                   | `false` | Disable every item in the group.                   |
| `aria-label` | `string`                                    | —       | Names the group for assistive tech.                |
| `className`  | <Code>string \| ((state) => string)</Code>  | —       | Extra classes, merged via `tailwind-merge`.        |

### ToolbarSeparator [#toolbarseparator]

A divider rendered **perpendicular** to the toolbar — vertical inside a horizontal toolbar, horizontal inside a vertical one.

| Prop          | <ColMinWidth width="180">Type</ColMinWidth> | Default                 | <ColMinWidth width="220">Description</ColMinWidth>                    |
| ------------- | ------------------------------------------- | ----------------------- | --------------------------------------------------------------------- |
| `orientation` | <Code>'horizontal' \| 'vertical'</Code>     | opposite of the toolbar | Override the divider axis. Rarely needed — the default flips for you. |
| `className`   | <Code>string \| ((state) => string)</Code>  | —                       | Extra classes, merged via `tailwind-merge`.                           |

## Accessibility [#accessibility]

* The root renders `role="toolbar"`; give it an accessible name with `aria-label` (or `aria-labelledby`).
* Focus uses a **roving tabindex** — the toolbar is a single tab stop, and the arrow keys move focus between items along the toolbar's orientation.
* **Home** / **End** jump focus to the first and last items.
* Name each `ToolbarGroup` with `aria-label` so its `role="group"` is announced.
* `disabled` on the toolbar (or a group) disables its items; items stay focusable when disabled (`focusableWhenDisabled`) so keyboard users can still reach and read them.


# Tooltip (/ui/components/react/tooltip)



<Playground component="tooltip" />

## Usage [#usage]

```tsx
import { TooltipProvider, Tooltip, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'
import { Button } from '@appica/ui-react/button'
```

```tsx
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger
      render={
        <Button variant="outline" size="icon-md" aria-label="Add to favorites">
          <Heart />
        </Button>
      }
    />
    <TooltipContent>Add to favorites</TooltipContent>
  </Tooltip>
</TooltipProvider>
```

A tooltip is a short, **non-interactive hint** that appears when its trigger is hovered or focused — most often to name an icon-only control. The trigger is wired to the popup through `render`: pass it your own [`Button`](/ui/components/react/button) (or any focusable element) and the tooltip manages its description and open/close.

`Tooltip` is a compound component built on [Base UI's Tooltip](https://base-ui.com/react/components/tooltip):

* **`TooltipProvider`** — wraps a group of tooltips and shares the hover `delay`. Place one high in your app so that once one tooltip has opened, moving to a sibling shows its tooltip instantly instead of waiting out the delay again.
* **`Tooltip`** — the root for a single tooltip. Holds its open state; set `trackCursorAxis` to follow the pointer or `disabled` to suppress it.
* **`TooltipTrigger`** — the element the tooltip describes. Use `render` to project it onto your own control.
* **`TooltipContent`** — the portalled, auto-positioned popup. Draws the bubble and the optional `arrow`, and accepts the shared [floating props](/ui/components/react/popover) (`side`, `align`, `sideOffset`, …).

<Callout type="warning" title="Tooltips aren't reachable on touch or by screen readers">
  A tooltip only appears on hover/focus, so its text is invisible on touch devices and isn't announced as the control's
  name. Always give an icon-only trigger its own `aria-label` (or visible text) — the tooltip is a visual nicety on top,
  not the accessible name. For content that must be reachable by everyone, use a [`Popover`](/ui/components/react/popover).
</Callout>

Reach for a `Tooltip` to **label or hint at** a control. For rich or interactive floating content, use a [`Popover`](/ui/components/react/popover); for a list of actions, use a [`Dropdown Menu`](/ui/components/react/dropdown-menu); for a hover preview of a link, use a [`Preview Card`](/ui/components/react/preview-card).

## Examples [#examples]

### Side & alignment [#side--alignment]

Position the bubble with `side` (`top` / `right` / `bottom` / `left`) and `align` (`start` / `center` / `end`) on `TooltipContent`. It flips and shifts automatically to stay in view.

```tsx
import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'
import { Button } from '@appica/ui-react/button'

const SIDES = ['top', 'right', 'bottom', 'left'] as const

export default function TooltipSides() {
  return (
    <TooltipProvider>
      <div className="flex flex-wrap items-center justify-center gap-3">
        {SIDES.map((side) => (
          <Tooltip key={side}>
            <TooltipTrigger render={<Button variant="outline">{side}</Button>} />
            <TooltipContent side={side}>Opens on the {side}</TooltipContent>
          </Tooltip>
        ))}
      </div>
    </TooltipProvider>
  )
}
```

### Shared provider [#shared-provider]

Wrap a group of controls — here a [`Toolbar`](/ui/components/react/toolbar) of formatting buttons — in a single `TooltipProvider`. The first tooltip waits out the `delay`; once it's open, sweeping the pointer to a neighbour shows that tooltip immediately. Within that grace window the tooltip also skips its open/close animation, so it reads as one tooltip *relocating* across the toolbar rather than each popup re-bouncing.

```tsx
import * as React from 'react'
import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'
import { Toolbar, ToolbarButton, ToolbarSeparator } from '@appica/ui-react/toolbar'
import { Button } from '@appica/ui-react/button'
import { Bold, Italic, Underline, Strikethrough, Link } from '@appica/icons-react'

const ACTIONS = [
  { label: 'Bold', Icon: Bold },
  { label: 'Italic', Icon: Italic },
  { label: 'Underline', Icon: Underline },
  { label: 'Strikethrough', Icon: Strikethrough },
  { label: 'Link', Icon: Link },
] as const

export default function TooltipProviderDemo() {
  return (
    <TooltipProvider delay={400}>
      <Toolbar aria-label="Text formatting">
        {ACTIONS.map(({ label, Icon }, index) => (
          <React.Fragment key={label}>
            {index === ACTIONS.length - 1 && <ToolbarSeparator />}
            <Tooltip>
              <TooltipTrigger
                render={
                  <ToolbarButton
                    render={
                      <Button variant="ghost" size="icon-md" aria-label={label}>
                        <Icon />
                      </Button>
                    }
                  />
                }
              />
              <TooltipContent>{label}</TooltipContent>
            </Tooltip>
          </React.Fragment>
        ))}
      </Toolbar>
    </TooltipProvider>
  )
}
```

### Rich content [#rich-content]

`TooltipContent` accepts any markup, so you can pair a label with a [`Kbd`](/ui/components/react/kbd) shortcut. Keep it terse and non-interactive — the popup closes as soon as the pointer leaves the trigger.

```tsx
import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'
import { Button } from '@appica/ui-react/button'
import { Kbd } from '@appica/ui-react/kbd'
import { Bookmark } from '@appica/icons-react'

export default function TooltipShortcut() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger
          render={
            <Button variant="outline" size="icon-md" aria-label="Save">
              <Bookmark />
            </Button>
          }
        />
        <TooltipContent className="flex items-center gap-2">
          Save
          <Kbd size="sm">⌘ S</Kbd>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}
```

### Follow the cursor [#follow-the-cursor]

Set `trackCursorAxis` on the `Tooltip` to `'x'`, `'y'`, or `'both'` so the bubble follows the pointer along that axis — handy over a wide target like a chart or canvas where a fixed anchor would feel disconnected.

```tsx
import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'

export default function TooltipTrackCursor() {
  return (
    <TooltipProvider>
      <Tooltip trackCursorAxis="x">
        <TooltipTrigger
          render={
            <div className="bg-background-subtle border-border-strong flex h-32 w-72 items-center justify-center rounded-xl border border-dashed text-sm select-none">
              Hover and move across
            </div>
          }
        />
        <TooltipContent>Following the cursor</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}
```

### Without an arrow [#without-an-arrow]

Pass `arrow={false}` to drop the pointer for a flatter bubble that sits flush against its offset.

```tsx
import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'
import { Button } from '@appica/ui-react/button'

export default function TooltipNoArrow() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline">No arrow</Button>} />
        <TooltipContent arrow={false}>Sits flush, without a pointer</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware placement follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

`start`/`end` alignment mirrors with the document direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).

<Callout type="note" title="Scoped RTL needs the direction on the positioner">
  The popup portals to `<body>`, so its `start`/`end` alignment mirrors from the **document** direction (read from CSS,
  not from `DirectionProvider`) — automatic when `<html dir="rtl">`. If you instead scope RTL to a subtree of an LTR
  page, set it on the positioner so alignment still mirrors: `<TooltipContent positionerProps={{ dir: 'rtl' }}>`. See
  [Floating popups in a scoped RTL region](/ui/docs/react/rtl#floating-popups-in-a-scoped-rtl-region).
</Callout>

<RtlPreview component="tooltip" />

## API reference [#api-reference]

`Tooltip` wraps [Base UI's Tooltip](https://base-ui.com/react/components/tooltip). Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

### TooltipProvider [#tooltipprovider]

Shares the hover delay across the tooltips it wraps. Renders no DOM of its own.

| Prop         | <ColMinWidth width="120">Type</ColMinWidth> | Default | <ColMinWidth width="240">Description</ColMinWidth>                                  |
| ------------ | ------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `delay`      | `number`                                    | `200`   | Hover-open delay in ms applied to every tooltip inside.                             |
| `closeDelay` | `number`                                    | `0`     | Hover-close delay in ms.                                                            |
| `timeout`    | `number`                                    | `400`   | Window after a tooltip closes during which the next one opens instantly (no delay). |

### Tooltip [#tooltip]

The root for a single tooltip. Holds the open state; renders no DOM of its own.

| Prop              | <ColMinWidth width="200">Type</ColMinWidth> | Default  | <ColMinWidth width="220">Description</ColMinWidth>          |
| ----------------- | ------------------------------------------- | -------- | ----------------------------------------------------------- |
| `open`            | `boolean`                                   | —        | Controlled open state. Pair with `onOpenChange`.            |
| `defaultOpen`     | `boolean`                                   | `false`  | Uncontrolled initial open state.                            |
| `onOpenChange`    | <Code>(open, eventDetails) => void</Code>   | —        | Fires when the tooltip opens or closes.                     |
| `trackCursorAxis` | <Code>'none' \| 'x' \| 'y' \| 'both'</Code> | `'none'` | Make the bubble follow the cursor along the given axis.     |
| `disabled`        | `boolean`                                   | `false`  | Prevent the tooltip from opening.                           |
| `delay`           | `number`                                    | —        | Override the provider's hover-open delay for this tooltip.  |
| `closeDelay`      | `number`                                    | —        | Override the provider's hover-close delay for this tooltip. |

### TooltipTrigger [#tooltiptrigger]

The element the tooltip describes. Forwards Base UI's `Tooltip.Trigger`; use `render` to project it onto your own control.

| Prop        | <ColMinWidth width="220">Type</ColMinWidth>                 | Default | Description                                                |
| ----------- | ----------------------------------------------------------- | ------- | ---------------------------------------------------------- |
| `render`    | <Code>ReactElement \| (props, state) => ReactElement</Code> | —       | Render the trigger as your own element (e.g. a `Button`).  |
| `className` | `string`                                                    | —       | Extra classes on the trigger, merged via `tailwind-merge`. |

### TooltipContent [#tooltipcontent]

The portalled, auto-positioned bubble. Draws the popup and the optional arrow, and accepts the shared floating props. Defaults to `side="top"`, `align="center"`, and `sideOffset={8}` (or `4` without an arrow).

| Prop               | <ColMinWidth width="160">Type</ColMinWidth>         | Default    | Description                                                            |
| ------------------ | --------------------------------------------------- | ---------- | ---------------------------------------------------------------------- |
| `arrow`            | `boolean`                                           | `true`     | Render the pointer.                                                    |
| `side`             | <Code>'top' \| 'right' \| 'bottom' \| 'left'</Code> | `'top'`    | Preferred side to open on.                                             |
| `align`            | <Code>'start' \| 'center' \| 'end'</Code>           | `'center'` | Alignment along that side.                                             |
| `sideOffset`       | `number`                                            | `8`        | Gap between the trigger and the bubble.                                |
| `alignOffset`      | `number`                                            | `0`        | Shift along the alignment axis.                                        |
| `collisionPadding` | `number`                                            | `5`        | Minimum gap kept from the viewport edge when flipping/shifting.        |
| `anchor`           | <Code>Element \| ref \| VirtualElement</Code>       | —          | Anchor against a different element than the trigger.                   |
| `container`        | <Code>HTMLElement \| ref \| null</Code>             | —          | Portal target — render the popup into a different node.                |
| `positionerProps`  | `object`                                            | —          | Escape hatch for the positioner element (`style`, `render`, `dir`, …). |
| `portalProps`      | `object`                                            | —          | Escape hatch for the portal element (`style`, `render`, …).            |
| `className`        | `string`                                            | —          | Extra classes on the bubble.                                           |

## Accessibility [#accessibility]

* The popup is wired to the trigger via `aria-describedby`, so screen readers announce it as a **description** — not the control's name. Give icon-only triggers an `aria-label` (or visible text) of their own.
* The tooltip opens on hover **and** keyboard focus, and closes on **Escape**, on blur, or when the pointer leaves.
* Tooltips don't open on touch — there's no hover — so never hide essential information in one.
* Within a `TooltipProvider`, the `delay` is shared and subsequent tooltips open instantly within the `timeout` window.
* Enter/exit transitions are skipped when the user prefers reduced motion.