`. Form controls are real `` / `

` elements. See [Philosophy](/philosophy#semantic-html-then-everything-else) for the full argument.
- **Composition over re-implementation.** Where the platform doesn't ship a primitive (combobox, dialog, tabs), we wrap a vetted unstyled library — we never re-implement keyboard or ARIA logic from scratch.
- **Progressive enhancement.** CSS-failure and no-JS rendering should still produce a usable page where possible. The skip link, semantic landmarks, and form constraint validation all work without script.
- **High contrast and reduced motion are not opt-ins.** Themes ship with high-contrast variants and animations respect `prefers-reduced-motion`.

## Required app-level setup

For full accessibility, an app embedding mantle must:

1. Mount [`<ThemeProvider>`](/components/theme), [`<TooltipProvider>`](/components/tooltip), and [`<Toaster>`](/components/toast) at the root of the document tree.
2. Place [`<SkipToMainLink />`](/components/skip-to-main-link) as the very first focusable element in `<body>`, paired with a [`<Main>`](/components/main) landmark wrapping the page's primary content.
3. Render a single `<h1>` per page that names the page.
4. Use real form elements with associated [`<Label>`](/components/label)s.
5. Provide accessible names on icon-only controls — [`IconButton`](/components/icon-button) requires `aria-label`.

## Skip-to-main and landmarks

Every page should be navigable by landmarks. The minimum structure:

```tsx
import { SkipToMainLink } from "@ngrok/mantle/skip-to-main-link";
import { Main } from "@ngrok/mantle/main";

export default function App() {
	return (
		<>
			<SkipToMainLink />
			<header>{/* nav */}</header>
			<Main>
				<h1>Page title</h1>
				{/* primary content */}
			</Main>
			<footer>{/* … */}</footer>
		</>
	);
}
```

`SkipToMainLink` is visually hidden until focused and uses the History API directly so it works in any framework. `Main` renders `<main id="main" tabIndex={-1}>` so the skip link can deliver focus without leaving a visible focus ring on the region itself.

## Keyboard interactions per component

The table below summarizes the keyboard contract for the most common interactive components. Underlying primitives (Radix, Ariakit) implement the full WAI-ARIA pattern — these are the keys consumers most often need to remember.

| Component                                                                                                 | Keys                                                                                                                                              |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Button](/components/button) / [IconButton](/components/icon-button)                                      | `Tab` to focus, `Enter` or `Space` to activate.                                                                                                   |
| [Anchor](/components/anchor)                                                                              | `Tab` to focus, `Enter` to follow.                                                                                                                |
| [Checkbox](/components/checkbox) / [Switch](/components/switch)                                           | `Tab` to focus, `Space` to toggle.                                                                                                                |
| [RadioGroup](/components/radio-group)                                                                     | `Tab` to enter the group, `Arrow` keys to move and select within the group.                                                                       |
| [Tabs](/components/tabs)                                                                                  | `Tab` to enter the tab list, `Arrow Left`/`Right` to move, `Home`/`End` to jump, `Enter`/`Space` to activate.                                     |
| [Dialog](/components/dialog) / [AlertDialog](/components/alert-dialog)                                    | Focus is trapped inside while open, `Esc` closes (Dialog only — AlertDialog requires explicit confirmation), `Tab`/`Shift+Tab` cycles focus.      |
| [Sheet](/components/sheet)                                                                                | Same as Dialog.                                                                                                                                   |
| [Popover](/components/popover) / [HoverCard](/components/hover-card)                                      | `Esc` closes; `Tab` cycles focusable content. HoverCard opens on hover/focus and is non-essential.                                                |
| [DropdownMenu](/components/dropdown-menu) / [Command](/components/command)                                | `Arrow Up`/`Down` to navigate items, `Enter` to select, `Esc` to close, type-ahead jumps to matching items.                                       |
| [Combobox](/components/combobox) / [MultiSelect](/components/multi-select) / [Select](/components/select) | `Arrow Up`/`Down` through options, `Enter` selects, type filters, `Esc` closes.                                                                   |
| [Slider](/components/slider)                                                                              | `Arrow Left`/`Right` (or `Up`/`Down`) increment/decrement, `Home`/`End` jump to min/max, `PageUp`/`PageDown` for larger steps.                    |
| [DataTable](/components/data-table)                                                                       | Row click handlers respond to `Enter` when used with `asChild` rendering of an `<a>` or `<button>`. Header sort buttons follow Button keys above. |
| [Toast](/components/toast)                                                                                | Auto-dismissing toasts respect `prefers-reduced-motion`; `F8` (browser default) cycles to the toast region.                                       |

## Focus management

- **Trap on modal surfaces.** `Dialog`, `AlertDialog`, and `Sheet` trap focus while open and restore it to the trigger on close.
- **Don't trap on non-modal surfaces.** `Popover` and `HoverCard` allow focus to escape — that's intentional.
- **Programmatic focus is fine.** When a route changes, focus the page's `<h1>` (or the `<Main>` landmark via `document.getElementById("main")?.focus()`) so screen reader users hear the page change.
- **Visible focus rings.** Mantle uses `:focus-visible` so focus styles appear for keyboard users without distracting mouse users. Don't override `outline` without providing an equivalent ring.

## ARIA roles and labels

Mantle components emit appropriate roles automatically. Consumers need to add:

- `aria-label` on [`IconButton`](/components/icon-button), and any [`Button`](/components/button) whose label is icon-only.
- `aria-label` or visually-hidden text on [`Kbd`](/components/kbd) when the visible glyph is a symbol (e.g. `⌘`).
- `aria-describedby` linking error/help text to form controls. [`Input`](/components/input) and friends do this for you when you use the validation prop, but custom messages should be wired manually.
- `aria-current="page"` on the active item in primary navigation (use react-router's `NavLink` for this).
- Live-region semantics — use [`Toast`](/components/toast) for transient announcements; use the [`Alert`](/components/alert) component with `role="alert"` for inline warnings.

## Color contrast and themes

- Color tokens (`text-strong`, `text-muted`, `bg-form`, `border-accent-600`, etc.) target WCAG AA contrast in both light and dark themes.
- High-contrast variants are provided via dedicated stylesheets — import [`@ngrok/mantle/mantle-light-high-contrast.css`](https://www.npmjs.com/package/@ngrok/mantle?activeTab=code) or `@ngrok/mantle/mantle-dark-high-contrast.css` to opt in.
- Don't communicate state by color alone. Use color **and** a label, icon, or copy. `Badge` and `Alert` do this by default; custom components should follow suit.

## Reduced motion

Animations across mantle (toasts, transitions, the password-input eye blink) honor `prefers-reduced-motion`. Custom animations should too:

```css
@media (prefers-reduced-motion: reduce) {
	.my-animation {
		animation: none;
	}
}
```

## Testing

Manual smoke checks per page or PR:

1. **Keyboard-only.** Hide your mouse. `Tab` from the top of the page. You should be able to reach every interactive element, see focus on each, activate it with the appropriate key, and never get stuck.
2. **Skip link.** First `Tab` from the top of the page should reveal the skip link; activating it should land focus inside `<Main>`.
3. **Screen reader.** A quick pass with VoiceOver (Mac, `Cmd+F5`) or NVDA (Windows) — every interactive element should announce its role and accessible name.
4. **Reduced motion.** In OS settings, enable Reduce Motion. Repeat any animated flow.
5. **High contrast.** Switch the imported theme to `*-high-contrast.css`. Confirm legibility.
6. **Zoom.** Zoom to 200% in Chrome — content should reflow without horizontal scroll.

For automated testing, [`axe-core`](https://github.com/dequelabs/axe-core) integrated via Playwright catches the bulk of WCAG issues. Mantle does not ship a custom axe runner, but the conventions in `CONVENTIONS.md` favor structures that pass it.

## When you can't fix the accessibility issue

If a third-party widget or constraint makes a component temporarily inaccessible:

1. Document it in a code comment that explains the *why* and links to the tracking issue.
2. Communicate the limitation to the user — don't ship invisible inaccessibility.
3. Provide a fallback path (e.g. a plain `<a>` with the same target) so keyboard and screen-reader users are not blocked.

The goal isn't perfect compliance forever — it's making the right choice the default and surfacing the exceptions honestly.

---

---
title: Breakpoints
description: Responsive breakpoints for building adaptive layouts in the mantle design system
---

# Breakpoints

Responsive breakpoints for building adaptive layouts.

## Live Demo

## Breakpoint Values

There are seven breakpoints by default, inspired by common device resolutions:

| Breakpoint prefix | Minimum width   | CSS                                 |
| ----------------- | --------------- | ----------------------------------- |
| `default`         | 0rem (0px)      | No media query                      |
| `2xs`             | 22.5rem (360px) | `@media (width >= 22.5rem) { ... }` |
| `xs`              | 30rem (480px)   | `@media (width >= 30rem) { ... }`   |
| `sm`              | 40rem (640px)   | `@media (width >= 40rem) { ... }`   |
| `md`              | 48rem (768px)   | `@media (width >= 48rem) { ... }`   |
| `lg`              | 64rem (1024px)  | `@media (width >= 64rem) { ... }`   |
| `xl`              | 80rem (1280px)  | `@media (width >= 80rem) { ... }`   |
| `2xl`             | 96rem (1536px)  | `@media (width >= 96rem) { ... }`   |

## useBreakpoint Hook

The `useBreakpoint` hook returns the current breakpoint based on the viewport width. It efficiently tracks all breakpoints and returns the largest one that currently matches.

```tsx
import { useBreakpoint } from "@ngrok/mantle/hooks";

function ResponsiveComponent() {
	const breakpoint = useBreakpoint();

return (
		<div>
			<p>Current breakpoint: {breakpoint}</p>
			{breakpoint === "lg" && <p>This only shows on large screens and above!</p>}
		</div>
	);
}
```

### Features

- **Performance optimized:** Uses a single subscription for all breakpoint changes
- **SSR compatible:** Returns `default` during server-side rendering
- **Real-time updates:** Automatically updates when the viewport size changes
- **TypeScript support:** Fully typed with autocompletion for all breakpoints

### Return Value

Returns a `Breakpoint` type that can be one of: `"default"`, `"2xs"`, `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, or `"2xl"`.

## useIsBelowBreakpoint Hook

The `useIsBelowBreakpoint` hook returns `true` if the current viewport width is below the specified breakpoint. Perfect for mobile-first responsive design patterns.

```tsx
import { useIsBelowBreakpoint } from "@ngrok/mantle/hooks";

function ResponsiveSidebar() {
	const isMobile = useIsBelowBreakpoint("md");

return (
		<aside className={isMobile ? "mobile-sidebar" : "desktop-sidebar"}>
			{isMobile ? <MobileNav /> : <DesktopNav />}
		</aside>
	);
}
```

### Parameters

Accepts a `TailwindBreakpoint` which can be one of: `"2xs"`, `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, or `"2xl"`.

### Common Use Cases

- **Mobile detection:** `useIsBelowBreakpoint("md")` for mobile-first layouts
- **Conditional rendering:** Show/hide components based on screen size
- **Dynamic styling:** Apply different CSS classes for mobile vs desktop
- **Component adaptation:** Switch between mobile and desktop component variants

---

---
title: Colors
description: Color system for the mantle design system with automatic dark and high contrast mode support
---

# Colors

Colors are a key component of any design system. They are used to convey meaning, attract
attention, and provide feedback. Mantle's color system is designed to be accessible
and flexible with dark and high contrast modes.

## Tailwind

Mantle uses Tailwind under the hood for all its CSS styling. However, we differ from
Tailwind when it comes to colors. Mantle provides a full color library that automatically
provides dark and high contrast modes. This is different from standard Tailwind usage
that *requires* dark class variations. By simply specifying light colors provided
by Mantle, you'll get dark and high contrast modes for free. If you require
additional customization, you can provide dark variant classes as an override.

## Variables

Mantle's colors are delivered as CSS variables via Tailwind's API e.g.
`.text-blue-500`. They can be directly accessed via `var(--color-blue-500)` and use `oklch()` color space.

## Black and White Color Variables

Mantle overrides what "black" and "white" mean depending on the theme. We transformed
these colors to be semantic colors instead of literal colors. For dark modes, we swap them
so that white is actually black and vice versa. Pay attention to the example below when
swapping between our themes!

## Overrides

Most colors should appropriately swap for sensible values in dark and high contrast modes.
However, there are often cases where you'll need to specify an override. The
`dark:` variant is well-documented on [Tailwind's website](https://tailwindcss.com/docs/dark-mode).
Mantle provides additional variants for high contrast and dark high contrast mode with
`high-contrast:` and `dark-high-contrast:` respectively.

## Functional Colors

Mantle generally limits its color choices to the following functional colors for primary
actions, and various states like danger and warnings.

### Neutral

### Accent

### Info

### Important

### Success

### Danger

### Warning

## Extended Palette

Mantle also supports a curated subset of Tailwind's color palette in light, dark, and high
contrast variants. These are to be used when there is no functional meaning behind the color
choice. We've left out the extended collection of Tailwind's grays eg.
slate, zinc, etc. since we only want to use our own custom branded gray.

### Gray

### Amber

### Lime

### Emerald

### Sky

### Purple

### Fuchsia

### Pink

### Rose

## Reserve Palette

These additional colors are available when you need more color variety than the extended
palette provides, such as for line charts, data visualization, or categorical distinctions.
They are less harmonious with the rest of the Mantle palette, so prefer functional and
extended colors first.

### Red

### Orange

### Yellow

### Green

### Teal

### Cyan

### Blue

### Indigo

### Violet

---

---
title: Scroll Fade
description: Utilities that fade the edges of a scroll container to signal more content.
---

# Scroll Fade

Edge-fade utilities for scroll containers. They mask the edge of an overflowing
container so content gently fades out where there is more to scroll, and render
cleanly once you reach that edge (or when there is no overflow at all).

The fade is driven entirely by a CSS [scroll-driven animation](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timeline/scroll) —
there is no scroll listener, `ResizeObserver`, or JavaScript involved. Apply the
utility directly to the scroll container itself (the element with
`overflow-*-auto`).

> \[!NOTE]
> Where `animation-timeline: scroll()` is unsupported (Firefox stable as of
> mid-2026), the fade is simply absent — content is never clipped.

## Both edges

### Vertical — `scroll-fade-y`

Fades the top and bottom edges of a vertically scrolling container. Scroll the
list to see each edge fade in and out.

```tsx
<div className="scroll-fade-y h-56 overflow-y-auto">{/* tall content */}</div>
```

### Horizontal — `scroll-fade-x`

Fades the left and right edges of a horizontally scrolling container.

```tsx
<div className="scroll-fade-x w-72 overflow-x-auto">{/* wide content */}</div>
```

## Single edge

When only one edge should fade — for example a sidebar that fades content
scrolling under a sticky header but stays flush at the bottom — use a single-edge
utility. The opposite edge always stays fully opaque.

| Utility         | Axis       | Fades       |
| --------------- | ---------- | ----------- |
| `scroll-fade-t` | vertical   | top edge    |
| `scroll-fade-b` | vertical   | bottom edge |
| `scroll-fade-l` | horizontal | left edge   |
| `scroll-fade-r` | horizontal | right edge  |

Use them exactly like the axis utilities — just put the edge class on the scroll
container. The sidebar example above becomes:

```tsx
<nav className="scroll-fade-t h-full overflow-y-auto">{/* tall content */}</nav>
```

Each box below is pre-scrolled to its midpoint so the single faded edge stands
out against the flush opposite edge.

## Requirements

- Apply the utility to the scroll container itself — the element that has
  `overflow-x-auto` / `overflow-y-auto`. The fade follows that element's own
  scroll position.
- The utility uses `mask-image`, so it composes with the element's background and
  content but cannot be combined with a different `mask-image` on the same
  element.

---

---
title: Shadows
description: Tokens for defining elevations in the mantle design system
---

# Shadows

Tokens for defining elevations.

---

---
title: Tailwind Variants
description: Custom Tailwind variants registered by mantle
---

# Tailwind Variants

Custom Tailwind variants registered by mantle via `@custom-variant` in `mantle.css`.

## Theme

| Variant                | Description                                                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.light:`              | Apply a class when the light theme is active.                                                                                                      |
| `.dark:`               | Apply a class when the dark theme is active. Overrides Tailwind's built-in `dark:` to use class-based detection instead of `prefers-color-scheme`. |
| `.high-contrast:`      | Apply a class if high contrast theming is enabled (light-high-contrast).                                                                           |
| `.dark-high-contrast:` | Apply a class if high contrast and dark themes are applied.                                                                                        |

## Hover Media Queries

|                                                          | Variant         | Description                                                                                                                                  |
| -------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|  | `.hover-hover:` | Apply a class if hover is supported. Unlike Tailwind's `hover:`, this applies unconditionally without requiring an actual hover interaction. |
|  | `.hover-none:`  | Apply a class if hover is unsupported.                                                                                                       |

## Aria

| Variant            | Description                                  |
| ------------------ | -------------------------------------------- |
| `.aria-collapsed:` | Match elements with `aria-expanded="false"`. |
| `.aria-invalid:`   | Match elements with `aria-invalid="true"`.   |
| `.aria-unchecked:` | Match elements with `aria-checked="false"`.  |

## Data Attribute — State

| Variant                      | Description                                      |
| ---------------------------- | ------------------------------------------------ |
| `.data-state-active:`        | Match elements with `data-state~=active`.        |
| `.data-state-checked:`       | Match elements with `data-state~=checked`.       |
| `.data-state-closed:`        | Match elements with `data-state~=closed`.        |
| `.data-state-idle:`          | Match elements with `data-state~=idle`.          |
| `.data-state-inactive:`      | Match elements with `data-state~=inactive`.      |
| `.data-state-indeterminate:` | Match elements with `data-state~=indeterminate`. |
| `.data-state-open:`          | Match elements with `data-state~=open`.          |
| `.data-state-pending:`       | Match elements with `data-state~=pending`.       |
| `.data-state-selected:`      | Match elements with `data-state~=selected`.      |
| `.data-state-submitting:`    | Match elements with `data-state~=submitting`.    |
| `.data-state-unchecked:`     | Match elements with `data-state~=unchecked`.     |

## Data Attribute — Orientation & Side

| Variant                         | Description                                          |
| ------------------------------- | ---------------------------------------------------- |
| `.data-orientation-horizontal:` | Match elements with `data-orientation="horizontal"`. |
| `.data-orientation-vertical:`   | Match elements with `data-orientation="vertical"`.   |
| `.data-side-bottom:`            | Match elements with `data-side="bottom"`.            |
| `.data-side-left:`              | Match elements with `data-side="left"`.              |
| `.data-side-right:`             | Match elements with `data-side="right"`.             |
| `.data-side-top:`               | Match elements with `data-side="top"`.               |

## Data Attribute — Validation

| Variant                     | Description                                      |
| --------------------------- | ------------------------------------------------ |
| `.data-validation-error:`   | Match elements with `data-validation="error"`.   |
| `.data-validation-success:` | Match elements with `data-validation="success"`. |
| `.data-validation-warning:` | Match elements with `data-validation="warning"`. |

## Data Attribute — Other

| Variant              | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `.data-active-item:` | Match elements with `data-active-item~="true"`.       |
| `.data-disabled:`    | Match elements with the `data-disabled` attribute.    |
| `.data-drag-over:`   | Match elements with `data-drag-over="true"`.          |
| `.data-highlighted:` | Match elements with the `data-highlighted` attribute. |

## Utility

| Variant   | Description                                               |
| --------- | --------------------------------------------------------- |
| `.where:` | Wraps the selector in `:where()` to zero out specificity. |

## Live Detection

The pills below show which variants are currently active in your browser:

---

---
title: Typography
description: Typography tokens for consistency and readability in the mantle design system
---

# Typography

Mantle provides various typography tokens for consistency and readability.

## Scale

Mantle provides a general type scale for various headers throughout our products. Text styling is independent of the actual markup, so a Heading 1 can be styled as a Heading 2 or Heading 5 as appropriate.

| Level     | Class                  | Size        | Weight        | Additional                  |
| --------- | ---------------------- | ----------- | ------------- | --------------------------- |
| Heading 1 | `text-5xl font-family` | `text-5xl`  | `font-medium` | `font-family`               |
| Heading 2 | `text-3xl font-family` | `text-3xl`  | `font-medium` | `font-family`               |
| Heading 3 | `text-2xl font-family` | `text-2xl`  | `font-medium` | `font-family`               |
| Heading 4 | `text-xl font-family`  | `text-xl`   | `font-medium` | `font-family`               |
| Heading 5 | `text-base`            | `text-base` | `font-medium` | `-`                         |
| Heading 6 | `text-xs`              | `text-xs`   | `font-medium` | `uppercase tracking-widest` |

## Colors

When possible, it's preferred to render text using the following tokens. This helps provide hierarchy outside of font size, and ensures type is the correct color across various themes.

| Token       | Class               | Description                          |
| ----------- | ------------------- | ------------------------------------ |
| Strong      | `.text-strong`      | High emphasis text, primary content. |
| Body        | `.text-body`        | Default body text.                   |
| Muted       | `.text-muted`       | De-emphasized, secondary text.       |
| Placeholder | `.text-placeholder` | Lowest emphasis, placeholder text.   |

## Fonts

Mantle specifies Roobert as the default font for UI and headings. We also use JetBrains Mono as a monospace typeface, and Family for longform prose and h1s.

| Class         | Font Family                                                                                      | Description                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `font-sans`   | `"Roobert"`, `ui-sans-serif`, `system-ui`, `sans-serif`                                          | The default font for rendering UI and headings. Also applied by `default`.        |
| `font-family` | `"Family"`, `"Georgia"`, `serif`                                                                 | Best when used in longform writing like prose documentation or h1 headings.       |
| `font-mono`   | `"JetBrains Mono"`, `ui-monospace`, `SFMono-Regular`, `Menlo`, `Monaco`, `Consolas`, `monospace` | Used to render code and tokens. Adjust the size a step down in most applications. |

---

---
title: Sheet + Async Data (React Query)
description: Render a Sheet immediately, then swap its body between pending, success, 404, and 500 states with TanStack Query.
---

# Sheet + Async Data (React Query)

Opening a [`Sheet`](/components/sheet) is a navigation — the user has already committed to seeing more context by clicking the trigger. When the body needs remote data, fetching before opening turns a 404 or 500 into a silent drop back to the parent view, and a spinner on the trigger leaves the click feeling unregistered. This recipe mounts the shell immediately and resolves data inside it, so every click produces forward motion and every error stays in the place the user navigated to.

## Why open the sheet first?

- **The open should feel instant, especially on slow networks.** The user already committed to the navigation by clicking the trigger. Waiting for the request to resolve before opening means dead air at the parent view, and the wait scales with request latency — long-running endpoints or slow connections turn into seconds where users can't tell whether the click registered. Mounting the shell immediately decouples click feedback from request time.
- **No flashing across the open → load → close → reopen cycle.** Within a single open, only `Sheet.Body` branches between pending, success, and error, so header, close, and footer stay mounted and layout shift is contained to one region. Across opens, TanStack Query's cache lets a re-trigger after a successful fetch skip the pending state entirely — fetch-then-open does the opposite, re-running the request on every trigger and flashing the chrome in only after each fetch resolves.
- **Errors stay where the user intended to be.** An inline error inside the sheet preserves the navigation and keeps recovery actions in reach. Closing on error forces a re-trigger and re-orientation from the parent view.
- **Retry is a product decision, not a default.** Transient `500` responses are worth another attempt; a definitive `404` is not. The query hook owns that policy so the view stays free of conditional retry logic and the intent stays reviewable in one place.

## What this covers

| Case       | Demo behavior                                                                     |
| ---------- | --------------------------------------------------------------------------------- |
| Happy path | Waits 1.5 seconds, then renders a loaded user profile.                            |
| 404 error  | Waits 1.5 seconds once, then renders a not-found empty state.                     |
| 500 error  | Waits 1.5 seconds per request, retries twice, then renders a service empty state. |

The route is also available as plain markdown at [`/blocks/sheet-async.md`](/blocks/sheet-async.md), so humans and LLM tools can fetch the same recipe without scraping the rendered page.

## Anatomy

```text showLineNumbers=false
Parent selection state
└── UserSheet (mounted immediately)
    └── useUserQuery({ userId, scenario })
        └── Sheet.Content
            ├── Sheet.Header        stable
            ├── Sheet.Body          pending | success | error
            └── Sheet.Footer        stable; disable actions until success
```

## Implementation

The "Why" section above is the user-perceived case for the pattern. These rules are how to wire it up so the code stays consistent with that intent.

1. **Mount the sheet on the click event.** Set selection state synchronously in the handler — never gate it on a fetch result.
2. **Branch only `Sheet.Body` on query state.** `query.isPending`, `query.isError`, and `query.isSuccess` belong inside the body. Header, close button, and footer stay outside the conditional.
3. **Factor the query into a hook.** `useUserQuery` owns fetching, retry, stale-time, and cancellation. The components that render query results (`UserSheet`, `UserSheetBody`) consume a `UseQueryResult` and never reach into TanStack Query directly. The cache-observability bits in `UserSheetDemo` (the `useQueryClient` subscription and `removeQueries` reset) are demo-only — production sheets shouldn't touch the cache.
4. **Encode the retry policy in `useQuery`.** Return `false` from `retry` for terminal errors like `404`. Return a bounded `failureCount` check for transient ones like `500`.
5. **Match the retry UI to the retry policy.** Show a retry button on recoverable errors. Omit it on terminal ones — retrying a definitive not-found is just latency without recovery.

## Complete Recipe

Copy the UI recipe into a client component that already has a `QueryClientProvider` mounted near the app root. The demo-only mock API is shown in the appendix below; in production, replace that import with your real API client and error type.

```tsx
import { Button } from "@ngrok/mantle/button";
import { DescriptionList } from "@ngrok/mantle/description-list";
import { Empty } from "@ngrok/mantle/empty";
import { MediaObject } from "@ngrok/mantle/media-object";
import { Separator } from "@ngrok/mantle/separator";
import { Sheet } from "@ngrok/mantle/sheet";
import { Skeleton } from "@ngrok/mantle/skeleton";
import { MagnifyingGlassIcon } from "@phosphor-icons/react/MagnifyingGlass";
import { SmileyMeltingIcon } from "@phosphor-icons/react/SmileyMelting";
import {
	useQuery,
	useQueryClient,
	type QueryClient,
	type UseQueryResult,
} from "@tanstack/react-query";
import { type ReactNode, useEffect, useState } from "react";
import {
	fetchUser,
	RequestCancelledError,
	UserRequestError,
	type User,
	type UserSheetScenario,
} from "./mock-user-api";

const SERVER_ERROR_RETRY_LIMIT = 2;
const USER_QUERY_RETRY_DELAY_MS = 500;
const USER_QUERY_KEY_ROOT = ["sheet-async-user"];

const scenarioLabels: Record<UserSheetScenario, string> = {
	success: "happy path",
	"not-found": "404",
	"server-error": "500",
};

/** Props for the controlled async sheet. */
type UserSheetProps = {
	/** User identifier requested by the sheet. */
	userId: string;
	/** Demo scenario selected by the user. */
	scenario: UserSheetScenario;
	/** Called when the user dismisses the sheet. */
	onClose: () => void;
};

/** Renders immediately, then swaps the sheet body from pending to success or error. */
export function UserSheet({ onClose, scenario, userId }: UserSheetProps) {
	const query = useUserQuery({ scenario, userId });

return (
		<Sheet.Root
			open
			onOpenChange={(nextOpen) => {
				if (!nextOpen) {
					onClose();
				}
			}}
		>
			<Sheet.Content preferredWidth="sm:max-w-[34rem]">
				<Sheet.Header>
					<Sheet.TitleGroup>
						<Sheet.Title>User details</Sheet.Title>
						<Sheet.Actions>
							<Sheet.CloseIconButton />
						</Sheet.Actions>
					</Sheet.TitleGroup>
					<Sheet.Description>
						Loading <span className="font-mono">{userId}</span> through the{" "}
						{scenarioLabels[scenario]} case.
					</Sheet.Description>
				</Sheet.Header>
				<Sheet.Body>
					<UserSheetBody query={query} />
				</Sheet.Body>
				<Sheet.Footer>
					<Sheet.Close asChild>
						<Button type="button" appearance="outlined" priority="neutral">
							Close
						</Button>
					</Sheet.Close>
					<Button type="button" appearance="filled" priority="neutral" disabled={!query.isSuccess}>
						Save changes
					</Button>
				</Sheet.Footer>
			</Sheet.Content>
		</Sheet.Root>
	);
}

/** Props for selecting which body state to render. */
type UserSheetBodyProps = {
	/** TanStack Query result that drives the body state. */
	query: UseQueryResult<User, Error>;
};

/** Keeps the sheet chrome stable while only the body content changes. */
function UserSheetBody({ query }: UserSheetBodyProps) {
	if (query.isPending) {
		return <UserDetailsLoading failureCount={query.failureCount} />;
	}

if (query.isError) {
		return (
			<UserDetailsError
				error={query.error}
				isRetrying={query.isFetching}
				onRetry={() => {
					void query.refetch();
				}}
			/>
		);
	}

if (query.isSuccess) {
		return <UserDetails user={query.data} />;
	}

return null;
}

/** Props for the loading state. */
type UserDetailsLoadingProps = {
	/** Failed attempts observed while TanStack Query is still retrying. */
	failureCount: number;
};

/** Mirrors the successful layout so the sheet body does not jump when data arrives. */
function UserDetailsLoading({ failureCount }: UserDetailsLoadingProps) {
	return (
		<div className="space-y-4" aria-busy="true" aria-label="Loading user details">
			<MediaObject.Root className="items-center">
				<MediaObject.Media>
					<Skeleton className="size-12 rounded-full" />
				</MediaObject.Media>
				<MediaObject.Content className="space-y-2">
					<Skeleton className="h-4 w-40" />
					<Skeleton className="h-3 w-56" />
				</MediaObject.Content>
			</MediaObject.Root>
			<Separator />
			<div className="space-y-2">
				<Skeleton className="h-3 w-full" />
				<Skeleton className="h-3 w-5/6" />
				<Skeleton className="h-3 w-3/4" />
			</div>
			{failureCount > 0 && (
				<p className="text-sm text-muted" role="status">
					Retrying after {failureCount} failed {failureCount === 1 ? "attempt" : "attempts"}.
				</p>
			)}
		</div>
	);
}

/** Props for the inline error state. */
type UserDetailsErrorProps = {
	/** Error thrown by the query function. */
	error: Error;
	/** Whether a manual retry is currently in flight. */
	isRetrying: boolean;
	/** Called when the user requests another attempt. */
	onRetry: () => void;
};

/** Renders a recoverable inline error instead of closing the sheet. */
function UserDetailsError({ error, isRetrying, onRetry }: UserDetailsErrorProps) {
	const copy = getUserErrorCopy(error);

return (
		<Empty.Root className="py-8">
			<Empty.Icon svg={copy.icon} />
			<Empty.Title className="text-lg">{copy.title}</Empty.Title>
			<Empty.Description>
				<p>{copy.description}</p>
				{copy.requestId && (
					<p>
						Request ID <span className="font-mono text-strong">{copy.requestId}</span>
					</p>
				)}
			</Empty.Description>
			{copy.canRetry && (
				<Empty.Actions>
					<Button
						type="button"
						appearance="filled"
						priority="danger"
						isLoading={isRetrying}
						onClick={onRetry}
					>
						Retry request
					</Button>
				</Empty.Actions>
			)}
		</Empty.Root>
	);
}

/** Copy values shown by the inline error state. */
type UserErrorCopy = {
	/** Whether the Empty state should render a retry action. */
	canRetry: boolean;
	/** Icon shown by the Empty state. */
	icon: ReactNode;
	/** Short Empty state title. */
	title: string;
	/** Human-readable remediation context. */
	description: string;
	/** Optional request id shown for support workflows. */
	requestId?: string;
};

/** Converts typed request errors into user-facing copy. */
function getUserErrorCopy(error: Error): UserErrorCopy {
	if (error instanceof UserRequestError && error.status === 404) {
		return {
			canRetry: false,
			icon: <MagnifyingGlassIcon />,
			title: "User not found",
			description: "The request completed, but no user exists for that id.",
			requestId: error.requestId,
		};
	}

if (error instanceof UserRequestError && error.status === 500) {
		return {
			canRetry: true,
			icon: <SmileyMeltingIcon />,
			title: "User service unavailable",
			description:
				"The service failed after retrying. Keep the sheet open so the user can try again.",
			requestId: error.requestId,
		};
	}

return {
		canRetry: true,
		icon: <SmileyMeltingIcon />,
		title: "Could not load user",
		description: error.message || "An unknown error occurred.",
	};
}

/** Props for the successful user details state. */
type UserDetailsProps = {
	/** Loaded user data returned by the query. */
	user: User;
};

/** Renders the successful data state. */
function UserDetails({ user }: UserDetailsProps) {
	return (
		<div className="space-y-4">
			<MediaObject.Root className="items-center">
				<MediaObject.Media>
					<div className="flex size-12 items-center justify-center rounded-full bg-accent-500 font-mono text-on-filled">
						{user.name[0]}
					</div>
				</MediaObject.Media>
				<MediaObject.Content>
					<p className="font-medium text-strong">{user.name}</p>
					<p className="text-sm text-muted">{user.email}</p>
				</MediaObject.Content>
			</MediaObject.Root>
			<Separator />
			<DescriptionList.Root>
				<DescriptionList.Item>
					<DescriptionList.Label>ID</DescriptionList.Label>
					<DescriptionList.Value>{user.id}</DescriptionList.Value>
				</DescriptionList.Item>
				<DescriptionList.Item>
					<DescriptionList.Label>Role</DescriptionList.Label>
					<DescriptionList.Value>{user.role}</DescriptionList.Value>
				</DescriptionList.Item>
				<DescriptionList.Item>
					<DescriptionList.Label>Workspace</DescriptionList.Label>
					<DescriptionList.Value>{user.workspace}</DescriptionList.Value>
				</DescriptionList.Item>
				<DescriptionList.Item>
					<DescriptionList.Label>Plan</DescriptionList.Label>
					<DescriptionList.Value>{user.plan}</DescriptionList.Value>
				</DescriptionList.Item>
				<DescriptionList.Item>
					<DescriptionList.Label>Joined</DescriptionList.Label>
					<DescriptionList.Value>{user.joinedAt}</DescriptionList.Value>
				</DescriptionList.Item>
				<DescriptionList.Item>
					<DescriptionList.Label>Last active</DescriptionList.Label>
					<DescriptionList.Value>{user.lastActiveAt}</DescriptionList.Value>
				</DescriptionList.Item>
			</DescriptionList.Root>
		</div>
	);
}

/** Selected sheet state owned by the parent list/page. */
type SelectedUserSheet = {
	/** User identifier requested by the sheet. */
	userId: string;
	/** Demo scenario selected by the user. */
	scenario: UserSheetScenario;
};

/** Query key for the success scenario, used to observe and clear just the happy-path cache entry. */
const HAPPY_PATH_QUERY_KEY = [...USER_QUERY_KEY_ROOT, userIdForScenario("success"), "success"];

/** Tracks whether the happy-path query has a successful response in the cache. The 404 and 500 scenarios throw, so they never reach a successful cache state. */
function useIsHappyPathCached(): boolean {
	const queryClient = useQueryClient();
	const [isCached, setIsCached] = useState(() => readIsHappyPathCached(queryClient));

useEffect(() => {
		const cache = queryClient.getQueryCache();
		const unsubscribe = cache.subscribe((event) => {
			// Ignore cache events that don't touch the happy-path query so other consumers of the
			// QueryClient don't trigger a recompute on every cache mutation.
			if (!isHappyPathCacheEvent(event)) {
				return;
			}
			const next = readIsHappyPathCached(queryClient);
			setIsCached((prev) => (prev === next ? prev : next));
		});
		return unsubscribe;
	}, [queryClient]);

return isCached;
}

/** Returns true when the happy-path query has a successful response in the cache. */
function readIsHappyPathCached(queryClient: QueryClient): boolean {
	const query = queryClient.getQueryCache().find({ queryKey: HAPPY_PATH_QUERY_KEY, exact: true });
	return query?.state.status === "success";
}

/** True when a query-cache event refers to the happy-path query key. */
function isHappyPathCacheEvent(event: { query: { queryKey: readonly unknown[] } }): boolean {
	const queryKey = event.query.queryKey;
	if (queryKey.length !== HAPPY_PATH_QUERY_KEY.length) {
		return false;
	}
	return queryKey.every((part, index) => part === HAPPY_PATH_QUERY_KEY[index]);
}

/** Builds the cache-state caption shown beneath the demo controls. */
function describeCacheState(isCached: boolean): string {
	if (isCached) {
		return `Happy path is cached. Reopening it now skips the pending state and renders the result immediately. Click "Clear cache" to reset.`;
	}
	return "No successful response is cached. Clicking happy path will fetch from scratch and show pending; closing the sheet keeps the result so reopening skips pending. The 404 and 500 scenarios throw, so reopening them always re-fetches.";
}

/** Opens the three async sheet states from parent-owned selection state. */
export function UserSheetDemo() {
	const [selection, setSelection] = useState<SelectedUserSheet | null>(null);
	const queryClient = useQueryClient();
	const isHappyPathCached = useIsHappyPathCached();

/** Opens a fresh sheet for the selected demo case. */
	const openSheet = (scenario: UserSheetScenario) => {
		setSelection({ scenario, userId: userIdForScenario(scenario) });
	};

/** Dismisses the sheet without clearing the cache so reopening can demonstrate skip-pending. */
	const closeSheet = () => {
		setSelection(null);
	};

/** Removes every cached sheet-async response so the next click shows the pending state again. */
	const clearCache = () => {
		queryClient.removeQueries({ queryKey: USER_QUERY_KEY_ROOT });
	};

return (
		<div className="flex flex-col gap-3">
			<div className="flex flex-wrap items-center gap-2">
				<Button
					type="button"
					appearance="filled"
					priority="neutral"
					onClick={() => openSheet("success")}
				>
					Happy path
				</Button>
				<Button
					type="button"
					appearance="outlined"
					priority="neutral"
					onClick={() => openSheet("not-found")}
				>
					404 error
				</Button>
				<Button
					type="button"
					appearance="filled"
					priority="danger"
					onClick={() => openSheet("server-error")}
				>
					500 error
				</Button>
			</div>
			<div className="flex flex-wrap items-center gap-2">
				<Button
					type="button"
					appearance="ghost"
					priority="neutral"
					onClick={clearCache}
					disabled={!isHappyPathCached}
				>
					Clear cache
				</Button>
			</div>
			<p className="text-sm text-muted" aria-live="polite">
				{describeCacheState(isHappyPathCached)}
			</p>
			{selection && (
				<UserSheet userId={selection.userId} scenario={selection.scenario} onClose={closeSheet} />
			)}
		</div>
	);
}

/** Returns the user id that makes the selected scenario readable in the UI. */
function userIdForScenario(scenario: UserSheetScenario): string {
	if (scenario === "not-found") {
		return "user_missing";
	}

return "user_01J8Q7Z5K2";
}

/** Options passed to the demo query hook. */
type UseUserQueryOptions = {
	/** User identifier requested by the sheet. */
	userId: string;
	/** Demo scenario selected by the user. */
	scenario: UserSheetScenario;
};

/** Fetches user details for the sheet with TanStack Query and an explicit retry policy. */
function useUserQuery({ scenario, userId }: UseUserQueryOptions): UseQueryResult<User, Error> {
	return useQuery<User, Error>({
		queryKey: [...USER_QUERY_KEY_ROOT, userId, scenario],
		queryFn: ({ signal }) => fetchUser({ userId, scenario, signal }),
		retry: (failureCount, error) => shouldRetryUserQuery({ error, failureCount }),
		retryDelay: USER_QUERY_RETRY_DELAY_MS,
		staleTime: 30_000,
		gcTime: 5 * 60_000,
	});
}

/** Options passed to the query retry policy. */
type ShouldRetryUserQueryOptions = {
	/** Number of failed attempts TanStack Query has observed. */
	failureCount: number;
	/** Error thrown by the query function. */
	error: Error;
};

/** Retries transient server failures while skipping terminal and cancelled requests. */
function shouldRetryUserQuery({ error, failureCount }: ShouldRetryUserQueryOptions): boolean {
	if (error instanceof RequestCancelledError) {
		return false;
	}

if (error instanceof UserRequestError && error.status === 500) {
		return failureCount < SERVER_ERROR_RETRY_LIMIT;
	}

return false;
}
```

## Mock API Appendix

The code above imports a mock API module so the sheet can demonstrate happy, 404, and 500 states without a backend. In production, replace this file with your real API client and preserve the same query behavior: accept `signal`, throw typed errors, and let the UI decide which errors are retryable.

```ts
const SIMULATED_USER_API_LATENCY_MS = 1_500;

/** Scenario names used by the docs demo controls. */
export type UserSheetScenario = "success" | "not-found" | "server-error";

/** The typed user record returned by the demo API. */
export type User = {
	/** Stable user identifier from the backend. */
	id: string;
	/** Display name shown in the sheet header content. */
	name: string;
	/** Primary email address for the account. */
	email: string;
	/** Role within the current workspace. */
	role: string;
	/** Workspace name used to make the example feel like app data. */
	workspace: string;
	/** Billing plan attached to the workspace. */
	plan: string;
	/** ISO date string for when the user joined. */
	joinedAt: string;
	/** Human-readable recent activity summary. */
	lastActiveAt: string;
};

/** The HTTP status codes intentionally simulated by the demo. */
type UserRequestErrorStatus = 404 | 500;

/** Options for constructing a typed demo request error. */
type UserRequestErrorOptions = {
	/** HTTP status returned by the simulated endpoint. */
	status: UserRequestErrorStatus;
	/** User-facing or operator-facing error message. */
	message: string;
	/** Request identifier included in the inline error UI. */
	requestId: string;
};

/** Error shape used when the simulated endpoint returns a non-2xx response. */
export class UserRequestError extends Error {
	/** HTTP status returned by the simulated endpoint. */
	readonly status: UserRequestErrorStatus;
	/** Request identifier included in the inline error UI. */
	readonly requestId: string;

/** Creates a typed request error that preserves HTTP metadata. */
	constructor({ message, requestId, status }: UserRequestErrorOptions) {
		super(message);
		this.name = "UserRequestError";
		this.requestId = requestId;
		this.status = status;
	}
}

/** Error used when TanStack Query aborts a request after the sheet unmounts. */
export class RequestCancelledError extends Error {
	/** Creates a cancellation error that the retry policy can ignore. */
	constructor() {
		super("The user details request was cancelled.");
		this.name = "RequestCancelledError";
	}
}

/** Options for delaying the simulated API response. */
type WaitForDemoApiOptions = {
	/** Delay duration in milliseconds. */
	durationMs: number;
	/** Abort signal passed by TanStack Query. */
	signal?: AbortSignal;
};

/** Waits before resolving so the sheet can show the pending state. */
function waitForDemoApi({ durationMs, signal }: WaitForDemoApiOptions): Promise<void> {
	return new Promise((resolve, reject) => {
		if (signal?.aborted) {
			reject(new RequestCancelledError());
			return;
		}

const timeoutId = setTimeout(() => {
			signal?.removeEventListener("abort", handleAbort);
			resolve();
		}, durationMs);

/** Cancels the simulated API delay when the query unmounts. */
		function handleAbort() {
			clearTimeout(timeoutId);
			signal?.removeEventListener("abort", handleAbort);
			reject(new RequestCancelledError());
		}

signal?.addEventListener("abort", handleAbort, { once: true });
	});
}

/** Options accepted by the simulated user fetcher. */
type FetchUserOptions = {
	/** User identifier requested by the sheet. */
	userId: string;
	/** Demo scenario selected by the user. */
	scenario: UserSheetScenario;
	/** Abort signal passed by TanStack Query. */
	signal?: AbortSignal;
};

/** Simulates a production API client with latency, typed data, and HTTP errors. */
export async function fetchUser({ scenario, signal, userId }: FetchUserOptions): Promise<User> {
	await waitForDemoApi({ durationMs: SIMULATED_USER_API_LATENCY_MS, signal });

if (scenario === "not-found") {
		throw new UserRequestError({
			status: 404,
			message: `No user exists for ${userId}.`,
			requestId: createDemoRequestId({ status: 404, userId }),
		});
	}

if (scenario === "server-error") {
		throw new UserRequestError({
			status: 500,
			message: "The user service failed before returning profile data.",
			requestId: createDemoRequestId({ status: 500, userId }),
		});
	}

return {
		id: userId,
		name: "Ada Lovelace",
		email: "ada.lovelace@example.com",
		role: "Founding Engineer",
		workspace: "Analytical Engines",
		plan: "Enterprise",
		joinedAt: "1843-07-08",
		lastActiveAt: "2 minutes ago",
	};
}

/** Options for creating a deterministic request id in the demo. */
type CreateDemoRequestIdOptions = {
	/** HTTP status returned by the simulated endpoint. */
	status: UserRequestErrorStatus;
	/** User identifier requested by the sheet. */
	userId: string;
};

/** Creates a stable request id so the error UI looks like real production output. */
function createDemoRequestId({ status, userId }: CreateDemoRequestIdOptions): string {
	return `req_${status}_${userId.replace(/[^a-z0-9]/gi, "").slice(-8)}`;
}
```

## Production Notes

- Keep the sheet UI in one component and keep API details behind `fetchUser` or your app's equivalent data client.
- Use the `signal` argument from TanStack Query's `queryFn` when your API client supports cancellation.
- Tune `retry` by status code. This demo does not retry 404 because the server already answered definitively. Retry not-found responses only when eventual consistency is expected.
- Let `staleTime` and `gcTime` govern cache lifetime; the sheet does not need to manually evict on close. The demo's "Clear cache" button only exists to make the cache state observable in docs — production sheets typically don't surface a manual reset.
- Prefer explicit query state branches here over `useSuspenseQuery`. Suspense works, but error recovery requires an additional reset boundary and is harder to copy into route-controlled sheets.

---

---
title: Changelog
description: Release notes for @ngrok/mantle, generated from the package's CHANGELOG.md via changesets.
---

# Changelog

Release notes for `@ngrok/mantle`, generated from the package's [`CHANGELOG.md`](https://github.com/ngrok/mantle/blob/main/packages/mantle/CHANGELOG.md) via [changesets](https://github.com/changesets/changesets). The same content is available as plain markdown at [`/changelog.md`](/changelog.md) for agent and tooling consumption.

See also the [npm version history](https://www.npmjs.com/package/@ngrok/mantle?activeTab=versions) and the [GitHub releases](https://github.com/ngrok/mantle/releases).

---

---

---
title: Alert
description: Displays a callout for user attention.
---

# Alert

Displays a callout for user attention.

```tsx
import { Alert } from "@ngrok/mantle/alert";
import { ShrimpIcon } from "@phosphor-icons/react/Shrimp";

<Alert.Root priority="danger">
	<Alert.Icon />
	<Alert.Content>
		<Alert.Title>Danger</Alert.Title>
		<Alert.Description>This is a danger Alert.</Alert.Description>
	</Alert.Content>
</Alert.Root>
<Alert.Root priority="info">
	<Alert.Icon />
	<Alert.Content>
		<Alert.Title>Info</Alert.Title>
		<Alert.DismissIconButton />
		<Alert.Description>This is an info Alert.</Alert.Description>
	</Alert.Content>
</Alert.Root>
<Alert.Root priority="important">
	<Alert.Icon />
	<Alert.Content>
		<Alert.Title>Important</Alert.Title>
		<Alert.Description>This is an important Alert.</Alert.Description>
	</Alert.Content>
</Alert.Root>
<Alert.Root priority="success">
	<Alert.Icon />
	<Alert.Content>
		<Alert.Title>Success</Alert.Title>
		<Alert.Description>This is a success Alert.</Alert.Description>
	</Alert.Content>
</Alert.Root>
<Alert.Root priority="warning">
	<Alert.Icon />
	<Alert.Content>
		<Alert.Title>Warning</Alert.Title>
		<Alert.Description>This is a warning Alert.</Alert.Description>
	</Alert.Content>
</Alert.Root>
<Alert.Root priority="danger">
	<Alert.Icon svg={<ShrimpIcon />} />
	<Alert.Content>
		<Alert.Title>Danger w/ custom icon</Alert.Title>
		<Alert.Description>This is a danger Alert.</Alert.Description>
	</Alert.Content>
</Alert.Root>
```

## Composition

Compose the parts of an `Alert` together to build your own:

```text showLineNumbers=false
Alert.Root
├── Alert.Icon
└── Alert.Content
    ├── Alert.Title
    ├── Alert.Description
    └── Alert.DismissIconButton
```

You can mix and match what you put inside the `Alert` component to create different types of Alert layouts.

```tsx
import { Alert } from "@ngrok/mantle/alert";

// Danger Alert with icon and Dismiss Icon Button
<Alert.Root priority="danger">
	<Alert.Icon />
	<Alert.Content>
		<Alert.Title>Danger Will Robinson</Alert.Title>
		<Alert.DismissIconButton />
		<Alert.Description>This is a danger alert.</Alert.Description>
	</Alert.Content>
</Alert.Root>

// Danger Alert without icon
<Alert.Root priority="danger">
	<Alert.Content>
		<Alert.Title>Danger Will Robinson</Alert.Title>
		<Alert.Description>This is a danger alert.</Alert.Description>
	</Alert.Content>
</Alert.Root>

// Danger Alert with icon and no description
<Alert.Root priority="danger">
	<Alert.Icon />
	<Alert.Content>
		<Alert.Title>Danger Will Robinson</Alert.Title>
	</Alert.Content>
</Alert.Root>

// Danger Alert without icon or description, but including a Dismiss Icon Button
<Alert.Root priority="danger">
	<Alert.Content>
		<Alert.Title>Danger Will Robinson</Alert.Title>
		<Alert.DismissIconButton />
	</Alert.Content>
</Alert.Root>
```

## Banners

For banner-like alerts, use the `appearance="banner"` prop. This automatically removes the top, left, and right border, leaving only the bottom border.

```tsx
import { Alert } from "@ngrok/mantle/alert";

<Alert.Root priority="info" appearance="banner">
	<Alert.Icon />
	<Alert.Content>
		<Alert.Title>This is an info Alert as a page banner</Alert.Title>
	</Alert.Content>
</Alert.Root>;
```

## Custom Dismiss Icon

Use the `icon` prop on `Alert.DismissIconButton` to render a custom icon in place of the default `X`.

```tsx
import { Alert } from "@ngrok/mantle/alert";
import { ShrimpIcon } from "@phosphor-icons/react/Shrimp";

<Alert.Root priority="warning">
	<Alert.Icon />
	<Alert.Content>
		<Alert.Title>Custom Dismiss Icon</Alert.Title>
		<Alert.DismissIconButton icon={<ShrimpIcon />} />
		<Alert.Description>This dismiss button uses a custom icon.</Alert.Description>
	</Alert.Content>
</Alert.Root>;
```

## API Reference

### Alert.Root

Displays a callout for user attention. Root container for all `Alert` sub-components.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop          | Type                                                 | Default     | Description                                                                                                                                                                                                    |
| ------------- | ---------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appearance?` | `"default"` \| `"banner"`                            | `"default"` | Controls the visual style. `"default"` provides standard rounded corners and borders. `"banner"` creates a banner-style alert with no rounded corners, sticky positioning, and no top, left, or right borders. |
| `priority`    | `"danger"` \| `"info"` \| `"success"` \| `"warning"` |             | Indicates the importance or impact level of the `Alert`, affecting its color and styling to communicate its purpose.                                                                                           |

### Alert.Content

The container for the content slot of an `Alert`. Place `Alert.Title`, `Alert.Description`, and `Alert.DismissIconButton` as direct children.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes).

### Alert.Description

The optional description of an `Alert`. Renders as a `div` by default, but can be changed to any other element using the `asChild` prop.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                                   |
| ---------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `AlertDescription` styling onto alternative element types or your own React components. |

### Alert.Icon

An optional icon that visually represents the priority of the `Alert`. The default rendered icon can be overridden with a custom icon using the `svg` prop.

All props from [svg](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/svg#attributes), plus:

| Prop   | Type        | Default | Description                                                                          |
| ------ | ----------- | ------- | ------------------------------------------------------------------------------------ |
| `svg?` | `ReactNode` |         | An optional icon that renders in place of the default icon for the `Alert` priority. |

### Alert.Title

The title of an `Alert`. Renders as an `h5` element by default; use `asChild` to render something else.

All props from [h5](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                             |
| ---------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `AlertTitle` styling onto alternative element types or your own React components. |

### Alert.DismissIconButton

A dismiss icon button that closes the alert when clicked.

All props from [IconButton](/components/icon-button#api-reference), with the following overridden defaults:

| Prop          | Type                                  | Default           | Description                                                                    |
| ------------- | ------------------------------------- | ----------------- | ------------------------------------------------------------------------------ |
| `appearance?` | `"ghost"` \| `"outlined"`             | `"ghost"`         | The visual style of the button.                                                |
| `icon?`       | `ReactNode`                           | `<XIcon />`       | An optional icon to render inside the dismiss button. Defaults to an `X` icon. |
| `label?`      | `string`                              | `"Dismiss Alert"` | The accessible label for the button, announced to screen readers.              |
| `size?`       | `"xs"` \| `"sm"` \| `"md"`            | `"sm"`            | The size of the button.                                                        |
| `type?`       | `"button"` \| `"submit"` \| `"reset"` | `"button"`        | The default behavior of the button.                                            |

---

---
title: Alert Dialog
description: A modal dialog that interrupts the user with important content and expects a response.
---

# Alert Dialog

A modal dialog that interrupts the user with important content and expects a response. Built on top of [Radix Dialog](https://www.radix-ui.com/primitives/docs/components/dialog).

## When to use

Use `AlertDialog` for destructive or irreversible confirmations (delete, sign out, leave without saving) where the user must explicitly acknowledge. `AlertDialog` blocks all background interaction. For non-destructive input modals, use [`Dialog`](/components/dialog).

```tsx
import { AlertDialog } from "@ngrok/mantle/alert-dialog";
import { Button } from "@ngrok/mantle/button";

<AlertDialog.Root priority="info">
	<AlertDialog.Trigger asChild>
		<Button type="button" appearance="outlined" priority="neutral">
			Show Info Alert Dialog
		</Button>
	</AlertDialog.Trigger>
	<AlertDialog.Content>
		<AlertDialog.Icon />
		<AlertDialog.Body>
			<AlertDialog.Header>
				<AlertDialog.Title>Are you absolutely sure?</AlertDialog.Title>
				<AlertDialog.Description>
					Proident quis nisi tempor irure sunt ut minim occaecat mollit sunt.
				</AlertDialog.Description>
			</AlertDialog.Header>
			<AlertDialog.Footer>
				<AlertDialog.Cancel type="button">Cancel</AlertDialog.Cancel>
				<AlertDialog.Action type="button">Continue</AlertDialog.Action>
			</AlertDialog.Footer>
		</AlertDialog.Body>
	</AlertDialog.Content>
</AlertDialog.Root>;
```

## Composition

Compose the parts of an `AlertDialog` together to build your own:

```text showLineNumbers=false
AlertDialog.Root
├── AlertDialog.Trigger
└── AlertDialog.Content
    ├── AlertDialog.Icon
    └── AlertDialog.Body
        ├── AlertDialog.Header
        │   ├── AlertDialog.Title
        │   └── AlertDialog.Description
        └── AlertDialog.Footer
            ├── AlertDialog.Cancel
            └── AlertDialog.Action
```

## API Reference

### AlertDialog.Root

The root component for the Alert Dialog.

All props from Radix [Dialog.Root](https://www.radix-ui.com/primitives/docs/components/dialog#root), plus:

| Prop       | Type                   | Default | Description                                                                                                              |
| ---------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `priority` | `"info"` \| `"danger"` |         | Indicates the importance or impact level of the AlertDialog, affecting its color and styling to communicate its purpose. |

### AlertDialog.Trigger

A button that opens the Alert Dialog.

Radix [Dialog.Trigger](https://www.radix-ui.com/primitives/docs/components/dialog#trigger) props.

### AlertDialog.Content

The popover Alert Dialog container. Renders on top of the overlay and is centered in the viewport.

Radix [Dialog.Content](https://www.radix-ui.com/primitives/docs/components/dialog#content) props, plus:

| Prop              | Type     | Default      | Description                                                                   |
| ----------------- | -------- | ------------ | ----------------------------------------------------------------------------- |
| `preferredWidth?` | `string` | `"max-w-md"` | The preferred width of the `AlertDialogContent` as a Tailwind `max-w-` class. |

### AlertDialog.Body

Contains the main content of the alert dialog.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                                  |
| ---------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `AlertDialogBody` styling onto alternative element types or your own React components. |

### AlertDialog.Header

Contains the header content of the dialog, including the title and description.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                                    |
| ---------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `AlertDialogHeader` styling onto alternative element types or your own React components. |

### AlertDialog.Footer

Contains the footer content of the dialog, including the action and cancel buttons.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                                    |
| ---------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `AlertDialogFooter` styling onto alternative element types or your own React components. |

### AlertDialog.Title

An accessible name to be announced when the dialog is opened.

Alternatively, you can provide `aria-label` or `aria-labelledby` to `AlertDialogContent` and exclude this component.

Radix [Dialog.Title](https://www.radix-ui.com/primitives/docs/components/dialog#title) props.

### AlertDialog.Description

An accessible description to be announced when the dialog is opened. Renders as a `div` by default, but can be changed to any other element using the `asChild` prop.

Alternatively, you can provide `aria-describedby` to `AlertDialogContent` and exclude this component.

Radix [Dialog.Description](https://www.radix-ui.com/primitives/docs/components/dialog#description) props.

### AlertDialog.Action

A button that confirms the Alert Dialog action. Defaults to `appearance="filled"` and the priority color from `AlertDialog.Root`. Does not close the alert dialog by default.

These buttons should be distinguished visually from `AlertDialog.Cancel`.

Composes around the mantle [Button](/components/button) component. Same props as [Button](/components/button).

### AlertDialog.Cancel

A button that closes the dialog and cancels the action. Defaults to `appearance="outlined"` and `priority="neutral"`.

This button should be distinguished visually from `AlertDialog.Action`.

Composes around the mantle [Button](/components/button) component. Same props as [Button](/components/button).

### AlertDialog.Icon

An icon displayed in the alert dialog, usually to indicate the type of alert.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                                   |
| ---------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `AlertDialog.Icon` styling onto alternative element types or your own React components. |

### AlertDialog.Close

A button that closes the dialog.

All props from [button](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                                    |
| ---------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `AlertDialog.Close` styling onto alternative element types or your own React components. |

---

---
title: Anchor
description: Fundamental component for rendering links to external addresses.
---

# Anchor

A styled hyperlink — a native `<a>` with mantle's link styling, focus treatment, optional leading/trailing icon, and a safer default for the `rel` attribute. Use for links that point *outside* the current application.

The `<Anchor>` element, with its `href` attribute, creates a hyperlink to web pages, files, email addresses, locations in the same page, or anything else a URL can address. See the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) for more information.

## When to use

- External URLs (docs, marketing pages, third-party sites).
- Links to files or `mailto:` / `tel:` destinations.

## When not to use

- Internal application routes — prefer the framework router's link primitive ([`react-router` `<Link>`](https://reactrouter.com/en/main/components/link)) so client-side navigation kicks in. You can keep mantle's styling by composing:

```tsx
<Anchor asChild>
	<Link to={href("/foo")}>…</Link>
</Anchor>
```

- For triggering an action — use a [`Button`](/components/button) instead. If it doesn't navigate, it's not a link.

## Icons

Pass `icon` (a phosphor or custom SVG) and optionally `iconPlacement` (`"start"` default, or `"end"`) to render a small inline icon — useful for "external link" or "download" affordances. Icons are decorative; the link text must still describe the destination on its own.

## Security

When `target="_blank"`, `rel` should include `"noopener noreferrer"`. The `rel` prop accepts an array — duplicates are de-duped and sorted, so it's safe to merge token sets.

## Accessibility

Link text must be self-describing — avoid "click here" / "read more". For purely decorative icons, no extra labeling is needed; for icon-only links, provide an `aria-label`.

```tsx
import { Anchor } from "@ngrok/mantle/anchor";
import { BookIcon } from "@phosphor-icons/react/Book";
import { ShrimpIcon } from "@phosphor-icons/react/Shrimp";

<p>
	This link will go to <Anchor href="https://ngrok.com/">ngrok.com</Anchor>!
</p>
<p>
	You can add icons! This one renders at the start:{" "}
	<Anchor href="https://ngrok.com/docs" icon={<BookIcon />}>
		ngrok docs
	</Anchor>
	!
</p>
<p>
	And this icon renders at the end:{" "}
	<Anchor href="https://dashboard.ngrok.com" icon={<ShrimpIcon />} iconPlacement="end">
		ngrok dashboard
	</Anchor>
	!
</p>
```

## API Reference

### Anchor

All props from [a](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes), plus:

| Prop             | Type                 | Default   | Description                                                                                                         |
| ---------------- | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------- |
| `icon?`          | `ReactNode`          |           | An icon to render inside the anchor.                                                                                |
| `iconPlacement?` | `"start"` \| `"end"` | `"start"` | The side that the icon will render on, if one is present.                                                           |
| `asChild?`       | `boolean`            | `false`   | Use the `asChild` prop to compose the `Anchor` styling onto alternative element types or your own React components. |

---

---
title: Badge
description: A non-interactive label used to highlight short, scannable information — a status, a category tag, or a count — in the smallest possible footprint.
---

# Badge

A non-interactive label used to highlight short, scannable information — a status, a category tag, or a count — in the smallest possible footprint.

## When to use

- Status indicators: `Succeeded`, `Failed`, `Pending`, `Beta`.
- Category or tag chips alongside list items, table rows, or cards.
- Counts (e.g. `12 new`) when paired with brief context.

## When not to use

- For interactive UI. Badges are not buttons or links — use [`Button`](/components/button) or [`Anchor`](/components/anchor) (optionally with `asChild` styling) instead.
- For long-form text. Keep labels to one or two short words.
- As the sole signal of meaning. Pair color with a label or icon so the distinction works without color (color blindness, monochrome themes).

## Choosing a color

Prefer functional colors (`success`, `warning`, `danger`, `info`, `accent`, `neutral`) for status meaning so theming stays coherent. Reach for named hues only when the badge's semantic role isn't already covered.

```tsx
import { Badge } from "@ngrok/mantle/badge";
import { GlobeHemisphereWestIcon } from "@phosphor-icons/react/GlobeHemisphereWest";

<Badge appearance="muted" color="neutral">
	Muted neutral
</Badge>
<Badge appearance="muted" color="neutral" icon={<GlobeHemisphereWestIcon />}>
	Muted neutral
</Badge>
```

## Polymorphism

When you want to render *something else* as a `Badge`, you can use the `asChild` prop to compose. This is useful when you want to splat the `Badge` styling onto a `react-router` `Link`.

```tsx
import { Badge } from "@ngrok/mantle/badge";
import { GlobeHemisphereWestIcon } from "@phosphor-icons/react/GlobeHemisphereWest";
import { Link, href } from "react-router";

<Badge appearance="muted" asChild color="pink" icon={<GlobeHemisphereWestIcon />}>
	<Link to={href("/base/colors")}>See our colors!</Link>
</Badge>;
```

## API Reference

### Badge

All props from [span](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span#attributes), plus:

| Prop         | Type                                                                                                                                                                                                                                                        | Default     | Description                                                                                                        |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `appearance` | `"muted"`                                                                                                                                                                                                                                                   |             | Defines the visual style of the `Badge`. Currently only supports the `muted` variant.                              |
| `asChild?`   | `boolean`                                                                                                                                                                                                                                                   | `false`     | Use the `asChild` prop to compose the `Badge` styling onto alternative element types or your own React components. |
| `color?`     | `"neutral"` \| `"danger"` \| `"important"` \| `"info"` \| `"success"` \| `"warning"` \| `"blue"` \| `"cyan"` \| `"fuchsia"` \| `"gray"` \| `"green"` \| `"indigo"` \| `"lime"` \| `"orange"` \| `"pink"` \| `"purple"` \| `"red"` \| `"teal"` \| `"yellow"` | `"neutral"` | The color variant of the `Badge`. Supports all [named colors](/base/colors), both functional and from the palette. |
| `icon?`      | `ReactNode`                                                                                                                                                                                                                                                 |             | An icon to render inside the badge. Will be automatically sized for you.                                           |

---

---
title: BrowserOnly
description: A wrapper component that ensures its children only render in the browser, after hydration has completed.
---

# BrowserOnly

A wrapper component that ensures its children only render in the browser, after hydration has completed. Useful for components that rely on browser-only APIs like `window`, `document`, `localStorage`, or media queries.

```tsx
import { BrowserOnly } from "@ngrok/mantle/browser-only";

<BrowserOnly fallback={<div className="h-8 w-32 bg-gray-200 animate-pulse rounded" />}>
	{() => <p>This only renders in the browser after hydration!</p>}
</BrowserOnly>

<BrowserOnly fallback={<div className="h-20 bg-gray-100 rounded p-4">Loading...</div>}>
	{() => (
		<div className="p-4 border rounded">
			<p>Browser-only content with window dimensions:</p>
			<p>Width: {window.innerWidth}px</p>
			<p>Height: {window.innerHeight}px</p>
		</div>
	)}
</BrowserOnly>
```

## API Reference

### BrowserOnly

| Prop        | Type              | Default | Description                                                                                                                                                                                               |
| ----------- | ----------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children`  | `() => ReactNode` |         | Children must be a render function so that evaluation is deferred until after hydration has occurred.                                                                                                     |
| `fallback?` | `ReactNode`       | `null`  | Optional fallback to render on the server (and during hydration) before the client-only children are mounted. Ideally, this should be the same dimensions as the eventual children to avoid layout shift. |

---

---
title: Button
description: Initiates an action, such as completing a task or submitting information.
---

# Button

Initiates an action, such as completing a task or submitting information.

```tsx
import { Button } from "@ngrok/mantle/button";

<Button>Outlined</Button>
<Button appearance="filled">Filled</Button>
<Button appearance="ghost">Ghost</Button>
<Button appearance="link">Link</Button>

<Button priority="neutral">Outlined</Button>
<Button priority="neutral" appearance="filled">Filled</Button>
<Button priority="neutral" appearance="ghost">Ghost</Button>
<Button priority="neutral" appearance="link">Link</Button>

<Button priority="danger">Outlined</Button>
<Button priority="danger" appearance="filled">Filled</Button>
<Button priority="danger" appearance="ghost">Ghost</Button>
<Button priority="danger" appearance="link">Link</Button>
```

## Type

Unlike the native `<button>` element — which defaults to `type="submit"` — a mantle `Button` defaults to **`type="button"`**. This matches the wider React ecosystem (Radix, shadcn, MUI, …) and stops a button from accidentally submitting a surrounding `<form>` when all you wanted was an `onClick`.

The tradeoff: a button that *should* submit a form has to opt in with `type="submit"` (or `type="reset"` to reset it). A plain `<Button>` that relies on native form submission will silently do nothing.

```tsx
// ✅ Opts in — submits the form
<Button type="submit" appearance="filled">Save</Button>

// ❌ Defaults to type="button" — native form submission never fires
<Button appearance="filled">Save</Button>
```

When `asChild` is used, `type` has no effect and is not forwarded to the child, so a wrapped anchor never inherits a `button` `type`.

## Icon and Positioning

Use the `icon` prop to add an icon to the button. By default, it will render on the logical start side of the button. Use the `iconPlacement` prop to change the side the icon is rendered on.

```tsx
import { Button } from "@ngrok/mantle/button";
import { FireIcon } from "@phosphor-icons/react/Fire";

<Button icon={<FireIcon weight="fill" />}>Icon Start</Button>
<Button icon={<FireIcon weight="fill" />} iconPlacement="end">
	Icon End
</Button>
```

## isLoading

`isLoading` determines whether or not the button is in a loading state, default `false`. Setting `isLoading` will replace any `icon` with a spinner, or add one if an icon wasn't given. It will also disable user interaction with the button and set `aria-disabled`.

```tsx
import { Button } from "@ngrok/mantle/button";
import { FireIcon } from "@phosphor-icons/react/Fire";

<Button>No Icon + Idle</Button>
<Button icon={<FireIcon weight="fill" />}>Icon Start + Idle</Button>
<Button icon={<FireIcon weight="fill" />} iconPlacement="end">
	Icon End + Idle
</Button>
<Button isLoading>No Icon + isLoading</Button>
<Button icon={<FireIcon weight="fill" />} isLoading>
	Icon Start + isLoading
</Button>
<Button icon={<FireIcon weight="fill" />} iconPlacement="end" isLoading>
	Icon End + isLoading
</Button>
```

## Polymorphism

When you want to render *something else* as a `Button`, you can use the `asChild` prop to compose. This is useful when you want to splat the `Button` styling onto a `react-router` `Link`. Keep in mind that when you use `asChild` the `type` prop will **NOT** be passed to the child component.

```tsx
import { Button } from "@ngrok/mantle/button";
import { FireIcon } from "@phosphor-icons/react/Fire";
import { Link, href } from "react-router";

<Button appearance="filled" icon={<FireIcon weight="fill" />} asChild>
	<Link to={href("/base/colors")}>See our colors!</Link>
</Button>;
```

## API Reference

### Button

All props from [button](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes), plus:

| Prop             | Type                                                | Default      | Description                                                                                                                                                                                                                                                                                                                                                            |
| ---------------- | --------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appearance?`    | `"ghost"` \| `"filled"` \| `"outlined"` \| `"link"` | `"outlined"` | Defines the visual style of the `Button`.                                                                                                                                                                                                                                                                                                                              |
| `asChild?`       | `boolean`                                           | `false`      | Use the `asChild` prop to compose the `Button` styling onto alternative element types or your own React components.                                                                                                                                                                                                                                                    |
| `icon?`          | `ReactNode`                                         |              | An icon to render inside the button. When `isLoading` is `true`, the icon will automatically be replaced with a spinner.                                                                                                                                                                                                                                               |
| `iconPlacement?` | `"start"` \| `"end"`                                | `"start"`    | The side that the icon will render on, if one is present. When `isLoading` is `true`, the loading spinner will also render on this side.                                                                                                                                                                                                                               |
| `isLoading?`     | `boolean`                                           | `false`      | Determines whether or not the button is in a loading state. Setting `isLoading` will replace any `icon` with a spinner, or add one if an icon wasn't given. It will also disable user interaction with the button and set `aria-disabled`.                                                                                                                             |
| `priority?`      | `"default"` \| `"danger"` \| `"neutral"`            | `"default"`  | Indicates the importance or impact level of the button, affecting its color and styling to communicate its purpose to the user.                                                                                                                                                                                                                                        |
| `type?`          | `"button"` \| `"reset"` \| `"submit"`               | `"button"`   | The behavior of the `Button` when activated. Defaults to `"button"`, so a `Button` inside a `<form>` will **not** submit it — pass `type="submit"` to submit the form. When `asChild` is used, `type` has no effect and is not forwarded to the child. See [the MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#type) for more information. |

---

---
title: Card
description: A container used to display content in a box, resembling a physical card.
---

# Card

A container used to display content in a box, resembling a physical card. Composed of several sub-components.

```tsx
import { Card } from "@ngrok/mantle/card";

<Card.Root>
	<Card.Body>
		<p>Laborum in aute officia adipisicing elit velit.</p>
	</Card.Body>
</Card.Root>

<Card.Root className="shadow-lg">
	<Card.Header>
		<Card.Title>Card Title Here</Card.Title>
	</Card.Header>
	<Card.Body>
		<p>Laborum in aute officia adipisicing elit velit.</p>
	</Card.Body>
	<Card.Footer>
		<p>Card footer</p>
	</Card.Footer>
</Card.Root>

<Card.Root>
	<Card.Header>
		<Card.Title>Card Title Here</Card.Title>
	</Card.Header>
	<Card.Body>
		<p>Laborum in aute officia adipisicing elit velit.</p>
	</Card.Body>
</Card.Root>

<Card.Root>
	<Card.Body>
		<p>Laborum in aute officia adipisicing elit velit.</p>
	</Card.Body>
	<Card.Footer>
		<p>Card footer</p>
	</Card.Footer>
</Card.Root>
```

## Composition

Compose the parts of a `Card` together to build your own:

```text showLineNumbers=false
Card.Root
├── Card.Header
│   └── Card.Title
├── Card.Body
└── Card.Footer
```

## API Reference

### Card.Root

A container that displays content in a box resembling a physical card. The root component of all `Card` sub-components.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                       |
| ---------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `Card` styling onto alternative element types or your own React components. |

### Card.Body

The main content of a card. Usually composed as a direct child of `Card.Root`.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                            |
| ---------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `Card.Body` styling onto alternative element types or your own React components. |

### Card.Footer

The footer container of a card. Usually composed as a direct child of `Card.Root`.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                              |
| ---------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `Card.Footer` styling onto alternative element types or your own React components. |

### Card.Header

The header container of a card. Usually composed as a direct child of `Card.Root`.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                              |
| ---------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `Card.Header` styling onto alternative element types or your own React components. |

### Card.Title

The title of a card. Usually composed as a direct child of `Card.Header`. Renders as an `h3` element by default, but can be changed to any other element by using the `asChild` prop. Prefer using a heading element (`h1-h6`) for accessibility.

All props from [h1-h6](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                             |
| ---------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `Card.Title` styling onto alternative element types or your own React components. |

---

---
title: Checkbox
description: A form control that allows the user to toggle between checked and not checked. Supports indeterminate state.
---

# Checkbox

A form control that allows the user to toggle between checked and not checked. Supports indeterminate state.

Pair with `Field.*` for label/description/error wiring in forms:

```tsx
import { Checkbox } from "@ngrok/mantle/checkbox";
import { Field } from "@ngrok/mantle/field";

<Field.Item name="terms-of-service">
	<Field.Label className="flex items-center gap-2">
		<Field.Control>
			<Checkbox />
		</Field.Control>
		Accept terms and conditions
	</Field.Label>
	<Field.Description>You must accept before continuing.</Field.Description>
</Field.Item>;
```

Or render the control on its own:

```tsx
import { Checkbox } from "@ngrok/mantle/checkbox";
import { Label } from "@ngrok/mantle/label";

<Label htmlFor="terms" className="flex items-center gap-2">
	<Checkbox name="terms" id="terms" />
	Accept terms and conditions
</Label>
<Label htmlFor="unchecked" className="flex items-center gap-2">
	<Checkbox id="unchecked" name="unchecked" checked={false} readOnly />
	Unchecked
</Label>
<Label htmlFor="checked" className="flex items-center gap-2">
	<Checkbox id="checked" name="checked" checked readOnly />
	Checked
</Label>
<Label htmlFor="indeterminate" className="flex items-center gap-2">
	<Checkbox id="indeterminate" name="indeterminate" defaultChecked="indeterminate" readOnly />
	Indeterminate
</Label>
```

## With TanStack Form

Use `@tanstack/react-form` with `zod` to keep the checkbox controlled and render errors through `Field.Errors`.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Checkbox } from "@ngrok/mantle/checkbox";
import { Field, toErrorMessages } from "@ngrok/mantle/field";
import { useForm } from "@tanstack/react-form";
import { z } from "zod";

export const formSchema = z.object({
	acceptedTerms: z.boolean().refine((value) => value, "Accept the terms to continue."),
});
function Example() {
	const defaultValues = {
		acceptedTerms: false,
	};
	const form = useForm({
		defaultValues,
		validators: {
			onSubmit: formSchema,
		},
		onSubmit: ({ value }) => {
			// Handle form submission here
		},
	});

return (
		<form
			className="space-y-4"
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<form.Field name="acceptedTerms">
				{(field) => (
					<Field.Item name={field.name}>
						<Field.Label className="flex items-center gap-2">
							<Field.Control>
								<Checkbox
									checked={field.state.value}
									onBlur={field.handleBlur}
									onChange={(event) => field.handleChange(event.target.checked)}
								/>
							</Field.Control>
							Accept terms and conditions
						</Field.Label>
						<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
					</Field.Item>
				)}
			</form.Field>
			<Button type="submit" appearance="filled" priority="neutral">
				Submit
			</Button>
		</form>
	);
}
```

## Select-all helper

`selectAllChecked` resolves the tri-state `checked` value for a "select all" checkbox from the current selection counts — `true` when everything is selected, `"indeterminate"` when only some is, and `false` when nothing is. Use it to keep the header checkbox of a multi-select list correct without hand-rolling the tri-state branch. It pairs directly with a [`DataTable`](/components/data-table#row-selection-with-checkboxes) row-selection column:

```tsx
import { Checkbox, selectAllChecked } from "@ngrok/mantle/checkbox";

<Checkbox
	aria-label="Select all rows"
	checked={selectAllChecked({
		allSelected: table.getIsAllRowsSelected(),
		someSelected: table.getIsSomeRowsSelected(),
	})}
	onChange={(event) => table.toggleAllRowsSelected(event.target.checked)}
/>;
```

Returns `boolean | "indeterminate"` (a `CheckedState`), ready to pass straight to `Checkbox`'s `checked` prop. `allSelected` takes precedence, so it wins even if a caller also reports `someSelected`.

## API Reference

### Checkbox

All props from [input\[type="checkbox"\]](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox), plus:

| Prop              | Type                                                                                                     | Default | Description                                                                                                                                                                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `checked?`        | `boolean` \| `"indeterminate"`                                                                           |         | Whether the checkbox is checked or not. Setting this to `"indeterminate"` will show the indeterminate state. This is useful for parent-child relationships, but requires manual, controlled state.                                           |
| `defaultChecked?` | `boolean` \| `"indeterminate"`                                                                           |         | The checked state of the checkbox when it is initially rendered. Use when you do not need to control its checked state.                                                                                                                      |
| `validation?`     | `"error"` \| `"success"` \| `"warning"` \| `false` \| `() => "error" \| "success" \| "warning" \| false` |         | Use the `validation` prop to show a specific validation status. This will change the border and outline of the checkbox. The `false` type is useful with short-circuiting logic. Setting `validation` to `"error"` also sets `aria-invalid`. |

---

---
title: Code
description: Marks a short fragment of inline computer code — a function name, a variable, a CLI flag, a key.
---

# Code

Marks a short fragment of inline computer code — a function name, a variable, a CLI flag, a key. Renders a native `<code>` element with mantle's monospace styling.

## When to use

- Inline within prose to identify code, file paths, env vars, or keys.
- Wrap technical terms that should visually stand apart from running text.

## When not to use

- For multi-line or syntax-highlighted blocks. Use [`CodeBlock`](/components/code-block) instead.
- For keyboard shortcuts. Use [`Kbd`](/components/kbd).
- For arbitrary monospace text that isn't code (use a plain monospace utility class).

```tsx
import { Code } from "@ngrok/mantle/code";

<p>
	Use the <Code>console.log()</Code> function to debug your code.
</p>;
```

## Polymorphism

Pass `asChild` to render `Code` styling on a different element — for example, a link wrapping a code-styled label.

```tsx
import { Anchor } from "@ngrok/mantle/anchor";
import { Code } from "@ngrok/mantle/code";

<Code asChild>
	<Anchor href="https://ngrok.com/docs">/api/components.json</Anchor>
</Code>;
```

## API Reference

### Code

All props from [code](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/code#attributes), plus:

| Prop         | Type        | Default | Description                                                                                                       |
| ------------ | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `asChild?`   | `boolean`   | `false` | Use the `asChild` prop to compose the `Code` styling onto alternative element types or your own React components. |
| `children`   | `ReactNode` |         | The content to be rendered inside the inline code element.                                                        |
| `className?` | `string`    |         | Additional CSS classes to apply to the inline code element.                                                       |

---

---
title: Code Block
description: Code blocks render and apply syntax highlighting to blocks of code using Shiki at build time.
---

# Code Block

Code blocks render and apply syntax highlighting to blocks of code. Syntax highlighting is performed at build time using [Shiki](https://shiki.style/) via the `mantleCodeBlockPlugins()` Vite plugin, so there is zero highlighting cost in the browser.

Use `mantleCode("language")` tagged template literals to define code values. The Vite plugin transforms these at build time, inlining pre-rendered HTML.

```tsx
import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";

<CodeBlock.Root>
	<CodeBlock.Header>
		<CodeBlock.Icon preset="file" />
		<CodeBlock.Title>…</CodeBlock.Title>
	</CodeBlock.Header>
	<CodeBlock.Body>
		<CodeBlock.CopyButton />
		<CodeBlock.Code value={mantleCode("javascript")`…`} />
	</CodeBlock.Body>
	<CodeBlock.ExpanderButton />
</CodeBlock.Root>;
```

## Examples

### Single Line with a Header

Many code blocks will be single line command line prompts and should be able to render with a header and copy button. This makes it absolutely clear that this example is a command line prompt and not a code sample.

```tsx
<CodeBlock.Root>
	<CodeBlock.Header>
		<CodeBlock.Icon preset="cli" />
		<CodeBlock.Title>Command Line</CodeBlock.Title>
	</CodeBlock.Header>
	<CodeBlock.Body>
		<CodeBlock.CopyButton />
		<CodeBlock.Code
			value={mantleCode(
				"bash",
			)`sudo unzip ~/Downloads/ngrok-v3-stable-darwin.zip -d /usr/local/bin`}
		/>
	</CodeBlock.Body>
</CodeBlock.Root>
```

### Horizontal Scrolling

This example is included to demonstrate that code blocks can scroll horizontally if the content is too wide. Mantle attempts to normalize scrollbar styling across browsers and platforms.

```tsx
<CodeBlock.Root>
	<CodeBlock.Header>
		<CodeBlock.Icon preset="file" />
		<CodeBlock.Title>ngrok-example.js</CodeBlock.Title>
	</CodeBlock.Header>
	<CodeBlock.Body>
		<CodeBlock.CopyButton />
		<CodeBlock.Code
			value={mantleCode("javascript")`
				const http = require('http');
				const ngrok = require("@ngrok/ngrok");
				const server = http.createServer((req, res) => {
					res.writeHead(200);
					res.end("Hello!");
					setTimeout(() => {
						Promise.resolve().then(() => {
							console.log("url:", server.tunnel.url());
						});
					}, timeout);
				});
				// Consumes authtoken from env automatically
				ngrok.listen(server).then(() => {
					console.log("url:", server.tunnel.url());
				});
				// really long line here that should wrap around and stuff Officia ipsum sint eu labore esse deserunt aliqua quis irure.
			`}
		/>
	</CodeBlock.Body>
</CodeBlock.Root>
```

### No Header or Copy Button

This is the most simple example of our code block component. While very useful, the copy button is optional. It is also perfectly acceptable to render a code block without a header, especially if context is provided in the surrounding content or the code block is self-explanatory eg. "In your index.js file, paste the following:".

```tsx
<CodeBlock.Root>
	<CodeBlock.Body>
		<CodeBlock.Code
			value={mantleCode("javascript")`
				const http = require('http');
				const ngrok = require("@ngrok/ngrok");
				const server = http.createServer((req, res) => {
					res.writeHead(200);
					res.end("Hello!");
				});
				ngrok.listen(server).then(() => {
					console.log("url:", server.tunnel.url());
				});
			`}
		/>
	</CodeBlock.Body>
</CodeBlock.Root>
```

### Single Line with Horizontal Scrolling

This example is included to show the interaction between the copy button and horizontal scrolling on a single verbose terminal command.

```tsx
<CodeBlock.Root>
	<CodeBlock.Body>
		<CodeBlock.CopyButton />
		<CodeBlock.Code
			value={mantleCode(
				"bash",
			)`ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4`}
		/>
	</CodeBlock.Body>
</CodeBlock.Root>
```

### Server-Rendered Syntax Highlighting

The `CodeBlock` supports server-rendered syntax highlighting for dynamic or user-provided code. Use `createMantleCodeBlockValue()` to construct a value from server-highlighted HTML and pass it to `CodeBlock.Code`. This is useful when the code to highlight isn't known at build time — for example, user input or API responses.

```tsx
import {
	CodeBlock,
	createMantleCodeBlockValue,
	type MantleCodeBlockValue,
} from "@ngrok/mantle/code-block";

// Fetch highlighted HTML from your server
const response = await fetch("/api/shiki-highlight", {
	method: "POST",
	headers: { "Content-Type": "application/json" },
	body: JSON.stringify({ code, language: "typescript", showLineNumbers: true }),
});
const data = await response.json();

// Create a MantleCodeBlockValue from the server response
const value: MantleCodeBlockValue = createMantleCodeBlockValue({
	code: data.code,
	language: "typescript",
	preHtml: data.html,
	showLineNumbers: data.showLineNumbers,
	highlightLines: data.highlightLines,
	lineNumberStart: data.lineNumberStart,
});

<CodeBlock.Root>
	<CodeBlock.Body>
		<CodeBlock.CopyButton />
		<CodeBlock.Code value={value} />
	</CodeBlock.Body>
</CodeBlock.Root>;
```

### Highlight Microservice (for Go / non-Node.js backends)

For frontends backed by non-Node.js services (Go, Python, etc.), deploy a small Node.js highlight service as a sidecar or shared microservice. This gives you the same server-rendered highlighting without shipping Shiki to the browser — the frontend just calls the API with `fetch`.

Create a highlight server using `createMantleServerSyntaxHighlighter`:

```ts
// highlight-service.ts — deploy as a sidecar alongside your Go service
import { createServer } from "node:http";
import { createMantleServerSyntaxHighlighter } from "@ngrok/mantle-server-syntax-highlighter";

const highlighter = createMantleServerSyntaxHighlighter();

createServer(async (req, res) => {
	// Handle CORS
	res.setHeader("Access-Control-Allow-Origin", "*");
	res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
	res.setHeader("Access-Control-Allow-Headers", "Content-Type");
	if (req.method === "OPTIONS") {
		res.writeHead(204).end();
		return;
	}

const chunks: Buffer[] = [];
	for await (const chunk of req) chunks.push(chunk);
	const { code, language, showLineNumbers, highlightLines, lineNumberStart } = JSON.parse(
		Buffer.concat(chunks).toString(),
	);

const result = await highlighter.highlight({
		code,
		language,
		showLineNumbers,
		highlightLines,
		lineNumberStart,
	});
	res.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify(result));
}).listen(4444, () => console.log("Highlight server on :4444"));
```

Then use it from any frontend the same way as the [server-rendered example](#server-rendered-syntax-highlighting) above, pointing at the highlight service URL:

```tsx
const response = await fetch("http://localhost:4444", {
	method: "POST",
	headers: { "Content-Type": "application/json" },
	body: JSON.stringify({ code, language: "json", showLineNumbers: true }),
});
const data = await response.json();

const value = createMantleCodeBlockValue({
	code: data.code,
	language: data.language,
	preHtml: data.html,
	showLineNumbers: data.showLineNumbers,
});
```

### Foldable code blocks

Code blocks automatically render editor-style fold carets in the gutter for any block whose language has a folding strategy — AST-based (JS/TS/JSX/TSX, HTML, XML), raw-source (JSON, CSS), bracket-paired (Go, Java, C#, Rust), indentation-based (Python, YAML), keyword-paired (Bash/Shell), or bracket + keyword (Ruby). Click the caret (or focus and press `Enter` / `Space`) to collapse the inner lines; the opener and closer lines stay visible, and a `⋯` placeholder marks the collapsed region.

Folding is computed before the block reaches the browser, and the entire interaction runs through a single delegated click handler per code block — no per-line listeners and no React re-renders on toggle. This keeps fold/unfold cheap even for code blobs with thousands of lines.

The `mantleCode()` Vite transform, MDX code fences, and `createMantleServerSyntaxHighlighter()` use the full server-side folding dispatcher. The lower-level `computeFoldRanges({ language, tokens })` export from `@ngrok/mantle/highlight-utils` is intentionally token-only for custom integrations; it covers bracket, indentation, and tag folds only. Use `@ngrok/mantle-server-syntax-highlighter` for AST, raw-source, or keyword strategies.

For one example per supported language plus a list of caveats, see [folding by language](/components/code-block/folding-by-language).

```tsx
import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";

<CodeBlock.Root>
	<CodeBlock.Header>
		<CodeBlock.Icon preset="file" />
		<CodeBlock.Title>package.json</CodeBlock.Title>
	</CodeBlock.Header>
	<CodeBlock.Body>
		<CodeBlock.CopyButton />
		<CodeBlock.Code
			value={mantleCode("json")`
				{
					"name": "@ngrok/mantle",
					"scripts": {
						"build": "tsdown",
						"test": "vitest run"
					},
					"pnpm": {
						"onlyBuiltDependencies": [
							"esbuild",
							"@tailwindcss/oxide"
						]
					}
				}
			`}
		/>
	</CodeBlock.Body>
</CodeBlock.Root>;
```

### Highlighting runtime JSON on the client

`mantleCode()` highlights at **build time**, so it can't highlight a value you only have at runtime — an API response, a table row's underlying record, anything fetched or computed in the browser. For that, use `jsonCodeBlockValue(value)`: it serializes the value with `JSON.stringify` (2-space indent), tokenizes it, and returns a `MantleCodeBlockValue` you pass straight to `CodeBlock.Code` — **entirely on the client, with no Shiki runtime, grammar, or WASM shipped to the browser** (\~1 KB). Because Mantle highlights with a CSS-variables theme the colors already live in CSS, so only tokenization happens at runtime; the output is byte-for-byte identical to a server/build-time highlighted block and adapts to light/dark themes for free.

Multi-line objects and arrays are collapsible by default — the same fold runtime as every other JSON block — so pass `{ foldable: false }` for a flat panel, or `{ showLineNumbers: true }` for a gutter. Serialization is safe and never throws: `BigInt` renders as its decimal string, circular/repeated references collapse to `"[Circular]"`, and values that serialize to `undefined` render as an empty string. It's ideal for inspecting a record inside a [`DataTable.ExpandedRow`](/components/data-table#expandable-rows).

```tsx
import { CodeBlock, jsonCodeBlockValue } from "@ngrok/mantle/code-block";

// `record` is any runtime value — an API response, a table row's object, etc.
<CodeBlock.Root>
	<CodeBlock.Body>
		<CodeBlock.CopyButton />
		<CodeBlock.Code value={jsonCodeBlockValue(record)} />
	</CodeBlock.Body>
</CodeBlock.Root>;

// Opt out of folding, or show a line-number gutter:
jsonCodeBlockValue(record, { foldable: false });
jsonCodeBlockValue(record, { showLineNumbers: true });
```

For lower-level control, `jsonToShikiHtml(code)` returns just the Shiki-identical inner HTML for a `<code>` element (no line-number or fold decoration); `jsonCodeBlockValue` builds on it.

### Tabbed Code Block

Use `CodeBlock.TabList`, `CodeBlock.TabTrigger`, and `CodeBlock.TabContent` to create a tabbed code block. Pass `defaultTab` (or `activeTab` / `onActiveTabChange` for controlled mode) to `CodeBlock.Root`, place the tab triggers in the `CodeBlock.Header`, and wrap each `CodeBlock.Code` in a `CodeBlock.TabContent`. The copy button automatically copies whichever code is currently displayed.

```tsx
import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";

const policyYml = mantleCode("yaml")`…`;
const policyJson = mantleCode("json")`…`;

<CodeBlock.Root defaultTab="yml">
	<CodeBlock.Header>
		<CodeBlock.TabList>
			<CodeBlock.TabTrigger value="yml">policy.yml</CodeBlock.TabTrigger>
			<CodeBlock.TabTrigger value="json">policy.json</CodeBlock.TabTrigger>
		</CodeBlock.TabList>
	</CodeBlock.Header>
	<CodeBlock.Body>
		<CodeBlock.CopyButton />
		<CodeBlock.TabContent value="yml">
			<CodeBlock.Code value={policyYml} />
		</CodeBlock.TabContent>
		<CodeBlock.TabContent value="json">
			<CodeBlock.Code value={policyJson} />
		</CodeBlock.TabContent>
	</CodeBlock.Body>
</CodeBlock.Root>;
```

### Reusing Fragments with Nested Interpolation

A `mantleCode` value can be embedded into another `mantleCode` template by interpolating its `.code` property. When the Vite plugin recognizes the reference, it inlines the fragment's source **at build time** — so the embedded code is highlighted line-for-line in its host language (correct line numbers, folding, and copy text) with **no runtime substitution cost**.

This is ideal for sharing a Traffic Policy or config snippet across multiple SDK examples without duplicating it. The fragment can live at the top level of the same module, or be imported from another module:

```tsx
// shared-policies.ts — author the reusable policy once.
import { mantleCode } from "@ngrok/mantle/code-block";

export const oauthPolicyFragment = mantleCode("yaml")`on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google`;
```

```tsx
// listener-demo.tsx — embed it into a Java text block.
import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";
import { oauthPolicyFragment } from "./shared-policies";

// `${oauthPolicyFragment.code}` is resolved and inlined at build time.
const javaSdkSnippet = mantleCode("java")`var policy = """
${oauthPolicyFragment.code}
""";

var listener = agent.listen(policy);`;
```

The fragment must be a top-level `mantleCode` `const` referenced as `.code` — either declared earlier in the same module, or a named import of a directly-exported top-level `const` from another module. Nested fragments are resolved recursively. Interpolations that can't be resolved statically (dynamic values, re-exports, bare identifiers without `.code`) fall back to runtime placeholder substitution, and an unresolved imported `.code` reference emits a build warning. Note that the embedded source is highlighted using the **outer** language's grammar — e.g. the YAML above is highlighted as Java text-block content, not as YAML.

### `mantleCode()` Options

The `mantleCode()` tagged template accepts an optional second argument with the following options:

- **`showLineNumbers`** — Whether to show line numbers. Defaults to `true` for most languages, but `false` for single-line shell snippets (`bash`, `sh`, `shell`). Pass `false` to hide them or `true` to force them on.
- **`highlightLines`** — An array of line numbers or ranges (e.g. `[2, "4-5"]`) to visually highlight.
- **`lineNumberStart`** — The starting line number when line numbers are displayed. Defaults to `1`.
- **`indentation`** — Override the default indentation style (`"tabs"` or `"spaces"`).

```tsx
import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";

<CodeBlock.Root>
	<CodeBlock.Header>
		<CodeBlock.Icon preset="file" />
		<CodeBlock.Title>all-options.ts</CodeBlock.Title>
	</CodeBlock.Header>
	<CodeBlock.Body>
		<CodeBlock.CopyButton />
		<CodeBlock.Code
			value={mantleCode("typescript", {
				showLineNumbers: false,
				highlightLines: [11, "13-14"],
				lineNumberStart: 10,
				indentation: "spaces",
			})`
				import { serve } from "bun";

const server = serve({
					port: 3000,
					fetch(req) {
						return new Response("Hello from Bun!");
					},
				});

console.log(\`Listening on \${server.url}\`);
			`}
		/>
	</CodeBlock.Body>
</CodeBlock.Root>;
```

### Overriding Defaults

The `mantleCode()` options let you customize how code is displayed. By default, line numbers are shown starting at 1 and indentation is inferred from the language. You can also specify highlighted lines per code block. The first example below uses the defaults (YAML auto-detects space indentation), while the second overrides all options: custom indentation, line number start, highlighted lines, and visible line numbers.

```tsx
{
	/* yaml auto-detects space indentation, all other defaults apply */
}
<CodeBlock.Code
	value={mantleCode("yaml")`
		on_http_request:
			actions:
				type: custom-response
				config:
					status_code: 200
					content: Hello, World!
	`}
/>;

{
	/* override all mantleCode() options */
}
<CodeBlock.Code
	value={mantleCode("javascript", {
		indentation: "spaces",
		showLineNumbers: true,
		highlightLines: [42, "46-48"],
		lineNumberStart: 42,
	})`
		const http = require('http');
		const ngrok = require("@ngrok/ngrok");
		const server = http.createServer((req, res) => {
			res.writeHead(200);
			res.end("Hello!");
		});
	`}
/>;
```

## API Reference

The `CodeBlock` renders and applies syntax highlighting to blocks of code and is composed of several sub-components.

### CodeBlock.Root

Root container for all `CodeBlock` sub-components. For tabbed code blocks, pass `defaultTab` (uncontrolled) or `activeTab` / `onActiveTabChange` (controlled) to enable tab switching.

All props from [standard HTML div attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

### CodeBlock.Body

The body of the `CodeBlock`. This is where the `CodeBlock.Code` and optional `CodeBlock.CopyButton` are rendered as direct children.

All props from [standard HTML div attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

### CodeBlock.Code

The `CodeBlock` content. This is where the code is rendered with pre-highlighted Shiki HTML.

All props from [standard HTML pre attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/pre#attributes), plus:

### CodeBlock.Header

An optional header slot of the `CodeBlock`. This is where things like the `CodeBlock.Icon` and `CodeBlock.Title` are rendered.

All props from [standard HTML div attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

### CodeBlock.Title

The (optional) title of a `CodeBlock`. Default renders as an `h3` element; use `asChild` to render something else.

All props from [standard HTML h3 attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#attributes), plus:

### CodeBlock.CopyButton

The (optional) copy button of the `CodeBlock`. Render this as a child of the `CodeBlock.Body` to allow users to copy the code block contents to their clipboard.

All props from [standard HTML button attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes), plus:

### CodeBlock.ExpanderButton

The (optional) expander button of the `CodeBlock`. Render this as a child of the `CodeBlock.Root` to allow users to expand/collapse the code block contents.

All props from [standard HTML button attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes), plus:

### CodeBlock.Icon

A small icon that represents the type of code block being displayed, rendered as an SVG next to the code block title in the code block header. You can pass in a custom SVG component or use one of the presets (you can exclusively pass one of `svg` or `preset`).

All props from [Icon](/components/icon), plus:

### CodeBlock.TabList

A tab list for the `CodeBlock` header. Renders pill-styled tab triggers that switch which code is displayed. Place this inside `CodeBlock.Header` and pair with `CodeBlock.TabContent` in `CodeBlock.Body`. Tab state is managed by `CodeBlock.Root` via `defaultTab` / `activeTab` / `onActiveTabChange`.

All props from [standard HTML div attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes).

### CodeBlock.TabTrigger

A pill-styled tab trigger for the `CodeBlock` header. Must be rendered within a `CodeBlock.TabList`.

All props from [standard HTML button attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes), plus:

### CodeBlock.TabContent

Conditionally renders its children when the associated tab is active. Pair with `CodeBlock.TabList` and `CodeBlock.TabTrigger` in the header, and set `defaultTab` / `activeTab` on `CodeBlock.Root`.

All props from [standard HTML div attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

### jsonCodeBlockValue

Builds a `MantleCodeBlockValue` that renders any value as syntax-highlighted JSON entirely on the client — no Shiki runtime, build-time plugin, or server roundtrip (see [Highlighting runtime JSON on the client](#highlighting-runtime-json-on-the-client)). Pass the result to `CodeBlock.Code`'s `value` prop. Serialization is safe and never throws: `BigInt` → decimal string, circular/repeated references → `"[Circular]"`, and values that serialize to `undefined` → `""`.

```ts
jsonCodeBlockValue(value: unknown, options?: JsonCodeBlockValueOptions): MantleCodeBlockValue
```

Byte-for-byte parity with server/build-time Shiki output is guaranteed for canonical `JSON.stringify` shapes — which is exactly what this function produces.

### jsonToShikiHtml

The lower-level primitive behind `jsonCodeBlockValue`. Tokenizes a JSON string into the same CSS-variable-colored `<code>` inner HTML that Mantle's server/build-time Shiki highlighter produces, without shipping Shiki to the browser. Returns an HTML string with **no** line-number or fold decoration — feed it through `decorateHighlightedHtml` for that, as `jsonCodeBlockValue` does. Reach for it only when you need the raw markup; most consumers want `jsonCodeBlockValue`.

```ts
jsonToShikiHtml(code: string): string
```

---

---
title: Code Block Folding by Language
description: One foldable code block per supported language, showing how each folding strategy behaves.
---

# Code Block Folding by Language

Mantle dispatches each supported language to the folding strategy that best fits its syntax. Most strategies run server- or build-side; only the toggle interaction runs in the browser.

- **AST-based (JS / TS / JSX / TSX)** — `oxc-parser` walks the AST and emits folds for block/class/switch bodies, object/array literals and patterns, JSX elements and fragments, multi-line template literals, and TypeScript constructs such as interfaces, type literals, enums, modules, and mapped types.
- **AST-based (HTML / XML)** — `parse5` tokenizes the source with `sourceCodeLocationInfo`, so void elements never open folds, self-closing XML tags are honored, and nested content inside `<template>` folds normally. Multi-line opening tags fold their attribute list into the tag name.
- **Raw-source (CSS / JSON)** — single-pass, parser-quality delimiter matchers. CSS folds `{ … }`; JSON folds `{ … }` and `[ … ]`; both skip strings and escapes, and CSS also skips comments.
- **Indentation-based (Python / YAML)** — blocks are detected by leading whitespace; the opener line stays visible and child lines collapse.
- **Bracket-paired (Go / Rust / Java / C#)** — multi-line `{ … }` / `[ … ]` ranges fold via TextMate-scope-aware token walking; brackets inside strings, comments, or regular expressions are ignored.
- **Keyword-paired (Bash / Shell)** — opener / closer keyword pairs from VS Code's grammars: `if … fi`, `case … esac`, `for|while|until|select … do … done`, and brace-form function bodies. Same-line close markers are command-boundary aware, so variables or arguments named `done`, `fi`, or `esac` do not suppress valid folds.
- **Bracket + keyword (Ruby)** — combines bracket-paired folding (block-style `{ … }`, arrays) with Ruby's keyword pairs: `def`, `class`, `module`, `begin`, `do`, `if`, `case`, etc., all closing on `end`.

Plain text (`text`, `txt`, `plain`, `plaintext`) intentionally has no folds.

The examples on this page use the full server highlighter pipeline. If you're building custom highlighting with `@ngrok/mantle/highlight-utils`, `computeFoldRanges({ language, tokens })` is a lower-level token helper for bracket, indentation, and tag folds. Use `@ngrok/mantle-server-syntax-highlighter` when you need the AST, raw-source, or keyword strategies listed here.

← [Back to Code Block](/components/code-block)

## AST-based languages

### JavaScript

### TypeScript

### TSX

JSX elements (`<Foo>…</Foo>`), fragments (`<>…</>`), and multi-line template literals all fold in addition to function bodies and object/array literals.

### JSX

### HTML

#### Multi-line opening tag

`parse5` emits `startTag.startLine`/`endLine` for multi-line opening tags, so the attribute list collapses into the tag name (matching VS Code).

### XML

XML-mode parsing routes through `parse5`'s SVG fragment context for XML-like (foreign-content) tokenizer rules — so `<empty/>` and `<other />` are correctly self-closing.

## Raw-source languages

### JSON

### CSS

## Indentation-based languages

### Python

### YAML

## Bracket-paired languages

### Go

### Java

### C\#

### Rust

## Keyword-paired languages

### Ruby

Ruby combines bracket folding (block-style `{ … }`, arrays) with keyword pairs — `def`, `class`, `module`, `begin`, `do`, `if`, `case`, etc., all closing on `end`.

### Bash / Shell

`if … fi`, `case … esac`, `for|while|until|select … do … done`, and brace-form function bodies all fold.

## Caveats

- **JSX / TSX self-closing elements** (`<Foo />`) get a toggle only when their attributes span multiple lines; collapsing hides the attribute lines while keeping the opening line and self-closing `/>` line visible.
- **Bracket strategy ignores `(…)`** — argument lists and tuple / parenthesized expressions never fold. This mirrors VS Code's default bracket folding.
- **Indentation strategy assumes consistent leading whitespace** within a block. Mixing tabs and spaces inside the same block can produce wrong spans.
- **Single-line spans never fold** — if a construct's opener and closer resolve to the same line, it emits no range. Inline objects/arrays inside a multi-line parent don't get their own toggle.
- **CSS folding is brace-only** — `@import url(…)` and other no-body at-rules don't have their own toggle (there's nothing to fold).
- **Shell same-line close detection is conservative** — line-leading closers and command-separated closers such as `; fi` suppress single-line folds, but ordinary data like `$done` or `echo done` does not.

---

---
title: Combobox
description: Fill in a React input field with autocomplete & autosuggest functionalities. Choose from a list of suggested values with full keyboard support.
---

# Combobox

Fill in a React input field with autocomplete & autosuggest functionalities. Choose from a list of suggested values with full keyboard support. This component is based on the [WAI-ARIA Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) and is powered by the [ariakit Combobox](https://ariakit.org/components/combobox).

## When to use

Use `Combobox` for a list where the user types to filter — large static lists, async/server-side data, or any single-select where search is helpful. For small finite lists without filtering, use [`Select`](/components/select). For multi-selection, use [`Multi Select`](/components/multi-select).

Pair with `Field.*` for label/description/error wiring in forms — wrap `Combobox.Input` in `Field.Control`. `Field.Control` flows the generated `id`, `name`, `aria-describedby`, `aria-errormessage`, and `aria-invalid` onto the focusable input.

```tsx
import { Combobox } from "@ngrok/mantle/combobox";
import { Field } from "@ngrok/mantle/field";

<Field.Item name="subdomain">
	<Field.Label>Subdomain</Field.Label>
	<Combobox.Root>
		<Field.Control>
			<Combobox.Input placeholder="Choose an ngrok subdomain..." />
		</Field.Control>
		<Combobox.Content>
			<Combobox.Group>
				<Combobox.GroupLabel>Available domains</Combobox.GroupLabel>
				<Combobox.Item value="https://${random}.ngrok.app">
					<Combobox.ItemValue />
				</Combobox.Item>
				<Combobox.Item value="https://${random}.ngrok.dev">
					<Combobox.ItemValue />
				</Combobox.Item>
				<Combobox.Item value="https://${random}.ngrok.io">
					<Combobox.ItemValue />
				</Combobox.Item>
			</Combobox.Group>
		</Combobox.Content>
	</Combobox.Root>
	<Field.Description>Start typing to filter available domains.</Field.Description>
</Field.Item>;
```

Or render the control on its own:

```tsx
import { Combobox } from "@ngrok/mantle/combobox";
import { CirclesThreePlusIcon } from "@phosphor-icons/react/CirclesThreePlus";

<Combobox.Root>
	<Combobox.Input />
	<Combobox.Content>
		<Combobox.Group>
			<Combobox.GroupLabel>Choose an ngrok subdomain</Combobox.GroupLabel>
			<Combobox.Item value="https://" disabled>
				<Combobox.ItemValue />
			</Combobox.Item>
			<Combobox.Item value="https://${random}.ngrok.app">
				<CirclesThreePlusIcon weight="duotone" className="text-accent-600" />
				<Combobox.ItemValue />
			</Combobox.Item>
			<Combobox.Item value="https://${random}.ngrok.dev">
				<Combobox.ItemValue />
			</Combobox.Item>
			<Combobox.Item value="https://${random}.ngrok.io">
				<Combobox.ItemValue />
			</Combobox.Item>
		</Combobox.Group>
		<Combobox.Separator />
		<Combobox.Item>
			Sit dolor enim eiusmod nulla nostrud officia in magna deserunt ut ex veniam cillum.
		</Combobox.Item>
	</Combobox.Content>
</Combobox.Root>;
```

## Examples

### With TanStack Form

Use `@tanstack/react-form` with `zod` to keep the combobox input controlled. Wrap `Combobox.Input` in `Field.Control` so label, name, and validation ARIA are applied to the focusable input.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Combobox } from "@ngrok/mantle/combobox";
import { Field, toErrorMessages } from "@ngrok/mantle/field";
import { useForm } from "@tanstack/react-form";
import { z } from "zod";

export const formSchema = z.object({
	region: z.string().min(1, "Choose a region."),
});
function Example() {
	const defaultValues = {
		region: "",
	};
	const form = useForm({
		defaultValues,
		validators: {
			onSubmit: formSchema,
		},
		onSubmit: ({ value }) => {
			// Handle form submission here
		},
	});

return (
		<form
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<form.Field name="region">
				{(field) => (
					<Field.Item name={field.name}>
						<Field.Label>Region</Field.Label>
						<Combobox.Root
							value={field.state.value}
							setValue={(value) => {
								field.handleChange(value);
							}}
						>
							<Field.Control>
								<Combobox.Input onBlur={field.handleBlur} placeholder="Choose a region..." />
							</Field.Control>
							<Combobox.Content>
								<Combobox.Item value="us-east-1">US East</Combobox.Item>
								<Combobox.Item value="us-west-2">US West</Combobox.Item>
								<Combobox.Item value="eu-west-1">EU West</Combobox.Item>
							</Combobox.Content>
						</Combobox.Root>
						<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
					</Field.Item>
				)}
			</form.Field>
			<Button type="submit" appearance="filled" priority="neutral">
				Submit
			</Button>
		</form>
	);
}
```

## Composition

Compose the parts of a `Combobox` together to build your own:

```text showLineNumbers=false
Combobox.Root
├── Combobox.Input
└── Combobox.Content
    ├── Combobox.Group
    │   ├── Combobox.GroupLabel
    │   └── Combobox.Item
    │       └── Combobox.ItemValue
    └── Combobox.Separator
```

## API Reference

The `Combobox` components are built on top of [ariakit Combobox](https://ariakit.org/components/combobox).

### Combobox.Root

Root component for a combobox. Provides a combobox store that controls the state of Combobox components.

All props from ariakit [ComboboxProvider](https://ariakit.org/reference/combobox-provider).

### Combobox.Input

Renders a combobox input element that can be used to filter a list of items.

All props from ariakit [Combobox](https://ariakit.org/reference/combobox), plus:

### Combobox.Content

Renders a popover that contains combobox content, e.g. items, groups, and separators.

All props from ariakit [ComboboxPopover](https://ariakit.org/reference/combobox-popover), plus:

### Combobox.Item

Renders a combobox item inside a `Combobox.Content` component.

All props from ariakit [ComboboxItem](https://ariakit.org/reference/combobox-item), plus:

### Combobox.ItemValue

Highlights the match between the current `Combobox.Input` value and parent `Combobox.Item` value. Should only be used as a child of `Combobox.Item`.

All props from ariakit [ComboboxItemValue](https://ariakit.org/reference/combobox-item-value), plus:

### Combobox.Group

Renders a group for `Combobox.Item` elements. Optionally, a `Combobox.GroupLabel` can be rendered as a child to provide a label for the group.

All props from ariakit [ComboboxGroup](https://ariakit.org/reference/combobox-group), plus:

### Combobox.GroupLabel

Renders a label in a combobox group. Should be wrapped with `Combobox.Group` so the `aria-labelledby` is correctly set on the group element.

All props from ariakit [ComboboxGroupLabel](https://ariakit.org/reference/combobox-group-label), plus:

### Combobox.Separator

Renders a separator between `Combobox.Item`s or `Combobox.Group`s.

All props from [Separator](/components/separator).

---

---
title: Command
description: A command palette that allows users to search and execute commands.
---

# Command

A command palette that allows users to search and execute commands. Built on top of [cmdk](https://cmdk.paco.me/).

### Command Example

```tsx
import { Command } from "@ngrok/mantle/command";
import { CalendarIcon, SmileyIcon, CalculatorIcon, UserIcon } from "@phosphor-icons/react";

<Command.Root className="rounded-lg border border-dialog shadow-lg bg-dialog md:min-w-112.5">
	<Command.Input placeholder="Type a command or search..." />
	<Command.List>
		<Command.Empty>No results found.</Command.Empty>
		<Command.Group heading="Suggestions">
			<Command.Item>
				<CalendarIcon />
				<span>Calendar</span>
			</Command.Item>
			<Command.Item>
				<SmileyIcon />
				<span>Search Emoji</span>
			</Command.Item>
			<Command.Item>
				<CalculatorIcon />
				<span>Calculator</span>
			</Command.Item>
		</Command.Group>
		<Command.Separator />
		<Command.Group heading="Settings">
			<Command.Item>
				<UserIcon />
				<span>Profile</span>
			</Command.Item>
		</Command.Group>
	</Command.List>
</Command.Root>;
```

### Command Dialog Example

```tsx
import { Button } from "@ngrok/mantle/button";
import { Command, MetaKey } from "@ngrok/mantle/command";
import {
	CalculatorIcon,
	CalendarIcon,
	CreditCardIcon,
	GearIcon,
	SmileyIcon,
	UserIcon,
} from "@phosphor-icons/react";
import { useEffect, useState } from "react";

function CommandDialogDemo() {
	const [open, setOpen] = useState(false);
	useHotkey("j", () => setOpen(!open));

return (
		<>
			<p className="text-muted-foreground text-sm gap-2 flex items-center">
				Press{" "}
				<kbd className="bg-muted text-muted pointer-events-none inline-flex h-5 items-center gap-1 rounded border px-1.5 font-mono text-[10px] font-medium opacity-100 select-none">
					<span className="text-xs">
						<MetaKey />
					</span>
					J
				</kbd>
				or
				<Button
					type="button"
					appearance="outlined"
					priority="neutral"
					onClick={() => setOpen(!open)}
				>
					Open Command Dialog
				</Button>
			</p>
			<Command.DialogRoot open={open} onOpenChange={setOpen}>
				<Command.DialogContent>
					<Command.Input placeholder="Type a command or search..." />
					<Command.List>
						<Command.Empty>No results found.</Command.Empty>
						<Command.Group heading="Suggestions">
							<Command.Item>
								<CalendarIcon />
								<span>Calendar</span>
							</Command.Item>
							<Command.Item>
								<SmileyIcon />
								<span>Search Emoji</span>
							</Command.Item>
							<Command.Item>
								<CalculatorIcon />
								<span>Calculator</span>
							</Command.Item>
						</Command.Group>
						<Command.Separator />
						<Command.Group heading="Settings">
							<Command.Item>
								<UserIcon />
								<span>Profile</span>
								<Command.Shortcut>
									<MetaKey /> P
								</Command.Shortcut>
							</Command.Item>
							<Command.Item>
								<CreditCardIcon />
								<span>Billing</span>
								<Command.Shortcut>
									<MetaKey /> B
								</Command.Shortcut>
							</Command.Item>
							<Command.Item>
								<GearIcon />
								<span>Settings</span>
								<Command.Shortcut>
									<MetaKey /> S
								</Command.Shortcut>
							</Command.Item>
						</Command.Group>
					</Command.List>
				</Command.DialogContent>
			</Command.DialogRoot>
		</>
	);
}
```

## Composition

Compose the parts of a `Command` together to build your own:

```text showLineNumbers=false
Command.DialogRoot
├── Command.DialogTrigger
└── Command.DialogContent
    ├── Command.Input
    └── Command.List
        ├── Command.Empty
        ├── Command.Group
        │   └── Command.Item
        │       └── Command.Shortcut
        └── Command.Separator
```

## API Reference

The `Command` component is built on top of [cmdk](https://cmdk.paco.me/) and provides a complete set of sub-components for building command palettes.

### Command.Root

The root component for the Command. It provides the context for all other command sub-components.

All props from cmdk's [Command Root](https://github.com/pacocoursey/cmdk?tab=readme-ov-file#command-cmdk-root).

### Command.DialogRoot

The root stateful component for the Command dialog. Manages open/closed state.

All props from Radix UI's [Dialog.Root](https://www.radix-ui.com/primitives/docs/components/dialog#root).

### Command.DialogTrigger

A button that opens the Command dialog when clicked. Supports `asChild` for custom trigger elements.

All props from Radix UI's [Dialog.Trigger](https://www.radix-ui.com/primitives/docs/components/dialog#trigger).

### Command.DialogContent

The visible content of the Command dialog. Renders inside the dialog portal and wraps the command palette UI.

### Command.Input

The input component for the Command. It provides the input for the command palette.

All props from cmdk's [Command Input](https://github.com/pacocoursey/cmdk?tab=readme-ov-file#input-cmdk-input).

### Command.List

The list component for the Command. It provides the scrollable list for the command palette.

All props from cmdk's [Command List](https://github.com/pacocoursey/cmdk?tab=readme-ov-file#list-cmdk-list).

### Command.Empty

The empty component for the Command. Displayed when no results match the search query.

All props from cmdk's [Command Empty](https://github.com/pacocoursey/cmdk?tab=readme-ov-file#empty-cmdk-empty).

### Command.Group

The group component for the Command. Used to group related command items together.

All props from cmdk's [Command Group](https://github.com/pacocoursey/cmdk?tab=readme-ov-file#group-cmdk-group-hidden).

### Command.Item

The item component for the Command. Represents a selectable command in the palette.

All props from cmdk's [Command Item](https://github.com/pacocoursey/cmdk?tab=readme-ov-file#item-cmdk-item-data-disabled-data-selected).

### Command.Separator

A visual separator between command groups or items. Automatically hidden when there is an active search query.

All props from cmdk's [Command Separator](https://github.com/pacocoursey/cmdk?tab=readme-ov-file#separator-cmdk-separator).

### Command.Shortcut

Displays a keyboard shortcut hint within a command item. Renders as a styled `span` element.

All props from the HTML `span` element.

### MetaKey

Renders the platform-appropriate meta key label (`⌘` for macOS/iOS or `Ctrl` for other platforms). It detects the platform on mount and is SSR-safe, defaulting to `Ctrl` to avoid hydration mismatches.

Use it in keyboard shortcut hints and `Command.Shortcut` labels to ensure the correct modifier key is displayed for each platform.

```tsx
import { Command, MetaKey } from "@ngrok/mantle/command";

<Command.Shortcut>
	<MetaKey /> S
</Command.Shortcut>
```

### useCommandState

A hook for accessing the command palette state.

All props from cmdk's [useCommandState](https://github.com/pacocoursey/cmdk?tab=readme-ov-file#usecommandstatestate--stateselectedfield).

---

---
title: Data Table
description: Tables purposefully designed for dynamic, application data with features like sorting, filtering, and pagination.
---

# Data Table

Tables purposefully designed for dynamic, application data with features like sorting, filtering, and pagination. Powered by [TanStack Table](https://tanstack.com/table/latest/docs/introduction).

## When to use

A `DataTable` is for **dynamic, application data** — anywhere users need to sort, filter, paginate, select, or click rows. It is built on top of [`Table`](/components/table) and wires up [TanStack Table](https://tanstack.com/table/latest/docs/introduction) so you get those behaviors out of the box.

- Prefer [`Table`](/components/table) for **static, presentational** tabular content (pricing matrices, reference tables, invoice summaries).
- All TanStack Table utilities (`createColumnHelper`, `getCoreRowModel`, `getSortedRowModel`, `getPaginationRowModel`, `getFilteredRowModel`, `useReactTable`, etc.) are re-exported from `@ngrok/mantle/data-table` — you do not need to add `@tanstack/react-table` as a separate dependency.

## Quick start

The minimum viable `DataTable`. Copy, paste, replace the type and data:

```tsx
import {
	DataTable,
	createColumnHelper,
	getCoreRowModel,
	useReactTable,
} from "@ngrok/mantle/data-table";

type Row = { id: string; name: string };

const columnHelper = createColumnHelper<Row>();

const columns = [
	columnHelper.accessor("name", {
		id: "name",
		header: (props) => (
			<DataTable.Header>
				<DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
					Name
				</DataTable.HeaderSortButton>
			</DataTable.Header>
		),
		cell: (props) => <DataTable.Cell key={props.cell.id}>{props.getValue()}</DataTable.Cell>,
	}),
];

function MyTable({ data }: { data: Row[] }) {
	const table = useReactTable({
		data,
		columns,
		getCoreRowModel: getCoreRowModel(),
	});

const rows = table.getRowModel().rows;

return (
		<DataTable.Root table={table}>
			<DataTable.Head />
			<DataTable.Body>
				{rows.length > 0 ? (
					rows.map((row) => <DataTable.Row key={row.id} row={row} />)
				) : (
					<DataTable.EmptyRow>No results.</DataTable.EmptyRow>
				)}
			</DataTable.Body>
		</DataTable.Root>
	);
}
```

A fuller example matching the demo above — sortable columns, pagination, filtering, row-click navigation, and a sticky action column:

```tsx
import {
	DataTable,
	createColumnHelper,
	getCoreRowModel,
	getFilteredRowModel,
	getPaginationRowModel,
	getSortedRowModel,
	useReactTable,
} from "@ngrok/mantle/data-table";
import { Empty } from "@ngrok/mantle/empty";
import { TrayIcon } from "@phosphor-icons/react/Tray";
import { href, useNavigate } from "react-router";
import { useMemo } from "react";

type Payment = {
	id: string;
	amount: number;
	status: "pending" | "processing" | "success" | "failed";
	email: string;
};

const columnHelper = createColumnHelper<Payment>();

const columns = [
	columnHelper.accessor("id", {
		id: "id",
		header: (props) => (
			<DataTable.Header>
				<DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
					ID
				</DataTable.HeaderSortButton>
			</DataTable.Header>
		),
		cell: (props) => <DataTable.Cell key={props.cell.id}>{props.getValue()}</DataTable.Cell>,
	}),
	// ... more columns
];

function PaymentsExample() {
	const navigate = useNavigate();
	const data = useMemo(() => examplePayments, []);

const table = useReactTable({
		data,
		columns,
		getCoreRowModel: getCoreRowModel(),
		getPaginationRowModel: getPaginationRowModel(),
		getSortedRowModel: getSortedRowModel(),
		getFilteredRowModel: getFilteredRowModel(),
		initialState: {
			sorting: [{ id: "email", desc: false }],
			pagination: { pageSize: 100 },
		},
	});

const rows = table.getRowModel().rows;

return (
		<DataTable.Root table={table}>
			<DataTable.Head />
			<DataTable.Body>
				{rows.length > 0 ? (
					rows.map((row) => (
						<DataTable.Row
							key={row.id}
							onClick={() => {
								navigate(href("/payments/:id", { id: row.original.id }));
							}}
							row={row}
						/>
					))
				) : (
					<DataTable.EmptyRow>
						<Empty.Root>
							<Empty.Icon svg={<TrayIcon />} />
							<Empty.Title>No payments yet</Empty.Title>
							<Empty.Description>
								<p>Payments you receive will appear here.</p>
							</Empty.Description>
						</Empty.Root>
					</DataTable.EmptyRow>
				)}
			</DataTable.Body>
		</DataTable.Root>
	);
}
```

## Composition

Compose the parts of a `DataTable` together to build your own:

```text showLineNumbers=false
DataTable.Root
├── DataTable.Head
│   └── DataTable.Row
│       ├── DataTable.Header
│       │   └── DataTable.HeaderSortButton
│       └── DataTable.ActionHeader
└── DataTable.Body
    ├── DataTable.Row
    │   ├── DataTable.Cell
    │   └── DataTable.ActionCell
    └── DataTable.EmptyRow
```

## Rules

Follow these invariants for a correctly styled, accessible, and behaving `DataTable`.

1. **Type columns with `createColumnHelper<TData>()`.** It threads `TData` through `header`, `cell`, and `row.original` so consumers get inference instead of `unknown`.
2. **Wrap every body cell in `DataTable.Cell`.** A raw `<td>` skips the mantle typography, padding, and sticky-column styling.
3. **Wrap every header in `DataTable.Header`.** For sortable columns, also wrap its contents in `DataTable.HeaderSortButton` — the icon, cycling behavior, and screen-reader announcements are provided by that button.
4. **Key rows with `row.id`.** TanStack Table tracks row identity across sort/filter/pagination; using array indexes will re-mount rows incorrectly.
5. **Always branch on `rows.length > 0` and render `DataTable.EmptyRow`** for the empty case. The empty row spans all columns and preserves the table's frame — returning `null` leaves an empty `<tbody>` and collapses the frame.
6. **Place an action column last, using `columnHelper.display({ ... })`.** Pair `DataTable.ActionHeader` (in `header`) with `DataTable.ActionCell` (in `cell`) so the pinned column aligns across header and body when scrolling horizontally.
7. **Pass `onClick` to `DataTable.Row` for row-click behavior.** The row auto-applies `cursor-pointer` when `onClick` is set — do not add it yourself. Override with another `cursor-*` class (for example, `cursor-wait`) via `className` if needed.
8. **Stop click propagation inside `DataTable.ActionCell` when the row is clickable.** Without it, clicks on dropdown triggers, buttons, and links inside the action cell will bubble and fire the row `onClick`.
9. **Provide a keyboard-accessible equivalent for row navigation.** A `<tr>` is not focusable and is not announced as interactive to assistive tech. If clicking a row navigates, render a `<Link>` in the primary cell so keyboard and screen-reader users have a reachable equivalent.
10. **Register the row models you use.** `useReactTable` only wires up what you pass in: `getSortedRowModel()` for sorting, `getPaginationRowModel()` for pagination, `getFilteredRowModel()` for filtering. Missing one and the corresponding feature silently no-ops.

## Anti-patterns

Common mistakes. The left column is what not to do; the right column is the fix.

```tsx
// ❌ Raw <td> — misses mantle styling
cell: (props) => <td>{props.getValue()}</td>,
// ✅
cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,

// ❌ Manual cursor-pointer — redundant, can desync from behavior
<DataTable.Row className="cursor-pointer" onClick={handle} row={row} />
// ✅
<DataTable.Row onClick={handle} row={row} />

// ❌ Plain button for a sortable header — no icon, no ARIA
header: () => <button onClick={() => column.toggleSorting()}>Name</button>,
// ✅
header: (props) => (
	<DataTable.Header>
		<DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
			Name
		</DataTable.HeaderSortButton>
	</DataTable.Header>
),

// ❌ Clickable row with a dropdown inside — trigger click fires the row onClick
<DataTable.Row onClick={navigate} row={row}>
	<DataTable.ActionCell>
		<DropdownMenu.Root>...</DropdownMenu.Root>
	</DataTable.ActionCell>
</DataTable.Row>
// ✅ Stop propagation at the action cell boundary
<DataTable.Row onClick={navigate} row={row}>
	<DataTable.ActionCell onClick={(event) => event.stopPropagation()}>
		<DropdownMenu.Root>...</DropdownMenu.Root>
	</DataTable.ActionCell>
</DataTable.Row>

// ❌ Empty state returns null — collapses the table frame
<DataTable.Body>{rows.map((row) => <DataTable.Row key={row.id} row={row} />)}</DataTable.Body>
// ✅ Use DataTable.EmptyRow
<DataTable.Body>
	{rows.length > 0
		? rows.map((row) => <DataTable.Row key={row.id} row={row} />)
		: <DataTable.EmptyRow>No results.</DataTable.EmptyRow>}
</DataTable.Body>

// ❌ Declared sorting but forgot the row model
useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
// ✅
useReactTable({
	data,
	columns,
	getCoreRowModel: getCoreRowModel(),
	getSortedRowModel: getSortedRowModel(),
});
```

## Recipes

### Empty states (no data vs. no results)

A list has **two** distinct empty states, and they need different copy and actions:

1. **No data** — nothing exists yet. Informational, optionally a primary "create" action.
2. **No results for the active filter/search** — the user filtered to nothing and needs a way out: a **Clear filters** button.

Branch on `rows.length`, then on whether a filter is active, and host an [`Empty`](/components/empty) inside `DataTable.EmptyRow` for each branch. `EmptyRow` already spans every column (auto `colSpan`) and `Empty.Root` centers itself — drop a single `Empty.Root` in as the child; don't hand-roll a `<td>` or any centering. Type into the filter below to see the "no results" branch and its working `Clear filters` reset:

```tsx
import { Button } from "@ngrok/mantle/button";
import { DataTable } from "@ngrok/mantle/data-table";
import { Empty } from "@ngrok/mantle/empty";
import { MagnifyingGlassIcon } from "@phosphor-icons/react/MagnifyingGlass";
import { TrayIcon } from "@phosphor-icons/react/Tray";

const rows = table.getRowModel().rows;
const isFiltered = globalFilter.trim() !== ""; // or table.getState().columnFilters.length > 0

<DataTable.Body>
	{rows.length > 0 ? (
		rows.map((row) => <DataTable.Row key={row.id} row={row} />)
	) : isFiltered ? (
		<DataTable.EmptyRow>
			<Empty.Root>
				<Empty.Icon svg={<MagnifyingGlassIcon />} />
				<Empty.Title>No results match your filter</Empty.Title>
				<Empty.Description>
					<p>Try a different search, or clear the filter to see everything.</p>
				</Empty.Description>
				<Empty.Actions>
					<Button
						type="button"
						appearance="outlined"
						priority="neutral"
						onClick={() => setGlobalFilter("")}
					>
						Clear filters
					</Button>
				</Empty.Actions>
			</Empty.Root>
		</DataTable.EmptyRow>
	) : (
		<DataTable.EmptyRow>
			<Empty.Root>
				<Empty.Icon svg={<TrayIcon />} />
				<Empty.Title>No endpoints yet</Empty.Title>
				<Empty.Description>
					<p>Endpoints you create will appear here.</p>
				</Empty.Description>
				<Empty.Actions>
					<Button type="button">Create endpoint</Button>
				</Empty.Actions>
			</Empty.Root>
		</DataTable.EmptyRow>
	)}
</DataTable.Body>;
```

### Navigating on row click

Pass `onClick` to `DataTable.Row` and navigate with React Router's `href()` + `useNavigate()`. Render a `<Link>` inside the primary cell for keyboard and screen-reader users — the row `onClick` acts as a larger pointer target on top.

```tsx
import { DataTable } from "@ngrok/mantle/data-table";
import { Link, href, useNavigate } from "react-router";

const columns = [
	columnHelper.accessor("id", {
		id: "id",
		header: (props) => (
			<DataTable.Header>
				<DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
					ID
				</DataTable.HeaderSortButton>
			</DataTable.Header>
		),
		cell: (props) => (
			<DataTable.Cell>
				<Link to={href("/payments/:id", { id: props.row.original.id })}>{props.getValue()}</Link>
			</DataTable.Cell>
		),
	}),
	// ... more columns
];

return (
		<DataTable.Root table={table}>
			<DataTable.Head />
			<DataTable.Body>
				{rows.map((row) => (
					<DataTable.Row
						key={row.id}
						onClick={() => {
							navigate(href("/payments/:id", { id: row.original.id }));
						}}
						row={row}
					/>
				))}
			</DataTable.Body>
		</DataTable.Root>
	);
}
```

### Action column with a dropdown menu

Define the action column with `columnHelper.display`, pair `DataTable.ActionHeader` with `DataTable.ActionCell`, and stop click propagation on the cell if the row is also clickable.

```tsx
import { IconButton } from "@ngrok/mantle/button";
import { DataTable } from "@ngrok/mantle/data-table";
import { DropdownMenu } from "@ngrok/mantle/dropdown-menu";
import { Icon } from "@ngrok/mantle/icon";
import { DotsThreeIcon } from "@phosphor-icons/react/DotsThree";
import { PencilSimpleIcon } from "@phosphor-icons/react/PencilSimple";
import { TrashIcon } from "@phosphor-icons/react/Trash";

columnHelper.display({
	id: "actions",
	header: () => <DataTable.ActionHeader />,
	cell: (props) => (
		<DataTable.ActionCell onClick={(event) => event.stopPropagation()}>
			<DropdownMenu.Root>
				<DropdownMenu.Trigger asChild>
					<IconButton
						appearance="ghost"
						size="sm"
						type="button"
						label="Open actions"
						icon={<DotsThreeIcon weight="bold" />}
					/>
				</DropdownMenu.Trigger>
				<DropdownMenu.Content align="end">
					<DropdownMenu.Item onSelect={() => editRow(props.row.original)}>
						<Icon svg={<PencilSimpleIcon />} /> Edit
					</DropdownMenu.Item>
					<DropdownMenu.Item
						className="text-danger-600"
						onSelect={() => deleteRow(props.row.original)}
					>
						<Icon svg={<TrashIcon />} /> Delete
					</DropdownMenu.Item>
				</DropdownMenu.Content>
			</DropdownMenu.Root>
		</DataTable.ActionCell>
	),
});
```

### Customizing cells (badges, numeric, truncation)

Cell rendering is just React. Use `Badge` for status pills, `text-right` for numeric columns, and `truncate max-w-*` for long strings.

```tsx
import { Badge } from "@ngrok/mantle/badge";
import { DataTable } from "@ngrok/mantle/data-table";

// Status pill
columnHelper.accessor("status", {
	id: "status",
	header: (props) => (
		<DataTable.Header>
			<DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
				Status
			</DataTable.HeaderSortButton>
		</DataTable.Header>
	),
	cell: (props) => {
		const status = props.getValue();
		const color = status === "success" ? "green" : status === "failed" ? "red" : "amber";
		return (
			<DataTable.Cell>
				<Badge color={color} appearance="muted">
					{status}
				</Badge>
			</DataTable.Cell>
		);
	},
}),

// Right-aligned numeric — the header button also needs justify-end + iconPlacement="start"
// so the sort affordance stays visually paired with the label
columnHelper.accessor("amount", {
	id: "amount",
	header: (props) => (
		<DataTable.Header>
			<DataTable.HeaderSortButton
				className="justify-end"
				column={props.column}
				iconPlacement="start"
				sortingMode="alphanumeric"
			>
				Amount
			</DataTable.HeaderSortButton>
		</DataTable.Header>
	),
	cell: (props) => (
		<DataTable.Cell className="text-right">${props.getValue().toFixed(2)}</DataTable.Cell>
	),
}),

// Truncate a long URL
columnHelper.accessor("url", {
	id: "url",
	header: (props) => (
		<DataTable.Header className="min-w-100">
			<DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
				URL
			</DataTable.HeaderSortButton>
		</DataTable.Header>
	),
	cell: (props) => <DataTable.Cell className="truncate max-w-100">{props.getValue()}</DataTable.Cell>,
}),
```

### Pagination controls

Register `getPaginationRowModel()`, then wire [`CursorPagination`](/components/pagination) to the table instance for a page-size dropdown plus previous/next buttons — no hand-rolled `Button`s or `Page X of Y` span needed.

```tsx
import {
	DataTable,
	getCoreRowModel,
	getPaginationRowModel,
	useReactTable,
} from "@ngrok/mantle/data-table";
import { CursorPagination } from "@ngrok/mantle/pagination";

// defaultPageSize seeds an UNCONTROLLED <Select>, so keep it stable — a module
// const (or the table's INITIAL page size), never the live page size. It must be
// one of CursorPagination's pageSizes (default 5 | 10 | 20 | 50 | 100).
const DEFAULT_PAGE_SIZE = 10;

function PaginatedTable({ data }: { data: Payment[] }) {
	const table = useReactTable({
		data,
		columns,
		getCoreRowModel: getCoreRowModel(),
		getPaginationRowModel: getPaginationRowModel(),
		initialState: { pagination: { pageSize: DEFAULT_PAGE_SIZE } },
	});

const rows = table.getRowModel().rows;

return (
		<>
			<DataTable.Root table={table}>
				<DataTable.Head />
				<DataTable.Body>
					{rows.length > 0 ? (
						rows.map((row) => <DataTable.Row key={row.id} row={row} />)
					) : (
						<DataTable.EmptyRow>No results.</DataTable.EmptyRow>
					)}
				</DataTable.Body>
			</DataTable.Root>

<CursorPagination.Root className="flex justify-end" defaultPageSize={DEFAULT_PAGE_SIZE}>
				<CursorPagination.PageSizeSelect
					onChangePageSize={(size) => {
						table.setPageSize(size);
						table.setPageIndex(0); // reset to the first page when the size changes
					}}
				/>
				<CursorPagination.Buttons
					hasPreviousPage={table.getCanPreviousPage()}
					hasNextPage={table.getCanNextPage()}
					onPreviousPage={() => table.previousPage()}
					onNextPage={() => table.nextPage()}
				/>
			</CursorPagination.Root>
		</>
	);
}
```

**Rules:**

- `defaultPageSize` must be present in `CursorPagination.PageSizeSelect`'s `pageSizes` (default `5 | 10 | 20 | 50 | 100`) or the select renders blank.
- `defaultPageSize` is an *uncontrolled* seed — derive it from the table's initial page size once; don't pass the live `table.getState().pagination.pageSize` (it changes and would thrash the select).
- Reset to page 0 on a size change.
- **Server/cursor data** (no `getPaginationRowModel`): wire `Buttons` to your fetch's has-next/has-prev + load callbacks, and use the read-only `CursorPagination.PageSizeValue` when the page size is fixed server-side rather than `PageSizeSelect`. See [Pagination → Within a data table](/components/pagination#within-a-data-table).

### Row selection with checkboxes

Add a `columnHelper.display` checkbox column — the header checkbox toggles every row (and goes indeterminate when only some are selected), each cell checkbox toggles its row. Drive `rowSelection` through `useReactTable` and read it back from the table instance. mantle's [`Checkbox`](/components/checkbox) is a native input, so handle changes with `onChange` + `event.target.checked` (not `onCheckedChange`), and resolve the header's tri-state with the exported [`selectAllChecked`](/components/checkbox#select-all-helper) helper.

```tsx
import { Checkbox, selectAllChecked } from "@ngrok/mantle/checkbox";
import {
	DataTable,
	getCoreRowModel,
	type RowSelectionState,
	useReactTable,
} from "@ngrok/mantle/data-table";
import { useState } from "react";

const columns = [
	columnHelper.display({
		id: "select",
		// `<th>` defaults to more horizontal padding (`px-4`) than `<td>` (`p-3`);
		// match the cell's padding so the header checkbox lines up with the rows.
		header: ({ table }) => (
			<DataTable.Header className="w-10 px-3">
				<Checkbox
					aria-label="Select all rows"
					checked={selectAllChecked({
						allSelected: table.getIsAllRowsSelected(),
						someSelected: table.getIsSomeRowsSelected(),
					})}
					onChange={(event) => table.toggleAllRowsSelected(event.target.checked)}
				/>
			</DataTable.Header>
		),
		cell: ({ row }) => (
			<DataTable.Cell className="w-10">
				<Checkbox
					aria-label="Select row"
					checked={row.getIsSelected()}
					onChange={(event) => row.toggleSelected(event.target.checked)}
				/>
			</DataTable.Cell>
		),
	}),
	// ... data columns
];

function SelectableTable({ data }: { data: Payment[] }) {
	const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
	const table = useReactTable({
		data,
		columns,
		getCoreRowModel: getCoreRowModel(),
		state: { rowSelection },
		onRowSelectionChange: setRowSelection,
		enableRowSelection: true,
	});

const selectedCount = table.getSelectedRowModel().rows.length;

return (
		<div className="flex flex-col gap-3">
			<p className="text-muted text-sm">
				{selectedCount} of {data.length} selected
			</p>
			<DataTable.Root table={table}>
				<DataTable.Head />
				<DataTable.Body>
					{table.getRowModel().rows.map((row) => (
						<DataTable.Row key={row.id} row={row} />
					))}
				</DataTable.Body>
			</DataTable.Root>
		</div>
	);
}
```

### Expandable rows

Expand a row into an inline detail panel with a `+`/`−` toggle — ideal for inspecting a row's underlying record without leaving the table. Expansion is driven entirely by [TanStack Table's expansion state](https://tanstack.com/table/latest/docs/guide/expanding) (mantle does not invent its own), so wire it up on `useReactTable` with `getExpandedRowModel()` and `getRowCanExpand: () => true` (required — without sub-rows, no row is expandable by default). A stable `getRowId` keeps both the expansion keys and the toggle's `aria-controls` association stable.

Two parts cover the toggle: `DataTable.ExpandHeader` (the toggle column header) and `DataTable.RowExpandButton` (the accessible `+`/`−` toggle, dropped into a leading `columnHelper.display` cell). For the detail panel itself, pass `renderExpanded` to `DataTable.Row` — when the row is expanded it renders its data row plus a sibling detail row holding the returned content, so you never hand-write the extra `<tr>` or the expand conditional. `renderExpanded` is called lazily (only while the row is open), so collapsed rows never build their panel. The detail row spans every visible column and sits on an opaque surface, so it coexists with a sticky [action column](#action-column-with-a-dropdown-menu).

The detail panel below renders each row's object as JSON via [`CodeBlock`](/components/code-block), highlighted with [`jsonCodeBlockValue`](/components/code-block) — entirely on the client, with no Shiki runtime shipped to the browser, no build-time plugin, and no server roundtrip. Multi-line objects and arrays are collapsible by default, just like every other JSON code block (pass `{ foldable: false }` for a flat panel).

```tsx
import { CodeBlock, jsonCodeBlockValue } from "@ngrok/mantle/code-block";
import {
	DataTable,
	type ExpandedState,
	createColumnHelper,
	getCoreRowModel,
	getExpandedRowModel,
	useReactTable,
} from "@ngrok/mantle/data-table";
import { useState } from "react";

const columnHelper = createColumnHelper<Payment>();

const columns = [
	// Leading expand-toggle column.
	columnHelper.display({
		id: "expander",
		header: () => <DataTable.ExpandHeader />,
		cell: (props) => (
			<DataTable.Cell className="w-9 px-0 text-center">
				<DataTable.RowExpandButton row={props.row} label={props.row.original.email} />
			</DataTable.Cell>
		),
	}),
	// ... your data columns (and an optional sticky action column)
];

function ExpandableTable({ data }: { data: Payment[] }) {
	// Controlled expansion via native TanStack state. Multiple rows may be open;
	// to enforce single-row expansion, reduce `next` down to one key in onExpandedChange.
	const [expanded, setExpanded] = useState<ExpandedState>({});

const table = useReactTable({
		data,
		columns,
		state: { expanded },
		onExpandedChange: setExpanded,
		getRowCanExpand: () => true, // required: no sub-rows exist, so opt every row in
		getCoreRowModel: getCoreRowModel(),
		getExpandedRowModel: getExpandedRowModel(), // required, or nothing expands
		getRowId: (row) => row.id, // stable expansion keys + aria-controls id
	});

return (
		<DataTable.Root table={table}>
			<DataTable.Head />
			<DataTable.Body>
				{table.getRowModel().rows.map((row) => (
					<DataTable.Row
						key={row.id}
						row={row}
						renderExpanded={(row) => (
							<CodeBlock.Root>
								<CodeBlock.Body>
									<CodeBlock.CopyButton />
									<CodeBlock.Code value={jsonCodeBlockValue(row.original)} />
								</CodeBlock.Body>
							</CodeBlock.Root>
						)}
					/>
				))}
			</DataTable.Body>
		</DataTable.Root>
	);
}
```

For full control over the detail row — a custom `colSpan`, multiple panels, or bespoke markup — omit `renderExpanded` and render `DataTable.ExpandedRow` yourself, directly after `DataTable.Row` and wrapped in a `Fragment` (never a DOM element, since a node between `<tbody>` and `<tr>` is invalid HTML):

```tsx
import { Fragment } from "react";

{
	table.getRowModel().rows.map((row) => (
		<Fragment key={row.id}>
			<DataTable.Row row={row} />
			{row.getIsExpanded() && (
				<DataTable.ExpandedRow row={row} colSpan={4}>
					{/* any detail markup */}
				</DataTable.ExpandedRow>
			)}
		</Fragment>
	));
}
```

## API Reference

The `DataTable` components are built on top of [TanStack Table](https://tanstack.com/table/latest/docs/introduction). All TanStack Table utilities (`createColumnHelper`, `getCoreRowModel`, `getSortedRowModel`, `getPaginationRowModel`, `getFilteredRowModel`, `useReactTable`, etc.) are re-exported from `@ngrok/mantle/data-table`.

### DataTable.Root

The root container for the data table. Wraps all other `DataTable` sub-components and provides the table context. Delegates rendering to [`Table.Root`](/components/table#tableroot).

### DataTable.Head

Automatically renders column headers from the table instance by iterating `table.getHeaderGroups()`. Does not accept children — the headers come from each column's `header` definition.

### DataTable.Body

The `<tbody>` container for rows of data. Typically wraps a map of `DataTable.Row` or a fallback `DataTable.EmptyRow`.

### DataTable.Row

Renders a single body row using the column definitions from the table instance. Does not accept children — cells come from each column's `cell` definition.

When `onClick` is provided, the row automatically receives `cursor-pointer`. Pass a different `cursor-*` class via `className` (for example, `cursor-wait`) to override.

Remaining props forward to the HTML `<tr>` element.

### DataTable.EmptyRow

An empty-state row that spans every column. Render this as the `else` branch when `rows.length === 0` to keep the table's frame intact.

### DataTable.Header

A `<th>` cell optimized for header actions. Wrap sortable headers' contents in `DataTable.HeaderSortButton`.

### DataTable.HeaderSortButton

A sortable button toggle for column headers. Clicking cycles through sort directions: `unsorted → asc → desc → unsorted` for `"alphanumeric"`, and `unsorted → desc → asc → unsorted` (newest-first) for `"time"`. Renders a sort icon that reflects the current direction.

All additional props from [`Button`](/components/button).

### DataTable.Cell

A `<td>` for rendering individual data cells. Provides mantle typography, padding, and alignment. Re-exported from [`Table.Cell`](/components/table#tablecell).

### DataTable.ActionHeader

A sticky-right `<th>` that pairs with `DataTable.ActionCell`. Use as the `header` for your action column so the pinned column stays aligned across the header and every body row when the table scrolls horizontally. Automatically opts out of stickiness when the table is empty so the scroll-fade shows correctly.

### DataTable.ActionCell

A sticky-right `<td>` for per-row action buttons (typically an `IconButton` that opens a `DropdownMenu`).

When the row has an `onClick`, pass `onClick={(event) => event.stopPropagation()}` on the action cell so clicks on controls inside do not bubble and trigger the row handler.

### DataTable.ExpandHeader

A narrow `<th>` for the leading expand-toggle column, mirroring `DataTable.ActionHeader`. Renders a screen-reader-only label by default so the column is announced while staying visually empty.

### DataTable.RowExpandButton

An accessible `+`/`−` toggle that expands or collapses a row's detail panel. Place it inside a `DataTable.Cell` in a leading `columnHelper.display` column and pair it with `DataTable.ExpandedRow`. Renders a real `<button>` that sets `aria-expanded` and (while expanded) `aria-controls`, stops click propagation so it never fires a row-level `onClick`, and renders nothing when `row.getCanExpand()` is `false`. Forwards [`IconButton`](/components/icon-button) props.

### DataTable.ExpandedRow

The sibling `<tr>` that renders a row's expanded detail panel. Render it directly after `DataTable.Row`, wrapped in a `Fragment` (never a DOM element), and only when `row.getIsExpanded()` is `true`. The single cell spans every visible column, carries the `id` that `DataTable.RowExpandButton` targets via `aria-controls`, and sits on an opaque card surface so it coexists with a sticky action column. Exposes `data-expanded-content` for styling.

---

---
title: Description List
description: A semantically correct description list built on the HTML dl element. Renders a list of label/value pairs, commonly used in detail views to display metadata about a resource.
---

# Description List

A semantically correct description list built on the HTML [`<dl>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl) element. Renders a list of label/value pairs, commonly used in detail views to display metadata about a resource.

Compose `<DescriptionList.Root>` with `<DescriptionList.Item>`, `<DescriptionList.Label>`, and `<DescriptionList.Value>` as direct children.

```tsx
import { DescriptionList } from "@ngrok/mantle/description-list";

<DescriptionList.Root>
	<DescriptionList.Item>
		<DescriptionList.Label>Key</DescriptionList.Label>
		<DescriptionList.Value className="font-bold">my-api-key</DescriptionList.Value>
	</DescriptionList.Item>
	<DescriptionList.Item>
		<DescriptionList.Label>ID</DescriptionList.Label>
		<DescriptionList.Value>aigk_2fKm9x8Hn3QpYT7zKlR0vW5</DescriptionList.Value>
	</DescriptionList.Item>
	<DescriptionList.Item>
		<DescriptionList.Label>Description</DescriptionList.Label>
		<DescriptionList.Value>Production API key for the billing service</DescriptionList.Value>
	</DescriptionList.Item>
	<DescriptionList.Item>
		<DescriptionList.Label>Created</DescriptionList.Label>
		<DescriptionList.Value>2 days ago by admin@example.com</DescriptionList.Value>
	</DescriptionList.Item>
	<DescriptionList.Item>
		<DescriptionList.Label>Last Used</DescriptionList.Label>
		<DescriptionList.Value>
			<span className="italic text-muted">Never</span>
		</DescriptionList.Value>
	</DescriptionList.Item>
	<DescriptionList.Item>
		<DescriptionList.Label>Metadata</DescriptionList.Label>
		<DescriptionList.Value>17 Bytes</DescriptionList.Value>
	</DescriptionList.Item>
</DescriptionList.Root>;
```

## Composition

Compose the parts of a `DescriptionList` together to build your own:

```text showLineNumbers=false
DescriptionList.Root
└── DescriptionList.Item
    ├── DescriptionList.Label
    └── DescriptionList.Value
```

## API Reference

### DescriptionList.Root

The root container for a description list. Renders a `<dl>` element.

All props from [dl](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl#attributes), plus:

| Prop         | Type        | Default | Description                                                                                                                       |
| ------------ | ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `children?`  | `ReactNode` |         | Compose `DescriptionList.Item` components as direct children.                                                                     |
| `className?` | `string`    |         | Additional CSS class names to apply to the root element.                                                                          |
| `asChild?`   | `boolean`   | `false` | Use the `asChild` prop to compose the `DescriptionList.Root` styling onto alternative element types or your own React components. |

### DescriptionList.Item

A wrapper that groups a `DescriptionList.Label` and `DescriptionList.Value` pair. Renders a `<div>` with a default subgrid layout that inherits column tracks from the root.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop         | Type        | Default | Description                                                                                                                       |
| ------------ | ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `children?`  | `ReactNode` |         | A `DescriptionList.Label` and `DescriptionList.Value` pair.                                                                       |
| `className?` | `string`    |         | Additional CSS class names to apply to the item wrapper.                                                                          |
| `asChild?`   | `boolean`   | `false` | Use the `asChild` prop to compose the `DescriptionList.Item` styling onto alternative element types or your own React components. |

### DescriptionList.Label

The label for a description list item. Renders a `<dt>` element.

All props from [dt](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dt#attributes), plus:

| Prop         | Type        | Default | Description                                                                                                                        |
| ------------ | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `children?`  | `ReactNode` |         | The label text for this description list item.                                                                                     |
| `className?` | `string`    |         | Additional CSS class names to apply to the label element.                                                                          |
| `asChild?`   | `boolean`   | `false` | Use the `asChild` prop to compose the `DescriptionList.Label` styling onto alternative element types or your own React components. |

### DescriptionList.Value

The value for a description list item. Renders a `<dd>` element. Compose any content inside — the component imposes no layout on its children.

All props from [dd](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dd#attributes), plus:

| Prop         | Type        | Default | Description                                                                                                                        |
| ------------ | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `children?`  | `ReactNode` |         | The value content for this description list item. Can be any React node — text, formatted values, interactive elements, etc.       |
| `className?` | `string`    |         | Additional CSS class names to apply to the value element.                                                                          |
| `asChild?`   | `boolean`   | `false` | Use the `asChild` prop to compose the `DescriptionList.Value` styling onto alternative element types or your own React components. |

---

---
title: Dialog
description: A window overlaid on either the primary window or another dialog window, rendering the content underneath inert.
---

# Dialog

A window overlaid on either the primary window or another dialog window, rendering the content underneath inert. Built on top of Radix UI Dialog.

## When to use

Use `Dialog` for a centered modal that interrupts the user to gather input or confirm a non-destructive choice. For destructive confirmations (delete, irreversible actions), use [`AlertDialog`](/components/alert-dialog). For side-panel content (filter panels, detail/inspector views, navigation drawers), use [`Sheet`](/components/sheet).

```tsx
import { Dialog } from "@ngrok/mantle/dialog";
import { Button } from "@ngrok/mantle/button";

<Dialog.Root>
	<Dialog.Trigger asChild>
		<Button type="button" appearance="filled" priority="neutral">
			Open dialog
		</Button>
	</Dialog.Trigger>
	<Dialog.Content>
		<Dialog.Header>
			<Dialog.Title>Are you absolutely sure?</Dialog.Title>
			<Dialog.CloseIconButton />
		</Dialog.Header>
		<Dialog.Body>
			This action cannot be undone. This will permanently delete your account and remove your data
			from our servers.
		</Dialog.Body>
		<Dialog.Footer>
			<Dialog.Close asChild>
				<Button type="button" priority="neutral" appearance="outlined">
					Cancel
				</Button>
			</Dialog.Close>
			<Dialog.Close asChild>
				<Button type="button" priority="danger" appearance="filled">
					Delete
				</Button>
			</Dialog.Close>
		</Dialog.Footer>
	</Dialog.Content>
</Dialog.Root>;
```

## Handling Autofill Overlays

When a dialog contains form inputs, browser autofill or password-manager plugins (e.g. 1Password) may render overlays as siblings to the dialog content. By default, clicking these overlays triggers `onPointerDownOutside`, which closes the dialog. Use `isDialogOverlayTarget` to prevent this:

```tsx
import { Dialog, isDialogOverlayTarget } from "@ngrok/mantle/dialog";

<Dialog.Content
	onPointerDownOutside={(event) => {
		// Allow closing only when clicking the actual overlay backdrop,
		// not browser autofill/password-manager popups
		if (isDialogOverlayTarget(event.target)) {
			return;
		}
		event.preventDefault();
	}}
>
	{/* dialog content with form inputs */}
</Dialog.Content>;
```

## Composition

Compose the parts of a `Dialog` together to build your own:

```text showLineNumbers=false
Dialog.Root
├── Dialog.Trigger
└── Dialog.Content
    ├── Dialog.Header
    │   ├── Dialog.Title
    │   ├── Dialog.Description
    │   └── Dialog.CloseIconButton
    ├── Dialog.Body
    └── Dialog.Footer
        └── Dialog.Close
```

## Combining with a Tooltip

In some cases, you might wish to have a tooltip over the dialog trigger. This is helpful if the dialog trigger is an `IconButton` and you wish to provide more context to what the button does. You can compose them both together to where the dialog trigger is also the tooltip trigger.

```tsx
import { Dialog } from "@ngrok/mantle/dialog";
import { Button, IconButton } from "@ngrok/mantle/button";
import { Tooltip } from "@ngrok/mantle/tooltip";
import { TrashSimpleIcon } from "@phosphor-icons/react/TrashSimple";

<Dialog.Root>
	<Tooltip.Root>
		<Tooltip.Trigger asChild>
			<Dialog.Trigger asChild>
				<IconButton type="button" label="Delete" size="sm" icon={<TrashSimpleIcon />} />
			</Dialog.Trigger>
		</Tooltip.Trigger>
		<Tooltip.Content>
			<p>Delete</p>
		</Tooltip.Content>
	</Tooltip.Root>
	<Dialog.Content>
		<Dialog.Header>
			<Dialog.Title>Are you absolutely sure?</Dialog.Title>
			<Dialog.CloseIconButton />
		</Dialog.Header>
		<Dialog.Body>
			This action cannot be undone. This will permanently delete your account and remove your data
			from our servers.
		</Dialog.Body>
		<Dialog.Footer>
			<Dialog.Close asChild>
				<Button type="button" priority="neutral" appearance="outlined">
					Cancel
				</Button>
			</Dialog.Close>
			<Dialog.Close asChild>
				<Button type="button" priority="danger" appearance="filled">
					Delete
				</Button>
			</Dialog.Close>
		</Dialog.Footer>
	</Dialog.Content>
</Dialog.Root>;
```

## API Reference

### Dialog.Root

The root stateful component that manages the open/closed state of the dialog.

| Prop            | Type                      | Default | Description                                                                                                                                                   |
| --------------- | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open?`         | `boolean`                 |         | The controlled open state of the dialog. Must be used in conjunction with `onOpenChange`.                                                                     |
| `onOpenChange?` | `(open: boolean) => void` |         | Event handler called when the open state of the dialog changes.                                                                                               |
| `defaultOpen?`  | `boolean`                 | `false` | The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.                                               |
| `modal?`        | `boolean`                 | `true`  | The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. |

### Dialog.Trigger

A button that opens the dialog.

| Prop       | Type      | Default | Description                                                                          |
| ---------- | --------- | ------- | ------------------------------------------------------------------------------------ |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the trigger functionality onto your own component. |

### Dialog.Content

The container for the dialog content. Renders on top of the overlay and is centered in the viewport.

| Prop                 | Type                             | Default      | Description                                                                                                                |
| -------------------- | -------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `preferredWidth?`    | `` `max-w-${string}` ``          | `"max-w-lg"` | The preferred width of the dialog content as a Tailwind `max-w-` class. Controls the maximum width of the dialog.          |
| `onEscapeKeyDown?`   | `(event: KeyboardEvent) => void` |              | Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`.                   |
| `onInteractOutside?` | `(event: Event) => void`         |              | Event handler called when the user interacts outside the component. It can be prevented by calling `event.preventDefault`. |

### Dialog.Header

Contains the header content of the dialog, including the title and close button.

| Prop       | Type        | Default | Description                                     |
| ---------- | ----------- | ------- | ----------------------------------------------- |
| `children` | `ReactNode` |         | The content to render inside the dialog header. |

### Dialog.Body

Contains the main content of the dialog.

| Prop       | Type        | Default | Description                                   |
| ---------- | ----------- | ------- | --------------------------------------------- |
| `children` | `ReactNode` |         | The content to render inside the dialog body. |

### Dialog.Footer

Contains the footer content of the dialog, including action buttons.

| Prop       | Type        | Default | Description                                                                        |
| ---------- | ----------- | ------- | ---------------------------------------------------------------------------------- |
| `children` | `ReactNode` |         | The content to render inside the dialog footer. Typically contains action buttons. |

### Dialog.Title

An accessible name to be announced when the dialog is opened.

| Prop       | Type        | Default | Description                                                                       |
| ---------- | ----------- | ------- | --------------------------------------------------------------------------------- |
| `children` | `ReactNode` |         | The title text for the dialog.                                                    |
| `asChild?` | `boolean`   | `false` | Use the `asChild` prop to render a custom element instead of the default heading. |

### Dialog.Description

An accessible description to be announced when the dialog is opened.

| Prop       | Type        | Default | Description                                                                                  |
| ---------- | ----------- | ------- | -------------------------------------------------------------------------------------------- |
| `children` | `ReactNode` |         | The description text for the dialog. Enhances accessibility by providing additional context. |
| `asChild?` | `boolean`   | `false` | Use the `asChild` prop to render a custom element instead of the default paragraph.          |

### Dialog.Close

A button that closes the dialog when clicked.

| Prop       | Type      | Default | Description                                                                        |
| ---------- | --------- | ------- | ---------------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the close functionality onto your own component. |

### Dialog.CloseIconButton

An icon button that closes the dialog when clicked.

| Prop          | Type                       | Default          | Description                                                              |
| ------------- | -------------------------- | ---------------- | ------------------------------------------------------------------------ |
| `size?`       | `"sm"` \| `"md"` \| `"lg"` | `"md"`           | The size of the close icon button.                                       |
| `label?`      | `string`                   | `"Close Dialog"` | The accessible label for the close button. Important for screen readers. |
| `appearance?` | `"ghost"` \| `"outlined"`  | `"ghost"`        | The visual appearance of the close icon button.                          |

---

---
title: Dropdown Menu
description: Displays a menu to the user — such as a set of actions or functions — triggered by a button.
---

# Dropdown Menu

Displays a menu to the user — such as a set of actions or functions — triggered by a button. Built on top of [Radix Dropdown Menu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu).

```tsx
import { Button } from "@ngrok/mantle/button";
import { DropdownMenu } from "@ngrok/mantle/dropdown-menu";
import { Icon } from "@ngrok/mantle/icon";

<DropdownMenu.Root>
	<DropdownMenu.Trigger asChild>
		<Button appearance="filled" priority="neutral" type="button">
			Open Menu
		</Button>
	</DropdownMenu.Trigger>
	<DropdownMenu.Content>
		<DropdownMenu.Label>corby.pickles@ngork.com</DropdownMenu.Label>
		<DropdownMenu.Separator />
		<DropdownMenu.RadioItem name="theme" value="system">
			<Icon svg={<DesktopIcon />} />
			System Preference
		</DropdownMenu.RadioItem>
		<DropdownMenu.Separator />
		<DropdownMenu.Item>
			<Icon svg={<GearIcon />} />
			User Settings
		</DropdownMenu.Item>
		<DropdownMenu.Separator />
		<DropdownMenu.Item>
			<Icon svg={<SignOutIcon />} />
			Log out
		</DropdownMenu.Item>
	</DropdownMenu.Content>
</DropdownMenu.Root>;
```

## Composition

Compose the parts of a `DropdownMenu` together to build your own:

```text showLineNumbers=false
DropdownMenu.Root
├── DropdownMenu.Trigger
└── DropdownMenu.Content
    ├── DropdownMenu.Group
    │   ├── DropdownMenu.Label
    │   ├── DropdownMenu.Item
    │   │   └── DropdownMenu.Shortcut
    │   ├── DropdownMenu.CheckboxItem
    │   └── DropdownMenu.RadioGroup
    │       └── DropdownMenu.RadioItem
    ├── DropdownMenu.Separator
    └── DropdownMenu.Sub
        ├── DropdownMenu.SubTrigger
        └── DropdownMenu.SubContent
```

## API Reference

The `DropdownMenu` components are built on top of [Radix Dropdown Menu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu).

### DropdownMenu.Root

The root, stateful component that manages the open/closed state of the dropdown menu.

### DropdownMenu.Trigger

The trigger button that opens the dropdown menu.

### DropdownMenu.Content

The container for the dropdown menu content. Appears in a portal with scrolling and animations.

All props from Radix [DropdownMenu.Content](https://www.radix-ui.com/primitives/docs/components/dropdown-menu#content), plus:

### DropdownMenu.Item

A standard item in the dropdown menu that can be selected or activated.

### DropdownMenu.CheckboxItem

A menu item with a checkbox that can be controlled or uncontrolled.

All props from Radix [DropdownMenu.CheckboxItem](https://www.radix-ui.com/primitives/docs/components/dropdown-menu#checkboxitem), including:

### DropdownMenu.RadioGroup

A radio group container for exclusive selection within the dropdown menu.

### DropdownMenu.RadioItem

A radio item where only one item in the group can be selected at a time.

All props from Radix [DropdownMenu.RadioItem](https://www.radix-ui.com/primitives/docs/components/dropdown-menu#radioitem), including:

### DropdownMenu.Label

A label for grouping and describing sections within the dropdown menu.

### DropdownMenu.Group

A group container for organizing related dropdown menu items. Accepts all props from Radix [DropdownMenu.Group](https://www.radix-ui.com/primitives/docs/components/dropdown-menu#group).

### DropdownMenu.Separator

A visual separator for dividing sections within the dropdown menu. All props from [`Separator`](/components/separator).

### DropdownMenu.Shortcut

A keyboard shortcut indicator for dropdown menu items. All props from [span](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span#attributes).

### DropdownMenu.Sub

A submenu container for creating nested dropdown menus. Accepts all props from Radix [DropdownMenu.Sub](https://www.radix-ui.com/primitives/docs/components/dropdown-menu#sub).

### DropdownMenu.SubTrigger

The trigger item that opens a submenu when hovered or focused.

### DropdownMenu.SubContent

The content container for submenu items. Appears in a portal with scrolling and animations.

---

---
title: Empty
description: Display a placeholder when there is no data or content to show.
---

# Empty

Display a placeholder when there is no data or content to show. Commonly used
inside tables, lists, or pages that have no results.

```tsx
import { Empty } from "@ngrok/mantle/empty";
import { Button } from "@ngrok/mantle/button";
import { GhostIcon, PlusIcon } from "@phosphor-icons/react";

<Empty.Root>
	<Empty.Icon svg={<GhostIcon />} />
	<Empty.Title>No endpoints yet</Empty.Title>
	<Empty.Description>
		<p>Create your first endpoint to get started.</p>
	</Empty.Description>
	<Empty.Actions>
		<Button type="button" appearance="filled" priority="neutral">
			<PlusIcon />
			Create endpoint
		</Button>
	</Empty.Actions>
</Empty.Root>;
```

## Error page

A full-page error state with a retry action.

```tsx
import { Empty } from "@ngrok/mantle/empty";
import { Button } from "@ngrok/mantle/button";
import { SmileyMeltingIcon } from "@phosphor-icons/react";

<Empty.Root>
	<Empty.Icon svg={<SmileyMeltingIcon />} />
	<Empty.Title>Oops, something went wrong.</Empty.Title>
	<Empty.Description>
		<p>Please try again in a few minutes.</p>
	</Empty.Description>
	<Empty.Actions>
		<Button type="button" appearance="outlined" priority="neutral">
			Retry
		</Button>
	</Empty.Actions>
</Empty.Root>;
```

## No filter results

A common pattern for empty states when a filter or search yields no results.

```tsx
import { Empty } from "@ngrok/mantle/empty";
import { Button } from "@ngrok/mantle/button";
import { MagnifyingGlassIcon } from "@phosphor-icons/react";

<Empty.Root>
	<Empty.Icon svg={<MagnifyingGlassIcon />} />
	<Empty.Title>No results matched your filter.</Empty.Title>
	<Empty.Description>
		<p>Check your spelling. It's possible what you're looking for no longer exists.</p>
	</Empty.Description>
	<Empty.Actions>
		<Button type="button" appearance="outlined" priority="neutral">
			Clear filters
		</Button>
	</Empty.Actions>
</Empty.Root>;
```

## Within a data table

Inside a [`DataTable`](/components/data-table), host `Empty` in `DataTable.EmptyRow`. The row already spans every column (auto `colSpan`) and `Empty.Root` centers itself, so you don't hand-roll a `<td>` or any centering. Branch on whether a filter is active to choose between the "no data yet" and "no results" copy — see the [DataTable empty-states recipe](/components/data-table#empty-states-no-data-vs-no-results) for the full two-state pattern.

<DataTable.Body>
	{rows.length > 0 ? (
		rows.map((row) => <DataTable.Row key={row.id} row={row} />)
	) : (
		<DataTable.EmptyRow>
			<Empty.Root>
				<Empty.Icon svg={<MagnifyingGlassIcon />} />
				<Empty.Title>No results matched your filter.</Empty.Title>
				<Empty.Description>
					<p>Try a different search, or clear the filter to see everything.</p>
				</Empty.Description>
				<Empty.Actions>
					<Button type="button" appearance="outlined" priority="neutral" onClick={clearFilters}>
						Clear filters
					</Button>
				</Empty.Actions>
			</Empty.Root>
		</DataTable.EmptyRow>
	)}
</DataTable.Body>;
```

## Minimal

You can use only the sub-components you need.

```tsx
import { Empty } from "@ngrok/mantle/empty";
import { GhostIcon } from "@phosphor-icons/react";

<Empty.Root>
	<Empty.Icon svg={<GhostIcon />} />
	<Empty.Title>Nothing here</Empty.Title>
</Empty.Root>;
```

## Composition

Compose the parts of an `Empty` state together to build your own:

```text showLineNumbers=false
Empty.Root
├── Empty.Icon
├── Empty.Title
├── Empty.Description
└── Empty.Actions
```

## API Reference

### Empty.Root

The root container for an empty state. Centers content horizontally with consistent vertical padding and max-width.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop       | Type      | Default | Description                                       |
| ---------- | --------- | ------- | ------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Render as a different element by passing a child. |

### Empty.Icon

Renders a large icon for the empty state. Pass a single SVG icon element via the `svg` prop. The icon is automatically sized to `size-16`.

All props from [svg](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg#attributes), plus:

| Prop  | Type        | Default | Description                |
| ----- | ----------- | ------- | -------------------------- |
| `svg` | `ReactNode` | —       | A single SVG icon element. |

### Empty.Title

The heading text for the empty state. Renders as an `h3` by default. Use `asChild` to render as a different heading level.

All props from [h3](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#attributes), plus:

| Prop       | Type      | Default | Description                                                                 |
| ---------- | --------- | ------- | --------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Render as a different heading element (e.g. `h2`, `h3`) by passing a child. |

### Empty.Description

Supporting descriptive text rendered below the title. Renders as a `div` with vertical spacing so multiple paragraphs can be placed inside.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

### Empty.Actions

A flex container for action buttons or links.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

---

---
title: Field
description: Layout primitive for a single form field — label, control, helper text, and error messaging stacked together with consistent spacing.
---

# Field

`Field` is a compound layout primitive for building a single form field. It groups `Field.Label`, a control (`Input`, `Select`, `Checkbox`, etc.), helper / hint text (`Field.Description`), and validation errors (`Field.Errors`, `Field.ErrorList`, `Field.ErrorItem`). Stack multiple fields together with `Field.Group`, or — for radios and related checkboxes specifically — wrap them in a `Field.Set` + `Field.Legend` for a properly-named semantic group.

`Field.Label` wraps the mantle [`Label`](/components/label) for ergonomic field composition. It keeps the same click-to-focus, disabled, and typography behavior as `Label`; see the [Label docs](/components/label) for the full surface.

**Label-to-control association is automatic inside a `Field.Item`.** `Field.Item` generates a stable control id, `Field.Control` splats that id onto its focusable child, and `Field.Label` consumes the same id as the default `htmlFor`. The required `name` on `Field.Item` is the single source of truth for the control's form name, so you can write `<Field.Label>Email</Field.Label>` next to `<Field.Control><Input /></Field.Control>` without threading a matching `htmlFor` / `id` pair (or a separate `useId()` call) at the call site. Pass an explicit `htmlFor` on `Field.Label` to opt out — for example when the focusable element is rendered outside of `Field.Control` and the auto-generated id never lands on it.

Wrap the focusable control in `Field.Control` so `Field.Item` can associate descriptions and rendered errors via `aria-describedby` / `aria-errormessage`. A rendered `Field.Errors` or `Field.ErrorList` infers error state; pass `validation` on `Field.Item` only when you need to override that state.

**`Field.Item` owns the full control contract.** When a focusable control is wrapped in `Field.Control`, the surrounding `Field.Item` owns its `id`, `name`, `aria-describedby`, `aria-errormessage`, `aria-invalid`, and `validation` — anything supplied on the child element (or on `Field.Control`) is overwritten. There's one place to override: `Field.Item` itself. To opt out of the contract entirely, render the control without `Field.Control`.

```tsx
import { Field } from "@ngrok/mantle/field";
import { Input } from "@ngrok/mantle/input";

<Field.Item name="username" className="max-w-80">
	<Field.Label>Username</Field.Label>
	<Field.Control>
		<Input placeholder="ada-lovelace" />
	</Field.Control>
	<Field.Description>Pick something memorable — you can change it later.</Field.Description>
</Field.Item>;
```

## Common mistakes

The canonical slot order inside a `Field.Item` is `Field.Label` → `Field.Control` → `Field.Errors` → `Field.Description`. `Field.Item` renders its children in source order and the JSX stays valid no matter how you arrange them, so a misplaced slot fails silently rather than erroring — the most common mistake is putting `Field.Description` (help text) **above** the control instead of below it.

```tsx
// ❌ Wrong — help text rendered between the label and the control
<Field.Item name="recoveryCode">
	<Field.Label>Recovery code</Field.Label>
	<Field.Description>This renders above the input.</Field.Description>
	<Field.Control>
		<Input />
	</Field.Control>
</Field.Item>
```

```tsx
// ✅ Correct — label, control, then errors and help text below
<Field.Item name="recoveryCode">
	<Field.Label>Recovery code</Field.Label>
	<Field.Control>
		<Input />
	</Field.Control>
	<Field.Errors messages={["Enter a valid recovery code."]} />
	<Field.Description>This renders below the input.</Field.Description>
</Field.Item>
```

## Error messages

Use `Field.Errors` below the control when validation fails. It accepts string messages, trims them, filters empty values, removes duplicates, and renders a semantic `<ul>` with `<li>` items so screen readers announce the errors as a list. When the list renders, `Field.Item` infers error state so the visual state and ARIA invalid state stay in sync.

For custom list markup or rich error content, compose the lower-level `Field.ErrorList` and `Field.ErrorItem` parts directly. A single error is still just a list of one.

When a `Field.Description` follows directly after `Field.Errors` or `Field.ErrorList`, `Field.Description` automatically collapses the parent's `gap-1.5` with a matching negative top margin so the errors + helper read as one tight block — matching the figma. Pass any margin utility on `Field.Description` (e.g. `className="mt-1"`, `className="mt-0"`) to override.

```tsx
<Field.Item name="email">
	<Field.Label>Email</Field.Label>
	<Field.Control>
		<Input type="email" />
	</Field.Control>
	<Field.Errors messages={["Enter a valid email address."]} />
	<Field.Description>We'll never share your email.</Field.Description>
</Field.Item>
```

## Multiple errors

Pass multiple messages to `Field.Errors` when a validator produces more than one message at once (e.g. `minLength` + `pattern` + custom rule). Items stack tightly so the whole error block reads as one unit.

```tsx
<Field.Item name="password">
	<Field.Label>Password</Field.Label>
	<Field.Control>
		<PasswordInput />
	</Field.Control>
	<Field.Errors
		messages={[
			"Must be at least 12 characters.",
			"Must include a number.",
			"Must include a symbol.",
		]}
	/>
	<Field.Description>Use a password manager to generate one.</Field.Description>
</Field.Item>
```

When errors arrive from a validator as an array (e.g. `field.state.meta.errors` from TanStack Form), map them to messages and pass them to `Field.Errors`. Empty, blank, missing, or duplicate messages render nothing and do not add an error message reference. Reach for `toErrorMessages` to handle the mixed string / `{ message }` / nullish shapes that TanStack Form yields — see [With TanStack Form](#with-tanstack-form) below.

## Manual error list

Prefer `Field.Errors` when you already have plain string messages. Compose `Field.ErrorList` and `Field.ErrorItem` directly when you need custom list contents, richer message markup, or a polymorphic list element. Use one or the other in a `Field.Item` — `Field.Item` owns a single errors slot ID, and `Field.Errors` is itself a `Field.ErrorList` under the hood, so rendering both would duplicate the `id` on the page.

```tsx
<Field.Item name="username">
	<Field.Label>Username</Field.Label>
	<Field.Control>
		<Input />
	</Field.Control>
	<Field.ErrorList>
		<Field.ErrorItem>Must be at least 3 characters.</Field.ErrorItem>
		<Field.ErrorItem>Use letters, numbers, hyphens, or underscores.</Field.ErrorItem>
	</Field.ErrorList>
	<Field.Description>Pick something memorable.</Field.Description>
</Field.Item>
```

## Optional fields

Use `Field.Optional` inside a `<Field.Label>` to mark a field as optional. It renders a muted "(Optional)" suffix at `text-sm` regular weight so it reads as secondary metadata without competing with the bolder label text. Defaults to the literal "(Optional)" — pass children to translate or replace.

```tsx
<Field.Item name="nickname">
	<Field.Label className="flex items-baseline gap-1">
		Nickname <Field.Optional />
	</Field.Label>
	<Field.Control>
		<Input placeholder="ada" />
	</Field.Control>
	<Field.Description>Visible on your public profile.</Field.Description>
</Field.Item>
```

Place `Field.Optional` inside the `<Field.Label>` so screen readers announce it as part of the accessible name (e.g. "Nickname, Optional, edit text"). The label's `flex items-baseline gap-1` keeps the suffix on the same baseline as the bolder label text.

## Help icon next to the label

When the label needs a sibling affordance that can't live inside the `<Field.Label>` itself — most commonly an interactive help-icon button — wrap the label and its decorations in `Field.LabelRow`. It's a horizontal flex container with `items-center` and `gap-1` so the label, optional suffix, and help icon all sit on a shared center line. (Center alignment, not baseline — SVG icon buttons have no text baseline, so `items-baseline` would push them above the label text.)

Putting an interactive button inside `<label>` is a footgun: clicks on a `<label>` forward focus to the associated control, so a help button nested in a `<Field.Label>` would steal that behavior. `Field.LabelRow` is the way out.

Reach for the bundled `Field.Help` / `Field.HelpTrigger` / `Field.HelpContent` rather than wiring `Popover` + `IconButton` + an icon by hand — it's the same composition, three thin wrappers, with sensible visual defaults (ghost `IconButton`, `xs` size, default Phosphor `QuestionIcon`, `text-body` color). `Field.HelpTrigger` still requires a contextual accessible `label` so repeated help icons do not all announce the same thing. [`Popover`](/components/popover) under the hood — not [`Tooltip`](/components/tooltip) — so the affordance is reachable on touch devices.

```tsx
<Field.Item name="apiKey">
	<Field.LabelRow>
		<Field.Label className="flex items-baseline gap-1">
			API key <Field.Optional />
		</Field.Label>
		<Field.Help>
			<Field.HelpTrigger label="What is an API key?" />
			<Field.HelpContent>Copy this from the ngrok dashboard.</Field.HelpContent>
		</Field.Help>
	</Field.LabelRow>
	<Field.Control>
		<Input />
	</Field.Control>
	<Field.Description>You can find this in the ngrok dashboard.</Field.Description>
</Field.Item>
```

`Field.HelpTrigger` accepts every `IconButton` prop, so swap the icon or change the appearance without dropping down to raw `Popover`:

```tsx
<Field.Help>
	<Field.HelpTrigger icon={<InfoIcon />} label="What is a webhook secret?" />
	<Field.HelpContent>
		Used to sign outbound webhook payloads so your endpoint can verify the request.
	</Field.HelpContent>
</Field.Help>
```

## Multiple fields

Wrap multiple `Field.Item`s in a `Field.Group` to stack them with consistent `gap-4` spacing. This is the default for any form with more than one field — pure layout, no `<fieldset>` semantics.

```tsx
<Field.Group>
	<Field.Item name="email">
		<Field.Label>Email</Field.Label>
		<Field.Control>
			<Input type="email" />
		</Field.Control>
	</Field.Item>
	<Field.Item name="password">
		<Field.Label>Password</Field.Label>
		<Field.Control>
			<PasswordInput />
		</Field.Control>
		<Field.Description>At least 12 characters.</Field.Description>
	</Field.Item>
</Field.Group>
```

## Radio and checkbox groups

`Field.Set` renders a real `<fieldset>` — paired with `Field.Legend`, it gives a related set of controls a single accessible name (so a screen reader announces "Notification frequency, group, Daily"). Reach for it specifically when the grouping is itself the question the user is answering: most commonly a [`RadioGroup`](/components/radio-group) (one question, many possible answers), or a set of related checkboxes (preference toggles, permission flags, opt-ins).

**When *not* to use it.** Stacking unrelated fields under a shared header is *not* a semantic group — `Field.Group` (above) is the right call. A `<fieldset>` around plain inputs reads as noise to assistive tech and looks visually heavy. If you find yourself reaching for `Field.Set` to add a section title to a form, render a regular heading instead.

Keep the `Field.Legend` self-contained: it is the accessible name for the group. `Field.Set` does not auto-associate `Field.Description`; if a group needs extra instructions announced by assistive technology, wire your own description with `aria-describedby`.

```tsx
<Field.Set>
	<Field.Legend>Notification frequency</Field.Legend>
	<RadioGroup.Root name="frequency" defaultValue="daily">
		<RadioGroup.Item value="daily" id="freq-daily">
			<RadioGroup.Indicator />
			<RadioGroup.ItemContent asChild>
				<label htmlFor="freq-daily">Daily</label>
			</RadioGroup.ItemContent>
		</RadioGroup.Item>
		<RadioGroup.Item value="weekly" id="freq-weekly">
			<RadioGroup.Indicator />
			<RadioGroup.ItemContent asChild>
				<label htmlFor="freq-weekly">Weekly</label>
			</RadioGroup.ItemContent>
		</RadioGroup.Item>
		<RadioGroup.Item value="never" id="freq-never">
			<RadioGroup.Indicator />
			<RadioGroup.ItemContent asChild>
				<label htmlFor="freq-never">Never</label>
			</RadioGroup.ItemContent>
		</RadioGroup.Item>
	</RadioGroup.Root>
</Field.Set>
```

## With TanStack Form

`Field` is designed to slot directly into [TanStack Form](https://tanstack.com/form). Pass `field.name` as the `name` prop on `Field.Item` — it splats onto the focusable control inside `Field.Control` and generates a stable id that wires `Field.Label` ↔ control association automatically. Wrap the input in `Field.Control` so descriptions and rendered errors are associated with the control.

`field.state.meta.errors` is a mixed array — TanStack Form yields plain strings, `{ message }` issue objects (Zod / Standard Schema), thrown `Error` instances, and falsy slots all in one place. Pass it through `toErrorMessages` to get a clean `string[]` for `Field.Errors`. The list renders nothing when the result is empty, and infers error state only when it has messages, so it's safe to leave mounted unconditionally:

```tsx
import { Field, toErrorMessages } from "@ngrok/mantle/field";
import { Input, PasswordInput } from "@ngrok/mantle/input";
import { Button } from "@ngrok/mantle/button";
import { useForm } from "@tanstack/react-form";
import { z } from "zod";

const schema = z.object({
	email: z.email("Enter a valid email."),
	password: z.string().min(12, "Must be at least 12 characters."),
});

export function AccountForm() {
	const form = useForm({
		defaultValues: { email: "", password: "" },
		validators: { onChange: schema },
		onSubmit: ({ value }) => {
			window.alert(JSON.stringify(value, null, 2));
		},
	});

return (
		<form
			className="flex flex-col gap-4"
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<Field.Group>
				<form.Field name="email">
					{(field) => (
						<Field.Item name={field.name}>
							<Field.Label>Email</Field.Label>
							<Field.Control>
								<Input
									type="email"
									value={field.state.value}
									onBlur={field.handleBlur}
									onChange={(event) => field.handleChange(event.target.value)}
								/>
							</Field.Control>
							<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
							<Field.Description>We'll never share your email.</Field.Description>
						</Field.Item>
					)}
				</form.Field>
				<form.Field name="password">
					{(field) => (
						<Field.Item name={field.name}>
							<Field.Label>Password</Field.Label>
							<Field.Control>
								<PasswordInput
									value={field.state.value}
									onBlur={field.handleBlur}
									onChange={(event) => field.handleChange(event.target.value)}
								/>
							</Field.Control>
							<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
							<Field.Description>At least 12 characters.</Field.Description>
						</Field.Item>
					)}
				</form.Field>
			</Field.Group>
			<Button type="submit" appearance="filled" priority="neutral">
				Submit
			</Button>
		</form>
	);
}
```

### Without `toErrorMessages`

`toErrorMessages` is a convenience — `Field.Errors` itself only needs a `string[]`. If you already know your validator's error shape (or you want to filter / re-format messages first), map the array inline and skip the helper. The example below mirrors the TanStack Form example above, but pulls `.message` off each entry by hand:

```tsx
<form.Field name="email">
	{(field) => (
		<Field.Item name={field.name}>
			<Field.Label>Email</Field.Label>
			<Field.Control>
				<Input
					type="email"
					value={field.state.value}
					onBlur={field.handleBlur}
					onChange={(event) => field.handleChange(event.target.value)}
				/>
			</Field.Control>
			<Field.Errors
				messages={field.state.meta.errors.map((error) =>
					typeof error === "string" ? error : error?.message,
				)}
			/>
		</Field.Item>
	)}
</form.Field>
```

`Field.Errors` already trims each string, filters empty / nullish / `false` entries, and renders nothing when no messages remain — so passing `undefined` / empty strings through the `.map` is safe and behaves the same as filtering them out. Use the inline form when the helper's mixed-shape handling isn't pulling its weight (e.g. a validator that always emits `{ message: string }`, where a bare `error?.message` map is enough), and reach for `toErrorMessages` when you want a single call that handles the full TanStack Form error array shape.

## Composition

Most forms only need a `Field.Group` of `Field.Item`s — that's the default tree. Each `Field.Item` may render at most one `Field.Description` and one `Field.Errors` **or** one `Field.ErrorList` (not both) — they share a single slot ID owned by the item.

```text showLineNumbers=false
Field.Group
└── Field.Item
    ├── Field.LabelRow
    │   ├── Field.Label            (or Field.LabelText for control-less rows)
    │   │   └── Field.Optional
    │   └── Field.Help
    │       ├── Field.HelpTrigger
    │       └── Field.HelpContent
    ├── Field.Control
    │   └── (control)
    ├── Field.Errors             (or)
    ├── Field.ErrorList
    │   └── Field.ErrorItem
    └── Field.Description
```

For radios or related checkboxes — where the grouping is itself the question being answered — wrap the controls in a semantic `Field.Set` + `Field.Legend` instead:

```text showLineNumbers=false
Field.Set
├── Field.Legend
└── (RadioGroup / Checkbox group)
```

Skip `Field.Set` for unrelated fields stacked together — `<fieldset>` semantics around plain inputs read as noise to assistive tech.

## Polymorphism

Layout parts plus `Field.Description`, `Field.Optional`, and `Field.ErrorList` accept an `asChild` prop. When `true`, the part renders its single child instead of its default element, forwarding all class names, `data-*` attributes, and the ref onto that child. `Field.Set`, `Field.Legend`, and `Field.ErrorItem` always render `<fieldset>`, `<legend>`, and `<li>` respectively, because those elements are the semantics those parts exist to provide.

```tsx
<Field.ErrorList asChild>
	<ol>
		<Field.ErrorItem>Fix this first.</Field.ErrorItem>
		<Field.ErrorItem>Then fix this.</Field.ErrorItem>
	</ol>
</Field.ErrorList>
```

## API Reference

### Field.Label

`Field.Label` wraps [`Label`](/components/label) and defaults `htmlFor` from the surrounding `Field.Item`. Use it inside `Field.Item` to give the control an accessible name and click-to-focus behavior.

See the [Label docs](/components/label) for association patterns, disabled state, and typography behavior.

All props from [`Label`](/components/label).

### Field.LabelText

Static, label-styled text for a `Field.Item` row that does **not** caption a focusable control. Renders a `<p>` (not a `<label>`) with the same typography as `Field.Label`, so a read-only row composes cleanly alongside real form fields without misrepresenting itself as a control caption.

#### When to use

- A `Field.Item` row that displays a derived or system-managed value — owner, created-at, computed status, an identity card — where there is no `<input>`, `<select>`, `<button>`, or other focusable target to caption.
- Read-only summary rows inside a sheet or details panel that should visually align with sibling `Field.Item`s but have no editable control.
- Anywhere you'd otherwise hand-roll a `<p>` styled to mimic `Field.Label` typography. Use `Field.LabelText` so the intent is explicit at the call site.

#### When *not* to use

- The row has a focusable control. Use `Field.Label` so the `htmlFor` ↔ control association, click-to-focus, and accessible name are wired automatically.
- For body copy, section headings, or any text whose typography only happens to match by accident. Reach for a heading or a plain `<p>` instead — `Field.LabelText` exists specifically to slot into the `Field.Label` position of a `Field.Item`.

```tsx
<Field.Item name="owner">
	<Field.LabelText>Owner</Field.LabelText>
	<CredentialOwnerCard owner={owner} />
	<Field.Description>The user or service user that owns this API key.</Field.Description>
</Field.Item>
```

All props from [p](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p#attributes), plus:

### Field.Item

A single form field. Renders a plain `<div>` with `flex flex-col gap-1.5` so `Field.Label`, control, and helper / error siblings stack tightly together. No implicit ARIA role — the `<label htmlFor>` ↔ control association already provides the right semantics for a single field. Provides description/error IDs and validation state to `Field.Control`; rendered errors infer `"error"` unless `validation` is provided.

**Single-slot constraint.** A `Field.Item` owns one description ID and one errors ID, so render at most one `Field.Description` and one `Field.Errors` *or* `Field.ErrorList` (not both) per item. A second instance would duplicate the slot `id` in the DOM — pass multiple messages to one `Field.Errors`, or multiple `Field.ErrorItem` children to one `Field.ErrorList`, instead.

**When to use:** for every individual field — text inputs, selects, single checkboxes, switches, password inputs, etc.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop          | Type                                         | Default | Description                                                                                                                                                                              |
| ------------- | -------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | `string`                                     | —       | Form field name. Splats onto the focusable child rendered inside `Field.Control`; `Field.Item` also owns the generated id used by `Field.Control` and `Field.Label`'s default `htmlFor`. |
| `asChild?`    | `boolean`                                    | `false` | Render as a different element by passing a child.                                                                                                                                        |
| `validation?` | `"error" \| "success" \| "warning" \| false` | —       | Override the validation state inherited by `Field.Control`.                                                                                                                              |

### Field.Control

Applies `Field.Item` description, error, identity, and validation state to a single control. It always behaves like an `asChild` slot: pass one child element to receive the generated props, or use a function child to place those props manually. Mantle compound controls that consume `FieldControlContext` can be wrapped at the root when their docs show that composition; otherwise use the render-prop form to place the generated props on the actual focusable element. Override validation on the surrounding `Field.Item`.

```tsx
<Field.Item name="email">
	<Field.Label>Email</Field.Label>
	<Field.Control>
		<Input />
	</Field.Control>
</Field.Item>

<Field.Item name="plan">
	<Field.Label>Plan</Field.Label>
	<Select.Root>
		<Field.Control>
			<Select.Trigger>
				<Select.Value placeholder="Select a plan" />
			</Select.Trigger>
		</Field.Control>
		<Select.Content>{/* ... */}</Select.Content>
	</Select.Root>
</Field.Item>
```

Use a function child when the focusable element is nested inside a wrapper that `Slot` cannot reach — for example a `<label>`-wrapped native checkbox where the `<input>` is the focusable target but the outer `<label>` is the rendered element. The function receives the generated ARIA props and the caller spreads them onto the inner control.

```tsx
<Field.Item name="termsAccepted">
	<Field.Control>
		{(controlProps) => (
			<label className="flex items-center gap-2">
				<input type="checkbox" {...controlProps} />
				Accept the terms of service
			</label>
		)}
	</Field.Control>
	<Field.Errors messages={["You must accept the terms to continue."]} />
</Field.Item>
```

| Prop          | Type                                         | Default | Description                                    |
| ------------- | -------------------------------------------- | ------- | ---------------------------------------------- |
| `validation?` | `"error" \| "success" \| "warning" \| false` | —       | Override validation inherited from Field.Item. |

### Field.Group

Layout container that stacks multiple `Field.Item`s vertically with `gap-4`. Renders a plain `<div>` — pure layout, no semantics.

**When to use:** any time a form has more than one field. This is the default way to compose multiple `Field.Item`s. Reach for `Field.Set` + `Field.Legend` instead only when the grouping itself carries semantic weight (radios, related checkboxes).

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

### Field.Set

Renders a semantic `<fieldset>` with default browser styling reset (no border, no padding, `min-width: 0`). Pair with `Field.Legend` to give the surrounding controls a single accessible name.

**When to use:** specifically for radios (one question, many possible answers) or sets of related checkboxes (preference toggles, permission flags). *Skip it* for stacking unrelated fields — `Field.Group` is the right call there. A `<fieldset>` around plain inputs reads as noise to assistive tech.

`Field.Set` does not automatically associate `Field.Description`. If the group needs additional announced instructions beyond the legend, pass `aria-describedby` to `Field.Set` and point it at your own text element.

All props from [fieldset](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset#attributes).

### Field.Legend

Caption for a `Field.Set`. Renders a `<legend>` styled to match the mantle `Label` typography. Always render a `Field.Legend` inside a `Field.Set` — it's what gives the surrounding fieldset its accessible name.

Carries a default `mb-1.5` so the legend sits 6px above the next sibling. The margin is on the legend (not the parent `Field.Set`'s flex `gap`) because `<legend>` has special browser rendering inside a `<fieldset>` that ignores the parent's flex `gap`. Override with any `mb-*` utility passed on `Field.Legend`.

All props from [legend](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/legend#attributes).

### Field.LabelRow

Horizontal layout container for the label area of a field — a flex row with `items-center` and `gap-1`. Use when the label needs a sibling affordance that can't live inside the `<Field.Label>` itself, like a help-icon `Field.HelpTrigger`. Center-aligned (not baseline) so SVG icon buttons sit visually centered next to the label text.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

### Field.Help

`Popover.Root` wrapper for the help-affordance pattern. Composes with `Field.HelpTrigger` and `Field.HelpContent`. Forwards all `Popover.Root` props (`open`, `defaultOpen`, `onOpenChange`, `modal`, etc.).

### Field.HelpTrigger

`Popover.Trigger` wired to a ghost-appearance `IconButton` with a default Phosphor `QuestionIcon`. Requires a contextual accessible `label`. Pre-styled with `text-body` so the icon reads as subtle metadata at rest; `IconButton`'s ghost `hover:text-strong` brightens it on interaction. Carries a default `-my-0.5` so the 24px `xs` button keeps a full click target while contributing only 20px to the `Field.LabelRow` flex line — matching the label's text line-height so the label is not pushed off-center.

Accepts every `IconButton` prop, with sensible visual defaults. `label` remains required:

| Prop          | Type                       | Default            | Description                                                          |
| ------------- | -------------------------- | ------------------ | -------------------------------------------------------------------- |
| `icon?`       | `ReactNode`                | `<QuestionIcon />` | Icon rendered inside the trigger button. Override to swap the glyph. |
| `label`       | `string`                   | —                  | Contextual visually-hidden label announced by screen readers.        |
| `appearance?` | `"ghost"` \| `"outlined"`  | `"ghost"`          | `IconButton` appearance variant.                                     |
| `size?`       | `"xs"` \| `"sm"` \| `"md"` | `"xs"`             | `IconButton` size.                                                   |
| `className?`  | `string`                   | —                  | Merged onto the underlying `IconButton`.                             |

### Field.HelpContent

Body of a `Field.Help` popover. Forwards every `Popover.Content` prop — see the [Popover docs](/components/popover#popovercontent) for the full surface (`side`, `align`, `preferredWidth`, etc.).

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

### Field.Optional

Inline "(Optional)" suffix to mark a field as optional. Renders a `<span>` in `text-muted` at `text-sm` / `font-normal`. Default content is the literal string "(Optional)" — pass children to translate or replace.

All props from [span](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span#attributes), plus:

### Field.Description

Helper / hint text. Renders a `<p>` in the muted body color. Use inside `Field.Item`, below the control, to clarify expected format or constraints for that single field. Render at most one per `Field.Item` — `Field.Item` owns a single description slot ID and applies it via context.

When rendered inside `Field.Item`, `Field.Description` receives an automatic generated ID that `Field.Control` merges into the control's `aria-describedby`. The ID is owned by `Field.Item` and is not consumer-overridable. When `Field.Description` is rendered immediately after `Field.Errors` or `Field.ErrorList`, it automatically collapses the parent's `gap-1.5` via a `-mt-1.5` so errors + helper read as a single tight block. The rule's specificity is flattened to `(0,1,0)` so any margin utility you pass on `Field.Description` (e.g. `mt-1`, `mt-0`) overrides cleanly.

All props from [p](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p#attributes) except `id`, plus:

### Field.Errors

Convenience renderer for validation messages. Accepts an array of strings, trims each message, filters empty, nullish, and false values, then renders a `Field.ErrorList` with one `Field.ErrorItem` per remaining message. When rendered inside `Field.Item`, a non-empty list receives an automatic generated ID and infers `"error"` validation unless `Field.Item` overrides it. `Field.Control` merges that ID into the control's `aria-describedby` and `aria-errormessage` when the field is invalid. The ID is owned by `Field.Item` and is not consumer-overridable.

Render at most one `Field.Errors` per `Field.Item`, and do not combine it with `Field.ErrorList` in the same item — both render a single shared errors slot. Pass multiple messages to one `Field.Errors` for the multi-error case.

`Field.Errors` owns its generated list items and does not accept `children` or `asChild`. Use `Field.ErrorList` / `Field.ErrorItem` directly when you need custom list contents or polymorphic list markup.

All props from [ul](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul#attributes) except `children` and `id`, plus:

| Prop        | Type                                       | Default | Description                                     |
| ----------- | ------------------------------------------ | ------- | ----------------------------------------------- |
| `messages?` | `(string \| null \| undefined \| false)[]` | `[]`    | Messages to trim, filter, and render as errors. |

### Field.ErrorItem

A single error message for a field. Renders an `<li>` in `text-danger-600`, so it must be nested inside a `Field.ErrorList`. Empty or blank children render nothing. A single error is just a list of one.

All props from [li](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li#attributes).

### Field.ErrorList

Wraps one or more `Field.ErrorItem` children in a semantic `<ul>` with `role="list"` so a list of validation errors is announced as a list by screen readers, including Safari/VoiceOver combinations that drop list semantics when list styling is removed. Renders nothing when given no renderable children. When rendered inside `Field.Item`, a non-empty list receives an automatic generated ID and infers `"error"` validation unless `Field.Item` overrides it. `Field.Control` merges that ID into the control's `aria-describedby` and `aria-errormessage` when the field is invalid. The ID is owned by `Field.Item` and is not consumer-overridable.

Render at most one `Field.ErrorList` per `Field.Item`, and do not combine it with `Field.Errors` in the same item — both render a single shared errors slot. Put multiple `Field.ErrorItem` children inside one list for the multi-error case.

Strips the default browser `<ul>` styling (no bullets, no padding, no margin) and stacks items as a flex column with no gap so consecutive errors read as a single tight block. Pass `asChild` with an `<ol>` if the list is meaningfully ordered.

All props from [ul](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul#attributes) except `id`, plus:

### toErrorMessages

Normalize a TanStack React Form field's `meta.errors` array (or any mixed array of `string` / `{ message }` / nullish / `false` entries) into a clean `string[]` ready to pass to `Field.Errors`. Trims whitespace, drops empty / whitespace-only entries, and removes duplicates so callers don't have to filter again.

Use this for [TanStack Form](https://tanstack.com/form) with Zod, Standard Schema, or thrown `Error` validators — `field.state.meta.errors` is a union of all of those shapes, and this helper folds them down to plain strings without coupling Mantle to a specific form library. For other validators where the error shape is already a `string[]`, skip the helper and pass the array directly.

```tsx
import { Field, toErrorMessages } from "@ngrok/mantle/field";

<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />;
```

| Argument | Type                                         | Description                                                    |
| -------- | -------------------------------------------- | -------------------------------------------------------------- |
| `errors` | `readonly FieldError[] \| null \| undefined` | Mixed array of validator outputs. `null` / `undefined` → `[]`. |

Returns `string[]`. `FieldError` is `{ message?: string } \| string \| null \| undefined \| false`.

---

---
title: Flag
description: Displays a flag as an svg based on the provided country code.
---

# Flag

Renders a country flag from an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code, served as an SVG from ngrok's CDN.

## When to use

- Showing the country associated with a region, IP, billing address, or locale.
- Inside a select option, list row, or status pill that needs a quick visual cue.

## When not to use

- As a stand-in for language. Flags are not languages — Brazilian Portuguese is not "Portugal", Spanish is not just "Spain". Use a language label instead.
- As decoration where the country isn't meaningful to the user.

## Sizing

`"s"` (16×12), `"m"` (20×15), and `"l"` (32×24, default) match common inline, list, and table contexts. Pick the size that matches its neighbors so the flag doesn't dominate or disappear.

## Accessibility

The underlying `<img>` is given `alt="flag for {code}"`. If the country is decorative or already labeled in adjacent text, consider passing `aria-hidden` via the wrapper `<div>` to avoid duplicate announcements.

## Loading

Defaults to `loading="lazy"`. Use `loading="eager"` for flags above the fold or in critical content.

```tsx
import { Flag } from "@ngrok/mantle/flag";

<Flag code="US" />
<Flag code="JP" loading="lazy" />
<Flag code="ES" loading="eager" />
```

## API Reference

The `Flag` accepts the following props in addition to the [standard HTML div attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes).

| Prop      | Type                    | Default  | Description                                                                                                                                                                                                              |
| --------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `code`    | `string`                |          | The country code of the flag to render.                                                                                                                                                                                  |
| `size`    | `"s"` \| `"m"` \| `"l"` | `"l"`    | The size of the flag to render. The default size is large.                                                                                                                                                               |
| `loading` | `"eager"` \| `"lazy"`   | `"lazy"` | A string providing a hint to the user agent as to how to best schedule the loading of the image to optimize page performance. [See MDN docs.](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/loading) |

---

---
title: Hover Card
description: For sighted users to preview content available behind a link.
---

# Hover Card

For sighted users to preview content available behind a link.

## When to use

A `HoverCard` shows a preview of richer content (a user card, link preview, etc.) when a sighted user hovers a link or trigger.

- Prefer [`Tooltip`](/components/tooltip) for short, non-interactive labels on controls.
- Prefer [`Popover`](/components/popover) when the content must be reachable by all users and may contain interactive elements.

> \[!WARNING]
> Do not rely on a `HoverCard` as the only accessible path to important content. Because it opens on pointer hover, it is not a reliable path for keyboard or screen reader users. Any information inside a `HoverCard` must also be available through another fully accessible path (usually the underlying link).

```tsx
import { Button } from "@ngrok/mantle/button";
import { HoverCard } from "@ngrok/mantle/hover-card";
import { Icon } from "@ngrok/mantle/icon";
import { CalendarIcon } from "@phosphor-icons/react/Calendar";
import { ShrimpIcon } from "@phosphor-icons/react/Shrimp";

<HoverCard.Root>
	<HoverCard.Trigger asChild>
		<Button type="button" appearance="link">
			Open Hover Card
		</Button>
	</HoverCard.Trigger>
	<HoverCard.Content className="w-80">
		<div className="flex justify-between space-x-4">
			<div className="flex size-16 shrink-0 items-center justify-center rounded-full bg-pink-300">
				<Icon svg={<ShrimpIcon />} className="size-12" />
			</div>
			<div className="space-y-1">
				<h4 className="text-sm font-medium">@ngrok/mantle</h4>
				<p className="text-sm">The Design System – created and maintained by @ngrok.</p>
				<div className="flex items-center pt-2">
					<Icon svg={<CalendarIcon />} className="mr-2 h-4 w-4 opacity-70" />{" "}
					<span className="text-muted-foreground text-xs">Joined November 2023</span>
				</div>
			</div>
		</div>
	</HoverCard.Content>
</HoverCard.Root>;
```

## Composition

Compose the parts of a `HoverCard` together to build your own:

```text showLineNumbers=false
HoverCard.Root
├── HoverCard.Trigger
└── HoverCard.Content
```

## API Reference

The `HoverCard` component is built on top of [Radix UI Hover Card](https://www.radix-ui.com/primitives/docs/components/hover-card).

### HoverCard.Root

The root stateful component that manages the open/closed state of the hover card.

| Prop           | Type                      | Default | Description                                                                                                         |
| -------------- | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `open`         | `boolean`                 |         | The controlled open state of the hover card. Must be used in conjunction with `onOpenChange`.                       |
| `onOpenChange` | `(open: boolean) => void` |         | Event handler called when the open state of the hover card changes.                                                 |
| `defaultOpen`  | `boolean`                 | `false` | The open state of the hover card when it is initially rendered. Use when you do not need to control its open state. |
| `openDelay`    | `number`                  | `100`   | The duration in milliseconds from when the mouse enters the trigger until the hover card opens.                     |
| `closeDelay`   | `number`                  | `300`   | The duration in milliseconds from when the mouse leaves the trigger or content until the hover card closes.         |

### HoverCard.Trigger

The trigger element that opens the hover card when hovered.

| Prop      | Type      | Default | Description                                                                          |
| --------- | --------- | ------- | ------------------------------------------------------------------------------------ |
| `asChild` | `boolean` | `false` | Use the `asChild` prop to compose the trigger functionality onto your own component. |

### HoverCard.Content

The content to render inside the hover card. Appears in a portal with rich styling and animations.

| Prop                | Type                                           | Default     | Description                                                                                                                             |
| ------------------- | ---------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `side`              | `"top"` \| `"right"` \| `"bottom"` \| `"left"` | `"bottom"`  | The preferred side of the trigger to render against when open. Will be reversed when collisions occur and `avoidCollisions` is enabled. |
| `align`             | `"start"` \| `"center"` \| `"end"`             | `"center"`  | The preferred alignment against the trigger. May change when collisions occur.                                                          |
| `sideOffset`        | `number`                                       | `4`         | The distance in pixels from the trigger.                                                                                                |
| `alignOffset`       | `number`                                       | `0`         | An offset in pixels from the `start` or `end` alignment options.                                                                        |
| `avoidCollisions`   | `boolean`                                      | `true`      | When `true`, overrides the `side` and `align` preferences to prevent collisions with boundary edges.                                    |
| `collisionBoundary` | `Element \| null \| Array<Element \| null>`    | `[]`        | The element used as the collision boundary. By default this is the viewport.                                                            |
| `collisionPadding`  | `number \| Partial<Record<Side, number>>`      | `0`         | The distance in pixels from the boundary edges where collision detection should occur.                                                  |
| `sticky`            | `"partial"` \| `"always"`                      | `"partial"` | The sticky behavior on the align axis.                                                                                                  |
| `hideWhenDetached`  | `boolean`                                      | `false`     | Whether to hide the content when the trigger becomes fully occluded.                                                                    |

---

---
title: Icon
description: Decorates an svg icon with automatic sizing. Useful when applying base styles to phosphor icons.
---

# Icon

Decorates an svg icon with automatic sizing. Useful when applying base styles to [phosphor icons](https://phosphoricons.com).

```tsx
import { Icon } from "@ngrok/mantle/icon";
import { FireIcon } from "@phosphor-icons/react/Fire";

<Icon svg={<FireIcon />} />
<Icon className="text-danger-600" svg={<FireIcon weight="fill" />} />
```

## Examples

### Merging `className`s

The `Icon` merges `className` selectors with the following order of precedence (last one wins):

1. SvgOnly base classes (only `"shrink-0"`)
2. Icon base classes
3. Icon className
4. svg className

```tsx
import { Icon } from "@ngrok/mantle/icon";
import { FireIcon } from "@phosphor-icons/react/Fire";

<Icon svg={<FireIcon />} />
<Icon svg={<FireIcon className="size-12 sm:size-16" />} />
<Icon className="size-20 sm:size-28" svg={<FireIcon />} />
<Icon className="size-20 sm:size-28" svg={<FireIcon className="size-12 sm:size-16" />} />
```

## API Reference

The `Icon` accepts the following props:

| Prop        | Type                  | Default | Description                                                                                                                     |
| ----------- | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `className` | `string`              |         | Specifies the element's CSS class name. See [the MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/Element/className). |
| `style`     | `React.CSSProperties` |         | An object with CSS styles. See [the MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style).              |
| `svg`       | `ReactNode`           |         | A single SVG icon passed as a JSX tag.                                                                                          |

---

---
title: Icon Button
description: Initiates an action, such as completing a task or submitting information. Renders only a single icon as children with an accessible, screen-reader-only label.
---

# Icon Button

Initiates an action, such as completing a task or submitting information. Renders only a single icon as children with an accessible, screen-reader-only label.

```tsx
import { IconButton } from "@ngrok/mantle/button";
import { GlobeIcon } from "@phosphor-icons/react/Globe";

<IconButton appearance="ghost" label="prestige worldwide" size="md" icon={<GlobeIcon />} />
<IconButton appearance="outlined" label="prestige worldwide" size="md" icon={<GlobeIcon />} />
```

## Type

Like [`Button`](/components/button#type), `IconButton` defaults to **`type="button"`** rather than the native `submit`, so it never accidentally submits a surrounding `<form>`. Opt in with `type="submit"` (or `type="reset"`) when the button should submit or reset a form. When `asChild` is used, `type` has no effect and is not forwarded to the child.

## isLoading

`isLoading` determines whether or not the icon button is in a loading state, default `false`. Setting `isLoading` will replace the icon with a spinner. It will also disable user interaction with the button and set `aria-disabled`.

```tsx
import { IconButton } from "@ngrok/mantle/button";
import { GlobeIcon } from "@phosphor-icons/react/Globe";

<IconButton appearance="ghost" label="prestige worldwide" isLoading icon={<GlobeIcon />} />
<IconButton appearance="outlined" label="prestige worldwide" isLoading icon={<GlobeIcon />} />
```

## Polymorphism

When you want to render *something else* as an `IconButton`, you can use the `asChild` prop to compose. This is useful when you want to splat the `IconButton` styling onto a `react-router` `Link`. Keep in mind that when you use `asChild` the `type` prop will **NOT** be passed to the child component.

```tsx
import { IconButton } from "@ngrok/mantle/button";
import { GlobeIcon } from "@phosphor-icons/react/Globe";
import { Link, href } from "react-router";

<IconButton appearance="outlined" asChild label="prestige worldwide" icon={<GlobeIcon />}>
	<Link to={href("/base/colors")} />
</IconButton>;
```

## API Reference

The `IconButton` accepts the following props in addition to the [standard HTML button attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button).

| Prop         | Type                                  | Default      | Description                                                                                                                                                                                                                                                     |
| ------------ | ------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appearance` | `"ghost"` \| `"outlined"`             | `"outlined"` | Defines the visual style of the `IconButton`.                                                                                                                                                                                                                   |
| `asChild`    | `boolean`                             | `false`      | Use the `asChild` prop to compose the `IconButton` styling and functionality onto alternative element types or your own React components.                                                                                                                       |
| `icon`       | `ReactNode`                           |              | The icon to render inside the button. When `isLoading` is `true`, the icon is automatically replaced with a spinner.                                                                                                                                            |
| `isLoading`  | `boolean`                             | `false`      | Determines whether or not the icon button is in a loading state. Setting `isLoading` will replace the icon with a spinner. It will also disable user interaction with the button and set `aria-disabled`.                                                       |
| `label`      | `string`                              |              | The accessible label for the icon. This label will be visually hidden but announced to screen reader users, similar to alt text for img tags.                                                                                                                   |
| `size`       | `"xs"` \| `"sm"` \| `"md"`            | `"md"`       | The size of the `IconButton`.                                                                                                                                                                                                                                   |
| `type`       | `"button"` \| `"reset"` \| `"submit"` | `"button"`   | The behavior of the `IconButton` when activated. Defaults to `"button"`, so an `IconButton` inside a `<form>` will **not** submit it — pass `type="submit"` to submit the form. When `asChild` is used, `type` has no effect and is not forwarded to the child. |

---

---
title: Icons
description: Custom icons used throughout ngrok UI.
---

# Icons

A list of custom icons that are used throughout ngrok UI.

```tsx
import {
	SortIcon,
	TrafficPolicyFileIcon,
	AutoThemeIcon,
	ThemeIcon,
	NgrokIcon,
} from "@ngrok/mantle/icons";
```

## API Reference

All custom icons are exported from `@ngrok/mantle/icons`.

### SortIcon

A sort direction indicator icon with different modes and directions.

### TrafficPolicyFileIcon

The ngrok traffic policy file icon.

### AutoThemeIcon

An icon that automatically adapts to the current applied theme.

### ThemeIcon

An icon for a specific theme.

### NgrokIcon

The ngrok logo icon.

## Icon Reference

This table is intentionally duplicated in plain markdown so readers (and AI agents) consuming the raw `.mdx` source can get full icon context without JSX rendering.

---

---
title: Input
description: Fundamental component for inputs.
---

# Input

Fundamental component for inputs.

Pair with `Field.*` for label/description/error wiring in forms:

```tsx
import { Field } from "@ngrok/mantle/field";
import { Input } from "@ngrok/mantle/input";

<Field.Item className="max-w-80" name="username">
	<Field.Label>Username</Field.Label>
	<Field.Control>
		<Input placeholder="Enter a username" />
	</Field.Control>
</Field.Item>
<Field.Item className="max-w-80" name="email">
	<Field.Label>Email</Field.Label>
	<Field.Control>
		<Input placeholder="Enter your email" autoComplete="email" />
	</Field.Control>
</Field.Item>

<Field.Item name="error">
	<Field.Label>Error</Field.Label>
	<Field.Control>
		<Input validation="error" />
	</Field.Control>
</Field.Item>
<Field.Item name="success">
	<Field.Label>Success</Field.Label>
	<Field.Control>
		<Input validation="success" />
	</Field.Control>
</Field.Item>
<Field.Item name="warning">
	<Field.Label>Warning</Field.Label>
	<Field.Control>
		<Input validation="warning" />
	</Field.Control>
</Field.Item>
```

Or render the control on its own:

```tsx
import { Input } from "@ngrok/mantle/input";

<Input placeholder="Enter a username" />;
```

## Examples

### With TanStack Form

Use `@tanstack/react-form` with `zod` when the input needs controlled value, blur, submit, and validation state. `Field.Item` owns the field name and `Field.Errors` renders normalized validator messages.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Field, toErrorMessages } from "@ngrok/mantle/field";
import { Input } from "@ngrok/mantle/input";
import { useForm } from "@tanstack/react-form";
import { z } from "zod";

export const formSchema = z.object({
	email: z.string().email("Enter a valid email address."),
});
function Example() {
	const defaultValues = {
		email: "",
	};
	const form = useForm({
		defaultValues,
		validators: {
			onSubmit: formSchema,
		},
		onSubmit: ({ value }) => {
			// Handle form submission here
		},
	});

return (
		<form
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<form.Field name="email">
				{(field) => (
					<Field.Item name={field.name}>
						<Field.Label>Email</Field.Label>
						<Field.Control>
							<Input
								type="email"
								value={field.state.value}
								onBlur={field.handleBlur}
								onChange={(event) => field.handleChange(event.target.value)}
							/>
						</Field.Control>
						<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
					</Field.Item>
				)}
			</form.Field>
			<Button type="submit" appearance="filled" priority="neutral">
				Submit
			</Button>
		</form>
	);
}
```

## Child Elements

You can compose additional visual or functional elements within the `Input` using `children`. The examples below show you how to render start and end icons or buttons. The [Password Input](/components/password-input) is built using this API under the hood! Keep in mind that you will need to manually pass the `InputCapture` component as children too because it is responsible for rendering the actual form `input` element! We provide an `InputCapture` component for you when you don't use the `children` API.

Note: when composing with interactive content (e.g. a `button`), you will need to consider whether or not that element should be tab-indexable or receive focus!

```tsx
import { Field } from "@ngrok/mantle/field";
import { Input, InputCapture } from "@ngrok/mantle/input";
import { InfoIcon } from "@phosphor-icons/react/Info";
import { MagnifyingGlassIcon } from "@phosphor-icons/react/MagnifyingGlass";

<Field.Item className="max-w-80" name="search-start">
	<Field.Label>Search with start icon</Field.Label>
	<Field.Control>
		<Input className="max-w-64" placeholder="Search...">
			<MagnifyingGlassIcon />
			<InputCapture />
		</Input>
	</Field.Control>
</Field.Item>
<Field.Item className="max-w-80" name="search-end">
	<Field.Label>Search with end icon</Field.Label>
	<Field.Control>
		<Input className="max-w-64" placeholder="Search...">
			<InputCapture />
			<InfoIcon />
		</Input>
	</Field.Control>
</Field.Item>
<Field.Item className="max-w-80" name="search-both">
	<Field.Label>Search with start and end icons</Field.Label>
	<Field.Control>
		<Input className="max-w-64" placeholder="Search...">
			<MagnifyingGlassIcon />
			<InputCapture />
			<InfoIcon />
		</Input>
	</Field.Control>
</Field.Item>
```

## When to use InputCapture

For 90% of cases — a simple input with optional icons or validation — pass children directly to `<Input>` (or omit children entirely). The `Input` renders an `InputCapture` for you internally, so you do not need to import or render it yourself.

`InputCapture` is the actual `<input>` element wrapper. Reach for it only when composing custom adornments — for example, a left-side prefix and a right-side suffix where the existing `Input` slots don't fit. When you supply your own `children`, you must include `<InputCapture />` so the form `input` element is still rendered. The [Password Input](/components/password-input) is built using this API under the hood.

## API Reference

The `Input` accepts the following props in addition to the [standard HTML input attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).

| Prop         | Type                                                                                                     | Default | Description                                                                                                                                                                                                                                                                                                             |
| ------------ | -------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `validation` | `"error"` \| `"success"` \| `"warning"` \| `false` \| `() => "error" \| "success" \| "warning" \| false` |         | Use the `validation` prop to show if the input has a specific validation status. This will change the border and outline of the input. The `false` type is useful when using short-circuiting logic so that you don't need to use a ternary with `undefined`. Setting `validation` to `error` also sets `aria-invalid`. |

---

---
title: Kbd
description: A square, centered keyboard "key" chip for rendering keyboard shortcut hints.
---

# Kbd

A square, centered keyboard "key" chip for rendering shortcut hints — `K`, `⌘`, `⌃`, `Enter`. Renders a native `<kbd>` element so screen readers announce it as keyboard input. Sized so letters and modifier symbols share a consistent visual height, width, and baseline.

## When to use

- Documenting keyboard shortcuts in copy or tooltips.
- Inside menu items and command palettes alongside the action label.
- Inline with prose: "Press  to open search."

## When not to use

- For arbitrary monospace text — use [`Code`](/components/code).
- For chord-style multi-key shortcuts as a single chip — render multiple `<Kbd>` elements separated by `+` text instead.

```tsx
import { Kbd } from "@ngrok/mantle/kbd";

<div className="flex items-center gap-2">
	<Kbd>K</Kbd>
	<Kbd>⌘</Kbd>
	<Kbd>⌃</Kbd>
	<Kbd>⇧</Kbd>
	<Kbd>⌥</Kbd>
</div>;
```

## Keyboard Shortcuts

Combine multiple `Kbd` components to display keyboard shortcuts.

```tsx
import { Kbd } from "@ngrok/mantle/kbd";

<div className="flex items-center gap-2">
	<Kbd>⌘</Kbd>
	<span>+</span>
	<Kbd>K</Kbd>
</div>;
```

## Accessibility

Symbol-only glyphs (`⌘`, `⌃`, `↵`) are not announced meaningfully by screen readers. Provide an accessible name via `aria-label` on the `<Kbd>` or include a visually-hidden label inside, and mark the visible glyph `aria-hidden`.

```tsx
import { Kbd } from "@ngrok/mantle/kbd";

<div className="flex items-center gap-2">
	<Kbd aria-label="Command">⌘</Kbd>
	<span>+</span>
	<Kbd>K</Kbd>
</div>;
```

## API Reference

### Kbd

The `Kbd` accepts the following props in addition to the [standard HTML kbd attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd).

---

---
title: Label
description: A Label represents a caption for an item in a user interface. Renders an accessible label associated with controls.
---

# Label

A caption for a form control — input, checkbox, radio, switch, select. Renders a native `<label>`. Pair every form control with a `Label` so the control has an accessible name, clicks on the label focus the control, and screen readers announce the field correctly.

## When to use

- Every visible form control. Always.
- Above or beside an input to describe it ("Email", "API key").
- Wrapping a checkbox or radio next to its descriptive text.

## When not to use

- For static UI text that isn't labeling a control — use a heading or plain `<p>`/`<span>`.
- As a substitute for `aria-label` on non-`<input>` widgets that don't support `<label for>` association.

## Two ways to associate

Either wrap the control inside the `<Label>` (implicit association — simplest) or set `htmlFor` to the control's `id` (explicit — required when the control isn't a child).

For the explicit form, React's [`useId()`](https://react.dev/reference/react/useId) is the easiest way to generate a unique, SSR-stable id without hand-managing strings:

```tsx
import { useId } from "react";

function EmailField() {
	const id = useId();
	return (
		<div className="flex flex-col gap-1.5">
			<Label htmlFor={id}>Email</Label>
			<Input id={id} type="email" />
		</div>
	);
}
```

When you're using [TanStack Form](https://tanstack.com/form), `field.name` is already a stable, unique string for each field — pass it as both `htmlFor` on the `Label` and `id` on the input. You get a guaranteed-correct association for free without calling `useId()` separately:

```tsx
<form.Field name="email">
	{(field) => (
		<div className="flex flex-col gap-1.5">
			<Label htmlFor={field.name}>Email</Label>
			<Input
				id={field.name}
				name={field.name}
				type="email"
				value={field.state.value}
				onBlur={field.handleBlur}
				onChange={(event) => field.handleChange(event.target.value)}
			/>
		</div>
	)}
</form.Field>
```

## Font weight

A `Label` automatically gets `font-medium` when it doesn't contain a nested form control (`<input>`, `<textarea>`, `<select>`, `<button>`, or `[contenteditable]`). The default is detected via `:has()` and applied through a `:where()`-wrapped variant so its specificity is `0` — any font-weight utility you pass on the `Label` itself overrides cleanly:

```tsx
<div className="flex flex-col gap-1.5">
	<Label htmlFor="email">Email</Label>          {/* → font-medium */}
	<Input id="email" type="email" />
</div>

<div className="flex flex-col gap-1.5">
	<Label htmlFor="email" className="font-bold">Email</Label>  {/* → font-bold */}
	<Input id="email" type="email" />
</div>
```

When the `Label` *wraps* a control, the auto-default is skipped on purpose — otherwise the control's own typography would inherit the medium weight from the label. In that case, apply `font-medium` to your own caption element (a `<span>` or `<p>`) inside the label:

```tsx
<Label htmlFor="email" className="flex flex-col gap-1.5">
	<span className="font-medium">Email</span>
	<Input id="email" type="email" />
</Label>
```

## Disabled state

Pass `disabled` to render the label in a disabled style. Typically you'll want this to mirror the underlying control's disabled state so the visual treatment stays consistent.

```tsx
import { Input } from "@ngrok/mantle/input";
import { Label } from "@ngrok/mantle/label";

<div className="flex items-center gap-2">
	<Label htmlFor="name" disabled>Name:</Label>
	<Input id="name" type="text" disabled readOnly value="foo" />
</div>
```

## API Reference

The `Label` accepts the following props in addition to the [standard HTML label attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#attributes).

| Prop       | Type      | Default | Description                                                                 |
| ---------- | --------- | ------- | --------------------------------------------------------------------------- |
| `disabled` | `boolean` | `false` | Use the `disabled` prop to explicitly render the label in a disabled state. |

---

---
title: Main
description: A focusable `<main>` landmark for the page's primary content, designed to be paired with a skip link.
---

# Main

A focusable `<main>` landmark for the page's primary content. Renders with `id="main"` and `tabIndex={-1}` so a skip link (or any programmatic focus call) can send keyboard users directly to the main content without exposing a visible focus ring on the region itself.

Pair with the [`SkipToMainLink`](/components/skip-to-main-link) component at the top of the document.

```tsx
import { Main } from "@ngrok/mantle/main";
import { SkipToMainLink } from "@ngrok/mantle/skip-to-main-link";

<SkipToMainLink />
<Header />
<Main>
	<h1>Page title</h1>
</Main>
```

## API Reference

### Main

Renders a `<main>` element with `id="main"`, `tabIndex={-1}`, and `focus:outline-hidden`. Accepts all standard `<main>` HTML attributes. Additional class names passed via `className` are merged with the defaults.

---

---
title: Media Object
description: The Media Object is an image/icon (media) to the left, with descriptive content (title and subtitle/description) to the right.
---

# Media Object

A small, reusable layout primitive for "image/icon on one side, descriptive content on the other" — the foundational [media object pattern](https://www.stubbornella.org/2010/06/25/the-media-object-saves-hundreds-of-lines-of-code/). Use it to compose avatars-with-text, icons-with-copy, thumbnails-with-titles, and similar two-up rows without re-implementing flexbox each time.

## When to use

- Comment threads (avatar + name + body).
- Compact list items (icon + label + secondary text).
- Notification rows.
- Feature lists, profile cards, attachment previews.

## When not to use

- For complex multi-region layouts — reach for [`Card`](/components/card) or build a bespoke flex/grid.
- When the media is purely decorative and adds no information — drop it and use a plain block.

## Spacing & alignment

Default gap is `gap-4`; override by passing a different `gap-*` class to `MediaObject.Root`. Use standard flex utilities (`items-start`, `items-center`, etc.) to align media and content vertically.

Compose the `<MediaObject>` with the `<MediaObject.Media>` and `<MediaObject.Content>` components as direct children. Each part accepts `asChild` for swapping the rendered element (e.g. render `Root` as an `<a>` to make the whole row clickable).

```tsx
import { MediaObject } from "@ngrok/mantle/media-object";

<MediaObject.Root>
	<MediaObject.Media>
		<ExampleMedia />
	</MediaObject.Media>
	<MediaObject.Content>
		<h4 className="text-lg font-medium">Lorem ipsum</h4>
		<p className="mb-4 mt-1">
			Repudiandae sint consequuntur vel. Amet ut nobis explicabo numquam expedita quia omnis
			voluptatem. Minus quidem ipsam quia iusto.
		</p>
		<p>Ea eiusmod eiusmod aute reprehenderit exercitation eu ea id adipisicing occaecat.</p>
	</MediaObject.Content>
</MediaObject.Root>;
```

## Composition

Compose the parts of a `MediaObject` together to build your own:

```text showLineNumbers=false
MediaObject.Root
├── MediaObject.Media
└── MediaObject.Content
```

## API Reference

### MediaObject.Root

The `MediaObject` is an image/icon (media) to the left, with descriptive content (title and subtitle/description) to the right. Root container for all `MediaObject.Root` sub-components.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop      | Type      | Default | Description                                                                                                                                |
| --------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean` | `false` | Use the `asChild` prop to compose the `MediaObject` styling and functionality onto alternative element types or your own React components. |

### MediaObject.Media

The container for an image or icon to display in the media slot of the `MediaObject`.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop      | Type      | Default | Description                                                                                                                                      |
| --------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asChild` | `boolean` | `false` | Use the `asChild` prop to compose the `MediaObject.Media` styling and functionality onto alternative element types or your own React components. |

### MediaObject.Content

The container for the content slot of a `MediaObject`.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop      | Type      | Default | Description                                                                                                                                        |
| --------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | `false` | Use the `asChild` prop to compose the `MediaObject.Content` styling and functionality onto alternative element types or your own React components. |

---

---
title: Multi Select
description: A typeahead multi-select combobox that allows users to select multiple values with filtering. Selected values are displayed as removable tags.
---

# Multi Select

A typeahead multi-select combobox that allows users to select multiple values with filtering. Selected values are displayed as removable tags. Built on top of [ariakit Combobox](https://ariakit.org/components/combobox) with full keyboard support and [WAI-ARIA Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) compliance.

## When to use

Use `Multi Select` when the user can choose multiple values from a list, with selected values rendered as removable tags/chips. For single selection, use [`Combobox`](/components/combobox) (with search) or [`Select`](/components/select) (without).

Pair with `Field.*` for label/description/error wiring in forms — wrap `MultiSelect.Root` in `Field.Control`. `Field.Control` flows the generated `id`, `name`, `aria-describedby`, `aria-errormessage`, and `aria-invalid` through to the focusable `MultiSelect.Input` via `FieldControlContext`.

```tsx
import { Field } from "@ngrok/mantle/field";
import { MultiSelect } from "@ngrok/mantle/multi-select";

<Field.Item name="fruits">
	<Field.Label>Fruits</Field.Label>
	<Field.Control>
		<MultiSelect.Root>
			<MultiSelect.Trigger>
				<MultiSelect.TagValues />
				<MultiSelect.Input placeholder="Select fruits..." />
			</MultiSelect.Trigger>
			<MultiSelect.Content>
				{fruits.map((value) => (
					<MultiSelect.Item key={value} value={value}>
						{value}
					</MultiSelect.Item>
				))}
			</MultiSelect.Content>
		</MultiSelect.Root>
	</Field.Control>
	<Field.Description>Pick one or more.</Field.Description>
</Field.Item>;
```

Or render the control on its own:

```tsx
import { MultiSelect } from "@ngrok/mantle/multi-select";
import { matchSorter } from "match-sorter";
import { useMemo, useState, useTransition } from "react";

const fruits = [
	"Apple",
	"Banana",
	"Blueberry",
	"Cherry",
	"Grapes",
	"Kiwi",
	"Lemon",
	"Mango",
	"Orange",
	"Peach",
	"Pear",
	"Pineapple",
	"Strawberry",
	"Watermelon",
];

function Example() {
	const [isPending, startTransition] = useTransition();
	const [searchValue, setSearchValue] = useState("");
	const matches = useMemo(() => matchSorter(fruits, searchValue), [searchValue]);

return (
		<MultiSelect.Root
			setOpen={() => {
				setSearchValue("");
			}}
		>
			<MultiSelect.Trigger>
				<MultiSelect.TagValues />
				<MultiSelect.Input
					onValueChange={(value) => startTransition(() => setSearchValue(value))}
					placeholder="Select fruits..."
				/>
			</MultiSelect.Trigger>
			<MultiSelect.Content aria-busy={isPending}>
				{matches.map((value) => (
					<MultiSelect.Item key={value} value={value}>
						{value}
					</MultiSelect.Item>
				))}
				{matches.length === 0 && <MultiSelect.Empty>No results found</MultiSelect.Empty>}
			</MultiSelect.Content>
		</MultiSelect.Root>
	);
}
```

## Examples

### Controlled

Use `selectedValue` and `setSelectedValue` to control the selected values.

```tsx
const [selected, setSelected] = useState(["Apple", "Cherry"]);

<MultiSelect.Root
	selectedValue={selected}
	setOpen={() => {
		setSearchValue("");
	}}
	setSelectedValue={setSelected}
>
	<MultiSelect.Trigger>
		<MultiSelect.TagValues />
		<MultiSelect.Input
			onValueChange={(value) => startTransition(() => setSearchValue(value))}
			placeholder="Select fruits..."
		/>
	</MultiSelect.Trigger>
	<MultiSelect.Content>
		{matches.map((value) => (
			<MultiSelect.Item key={value} value={value}>
				{value}
			</MultiSelect.Item>
		))}
	</MultiSelect.Content>
</MultiSelect.Root>;
```

### In a Sheet

Use `@tanstack/react-form` to manage the selected values when a side panel needs validation and submit handling. `MultiSelect.Content` will automatically scope its portal to the surrounding sheet so the default modal behavior works without extra configuration.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Field, toErrorMessages } from "@ngrok/mantle/field";
import { MultiSelect } from "@ngrok/mantle/multi-select";
import { Sheet } from "@ngrok/mantle/sheet";
import { useForm } from "@tanstack/react-form";
import { matchSorter } from "match-sorter";
import { useId, useMemo, useState, useTransition } from "react";
import { z } from "zod";

const formSchema = z.object({
	favorites: z.string().array().min(1, "Select at least one fruit."),
});

type FormValues = z.infer<typeof formSchema>;

const [isPending, startTransition] = useTransition();
const formId = useId();
const [searchValue, setSearchValue] = useState("");
const defaultValues: FormValues = {
	favorites: ["Cherry"],
};
const form = useForm({
	defaultValues,
	validators: {
		onSubmit: formSchema,
	},
	onSubmit: ({ value }) => {
		window.alert(`Submitted: ${JSON.stringify(value, null, 2)}`);
	},
});

const filteredFruits = useMemo(
	() => matchSorter(["Apple", "Banana", "Cherry", "Grapes", "Orange", "Strawberry"], searchValue),
	[searchValue],
);
const filteredVeggies = useMemo(
	() => matchSorter(["Carrot", "Cucumber", "Lettuce", "Tomato", "Zucchini"], searchValue),
	[searchValue],
);

<Sheet.Root>
	<Sheet.Trigger asChild>
		<Button type="button" appearance="filled" priority="neutral">
			Assign fruits
		</Button>
	</Sheet.Trigger>
	<Sheet.Content preferredWidth="sm:max-w-[560px]">
		<Sheet.Header>
			<Sheet.TitleGroup>
				<Sheet.Title>Assign fruits</Sheet.Title>
				<Sheet.Actions>
					<Sheet.CloseIconButton />
				</Sheet.Actions>
			</Sheet.TitleGroup>
			<Sheet.Description>
				Use TanStack Form to validate and submit a multi-select inside a sheet workflow.
			</Sheet.Description>
		</Sheet.Header>
		<form
			className="contents"
			id={formId}
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<Sheet.Body>
				<form.Field name="favorites">
					{(field) => (
						<Field.Item name={field.name}>
							<Field.Label>Fruits</Field.Label>
							<Field.Control>
								<MultiSelect.Root
									selectedValue={field.state.value}
									setSelectedValue={field.handleChange}
									setOpen={() => {
										setSearchValue("");
									}}
								>
									<MultiSelect.Trigger onBlur={field.handleBlur}>
										<MultiSelect.TagValues />
										<MultiSelect.Input
											onValueChange={(value) => startTransition(() => setSearchValue(value))}
											placeholder="Select fruits and vegetables..."
										/>
									</MultiSelect.Trigger>
									<MultiSelect.Content aria-busy={isPending}>
										{filteredFruits.length > 0 && (
											<MultiSelect.Group>
												<MultiSelect.GroupLabel>Fruits</MultiSelect.GroupLabel>
												{filteredFruits.map((value) => (
													<MultiSelect.Item key={value} value={value}>
														{value}
													</MultiSelect.Item>
												))}
											</MultiSelect.Group>
										)}
										{filteredFruits.length > 0 && filteredVeggies.length > 0 && (
											<MultiSelect.Separator />
										)}
										{filteredVeggies.length > 0 && (
											<MultiSelect.Group>
												<MultiSelect.GroupLabel>Vegetables</MultiSelect.GroupLabel>
												{filteredVeggies.map((value) => (
													<MultiSelect.Item key={value} value={value}>
														{value}
													</MultiSelect.Item>
												))}
											</MultiSelect.Group>
										)}
										{filteredFruits.length === 0 && filteredVeggies.length === 0 && (
											<MultiSelect.Empty>No results found</MultiSelect.Empty>
										)}
									</MultiSelect.Content>
								</MultiSelect.Root>
							</Field.Control>
							<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
						</Field.Item>
					)}
				</form.Field>
			</Sheet.Body>
			<Sheet.Footer>
				<Sheet.Close asChild>
					<Button type="button" appearance="outlined" priority="neutral">
						Cancel
					</Button>
				</Sheet.Close>
				<form.Subscribe selector={(state) => state.isDirty}>
					{(isDirty) => (
						<Button
							type="submit"
							form={formId}
							appearance="filled"
							priority="neutral"
							disabled={!isDirty}
						>
							Save
						</Button>
					)}
				</form.Subscribe>
			</Sheet.Footer>
		</form>
	</Sheet.Content>
</Sheet.Root>;
```

### Locked Values

Use `lockedValues` on `MultiSelect.TagValues` to pin specific tags that cannot be removed. Locked tags display a lock icon instead of an ✕ and shake when the user tries to remove them. Locked values also cannot be deselected by clicking them in the popover.

```tsx
const [selected, setSelected] = useState(["apple", "banana", "cherry"]);

<MultiSelect.Root
	selectedValue={selected}
	setOpen={() => {
		setSearchValue("");
	}}
	setSelectedValue={setSelected}
>
	<MultiSelect.Trigger>
		<MultiSelect.TagValues lockedValues={["apple", "cherry"]} />
		<MultiSelect.Input
			onValueChange={(value) => startTransition(() => setSearchValue(value))}
			placeholder="Select fruits..."
		/>
	</MultiSelect.Trigger>
	<MultiSelect.Content>
		<MultiSelect.Item value="apple">apple</MultiSelect.Item>
		<MultiSelect.Item value="banana">banana</MultiSelect.Item>
		<MultiSelect.Item value="cherry">cherry</MultiSelect.Item>
	</MultiSelect.Content>
</MultiSelect.Root>;
```

### Creatable

Render a dynamic "Create …" item when the search text doesn't match any existing option. When selected, add the new value to both your options list and the selection. No component changes needed — consumers own the items rendered in `Content`.

```tsx
const [selected, setSelected] = useState(["Apple", "Cherry"]);
const [options, setOptions] = useState(fruits);
const matches = useMemo(() => matchSorter(options, searchValue), [options, searchValue]);
const showCreate =
	searchValue.trim() !== "" &&
	!options.some((o) => o.toLowerCase() === searchValue.trim().toLowerCase());

<MultiSelect.Root
	selectedValue={selected}
	setOpen={() => {
		setSearchValue("");
	}}
	setSelectedValue={(values) => {
		setSelected(values);
		startTransition(() => setSearchValue(""));
	}}
>
	<MultiSelect.Trigger>
		<MultiSelect.TagValues />
		<MultiSelect.Input
			onValueChange={(value) => startTransition(() => setSearchValue(value))}
			placeholder="Select or create fruits..."
		/>
	</MultiSelect.Trigger>
	<MultiSelect.Content>
		{matches.map((value) => (
			<MultiSelect.Item key={value} value={value}>
				{value}
			</MultiSelect.Item>
		))}
		{showCreate && (
			<MultiSelect.Item
				value={searchValue.trim()}
				onClick={() => setOptions((prev) => [...prev, searchValue.trim()])}
			>
				Create "{searchValue.trim()}"
			</MultiSelect.Item>
		)}
		{matches.length === 0 && !showCreate && <MultiSelect.Empty>No results found</MultiSelect.Empty>}
	</MultiSelect.Content>
</MultiSelect.Root>;
```

### With Groups

Use `MultiSelect.Group`, `MultiSelect.GroupLabel`, and `MultiSelect.Separator` to organize items.

```tsx
<MultiSelect.Root
	setOpen={() => {
		setSearchValue("");
	}}
>
	<MultiSelect.Trigger>
		<MultiSelect.TagValues />
		<MultiSelect.Input
			onValueChange={(value) => startTransition(() => setSearchValue(value))}
			placeholder="Select items..."
		/>
	</MultiSelect.Trigger>
	<MultiSelect.Content>
		<MultiSelect.Group>
			<MultiSelect.GroupLabel>Fruits</MultiSelect.GroupLabel>
			<MultiSelect.Item value="Apple">Apple</MultiSelect.Item>
			<MultiSelect.Item value="Banana">Banana</MultiSelect.Item>
		</MultiSelect.Group>
		<MultiSelect.Separator />
		<MultiSelect.Group>
			<MultiSelect.GroupLabel>Vegetables</MultiSelect.GroupLabel>
			<MultiSelect.Item value="Carrot">Carrot</MultiSelect.Item>
			<MultiSelect.Item value="Lettuce">Lettuce</MultiSelect.Item>
		</MultiSelect.Group>
	</MultiSelect.Content>
</MultiSelect.Root>
```

### With TanStack Form

Use `@tanstack/react-form` with `zod` to wire selected values into form state. Pass `field.state.value` to `selectedValue` and `field.handleChange` to `setSelectedValue`.

const fruits = ["Apple", "Banana", "Cherry", "Grapes", "Orange", "Strawberry"];

const formSchema = z.object({
	favorites: z.string().array().min(1, "Select at least one fruit."),
});

type FormValues = z.infer<typeof formSchema>;

function Example() {
	const defaultValues: FormValues = {
		favorites: [],
	};
	const form = useForm({
		defaultValues,
		validators: {
			onSubmit: formSchema,
		},
		onSubmit: ({ value }) => {
			// Handle form submission here
		},
	});

return (
		<form
			className="space-y-4"
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<form.Field name="favorites">
				{(field) => (
					<Field.Item name={field.name}>
						<Field.Label>Favorites</Field.Label>
						<Field.Control>
							<MultiSelect.Root
								selectedValue={field.state.value}
								setSelectedValue={field.handleChange}
							>
								<MultiSelect.Trigger onBlur={field.handleBlur}>
									<MultiSelect.TagValues />
									<MultiSelect.Input placeholder="Select fruits..." />
								</MultiSelect.Trigger>
								<MultiSelect.Content>
									{fruits.map((value) => (
										<MultiSelect.Item key={value} value={value}>
											{value}
										</MultiSelect.Item>
									))}
								</MultiSelect.Content>
							</MultiSelect.Root>
						</Field.Control>
						<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
					</Field.Item>
				)}
			</form.Field>
			<Button type="submit" appearance="filled" priority="neutral">
				Submit
			</Button>
		</form>
	);
}
```

### Validation States

Use the `validation` prop on `MultiSelect.Trigger` to show validation states.

```tsx
<MultiSelect.Root>
	<MultiSelect.Trigger validation="error">
		<MultiSelect.TagValues />
		<MultiSelect.Input placeholder="Error state..." />
	</MultiSelect.Trigger>
	<MultiSelect.Content>
		<MultiSelect.Item value="Apple">Apple</MultiSelect.Item>
	</MultiSelect.Content>
</MultiSelect.Root>
```

### Region Pinning

A real-world example with three groups (regional aliases, PoPs, dedicated IPs), disabled items, secondary metadata per item, a stacked item description layout, a trailing link in the trigger, and a sticky footer CTA inside the content.

```tsx
import { Anchor } from "@ngrok/mantle/anchor";
import { Button } from "@ngrok/mantle/button";
import { MultiSelect } from "@ngrok/mantle/multi-select";
import { matchSorter } from "match-sorter";
import { useMemo, useState, useTransition } from "react";

const regionalAliases = [
	{ value: "global", popCount: "All PoPs" },
	{ value: "united-states", popCount: "2 PoPs" },
	{ value: "european-union", popCount: "1 PoP" },
];

const pointsOfPresence = [
	{ value: "sg-sin-1", location: "Asia / Pacific (Singapore)" },
	{ value: "au-syd-1", location: "Australia (Sydney)" },
	{ value: "de-fra-1", location: "European Union (Frankfurt)" },
	{ value: "in-mum-1", location: "India (Mumbai)" },
	{ value: "jp-tokyo-1", location: "Japan (Tokyo)" },
	{ value: "br-sao-1", location: "South America (São Paulo)" },
	{ value: "us-ohio-1", location: "United States (Ohio)" },
	{ value: "us-cal-1", location: "United States (California)" },
];

const dedicatedIPs = [
	{ ip: "52.191.171.57", description: "this is a helpful description that is exceedingly lengthy" },
	{ ip: "40.95.110.217", description: "this is a helpful description" },
	{ ip: "63.243.178.35", description: "" },
];

return (
		<div className="flex w-full max-w-lg flex-col gap-1.5">
			<p className="text-strong text-sm font-medium">Resolves to</p>
			<MultiSelect.Root
				selectedValue={selected}
				setOpen={() => {
					setSearchValue("");
				}}
				setSelectedValue={setSelected}
			>
				<MultiSelect.Trigger>
					<MultiSelect.TagValues />
					<MultiSelect.Input
						onValueChange={(value) => startTransition(() => setSearchValue(value))}
						placeholder="Select regions..."
					/>
					{/* Input is flex-1 so this sibling is pushed to the right */}
					<Anchor className="shrink-0 whitespace-nowrap text-xs" href="#">
						Requires Upgrade
					</Anchor>
				</MultiSelect.Trigger>
				<MultiSelect.Content aria-busy={isPending}>
					{filteredAliases.length > 0 && (
						<MultiSelect.Group>
							<MultiSelect.GroupLabel>Regional Aliases</MultiSelect.GroupLabel>
							<MultiSelect.GroupDescription>
								Include all points of presence that are geographically within the region.
							</MultiSelect.GroupDescription>
							{filteredAliases.map(({ value, popCount }) => (
								<MultiSelect.Item key={value} value={value}>
									<span className="flex min-w-0 flex-1 items-center justify-between gap-2">
										<span className="font-mono">{value}</span>
										<span className="text-muted font-sans text-xs font-normal">{popCount}</span>
									</span>
								</MultiSelect.Item>
							))}
						</MultiSelect.Group>
					)}
					{filteredAliases.length > 0 && filteredPops.length > 0 && <MultiSelect.Separator />}
					{filteredPops.length > 0 && (
						<MultiSelect.Group>
							<MultiSelect.GroupLabel>Points of presence</MultiSelect.GroupLabel>
							<MultiSelect.GroupDescription>
								If you've included a region, you cannot include PoPs that are within it.
							</MultiSelect.GroupDescription>
							{filteredPops.map(({ value, location }) => (
								<MultiSelect.Item key={value} value={value} disabled>
									<span className="flex min-w-0 flex-1 items-center justify-between gap-2">
										<span className="font-mono">{value}</span>
										<span className="text-muted font-sans text-xs font-normal">{location}</span>
									</span>
								</MultiSelect.Item>
							))}
						</MultiSelect.Group>
					)}
					{(filteredAliases.length > 0 || filteredPops.length > 0) &&
						filteredDedicatedIPs.length > 0 && <MultiSelect.Separator />}
					{filteredDedicatedIPs.length > 0 && (
						<MultiSelect.Group>
							<MultiSelect.GroupLabel>Dedicated IPs</MultiSelect.GroupLabel>
							{filteredDedicatedIPs.map(({ ip, description }) => (
								<MultiSelect.Item key={ip} value={ip} disabled>
									<span className="flex min-w-0 flex-1 flex-col">
										<span className="font-mono">{ip}</span>
										{description && (
											<span className="text-muted font-sans text-xs font-normal">
												{description}
											</span>
										)}
									</span>
								</MultiSelect.Item>
							))}
						</MultiSelect.Group>
					)}
					{filteredAliases.length === 0 &&
						filteredPops.length === 0 &&
						filteredDedicatedIPs.length === 0 && (
							<MultiSelect.Empty>No results found</MultiSelect.Empty>
						)}
					<MultiSelect.ContentFooter>
						<div className="flex items-center justify-between gap-3 bg-accent-600/10 px-3 py-3">
							<p className="text-accent-600 text-sm font-medium">
								Upgrade your plan to specify regions, PoPs, and dedicated IPs.
							</p>
							<Button appearance="filled" priority="neutral" className="shrink-0" asChild>
								<Link
									to={{
										pathname: href("/billing/choose-a-plan"),
										search: "?plan=paygo",
									}}
								>
									Upgrade to Pay-as-you-go
								</Link>
							</Button>
						</div>
					</MultiSelect.ContentFooter>
				</MultiSelect.Content>
			</MultiSelect.Root>
		</div>
	);
}
```

## Composition

Compose the parts of a `MultiSelect` together to build your own:

```text showLineNumbers=false
MultiSelect.Root
├── MultiSelect.Trigger
│   ├── MultiSelect.TagValues
│   └── MultiSelect.Input
└── MultiSelect.Content
    ├── MultiSelect.Group
    │   ├── MultiSelect.GroupLabel
    │   ├── MultiSelect.GroupDescription
    │   └── MultiSelect.Item
    ├── MultiSelect.Separator
    ├── MultiSelect.Empty
    └── MultiSelect.ContentFooter
```

## API Reference

The `MultiSelect` components are built on top of [ariakit Combobox](https://ariakit.org/components/combobox).

### MultiSelect.Root

Root component for the multi-select. Provides state management for selecting multiple values with typeahead filtering.

All props from ariakit [ComboboxProvider](https://ariakit.org/reference/combobox-provider) (typed to `string[]` for multi-select), plus:

### MultiSelect.Trigger

The trigger container for the multi-select. Wraps the input and selected value tags in a styled container that looks like a form input.

### MultiSelect.TagValues

Renders the selected values as removable tags. Place this inside `MultiSelect.Trigger`, followed by `MultiSelect.Input`.

| Prop            | Type                                         | Default | Description                                                                                                                                    |
| :-------------- | :------------------------------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `lockedValues?` | `string[]`                                   | `[]`    | Values that cannot be removed. Locked tags show a lock icon, shake on Backspace/Delete, and shake when Backspace is pressed on an empty input. |
| `children?`     | `(props: TagRenderProps) => React.ReactNode` |         | Render function for each tag. Receives `{ value, onRemove, locked, ref }` — spread onto `Tag` for full keyboard-nav support.                   |

`TagRenderProps`:

### MultiSelect.Input

The combobox input for filtering items. Place this inside `MultiSelect.Trigger`, after `MultiSelect.TagValues`.

All props from ariakit [Combobox](https://ariakit.org/reference/combobox). Key props:

### MultiSelect.Tag

The default tag component rendered inside `MultiSelect.TagValues` for each selected value. Displays the value label with a remove button and full keyboard navigation support.

Use this when building a custom `TagValues`-like component and you want the default tag chrome with consistent styling.

Also accepts all standard `span` element props (except `children`). The `onKeyDown` prop is supported and is called after the internal locked-key handling.

### MultiSelect.Content

Renders a popover that contains multi-select content.

All props from ariakit [ComboboxPopover](https://ariakit.org/reference/combobox-popover), plus:

### MultiSelect.Item

Renders a selectable item with a checkbox indicator inside a `MultiSelect.Content`.

All props from ariakit [ComboboxItem](https://ariakit.org/reference/combobox-item), plus:

### MultiSelect.Group

Renders a group for `MultiSelect.Item` elements. Optionally, a `MultiSelect.GroupLabel` can be rendered as a child to provide a label for the group.

All props from ariakit [ComboboxGroup](https://ariakit.org/reference/combobox-group), plus:

### MultiSelect.GroupLabel

Renders a label in a multi-select group. Should be wrapped with `MultiSelect.Group` so the `aria-labelledby` is correctly set on the group element.

All props from ariakit [ComboboxGroupLabel](https://ariakit.org/reference/combobox-group-label), plus:

### MultiSelect.GroupDescription

Renders a descriptive paragraph inside a `MultiSelect.Group`, placed after `MultiSelect.GroupLabel`. Provides additional context about the group's items.

Standard `p` element props.

### MultiSelect.Separator

Renders a separator between `MultiSelect.Item`s or `MultiSelect.Group`s.

All props from [Separator](/components/separator).

### MultiSelect.Empty

Renders a message when no items match the current filter.

Standard `div` element props.

### MultiSelect.ContentFooter

Renders a sticky footer inside `MultiSelect.Content` that stays pinned to the bottom edge of the content area. Place it as the last child of `MultiSelect.Content`.

Standard `div` element props.

---

---
title: OTP Input
description: Accessible one-time passcode (OTP) input with paste, autofill, and IME support.
---

# OTP Input

Capture a short, fixed-length one-time passcode (OTP) — for two-factor codes,
email verification codes, magic-link codes, and similar flows. Built on top of
[`input-otp`](https://github.com/guilhermerodz/input-otp), it renders a single
hidden input that handles paste, autofill, and IME correctly while displaying
each character in its own styled slot.

Pair with `Field.*` for label/description/error wiring in forms:

```tsx
import { Field } from "@ngrok/mantle/field";
import { OtpInput } from "@ngrok/mantle/otp-input";

<Field.Item name="otp">
	<Field.Label>Verification code</Field.Label>
	<Field.Control>
		<OtpInput.Root maxLength={6}>
			<OtpInput.Group>
				<OtpInput.Slot index={0} />
				<OtpInput.Slot index={1} />
				<OtpInput.Slot index={2} />
				<OtpInput.Slot index={3} />
				<OtpInput.Slot index={4} />
				<OtpInput.Slot index={5} />
			</OtpInput.Group>
		</OtpInput.Root>
	</Field.Control>
	<Field.Description>Enter the 6-digit code we emailed you.</Field.Description>
</Field.Item>;
```

Or render the control on its own:

```tsx
import { OtpInput } from "@ngrok/mantle/otp-input";

<OtpInput.Root maxLength={6}>
	<OtpInput.Group>
		<OtpInput.Slot index={0} />
		<OtpInput.Slot index={1} />
		<OtpInput.Slot index={2} />
	</OtpInput.Group>
	<OtpInput.Separator />
	<OtpInput.Group>
		<OtpInput.Slot index={3} />
		<OtpInput.Slot index={4} />
		<OtpInput.Slot index={5} />
	</OtpInput.Group>
</OtpInput.Root>;
```

## With TanStack Form

Use `@tanstack/react-form` with `zod` to validate the hidden OTP input while `Field.Control` handles label, name, and validation ARIA.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Field, toErrorMessages } from "@ngrok/mantle/field";
import { OtpInput, REGEXP_ONLY_DIGITS } from "@ngrok/mantle/otp-input";
import { useForm } from "@tanstack/react-form";
import { z } from "zod";

export const formSchema = z.object({
	code: z.string().length(6, "Enter the 6-digit code."),
});
function Example() {
	const defaultValues = {
		code: "",
	};
	const form = useForm({
		defaultValues,
		validators: {
			onSubmit: formSchema,
		},
		onSubmit: ({ value }) => {
			// Handle form submission here
		},
	});

return (
		<form
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<form.Field name="code">
				{(field) => (
					<Field.Item name={field.name}>
						<Field.Label>Verification code</Field.Label>
						<Field.Control>
							<OtpInput.Root
								value={field.state.value}
								onBlur={field.handleBlur}
								onChange={field.handleChange}
								maxLength={6}
								pattern={REGEXP_ONLY_DIGITS}
							>
								<OtpInput.Group>
									<OtpInput.Slot index={0} />
									<OtpInput.Slot index={1} />
									<OtpInput.Slot index={2} />
									<OtpInput.Slot index={3} />
									<OtpInput.Slot index={4} />
									<OtpInput.Slot index={5} />
								</OtpInput.Group>
							</OtpInput.Root>
						</Field.Control>
						<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
					</Field.Item>
				)}
			</form.Field>
			<Button type="submit" appearance="filled" priority="neutral">
				Submit
			</Button>
		</form>
	);
}
```

## Single group

Render all slots in a single group with no separator.

```tsx
<OtpInput.Root maxLength={4}>
	<OtpInput.Group>
		<OtpInput.Slot index={0} />
		<OtpInput.Slot index={1} />
		<OtpInput.Slot index={2} />
		<OtpInput.Slot index={3} />
	</OtpInput.Group>
</OtpInput.Root>
```

## Digits only

Restrict input to numeric characters using the `pattern` prop and the
`REGEXP_ONLY_DIGITS` helper.

```tsx
import { OtpInput, REGEXP_ONLY_DIGITS } from "@ngrok/mantle/otp-input";

<OtpInput.Root maxLength={6} pattern={REGEXP_ONLY_DIGITS}>
	<OtpInput.Group>
		<OtpInput.Slot index={0} />
		<OtpInput.Slot index={1} />
		<OtpInput.Slot index={2} />
		<OtpInput.Slot index={3} />
		<OtpInput.Slot index={4} />
		<OtpInput.Slot index={5} />
	</OtpInput.Group>
</OtpInput.Root>;
```

## Disabled

Pass `disabled` to the root to disable the entire input.

```tsx
<OtpInput.Root maxLength={6} disabled>
	{/* ... */}
</OtpInput.Root>
```

## Validation

Pass `validation="error"`, `"success"`, or `"warning"` on `OtpInput.Root` to
recolor each group's outer borders and the active focus ring with the matching
validation hue. `validation="error"` also sets `aria-invalid` on the
underlying input so assistive tech announces the failure state.

`validation` may be a literal value or a function that returns a value. Since
the prop also accepts `false`, form-library state can short-circuit validation
styling, e.g.
`validation={field.state.meta.errors.length > 0 && "error"}`.

```tsx
<OtpInput.Root maxLength={6} validation="error">
	{/* ... */}
</OtpInput.Root>
```

## Polymorphism

`OtpInput.Group` and `OtpInput.Separator` accept an `asChild` prop. When `true`,
the part renders its single child instead of its default `div`, forwarding all
class names, `data-*` attributes, and the ref onto that child. Use this when you
need a different underlying element — for example, rendering the separator as a
semantic span, or wrapping a group in a styled label.

```tsx
<OtpInput.Separator asChild>
	<span aria-hidden>·</span>
</OtpInput.Separator>
```

## Composition

Compose the parts of an `OtpInput` together to build your own:

```text showLineNumbers=false
OtpInput.Root
├── OtpInput.Group
│   └── OtpInput.Slot
├── OtpInput.Separator
└── OtpInput.Group
    └── OtpInput.Slot
```

## API Reference

### OtpInput.Root

The root of the OTP input. Wraps the hidden input that captures keystrokes,
paste, and autofill, and provides per-slot state to descendant `OtpInput.Slot`
parts via context.

All props from the underlying [`OTPInput`](https://github.com/guilhermerodz/input-otp#api-reference) component, including standard `input` props, plus:

| Prop                           | Type                             | Default  | Description                                                               |
| ------------------------------ | -------------------------------- | -------- | ------------------------------------------------------------------------- |
| `maxLength`                    | `number`                         | —        | The total number of character slots. Required.                            |
| `value?`                       | `string`                         | —        | Controlled value.                                                         |
| `onChange?`                    | `(value: string) => void`        | —        | Fired when the value changes.                                             |
| `onComplete?`                  | `(value: string) => void`        | —        | Fired when the user fills the final slot.                                 |
| `pattern?`                     | `string`                         | —        | Regex source restricting accepted characters (e.g. `REGEXP_ONLY_DIGITS`). |
| `textAlign?`                   | `"left" \| "center" \| "right"`  | `"left"` | Caret alignment within the hidden input.                                  |
| `containerClassName?`          | `string`                         | —        | Class applied to the slot container element.                              |
| `pasteTransformer?`            | `(pasted: string) => string`     | —        | Transform pasted text before it is consumed.                              |
| `pushPasswordManagerStrategy?` | `"increase-width" \| "none"`     | —        | Strategy to push password-manager badges out of the way.                  |
| `validation?`                  | `Validation \| () => Validation` | —        | Validation state. `"error"` also sets `aria-invalid` on the input.        |

### OtpInput.Group

Groups one or more `OtpInput.Slot` parts into a visually-connected segment with shared rounded corners and joined borders.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

### OtpInput.Slot

A single character slot. Must be rendered inside an `OtpInput.Root`. Reads its character, active state, and fake caret position from the root via context.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop    | Type     | Default | Description                                                    |
| ------- | -------- | ------- | -------------------------------------------------------------- |
| `index` | `number` | —       | Zero-based index of the slot. Required. Must be `< maxLength`. |

### OtpInput.Separator

A visual separator between two `OtpInput.Group` segments. Renders a minus icon by default; pass `children` to override.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop        | Type      | Default | Description                                                                                          |
| ----------- | --------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `asChild?`  | `boolean` | `false` | Render as a different element by passing a child.                                                    |
| `semantic?` | `boolean` | `false` | If `true`, renders with `role="separator"`. Otherwise the separator is decorative and `aria-hidden`. |

### Pattern helpers

Re-exported from `input-otp` for convenience:

| Export                         | Pattern          |
| ------------------------------ | ---------------- |
| `REGEXP_ONLY_DIGITS`           | `^\d+$`          |
| `REGEXP_ONLY_CHARS`            | `^[a-zA-Z]+$`    |
| `REGEXP_ONLY_DIGITS_AND_CHARS` | `^[a-zA-Z0-9]+$` |

---

---
title: Pagination
description: Components and hooks for navigating through paged data with cursor-based and offset-based pagination strategies.
---

# Pagination

Components and hooks for navigating through paged data with cursor-based and offset-based pagination strategies.

## Cursor Pagination

A pagination component for use with cursor-based pagination. Cursor-based pagination loads data in chunks by using a cursor from the last item on the current page to know where to start the next set. It doesn't let you jump to a specific page or know how many total pages there are, but it's more efficient for large or real-time data sets.

```tsx
import { CursorPagination } from "@ngrok/mantle/pagination";

<CursorPagination.Root defaultPageSize={100}>
	<CursorPagination.PageSizeSelect />
	<CursorPagination.Buttons hasNextPage hasPreviousPage />
</CursorPagination.Root>

<CursorPagination.Root defaultPageSize={100}>
	<CursorPagination.PageSizeValue />
	<CursorPagination.Buttons hasNextPage hasPreviousPage />
</CursorPagination.Root>

<CursorPagination.Root defaultPageSize={20}>
	<CursorPagination.Buttons hasNextPage hasPreviousPage={false} />
</CursorPagination.Root>
```

## Within a data table

`CursorPagination` pairs with a [`DataTable`](/components/data-table) — drive its `Buttons` and `PageSizeSelect` from a TanStack Table instance.

**Client-paginated** — the table holds every row and `getPaginationRowModel()` slices them. Read `getCanPreviousPage()` / `getCanNextPage()` for the buttons and call `setPageSize()` / `setPageIndex(0)` when the size changes:

```tsx
import {
	DataTable,
	getCoreRowModel,
	getPaginationRowModel,
	useReactTable,
} from "@ngrok/mantle/data-table";
import { CursorPagination } from "@ngrok/mantle/pagination";

// defaultPageSize seeds an UNCONTROLLED <Select>, so keep it stable — a module
// const (or the table's INITIAL page size), never the live page size.
const DEFAULT_PAGE_SIZE = 10;

return (
		<>
			<DataTable.Root table={table}>{/* … Head + Body … */}</DataTable.Root>
			<CursorPagination.Root className="flex justify-end" defaultPageSize={DEFAULT_PAGE_SIZE}>
				<CursorPagination.PageSizeSelect
					onChangePageSize={(size) => {
						table.setPageSize(size);
						table.setPageIndex(0); // reset to the first page when the size changes
					}}
				/>
				<CursorPagination.Buttons
					hasPreviousPage={table.getCanPreviousPage()}
					hasNextPage={table.getCanNextPage()}
					onPreviousPage={() => table.previousPage()}
					onNextPage={() => table.nextPage()}
				/>
			</CursorPagination.Root>
		</>
	);
}
```

**Server / cursor data** — the server returns one page at a time, so there is no `getPaginationRowModel` and no total count. Wire `Buttons` to your fetch's has-next / has-prev and load callbacks, and show the fixed, server-controlled page size with the read-only `PageSizeValue` instead of `PageSizeSelect`:

```tsx
import { CursorPagination } from "@ngrok/mantle/pagination";

<CursorPagination.Root className="flex justify-end" defaultPageSize={pageSize}>
	<CursorPagination.PageSizeValue />
	<CursorPagination.Buttons
		hasPreviousPage={Boolean(previousCursor)}
		hasNextPage={Boolean(nextCursor)}
		onPreviousPage={() => loadPage(previousCursor)}
		onNextPage={() => loadPage(nextCursor)}
	/>
</CursorPagination.Root>;
```

See the [DataTable pagination recipe](/components/data-table#pagination-controls) for the full table markup.

## Composition

Compose the parts of a `CursorPagination` together to build your own:

```text showLineNumbers=false
CursorPagination.Root
├── CursorPagination.PageSizeSelect
├── CursorPagination.PageSizeValue
└── CursorPagination.Buttons
```

## API Reference

### CursorPagination.Root

The root container for cursor-based pagination. Manages the page size state.

All props from the HTML `div` element, plus:

### CursorPagination.Buttons

A pair of previous/next buttons for navigating between pages.

### CursorPagination.PageSizeSelect

A select input for changing the number of items per page.

### CursorPagination.PageSizeValue

Displays the current page size as a read-only value (e.g. "100 per page").

## Offset Pagination

### useOffsetPagination

A headless hook for managing offset-based pagination state. Offset-based pagination lets you jump to a specific page and know the total number of pages.

```tsx
import { useOffsetPagination } from "@ngrok/mantle/pagination";

const pagination = useOffsetPagination({
	listSize: 150,
	pageSize: 10,
});

// pagination.currentPage — current page number (1-indexed)
// pagination.totalPages — total number of pages
// pagination.hasNextPage — whether there is a next page
// pagination.hasPreviousPage — whether there is a previous page
// pagination.nextPage() — go to next page
// pagination.previousPage() — go to previous page
// pagination.goToPage(n) — go to a specific page
// pagination.goToFirstPage() — go to the first page
// pagination.goToLastPage() — go to the last page
// pagination.offset — the offset of the current page
// pagination.pageSize — the current page size
// pagination.setPageSize(n) — set the page size (resets to page 1)
```

### getOffsetPaginatedSlice

A utility function to get a paginated slice of a list based on the current offset pagination state.

```tsx
import { getOffsetPaginatedSlice, useOffsetPagination } from "@ngrok/mantle/pagination";

const data = ["a", "b", "c", "d", "e", "f"];
const pagination = useOffsetPagination({ listSize: data.length, pageSize: 2 });
const currentPageData = getOffsetPaginatedSlice(data, pagination);
// Returns: ['a', 'b'] for page 1, ['c', 'd'] for page 2, etc.
```

---

---
title: Password Input
description: Fundamental component for password inputs.
---

# Password Input

An input optimized for password and other sensitive-value entry. Renders a native `<input type="password">` with a built-in trailing button that toggles between hidden (`••••`) and revealed (`text`) display.

## When to use

- Password fields on login, signup, and reset flows.
- One-time tokens, recovery codes, or secrets the user needs to type accurately and may want to verify visually before submitting.

## When not to use

- For values that are never sensitive — use a plain [`Input`](/components/input).
- For controls where the toggle would be confusing (e.g. masked input formatting like phone numbers).

## Visibility state

The toggle is uncontrolled by default. Pass `showValue` to control the visibility from the outside (useful when one UI control toggles multiple password fields), and `onValueVisibilityChange` to be notified when the user toggles via the built-in button.

## Accessibility

Always pair with a [`Label`](/components/label). The toggle button has its own accessible name announcing the current state. The input keeps `autocomplete="current-password"` / `"new-password"` semantics — set `autoComplete` explicitly per flow.

## Browser password managers

When revealed, the input switches to `type="text"` — some password managers may pause autofill in this state, which is the intended security tradeoff.

Pair with `Field.*` for label/description/error wiring in forms:

```tsx
import { Field } from "@ngrok/mantle/field";
import { PasswordInput } from "@ngrok/mantle/input";

<Field.Item className="max-w-64" name="password">
	<Field.Label>Password</Field.Label>
	<Field.Control>
		<PasswordInput />
	</Field.Control>
</Field.Item>
<Field.Item className="max-w-64" name="password-error">
	<Field.Label>Password (error)</Field.Label>
	<Field.Control>
		<PasswordInput validation="error" />
	</Field.Control>
</Field.Item>
```

Or render the control on its own:

```tsx
import { PasswordInput } from "@ngrok/mantle/input";

<PasswordInput aria-label="Password" />;
```

## Examples

### With TanStack Form

Use `@tanstack/react-form` with `zod` to validate a controlled `PasswordInput` inside `Field.Item`.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Field, toErrorMessages } from "@ngrok/mantle/field";
import { PasswordInput } from "@ngrok/mantle/input";
import { useForm } from "@tanstack/react-form";
import { z } from "zod";

export const formSchema = z.object({
	password: z.string().min(8, "Use at least 8 characters."),
});
function Example() {
	const defaultValues = {
		password: "",
	};
	const form = useForm({
		defaultValues,
		validators: {
			onSubmit: formSchema,
		},
		onSubmit: ({ value }) => {
			// Handle form submission here
		},
	});

return (
		<form
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<form.Field name="password">
				{(field) => (
					<Field.Item name={field.name}>
						<Field.Label>Password</Field.Label>
						<Field.Control>
							<PasswordInput
								value={field.state.value}
								onBlur={field.handleBlur}
								onChange={(event) => field.handleChange(event.target.value)}
								autoComplete="new-password"
							/>
						</Field.Control>
						<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
					</Field.Item>
				)}
			</form.Field>
			<Button type="submit" appearance="filled" priority="neutral">
				Submit
			</Button>
		</form>
	);
}
```

## API Reference

The `PasswordInput` accepts the following props in addition to the [standard HTML input attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).

| Prop                      | Type                                                                                                     | Default | Description                                                                                                                                                                                                                                                                                                             |
| ------------------------- | -------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onValueVisibilityChange` | `(value: boolean) => void`                                                                               |         | Callback for when the visibility of the password value changes.                                                                                                                                                                                                                                                         |
| `showValue`               | `boolean`                                                                                                | `false` | Show/hide the password value as a controlled state.                                                                                                                                                                                                                                                                     |
| `validation`              | `"error"` \| `"success"` \| `"warning"` \| `false` \| `() => "error" \| "success" \| "warning" \| false` |         | Use the `validation` prop to show if the input has a specific validation status. This will change the border and outline of the input. The `false` type is useful when using short-circuiting logic so that you don't need to use a ternary with `undefined`. Setting `validation` to `error` also sets `aria-invalid`. |

---

---
title: Popover
description: Displays rich content in a portal, triggered by a button.
---

# Popover

Displays rich content in a portal, triggered by a button.

## When to use

A `Popover` is a non-modal dialog anchored to a trigger. Use it when the floating content must be interactive — forms, menus of actions, filters, settings.

- Prefer [`Tooltip`](/components/tooltip) for a short, non-interactive label on a control (for example, the purpose of an icon-only button).
- Prefer [`HoverCard`](/components/hover-card) for a sighted-only preview of content that already lives behind a link.

Popover is a non-modal dialog by default: focus moves into the content on open, `Escape` closes and returns focus to the trigger, clicking outside dismisses, and the page (body and any scroll containers) continues to scroll normally. Pass `modal` on `Popover.Root` to trap focus inside the content, block interaction with the rest of the page, and lock body scroll while the popover is open (the [WAI-ARIA dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)).

```tsx
import { Button } from "@ngrok/mantle/button";
import { Popover } from "@ngrok/mantle/popover";

<Popover.Root>
	<Popover.Trigger asChild>
		<Button type="button" appearance="filled" priority="neutral">
			Open popover
		</Button>
	</Popover.Trigger>
	<Popover.Content preferredWidth="max-w-96">
		<p>Reprehenderit veniam excepteur incididunt et ut eu.</p>
	</Popover.Content>
</Popover.Root>;
```

## Composition

Compose the parts of a `Popover` together to build your own:

```text showLineNumbers=false
Popover.Root
├── Popover.Trigger
├── Popover.Anchor
└── Popover.Content
    └── Popover.Close
```

## API Reference

The `Popover` components are built on top of [Radix Popover](https://www.radix-ui.com/primitives/docs/components/popover).

### Popover.Root

The root, stateful component that manages the open/closed state of the popover.

All props from Radix [Popover.Root](https://www.radix-ui.com/primitives/docs/components/popover#root).

### Popover.Trigger

The button that toggles the popover.

All props from Radix [Popover.Trigger](https://www.radix-ui.com/primitives/docs/components/popover#trigger).

### Popover.Content

The content to render inside the popover. Appears in a portal with styling and animations.

All props from Radix [Popover.Content](https://www.radix-ui.com/primitives/docs/components/popover#content), plus:

| Prop              | Type                                     | Default      | Description                                          |
| :---------------- | :--------------------------------------- | :----------- | :--------------------------------------------------- |
| `preferredWidth?` | `` `max-w-${string}` ``                  | `"max-w-72"` | The preferred width as a Tailwind `max-w-` class.    |
| `side?`           | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"`   | The preferred side of the trigger to render against. |
| `sideOffset?`     | `number`                                 | `4`          | The distance in pixels from the trigger.             |
| `align?`          | `"start" \| "center" \| "end"`           | `"center"`   | The preferred alignment against the trigger.         |

### Popover.Anchor

An optional element to position the `Popover.Content` against. If not used, the content will position alongside the `Popover.Trigger`.

All props from Radix [Popover.Anchor](https://www.radix-ui.com/primitives/docs/components/popover#anchor).

### Popover.Close

A button that closes an open popover.

All props from Radix [Popover.Close](https://www.radix-ui.com/primitives/docs/components/popover#close).

---

---
title: Accordion
description: A vertically stacked set of interactive headings that each reveal an associated section of content.
---

A vertically stacked set of interactive headings that each reveal an associated section of content.

```tsx
import { Accordion } from "@ngrok/mantle/accordion";
import { Badge } from "@ngrok/mantle/badge";
import { Button } from "@ngrok/mantle/button";
import { Card } from "@ngrok/mantle/card";

<Accordion.Root type="multiple" defaultValue={["on_tcp_connect", "on_http_response"]}>
	<Accordion.Item value="on_tcp_connect">
		<Accordion.Heading className="mx-4 flex items-center gap-2" asChild>
			<h2>
				<Accordion.Trigger>
					<span className="font-mono text-sm font-medium">on_tcp_connect</span>
					<Badge appearance="muted" color="neutral" className="rounded-full">
						3
					</Badge>
					<Accordion.TriggerIcon />
				</Accordion.Trigger>
				<Separator orientation="horizontal" className="flex-1" />
				<Button type="button" appearance="link" icon={<PlusIcon />}>
					Add Rule
				</Button>
			</h2>
		</Accordion.Heading>
		<Accordion.Content>
			<Card.Root>
				<Card.Body>Proident irure consequat Lorem incididunt ullamco.</Card.Body>
			</Card.Root>
		</Accordion.Content>
	</Accordion.Item>
	<Accordion.Item value="on_http_request">
		<Accordion.Heading className="mx-4 flex items-center gap-2" asChild>
			<h2>
				<Accordion.Trigger>
					<span className="font-mono text-sm font-medium">on_http_request</span>
					<Badge appearance="muted" color="neutral" className="rounded-full">
						2
					</Badge>
					<Accordion.TriggerIcon />
				</Accordion.Trigger>
				<Separator orientation="horizontal" className="flex-1" />
				<Button type="button" appearance="link" icon={<PlusIcon />}>
					Add Rule
				</Button>
			</h2>
		</Accordion.Heading>
		<Accordion.Content>
			<Card.Root>
				<Card.Body>Excepteur amet laboris occaecat anim minim reprehenderit.</Card.Body>
			</Card.Root>
		</Accordion.Content>
	</Accordion.Item>
	<Accordion.Item value="on_http_response">
		<Accordion.Heading className="mx-4 flex items-center gap-2" asChild>
			<h2>
				<Accordion.Trigger>
					<span className="font-mono text-sm font-medium">on_http_response</span>
					<Badge appearance="muted" color="neutral" className="rounded-full">
						0
					</Badge>
					<Accordion.TriggerIcon />
				</Accordion.Trigger>
				<Separator orientation="horizontal" className="flex-1" />
				<Button type="button" appearance="link" icon={<PlusIcon />}>
					Add Rule
				</Button>
			</h2>
		</Accordion.Heading>
		<Accordion.Content>
			<p className="text-center">This phase does not have any rules defined</p>
		</Accordion.Content>
	</Accordion.Item>
</Accordion.Root>;
```

---

---
title: Calendar
description: A date field component that allows users to enter and edit date.
---

A date field component that allows users to enter and edit date.

```tsx
import { Calendar } from "@ngrok/mantle/calendar";

<Calendar mode="single" selected={date} onSelect={setDate} />;
```

## API Reference

The `Calendar` is built on top of [React DayPicker](https://react-day-picker.js.org/).

---

---
title: Progress Bar
description: Displays an indicator showing the completion progress of a task as a linear progress bar with customizable colors.
---

# Progress Bar

Displays an indicator showing the completion progress of a task as a linear progress bar with customizable colors.

The progress bar consists of an indicator (filled portion) that shows the current progress value against a background container.

```tsx
import { ProgressBar } from "@ngrok/mantle/progress";

<ProgressBar.Root value={60}>
	<ProgressBar.Indicator className="bg-warning-600" />
</ProgressBar.Root>

<ProgressBar.Root value={30}>
	<ProgressBar.Indicator className="bg-accent-600" />
</ProgressBar.Root>

<div className="flex flex-col gap-3">
	<div className="flex items-center gap-3 text-sm">
		<ProgressBar.Root value={100} className="w-24">
			<ProgressBar.Indicator className="bg-success-600" />
		</ProgressBar.Root>
		Complete
	</div>

<div className="flex items-center gap-3 text-sm">
		<ProgressBar.Root value={45} className="w-24">
			<ProgressBar.Indicator className="bg-warning-600" />
		</ProgressBar.Root>
		In Progress
	</div>
</div>
```

## Custom Maximum Value

You can set a custom maximum value using the `max` prop. The progress value will be calculated as a percentage of this maximum.

```tsx
import { ProgressBar } from "@ngrok/mantle/progress";

<ProgressBar.Root value={150} max={200}>
	<ProgressBar.Indicator className="bg-purple-600" />
</ProgressBar.Root>;
```

## Indeterminate Value

You can set the `value` prop to `"indeterminate"` to show the progress bar in an indeterminate state. Currently, this displays as a progress bar at 0% but maintains accessibility attributes for screen readers.

```tsx
import { ProgressBar } from "@ngrok/mantle/progress";

<ProgressBar.Root value="indeterminate">
	<ProgressBar.Indicator className="bg-accent-600" />
</ProgressBar.Root>;
```

## Dynamic Colors

The color of the `ProgressBar.Indicator` can be customized using the `className` prop. This allows you to change colors based on the current progress value or application state.

```tsx
import { ProgressBar } from "@ngrok/mantle/progress";

const Example = () => {
	const [value, setValue] = useState(0);

function computeIndicatorColor() {
		switch (true) {
			case value <= 20:
				return "bg-danger-600";
			case value <= 40:
				return "bg-warning-600";
			case value <= 60:
				return "bg-accent-600";
			case value <= 80:
				return "bg-success-600";
			default:
				return "bg-fuchsia-600";
		}
	}

return (
		<form className="space-y-4">
			<ProgressBar.Root value={value}>
				<ProgressBar.Indicator className={computeIndicatorColor()} />
			</ProgressBar.Root>
			<label className="block space-y-1">
				<p>Value:</p>
				<input
					type="range"
					min={0}
					max={100}
					value={value}
					onChange={(e) => setValue(Number(e.target.value))}
				/>{" "}
				({value}%)
			</label>
		</form>
	);
};
```

## Composition

Compose the parts of a `ProgressBar` together to build your own:

```text showLineNumbers=false
ProgressBar.Root
└── ProgressBar.Indicator
```

## API Reference

### ProgressBar.Root

A linear progress bar that displays completion progress with customizable colors.

The `ProgressBar.Root` accepts the following props in addition to the [standard HTML div attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes).

| Prop    | Type                          | Default | Description                                                                                                                                    |
| ------- | ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `max`   | `number`                      | `100`   | The maximum value of the progress bar. Must have a value greater than 0.                                                                       |
| `value` | `number` \| `"indeterminate"` | `0`     | The current value of the progress bar. Must be between 0 and `max`. If set to `"indeterminate"`, the progress bar is considered indeterminate. |

### ProgressBar.Indicator

The indicator portion of the progress bar that shows the completed progress. This component is automatically positioned and sized based on the current value relative to the maximum value.

All props from [HTML div element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div).

---

---
title: Progress Donut
description: Displays an indicator showing the completion progress of a task as a circular progress bar.
---

# Progress Donut

Displays an indicator showing the completion progress of a task as a circular progress bar.

The indicator color is inherited via `currentColor`. Override the default (`accent-600`) by setting the `ProgressDonut.Indicator`'s text color.

```tsx
import { ProgressDonut } from "@ngrok/mantle/progress";

<ProgressDonut.Root value={60} className="size-10" strokeWidth="0.375rem">
	<ProgressDonut.Indicator />
</ProgressDonut.Root>

<ProgressDonut.Root value={60} className="size-10" strokeWidth="0.375rem">
	<ProgressDonut.Indicator className="text-fuchsia-600" />
</ProgressDonut.Root>

<div className="flex flex-col gap-2">
	<div className="flex items-center gap-1.5 text-sm">
		<ProgressDonut.Root value={100} className="size-6">
			<ProgressDonut.Indicator />
		</ProgressDonut.Root>
		Data transfer out
	</div>

<div className="flex items-center gap-1.5 text-xs">
		<div className="grid w-6 place-items-center">
			<ProgressDonut.Root value={100} className="size-4" strokeWidth="0.1875rem">
				<ProgressDonut.Indicator />
			</ProgressDonut.Root>
		</div>
		Included
	</div>

<div className="flex items-center gap-1.5 text-xs">
		<div className="grid w-6 place-items-center">
			<ProgressDonut.Root value={25} className="size-4" strokeWidth="0.1875rem">
				<ProgressDonut.Indicator className="text-success-600" />
			</ProgressDonut.Root>
		</div>
		Additional
	</div>
</div>
```

## Indeterminate Value

You can set the `value` prop to `"indeterminate"` to show the progress bar in an indeterminate state.

You can control the rotation speed with the `indeterminateRotationSpeed` prop.

```tsx
import { ProgressDonut } from "@ngrok/mantle/progress";

<ProgressDonut.Root className="size-10" value="indeterminate" strokeWidth="0.375rem">
	<ProgressDonut.Indicator />
</ProgressDonut.Root>

<ProgressDonut.Root
	className="size-10"
	value="indeterminate"
	indeterminateRotationSpeed="animation-duration-[2s]"
	strokeWidth="0.375rem"
>
	<ProgressDonut.Indicator />
</ProgressDonut.Root>
```

## Dynamic Colors

The color of the `ProgressDonut.Indicator` is inherited from the parent text color using `currentColor`. Using this, you can easily change the color of it based on the current progress value.

```tsx
import { ProgressDonut } from "@ngrok/mantle/progress";

const Example = () => {
	const [value, setValue] = useState(0);

function computeColor() {
		switch (true) {
			case value <= 20:
				return "text-accent-600";
			case value <= 40:
				return "text-success-600";
			case value <= 60:
				return "text-warning-600";
			case value <= 80:
				return "text-fuchsia-600";
			default:
				return "text-danger-600";
		}
	}

return (
		<form className="space-y-4">
			<ProgressDonut.Root value={value} className="size-10" strokeWidth="0.375rem">
				<ProgressDonut.Indicator className={computeColor()} />
			</ProgressDonut.Root>
			<label className="block space-y-1">
				<p>Value:</p>
				<input
					type="range"
					min={0}
					max={100}
					value={value}
					onChange={(e) => setValue(Number(e.target.value))}
				/>{" "}
				({value}%)
			</label>
		</form>
	);
};
```

## Composition

Compose the parts of a `ProgressDonut` together to build your own:

```text showLineNumbers=false
ProgressDonut.Root
└── ProgressDonut.Indicator
```

## API Reference

### ProgressDonut.Root

A simple circular progress bar which shows the completion progress of a task.

The indicator color is inherited via `currentColor`. Override the default (`accent-600`) by setting the `ProgressDonut.Indicator`'s text color.

The `ProgressDonut` accepts the following props in addition to the [standard HTML svg attributes](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg#attributes).

| Prop                         | Type                                 | Default                      | Description                                                                                                                                                         |
| ---------------------------- | ------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `indeterminateRotationSpeed` | `` `animation-duration-${string}` `` | `"animation-duration-[15s]"` | Controls the rotation speed of the indeterminate spinner state, as a Tailwind `animation-duration-*` class.                                                         |
| `max`                        | `number`                             | `100`                        | The maximum value of the progress bar. Must have a value greater than 0.                                                                                            |
| `strokeWidth`                | `number` \| `` `${number}rem` ``     | `"0.25rem"`                  | The width of the progress bar stroke. Note, we clamp the stroke width to a minimum of 1px and max of 12px since it is proportional to the viewbox size (0 0 32 32). |
| `value`                      | `number` \| `"indeterminate"`        | `0`                          | The current value of the progress bar. Must be between 0 and `max`. If set to `"indeterminate"`, the progress bar is considered indeterminate.                      |

### ProgressDonut.Indicator

The indicator for the circular progress bar.

All props from [svg g](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/g).

---

---
title: QR Code
description: Render a scannable QR code, optionally branded with a centered logo.
---

# QR Code

Render a scannable QR code from any string — a URL, an `otpauth://` MFA
enrollment URI, a Wi-Fi credential, and so on. The value is encoded with the
dependency-free [`uqr`](https://github.com/unjs/uqr) library.

Compose a `QrCode.Frame` (the `svg`) wrapping a `QrCode.Pattern` (the modules)
inside a `QrCode.Root`, and optionally drop a `QrCode.Overlay` in the center for
a brand logo.

```tsx
import { QrCode } from "@ngrok/mantle/qr-code";
import { NgrokLettermarkIcon } from "@ngrok/mantle/icons";

<QrCode.Root
	value="otpauth://totp/ngrok:alice@example.com?secret=JBSWY3DPEHPK3PXP&issuer=ngrok"
	ecc="H"
>
	<QrCode.Frame>
		<QrCode.Pattern />
	</QrCode.Frame>
	<QrCode.Overlay>
		<NgrokLettermarkIcon className="size-7" />
	</QrCode.Overlay>
</QrCode.Root>;
```

The tile is intentionally white with dark modules in every theme — inverting a
QR code's colors makes it unreliable for many scanners, so it stays
black-on-white by default for scannability.

## Basic

The minimal QR code is a `Root` with a `Frame` and `Pattern`. The default error
correction level is `L` (\~7% recovery), which is plenty when there is no overlay
covering modules.

```tsx
import { QrCode } from "@ngrok/mantle/qr-code";

<QrCode.Root value="https://ngrok.com">
	<QrCode.Frame>
		<QrCode.Pattern />
	</QrCode.Frame>
</QrCode.Root>;
```

## Error correction

A `QrCode.Overlay` hides the modules beneath it, so raise the error correction
level via the `ecc` prop to keep the code scannable. Levels are `L` (\~7%), `M`
(\~15%), `Q` (\~25%), and `H` (\~30%). Prefer `H` whenever a logo is present.

```tsx
<QrCode.Root value="https://ngrok.com" ecc="H">
	<QrCode.Frame>
		<QrCode.Pattern />
	</QrCode.Frame>
	<QrCode.Overlay>
		<NgrokLettermarkIcon className="size-7" />
	</QrCode.Overlay>
</QrCode.Root>
```

## Sizing

The `Frame` defaults to a square `size-48`. Because the encoded pattern scales
to the frame's `viewBox`, resize the whole code by passing a different size to
the `Frame`'s `className`.

```tsx
<QrCode.Root value="https://ngrok.com">
	<QrCode.Frame className="size-32">
		<QrCode.Pattern />
	</QrCode.Frame>
</QrCode.Root>
```

## Quiet zone

A QR code includes a margin of light modules around the pattern — the *quiet
zone* — that scanners rely on to locate the code. It's encoded into the grid
itself, not cosmetic CSS padding, so adjust it with the `quietZone` prop on
`Root` rather than `className`. It defaults to `4`, the QR spec's recommended
margin. Lower it to tighten the surrounding whitespace; avoid `0`, which makes
the code unreliable for many scanners.

```tsx
<QrCode.Root value="https://ngrok.com" quietZone={1}>
	<QrCode.Frame>
		<QrCode.Pattern />
	</QrCode.Frame>
</QrCode.Root>
```

## Composition

Compose the parts of a `QrCode` together to build your own:

```text showLineNumbers=false
QrCode.Root
├── QrCode.Frame
│   └── QrCode.Pattern
└── QrCode.Overlay
```

## Polymorphism

`QrCode.Root` and `QrCode.Overlay` support the `asChild` prop. When `asChild` is
`true`, the part renders its single child instead of its default element,
forwarding all class names, `data-*` attributes, and behavior onto that child —
for example, to render the whole code as a link.

`QrCode.Frame` and `QrCode.Pattern` render fixed SVG elements (`svg` and `path`)
and do not support `asChild` — the QR pattern must live inside an svg, so those
elements cannot be swapped.

```tsx
<QrCode.Root asChild value="https://ngrok.com">
	<a href="https://ngrok.com">
		<QrCode.Frame>
			<QrCode.Pattern />
		</QrCode.Frame>
	</a>
</QrCode.Root>
```

## API Reference

### QrCode.Root

The root container. Encodes `value` and renders a white tile around the code.
Renders a `div`.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop         | Type                       | Default | Description                                                       |
| ------------ | -------------------------- | ------- | ----------------------------------------------------------------- |
| `value`      | `string`                   | —       | The string to encode (required).                                  |
| `ecc?`       | `"L" \| "M" \| "Q" \| "H"` | `"L"`   | Error correction level. Use `"H"` when an overlay covers modules. |
| `pixelSize?` | `number`                   | `10`    | The pixel size of each module (affects internal resolution).      |
| `quietZone?` | `number`                   | `4`     | Light-module margin baked around the code. Lower tightens it.     |
| `asChild?`   | `boolean`                  | `false` | Render as a different element by passing a child.                 |

### QrCode.Frame

The `svg` frame that holds the `Pattern`. Defaults to `size-48` and scales the
pattern to fit via its `viewBox`. Renders an `svg`. Does not support `asChild`.

Accepts all props from [svg](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg#attributes).

### QrCode.Pattern

The encoded modules, rendered as a single `path` inside the `Frame`. Always
filled black. Renders a `path`. Does not support `asChild`.

Accepts all props from [path](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/path#attributes).

### QrCode.Overlay

A container centered on top of the code, typically holding a brand logo. Renders
a white rounded "punch-out" so the logo stays legible. Renders a `div`.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

---

---
title: Radio Group
description: A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time.
---

# Radio Group

A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time.

Pair with `Field.Set` and `Field.Legend` for grouped label/description/error wiring in forms. `RadioGroup` keeps its own `name` prop on `RadioGroup.Root`:

```tsx
import { Field } from "@ngrok/mantle/field";
import { RadioGroup } from "@ngrok/mantle/radio-group";

<Field.Set>
	<Field.Legend>Density</Field.Legend>
	<RadioGroup.Root name="density" defaultValue="compact">
		<RadioGroup.Item value="default" id="density-default">
			<RadioGroup.Indicator />
			<RadioGroup.ItemContent asChild>
				<label htmlFor="density-default">Default</label>
			</RadioGroup.ItemContent>
		</RadioGroup.Item>
		<RadioGroup.Item value="comfortable" id="density-comfortable">
			<RadioGroup.Indicator />
			<RadioGroup.ItemContent asChild>
				<label htmlFor="density-comfortable">Comfortable</label>
			</RadioGroup.ItemContent>
		</RadioGroup.Item>
		<RadioGroup.Item value="compact" id="density-compact">
			<RadioGroup.Indicator />
			<RadioGroup.ItemContent asChild>
				<label htmlFor="density-compact">Compact</label>
			</RadioGroup.ItemContent>
		</RadioGroup.Item>
	</RadioGroup.Root>
	<Field.Description>Choose the row spacing for tables.</Field.Description>
</Field.Set>;
```

Or render the control on its own:

```tsx
import { RadioGroup } from "@ngrok/mantle/radio-group";

<RadioGroup.Root defaultValue="comfortable">
	<RadioGroup.Item className="py-1" value="default" id="simple-1">
		<RadioGroup.Indicator />
		<RadioGroup.ItemContent asChild>
			<label htmlFor="simple-1">Default</label>
		</RadioGroup.ItemContent>
	</RadioGroup.Item>
	<RadioGroup.Item className="py-1" value="comfortable" id="simple-2" disabled>
		<RadioGroup.Indicator />
		<RadioGroup.ItemContent asChild>
			<label htmlFor="simple-2">Comfortable</label>
		</RadioGroup.ItemContent>
	</RadioGroup.Item>
	<RadioGroup.Item className="py-1" value="compact" id="simple-3">
		<RadioGroup.Indicator />
		<RadioGroup.ItemContent asChild>
			<label htmlFor="simple-3">Compact</label>
		</RadioGroup.ItemContent>
	</RadioGroup.Item>
</RadioGroup.Root>

<RadioGroup.ButtonGroup defaultValue="production">
	<RadioGroup.Button value="development">Development</RadioGroup.Button>
	<RadioGroup.Button value="staging">Staging</RadioGroup.Button>
	<RadioGroup.Button value="production">Production</RadioGroup.Button>
</RadioGroup.ButtonGroup>

<RadioGroup.List defaultValue="comfortable">
	<RadioGroup.ListItem value="default" disabled id="rli1">
		<RadioGroup.Indicator />
		<RadioGroup.ItemContent>
			<label className="font-medium text-strong" htmlFor="rli1">Default</label>
			<p className="text-body">Laborum esse cillum incididunt est dolore.</p>
		</RadioGroup.ItemContent>
	</RadioGroup.ListItem>
	<RadioGroup.ListItem value="comfortable" id="rli2">
		<RadioGroup.Indicator />
		<RadioGroup.ItemContent>
			<label className="font-medium text-strong" htmlFor="rli2">Comfortable</label>
			<p className="text-body">Ea laboris tempor laborum officia ea adipisicing exercitation.</p>
		</RadioGroup.ItemContent>
	</RadioGroup.ListItem>
</RadioGroup.List>

<RadioGroup.Root className="grid grid-cols-1 gap-y-6 sm:grid-cols-3 sm:gap-x-4" defaultValue="existing">
	<RadioGroup.Card className="flex" value="newsletter" id="radiocard-1">
		<div className="flex-1">
			<label htmlFor="radiocard-1" className="block text-sm font-medium text-strong">Newsletter</label>
			<p className="mt-1 flex items-center text-sm text-gray-500">Last message sent an hour ago</p>
			<p className="mt-6 text-sm font-medium">621 users</p>
		</div>
		<RadioGroup.Indicator />
	</RadioGroup.Card>
</RadioGroup.Root>
```

## With TanStack Form

Use `@tanstack/react-form` with `zod` to keep a radio group controlled. Use `Field.Set` and `Field.Legend` because the grouped choices answer one shared question.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Field, toErrorMessages } from "@ngrok/mantle/field";
import { RadioGroup } from "@ngrok/mantle/radio-group";
import { useForm } from "@tanstack/react-form";
import { z } from "zod";

export const formSchema = z.object({
	density: z.string().min(1, "Choose a density."),
});
function Example() {
	const defaultValues = {
		density: "",
	};
	const form = useForm({
		defaultValues,
		validators: {
			onSubmit: formSchema,
		},
		onSubmit: ({ value }) => {
			// Handle form submission here
		},
	});

return (
		<form
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<form.Field name="density">
				{(field) => (
					<Field.Set>
						<Field.Legend>Density</Field.Legend>
						<RadioGroup.Root
							name={field.name}
							value={field.state.value}
							onChange={field.handleChange}
						>
							<RadioGroup.Item value="default" id="density-default">
								<RadioGroup.Indicator />
								<RadioGroup.ItemContent asChild>
									<label htmlFor="density-default">Default</label>
								</RadioGroup.ItemContent>
							</RadioGroup.Item>
							<RadioGroup.Item value="comfortable" id="density-comfortable">
								<RadioGroup.Indicator />
								<RadioGroup.ItemContent asChild>
									<label htmlFor="density-comfortable">Comfortable</label>
								</RadioGroup.ItemContent>
							</RadioGroup.Item>
							<RadioGroup.Item value="compact" id="density-compact">
								<RadioGroup.Indicator />
								<RadioGroup.ItemContent asChild>
									<label htmlFor="density-compact">Compact</label>
								</RadioGroup.ItemContent>
							</RadioGroup.Item>
						</RadioGroup.Root>
						<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
					</Field.Set>
				)}
			</form.Field>
			<Button type="submit" appearance="filled" priority="neutral">
				Submit
			</Button>
		</form>
	);
}
```

## Composition

`RadioGroup` supports several layout variants. Compose the parts together to build your own:

```text showLineNumbers=false
# Default radios
RadioGroup.Root
└── RadioGroup.Item
    ├── RadioGroup.Indicator
    └── RadioGroup.ItemContent

# List layout with descriptions
RadioGroup.List
└── RadioGroup.ListItem
    ├── RadioGroup.Indicator
    └── RadioGroup.ItemContent

# Segmented button group
RadioGroup.ButtonGroup
└── RadioGroup.Button

# Card-style radios
RadioGroup.Root
└── RadioGroup.Card
    └── RadioGroup.Indicator
```

## API Reference

### RadioGroup.Root

A group of radio items. Manages state so only one item can be selected at a time. Unstyled and simple.

All props from [Headless UI RadioGroup](https://headlessui.com/react/radio-group), including:

### RadioGroup.Item

A simple radio item. The conventional use-case for basic radio options. Must be a child of `RadioGroup.Root`.

### RadioGroup.Indicator

The selection indicator for any radio item. By default, renders a circle that changes color when checked. Use as a child of `RadioGroup.Item`, `RadioGroup.ListItem`, or `RadioGroup.Card`.

Accepts a render-props function `(context) => ReactNode` as children for custom indicators. The context includes `checked`, `disabled`, `focus`, `hover`, and `autofocus`.

### RadioGroup.ItemContent

The content wrapper for any radio item. Wrap labels, descriptions, or other content inside.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

### RadioGroup.ButtonGroup

An inline group of radio buttons rendered as a horizontal segmented control. Use `RadioGroup.Button` as direct children.

Same props as `RadioGroup.Root`.

### RadioGroup.Button

A radio button used inside `RadioGroup.ButtonGroup` for inline grouped radio options.

### RadioGroup.List

A group of radio list items with connected borders. Use `RadioGroup.ListItem` as direct children.

Same props as `RadioGroup.Root`.

### RadioGroup.ListItem

A radio list item used inside `RadioGroup.List` for connected list-style radio options with borders and padding.

### RadioGroup.Card

A radio card item with enhanced styling for card-based radio options.

### RadioGroup.InputSandbox

A sandbox container for input elements composed within radio group items. Prevents default radio selection behavior when interacting with the input.

---

---
title: SandboxedOnClick
description: A container that prevents the click event from bubbling out of it.
---

# SandboxedOnClick

A container that prevents the click event from bubbling out of it.

Each table row will trigger a `window.alert()` when clicked. The icon button is wrapped in `SandboxedOnClick` and navigates you to [the ngrok docs.](https://ngrok.com/docs)

```tsx
import { IconButton } from "@ngrok/mantle/button";
import { SandboxedOnClick } from "@ngrok/mantle/sandboxed-on-click";
import { Table } from "@ngrok/mantle/table";
import { BookIcon } from "@phosphor-icons/react/Book";

<Table.Root>
	<Table.Element>
		<Table.Caption>A list of your recent invoices.</Table.Caption>
		<Table.Head>
			<Table.Row>
				<Table.Header className="w-25">Invoice</Table.Header>
				<Table.Header>Status</Table.Header>
				<Table.Header>Method</Table.Header>
				<Table.Header className="text-right">Amount</Table.Header>
				<Table.Header className="text-right">Actions</Table.Header>
			</Table.Row>
		</Table.Head>
		<Table.Body>
			{invoices.map((invoice) => (
				<Table.Row
					key={invoice.invoice}
					className="cursor-pointer"
					onClick={() => {
						window.alert(`Clicked on ${invoice.invoice}!`);
					}}
				>
					<Table.Cell className="font-medium">{invoice.invoice}</Table.Cell>
					<Table.Cell>{invoice.paymentStatus}</Table.Cell>
					<Table.Cell>{invoice.paymentMethod}</Table.Cell>
					<Table.Cell className="text-right">{invoice.totalAmount}</Table.Cell>
					<Table.Cell className="text-right">
						<SandboxedOnClick allowClickEventDefault>
							<IconButton label="See ngrok docs" icon={<BookIcon />} asChild>
								<a href="https://ngrok.com/docs" target="_blank" rel="noopener noreferrer" />
							</IconButton>
						</SandboxedOnClick>
					</Table.Cell>
				</Table.Row>
			))}
		</Table.Body>
		<Table.Foot>
			<Table.Row>
				<Table.Cell colSpan={3}>Total</Table.Cell>
				<Table.Cell className="text-right">$2,500.00</Table.Cell>
				<Table.Cell />
			</Table.Row>
		</Table.Foot>
	</Table.Element>
</Table.Root>;
```

## API Reference

### SandboxedOnClick

A container that prevents the click event from bubbling out of it. Good to use when you want to provide some action buttons inside of a table row or list item that navigates on click.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop                     | Type      | Default | Description                                                                                                                                                                                                                                                                                                                 |
| ------------------------ | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowClickEventDefault` | `boolean` | `false` | Only call `event.preventDefault()` in the `onClick` handler if the user has not set `allowClickEventDefault` to `true`. This allows the user to control whether or not the default behavior of the click event should be allowed. This is useful for links or buttons that should navigate or perform some action on click. |
| `asChild`                | `boolean` | `false` | Use the `asChild` prop to compose the `SandboxedOnClick` functionality onto alternative element types or your own React components.                                                                                                                                                                                         |

---

---
title: Select
description: Displays a list of options for the user to pick from—triggered by a button.
---

# Select

Displays a list of options for the user to pick from—triggered by a button.

## When to use

Use `Select` for a small, finite list of options (\~2-15) where the user picks exactly one and search/filtering is unnecessary. For larger lists, async data, or any single-select where typing to filter is helpful, use [`Combobox`](/components/combobox). For picking multiple options, use [`Multi Select`](/components/multi-select).

When a `Select` is rendered inside `Field.Item`, wrap `Select.Root` in `Field.Control`. `Field.Control` flows the generated `id`, `name`, `aria-describedby`, `aria-errormessage`, and `aria-invalid` through to the focusable `Select.Trigger` — the `name` lands on `Select.Root` (so the hidden form input picks it up) and the trigger reads the ARIA props from context.

```tsx
import { Field } from "@ngrok/mantle/field";
import { Select } from "@ngrok/mantle/select";

<Field.Item className="max-w-64" name="fruits">
	<Field.Label>Fruits</Field.Label>
	<Field.Control>
		<Select.Root>
			<Select.Trigger>
				<Select.Value placeholder="Select a fruit" />
			</Select.Trigger>
			<Select.Content width="trigger">
				<Select.Group>
					<Select.Label>Fruits</Select.Label>
					<Select.Item value="apple">Apple</Select.Item>
					<Select.Item value="banana">Banana</Select.Item>
					<Select.Item value="blueberry">Blueberry</Select.Item>
					<Select.Item value="grapes">Grapes</Select.Item>
					<Select.Item value="pineapple">Pineapple</Select.Item>
				</Select.Group>
				<Select.Separator />
				<Select.Group>
					<Select.Label>Vegetables</Select.Label>
					<Select.Item value="carrot">Carrot</Select.Item>
					<Select.Item value="cucumber">Cucumber</Select.Item>
					<Select.Item value="lettuce">Lettuce</Select.Item>
					<Select.Item value="tomato">Tomato</Select.Item>
					<Select.Item value="zucchini">
						<p>Zucchini</p>
						<p>Ex sit voluptate incididunt pariatur velit consequat reprehenderit.</p>
					</Select.Item>
				</Select.Group>
			</Select.Content>
		</Select.Root>
	</Field.Control>
</Field.Item>;
```

## Examples

### With TanStack Form

Use `@tanstack/react-form` with `zod` to keep `Select.Root` controlled. Wrap the root in `Field.Control` so the generated name, id, and ARIA props reach the select trigger and hidden input.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Field, toErrorMessages } from "@ngrok/mantle/field";
import { Select } from "@ngrok/mantle/select";
import { useForm } from "@tanstack/react-form";
import { z } from "zod";

export const formSchema = z.object({
	fruit: z.string().min(1, "Choose a fruit."),
});
function Example() {
	const defaultValues = {
		fruit: "",
	};
	const form = useForm({
		defaultValues,
		validators: {
			onSubmit: formSchema,
		},
		onSubmit: ({ value }) => {
			// Handle form submission here
		},
	});

return (
		<form
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<form.Field name="fruit">
				{(field) => (
					<Field.Item name={field.name}>
						<Field.Label>Fruit</Field.Label>
						<Field.Control>
							<Select.Root
								value={field.state.value}
								onBlur={field.handleBlur}
								onValueChange={field.handleChange}
							>
								<Select.Trigger>
									<Select.Value placeholder="Select a fruit" />
								</Select.Trigger>
								<Select.Content width="trigger">
									<Select.Item value="apple">Apple</Select.Item>
									<Select.Item value="banana">Banana</Select.Item>
									<Select.Item value="blueberry">Blueberry</Select.Item>
								</Select.Content>
							</Select.Root>
						</Field.Control>
						<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
					</Field.Item>
				)}
			</form.Field>
			<Button type="submit" appearance="filled" priority="neutral">
				Submit
			</Button>
		</form>
	);
}
```

### Raw usage and validation

Use `Select.Root` directly when you don't need `Field` label, helper, or error wiring. Set `validation` on `Select.Root` to render a success, warning, or error state outside of a field.

```tsx
import { Select } from "@ngrok/mantle/select";

<Select.Root>
	<Select.Trigger className="max-w-64" aria-label="Fruit">
		<Select.Value placeholder="Select a fruit" />
	</Select.Trigger>
	<Select.Content width="trigger">
		<Select.Item value="apple">Apple</Select.Item>
		<Select.Item value="banana">Banana</Select.Item>
		<Select.Item value="blueberry">Blueberry</Select.Item>
	</Select.Content>
</Select.Root>

<Select.Root validation="error">
	<Select.Trigger className="max-w-64" aria-label="Fruit with error">
		<Select.Value placeholder="Select a fruit" />
	</Select.Trigger>
	<Select.Content width="trigger">
		<Select.Item value="apple">Apple</Select.Item>
		<Select.Item value="banana">Banana</Select.Item>
		<Select.Item value="blueberry">Blueberry</Select.Item>
	</Select.Content>
</Select.Root>

<Select.Root validation="success">
	<Select.Trigger className="max-w-64" aria-label="Fruit with success">
		<Select.Value placeholder="Select a fruit" />
	</Select.Trigger>
	<Select.Content width="trigger">
		<Select.Item value="apple">Apple</Select.Item>
		<Select.Item value="banana">Banana</Select.Item>
		<Select.Item value="blueberry">Blueberry</Select.Item>
	</Select.Content>
</Select.Root>

<Select.Root validation="warning">
	<Select.Trigger className="max-w-64" aria-label="Fruit with warning">
		<Select.Value placeholder="Select a fruit" />
	</Select.Trigger>
	<Select.Content width="trigger">
		<Select.Item value="apple">Apple</Select.Item>
		<Select.Item value="banana">Banana</Select.Item>
		<Select.Item value="blueberry">Blueberry</Select.Item>
	</Select.Content>
</Select.Root>;
```

### Custom selected value

By default the selected item's text will be rendered when selected. Sometimes you may need to render something different. You can control the select and pass `children` instead.

```tsx
import { Select } from "@ngrok/mantle/select";

<Select.Root value={value} onValueChange={setValue}>
	<Select.Trigger className="w-45">
		<Select.Value placeholder="Select a fruit">
			{value === "apple" ? <>🍎 Apple!</> : <>🍑 Peach!</>}
		</Select.Value>
	</Select.Trigger>
	<Select.Content width="trigger">
		<Select.Item value="apple">Apple</Select.Item>
		<Select.Item value="peach">Peach</Select.Item>
	</Select.Content>
</Select.Root>;
```

## Composition

Compose the parts of a `Select` together to build your own:

```text showLineNumbers=false
Select.Root
├── Select.Trigger
│   └── Select.Value
└── Select.Content
    ├── Select.Group
    │   ├── Select.Label
    │   └── Select.Item
    └── Select.Separator
```

## API Reference

The `Select` components are built on top of [Radix Select](https://www.radix-ui.com/primitives/docs/components/select).

### Select.Root

Displays a list of options for the user to pick from—triggered by a button.

Set `validation` on `Select.Root` when the whole select has an explicit state; this root-level state is forwarded to the trigger and takes precedence over ambient field-level validation from `Field.Item`.

Rendered `Field.Errors` or `Field.ErrorList` still force the trigger into the error state because `Field.Control` sets `aria-invalid="true"` on the focusable trigger, and an explicit invalid ARIA value always wins. If a non-error `Select.Root` state needs to win even when errors are rendered, pass `validation` on `Field.Item` to suppress the inferred error.

All props from Radix [Select.Root](https://www.radix-ui.com/primitives/docs/components/select#root), plus:

| Prop             | Type                                                                                               | Default | Description                                                                                                                                                                                                                                                                                                                               |
| ---------------- | -------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onValueChange?` | `(value: string) => void`                                                                          |         | Event handler called when the value changes.                                                                                                                                                                                                                                                                                              |
| `validation?`    | `"error" \| "success" \| "warning" \| false \| (() => "error" \| "success" \| "warning" \| false)` |         | Use the `validation` prop to show if the select trigger has a specific validation status. This will change the border and outline of the select trigger. The `false` type is useful when using short-circuiting logic so that you don't need to use a ternary with `undefined`. Setting `validation` to `error` also sets `aria-invalid`. |

### Select.Trigger

The button that toggles the `Select`. The `Select.Content` will position itself adjacent to the trigger.

When composing with `Field.Item`, wrap `Select.Root` (not the trigger) in `Field.Control`. The generated `id`, `name`, and `aria-invalid` flow onto `Select.Root` — so the hidden form input picks up the field name — and the trigger reads `aria-describedby` / `aria-errormessage` from `FieldControlContext`. Validation resolves from explicit `Select.Root`, then `Select.Trigger`, then the nearest `Field.Item`.

All props from Radix [Select.Trigger](https://www.radix-ui.com/primitives/docs/components/select#trigger), plus:

| Prop          | Type                                                                                               | Default | Description                                                                                                                                                                                                                                                                                                                               |
| ------------- | -------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `validation?` | `"error" \| "success" \| "warning" \| false \| (() => "error" \| "success" \| "warning" \| false)` |         | Use the `validation` prop to show if the select trigger has a specific validation status. This will change the border and outline of the select trigger. The `false` type is useful when using short-circuiting logic so that you don't need to use a ternary with `undefined`. Setting `validation` to `error` also sets `aria-invalid`. |

### Select.Value

The part that reflects the selected value. By default the selected item's text will be rendered. If you require more control, you can instead control the `Select` and pass your own children. It should not be styled to ensure correct positioning. An optional placeholder prop is also available for when the `Select` has no value.

Radix [Select.Value](https://www.radix-ui.com/primitives/docs/components/select#value) props.

### Select.Content

The component that pops out when the `Select` is open as a portal adjacent to the `Select.Trigger` button. It contains a scrolling viewport of the select items.

All props from Radix [Select.Content](https://www.radix-ui.com/primitives/docs/components/select#content), plus:

| Prop     | Type                     | Default     | Description                                                                                                                                                                                  |
| -------- | ------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `width?` | `"trigger" \| "content"` | `"trigger"` | `trigger` will ensure the content is the same width as the trigger button. `content` will make it the intrinsic size of the content itself; it will be the width of the longest/widest item. |

### Select.Group

A group of related options within a select menu. Similar to an html `optgroup` element. Use in conjunction with `Select.Label` to ensure good accessibility via automatic labelling.

Radix [Select.Group](https://www.radix-ui.com/primitives/docs/components/select#group) props.

### Select.Separator

Used to visually separate items in the select. Composed from [Mantle Separator](/components/separator).

### Select.Item

An option within a select menu. Similar to an html `option` element. Has a required `value` prop that will be passed to the `onValueChange` handler of the `Select` component when this item is selected. Displays the children as the option's text.

Radix [Select.Item](https://www.radix-ui.com/primitives/docs/components/select#item) props.

### Select.Label

Used to render the label of a group. It won't be focusable using arrow keys. Use in conjunction with `Select.Group` to ensure good accessibility via automatic labelling of a group.

Radix [Select.Label](https://www.radix-ui.com/primitives/docs/components/select#label) props.

---

---
title: Separator
description: Visually or semantically separates content.
---

# Separator

Visually or semantically separates content.

```tsx
import { HorizontalSeparatorGroup, Separator } from "@ngrok/mantle/separator";

<div>
	<div className="space-y-1">
		<h4 className="text-sm font-medium leading-none">mantle</h4>
		<p className="text-muted-foreground text-sm">An open-source UI component library.</p>
	</div>
	<Separator className="my-4" />
	<Separator className="my-4" semantic />
	<div className="flex h-5 items-center gap-4 text-sm">
		Blog
		<Separator orientation="vertical" />
		Docs
		<Separator orientation="vertical" />
		Source
	</div>
	<HorizontalSeparatorGroup>
		<Separator />
		<h3>ngrok mantle</h3>
		<Separator />
	</HorizontalSeparatorGroup>
	<HorizontalSeparatorGroup>
		<h3>ngrok mantle</h3>
		<Separator />
	</HorizontalSeparatorGroup>
	<HorizontalSeparatorGroup>
		<Separator />
		<h3>ngrok mantle</h3>
	</HorizontalSeparatorGroup>
</div>;
```

## Polymorphism

When you want to render *something else* as a `HorizontalSeparatorGroup` or `Separator`, you can use the `asChild` prop to compose.

```tsx
import { HorizontalSeparatorGroup, Separator } from "@ngrok/mantle/separator";

<form>
	<fieldset className="space-y-4">
		<HorizontalSeparatorGroup className="w-full" asChild>
			<legend>
				Choose your favorite fruit!
				<Separator asChild>
					<span />
				</Separator>
			</legend>
		</HorizontalSeparatorGroup>
		<div className="space-y-2">
			<div className="space-x-2">
				<input type="radio" id="apple" name="monster" value="apple" />
				<label htmlFor="apple">Apple</label>
			</div>
			<div className="space-x-2">
				<input type="radio" id="mango" name="monster" value="mango" />
				<label htmlFor="mango">Mango</label>
			</div>
			<div className="space-x-2">
				<input type="radio" id="pear" name="monster" value="pear" />
				<label htmlFor="pear">Pear</label>
			</div>
		</div>
	</fieldset>
</form>

<div className="flex h-5 items-center space-x-4 text-sm">
	<div>Blog</div>
	<Separator orientation="vertical" asChild>
		<span />
	</Separator>
	<div>Docs</div>
	<Separator orientation="vertical" asChild>
		<span />
	</Separator>
	<div>Source</div>
</div>
```

## API Reference

### Separator

Visually or semantically separates content.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop           | Type                           | Default        | Description                                                                                                                                                                                                                                                                          |
| -------------- | ------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `orientation?` | `"horizontal"` \| `"vertical"` | `"horizontal"` | The orientation of the separator, does it render horizontally or vertically.                                                                                                                                                                                                         |
| `semantic?`    | `boolean`                      | `false`        | If `true`, the separator will be rendered with all accessibility-related attributes and `role="separator"`. If `false`, the separator is purely decorative and all accessibility-related attributes are updated so that the rendered element is removed from the accessibility tree. |
| `asChild?`     | `boolean`                      | `false`        | Use the `asChild` prop to compose the `Separator` styling and functionality onto alternative element types or your own React components.                                                                                                                                             |

### HorizontalSeparatorGroup

A container to layout a group of horizontal separators and other children.
Overrides all children `Separator`s to be `orientation="horizontal"`.
All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop       | Type      | Default | Description                                                                                                                                             |
| ---------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `HorizontalSeparatorGroup` styling and functionality onto alternative element types or your own React components. |

---

---
title: Sheet
description: A container that overlays the current view from the edge of the screen.
---

# Sheet

A container that overlays the current view from the edge of the screen. It is a lightweight way of allowing users to complete a task without losing contextual information of the view beneath it.

## When to use

Use `Sheet` for side-panel content that slides in from any edge — filter panels, detail/inspector views, navigation drawers, mobile menus. For a centered modal, use [`Dialog`](/components/dialog) or [`AlertDialog`](/components/alert-dialog) (for destructive confirmations).

```tsx
import { Button, IconButton } from "@ngrok/mantle/button";
import { Separator } from "@ngrok/mantle/separator";
import { Sheet } from "@ngrok/mantle/sheet";
import { ListMagnifyingGlassIcon } from "@phosphor-icons/react/ListMagnifyingGlass";
import { TerminalWindowIcon } from "@phosphor-icons/react/TerminalWindow";
import { TrashSimpleIcon } from "@phosphor-icons/react/TrashSimple";

<Sheet.Root>
	<Sheet.Trigger asChild>
		<Button type="button" appearance="filled" priority="neutral">
			Open Sheet
		</Button>
	</Sheet.Trigger>
	<Sheet.Content>
		<Sheet.Header>
			<Sheet.TitleGroup>
				<Sheet.Title>Are you absolutely sure?</Sheet.Title>
				<Sheet.Actions>
					<IconButton
						appearance="ghost"
						type="button"
						icon={<TerminalWindowIcon />}
						label="Start a Tunnel"
					/>
					<IconButton
						appearance="ghost"
						type="button"
						icon={<ListMagnifyingGlassIcon />}
						label="See Traffic"
					/>
					<IconButton appearance="ghost" type="button" icon={<TrashSimpleIcon />} label="Delete" />
					<Separator orientation="vertical" className="h-[80%]" />
					<Sheet.CloseIconButton />
				</Sheet.Actions>
			</Sheet.TitleGroup>
			<Sheet.Description>
				This action cannot be undone. This will permanently delete your account and remove your data
				from our servers.
			</Sheet.Description>
		</Sheet.Header>
		<Sheet.Body className="space-y-4">
			<p>Lorem ipsum</p>
		</Sheet.Body>
		<Sheet.Footer>
			<Sheet.Close asChild>
				<Button type="button" appearance="outlined" priority="neutral">
					Close
				</Button>
			</Sheet.Close>
		</Sheet.Footer>
	</Sheet.Content>
</Sheet.Root>;
```

## Examples

### Router or state management controlled Sheet

You can control when to render a Sheet with a router or via outside state management. This will allow you to open and close the Sheet programmatically without using a `Sheet.Trigger`.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Sheet } from "@ngrok/mantle/sheet";
import { useNavigate } from "react-router";

// this is a react-router route module component export
export default function Component() {
	const navigate = useNavigate();

return (
		<Sheet.Root open onOpenChange={() => navigate("..")}>
			<Sheet.Content>
				<Sheet.Header>
					<Sheet.TitleGroup>
						<Sheet.Title>A controlled Sheet</Sheet.Title>
						<Sheet.Actions>
							<Sheet.CloseIconButton />
						</Sheet.Actions>
					</Sheet.TitleGroup>
					<Sheet.Description>
						This sheet is controlled by a router or state manager.
					</Sheet.Description>
				</Sheet.Header>
				<Sheet.Body>
					<p>
						Consequat do voluptate culpa fugiat consequat nostrud duis aliqua minim. Tempor
						voluptate cillum elit velit. Voluptate aliqua ipsum aliqua dolore in nisi ea fugiat
						aliqua velit proident amet.
					</p>
				</Sheet.Body>
				<Sheet.Footer>
					<Sheet.Close asChild>
						<Button type="button" appearance="outlined" priority="neutral">
							Close
						</Button>
					</Sheet.Close>
				</Sheet.Footer>
			</Sheet.Content>
		</Sheet.Root>
	);
}
```

### Setting a preferred width of the Sheet

By default, a `Sheet`'s content width is responsive with a default *preferred width*: the maximum width of the `Sheet.Content` when the window viewport is larger than the mobile breakpoint (`sm`). You can control the preferred width of the `Sheet.Content` by using the `preferredWidth` prop:

```tsx
import { Button } from "@ngrok/mantle/button";
import { Sheet } from "@ngrok/mantle/sheet";

<Sheet.Root>
	<Sheet.Trigger asChild>
		<Button type="button" appearance="filled" priority="neutral">
			Open 800px wide Sheet
		</Button>
	</Sheet.Trigger>
	{/* using the 👇 `preferredWidth` prop */}
	<Sheet.Content preferredWidth="sm:max-w-[800px]">
		<Sheet.Header>
			<Sheet.TitleGroup>
				<Sheet.Title>Tempor pariatur fugiat fugiat cupidatat velit.</Sheet.Title>
				<Sheet.Actions>
					<Sheet.CloseIconButton />
				</Sheet.Actions>
			</Sheet.TitleGroup>
		</Sheet.Header>
		<Sheet.Body className="space-y-4">
			<p>
				Consequat do voluptate culpa fugiat consequat nostrud duis aliqua minim. Tempor voluptate
				cillum elit velit. Voluptate aliqua ipsum aliqua dolore in nisi ea fugiat aliqua velit
				proident amet.
			</p>
		</Sheet.Body>
		<Sheet.Footer>
			<Sheet.Close asChild>
				<Button type="button" appearance="outlined" priority="neutral">
					Close
				</Button>
			</Sheet.Close>
			<Button type="button" appearance="filled" priority="neutral">
				Save
			</Button>
		</Sheet.Footer>
	</Sheet.Content>
</Sheet.Root>;
```

## Composition

Compose the parts of a `Sheet` together to build your own:

```text showLineNumbers=false
Sheet.Root
├── Sheet.Trigger
└── Sheet.Content
    ├── Sheet.Header
    │   ├── Sheet.TitleGroup
    │   │   ├── Sheet.Title
    │   │   └── Sheet.Actions
    │   └── Sheet.Description
    ├── Sheet.Body
    └── Sheet.Footer
        └── Sheet.Close
```

## API Reference

The `Sheet` components are built on top of [Radix Dialog](https://www.radix-ui.com/primitives/docs/components/dialog).

### Sheet.Root

The root component for a `Sheet`. Should compose the `Sheet.Trigger` and `Sheet.Content`. Acts as a stateful provider for the Sheet's open/closed state.

All props from Radix [Dialog.Root](https://www.radix-ui.com/primitives/docs/components/dialog#root).

### Sheet.Trigger

The button trigger for a `Sheet`. Should be rendered as a child of the `Sheet` component. Renders an unstyled `button` by default, but can be customized with the `asChild` prop.

All props from Radix [Dialog.Trigger](https://www.radix-ui.com/primitives/docs/components/dialog#trigger).

### Sheet.Close

The close button for a `Sheet`. Should be rendered as a child of the `Sheet.Content` component. Usually contained within the `Sheet.Footer` component. Renders an unstyled `button` by default, but can be customized with the `asChild` prop.

Radix [Dialog.Close](https://www.radix-ui.com/primitives/docs/components/dialog#close) props.

### Sheet.Content

The main container for a `Sheet`. Should be rendered as a child of the `Sheet` component. Renders on top of the overlay backdrop. Should contain the `Sheet.Header`, `Sheet.Body`, and `Sheet.Footer`.

All props from Radix [Dialog.Content](https://www.radix-ui.com/primitives/docs/components/dialog#content), plus:

| Prop              | Type                                     | Default              | Description                                                                                                                                                                                                                                                                   |
| ----------------- | ---------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preferredWidth?` | `string`                                 | `"sm:max-w-[30rem]"` | The preferred width of the `Sheet.Content` as a tailwind `max-w-` class. By default, a `Sheet`'s content width is responsive with a default *preferred width*: the maximum width of the `Sheet.Content` when the window viewport is larger than the mobile breakpoint (`sm`). |
| `side?`           | `"top" \| "bottom" \| "left" \| "right"` | `"right"`            | The side of the screen from which the sheet will animate in from.                                                                                                                                                                                                             |

### Sheet.CloseIconButton

An icon button that closes the `Sheet` when clicked. Should be rendered within the `Sheet.Header` as a child of `Sheet.Actions`.

Same props as [Mantle IconButton](/components/icon-button).

### Sheet.Body

The body container for a `Sheet`. This is where you would typically place the main content of the sheet, such as forms or text. Should be rendered as a child of `Sheet.Content`.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes).

### Sheet.Header

The header container for a `Sheet`. This is where you would typically place the title, description, and actions. Should be rendered as a child of `Sheet.Content`.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes).

### Sheet.Footer

The footer container for a `Sheet`. This is where you would typically place close and submit buttons. Should be rendered as a child of `Sheet.Content`.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes).

### Sheet.Title

The title for a `Sheet`. Typically rendered as a child of `Sheet.TitleGroup`. Defaults to an `h2` element, but can be changed via the `asChild` prop.

All props from Radix [Dialog.Title](https://www.radix-ui.com/primitives/docs/components/dialog#title).

### Sheet.TitleGroup

A group container for the title and actions of a `Sheet`. Typically rendered as a child of `Sheet.Header`.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes).

### Sheet.Description

A description for a `Sheet`. Typically rendered as a child of `Sheet.Header`.

All props from Radix [Dialog.Description](https://www.radix-ui.com/primitives/docs/components/dialog#description).

### Sheet.Actions

A group container for the actions of a `Sheet`. Typically rendered as a child of `Sheet.TitleGroup`.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes).

---

---
title: Skeleton
description: Use to show a placeholder while content is loading.
---

# Skeleton

A skeleton is a placeholder for content that is loading. By rendering a neutral block where real content will eventually appear, you give the user an early sense of layout and reduce both perceived loading time and Cumulative Layout Shift (CLS).

## When to use

- Async-loaded content where the eventual shape is predictable (lists, cards, tables, avatars).
- On initial page load, before data has resolved.

## When not to use

- For very short fetches (under \~200 ms) — a flash of skeleton is more distracting than helpful.
- To convey error or empty states. Use [`Empty`](/components/empty) instead.
- As a permanent decorative shape.

## Sizing

Default height is `1rem`. Override `className` with `h-*`, `w-*`, and `rounded-*` utilities to match the real content's dimensions — the more closely the skeleton matches, the less layout shift on swap.

## Accessibility

Skeletons are decorative and convey no semantic meaning to assistive tech. If the underlying region is loading, also announce it to screen readers — e.g. wrap in an element with `role="status"` and a visually-hidden "Loading…" label.

```tsx
<div role="status" aria-live="polite">
	<span className="sr-only">Loading profile…</span>
	<Skeleton className="h-12 w-12 rounded-full" />
</div>
```

```tsx
import { Skeleton } from "@ngrok/mantle/skeleton";

<Skeleton className="w-full" />;
```

## Examples

### Composition: Skeleton within a Media Object

The Skeleton component can be included within components. You can also pass Tailwind utility classes for further control.

```tsx
import { MediaObject } from "@ngrok/mantle/media-object";
import { Skeleton } from "@ngrok/mantle/skeleton";

<MediaObject.Root className="w-full max-w-96 items-center">
	<MediaObject.Media>
		<Skeleton className="h-12 w-12 rounded-full" />
	</MediaObject.Media>
	<MediaObject.Content className="space-y-3">
		<Skeleton className="w-full" />
		<Skeleton className="w-4/5" />
	</MediaObject.Content>
</MediaObject.Root>;
```

## API Reference

### Skeleton

The `Skeleton` accepts the following props in addition to the [standard HTML div attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes).

---

---
title: SkipToMainLink
description: A visually-hidden-until-focused "skip link" that lets keyboard users jump to the page's main content landmark.
---

# SkipToMainLink

A visually-hidden-until-focused "skip link" that lets keyboard users jump past repeated navigation and land directly on the page's main content landmark. When activated, it focuses the element identified by `targetId` (defaulting to `"main"`) without scrolling, and updates the URL hash using the browser History API — so it works in any framework, including React Router, Next.js, or plain HTML.

Pair with the [`Main`](/components/main) component (or any element with a matching `id` and `tabIndex={-1}`) so it can receive focus.

```tsx
import { SkipToMainLink } from "@ngrok/mantle/skip-to-main-link";
import { Main } from "@ngrok/mantle/main";

<SkipToMainLink />
<Header />
<Main>
	<h1>Page title</h1>
</Main>
```

## API Reference

### SkipToMainLink

Renders an anchor element that is visually hidden until focused. Accepts all standard `<a>` HTML attributes except `href`, which is derived from `targetId`.

| Prop        | Type        | Default                  | Description                                                                                  |
| ----------- | ----------- | ------------------------ | -------------------------------------------------------------------------------------------- |
| `targetId?` | `string`    | `"main"`                 | The `id` of the element to focus when activated. The link's `href` is set to `#${targetId}`. |
| `children?` | `ReactNode` | `"Skip to main content"` | The label displayed when the link is focused.                                                |

---

---
title: Slider
description: An input where the user selects a value from within a given range.
---

# Slider

An input where the user selects a value from within a given range.

Pair with `Field.*` for description/error wiring in forms. Pass `aria-label` to `Slider` so the rendered thumb has an accessible name:

```tsx
import { Field } from "@ngrok/mantle/field";
import { Slider } from "@ngrok/mantle/slider";

<Field.Item name="volume">
	<Field.Label>Volume</Field.Label>
	<Field.Control>
		<Slider aria-label="Volume" defaultValue={67} max={100} step={1} />
	</Field.Control>
	<Field.Description>Drag to adjust playback volume.</Field.Description>
</Field.Item>;
```

Or render the control on its own:

```tsx
import { Slider } from "@ngrok/mantle/slider";

<Slider aria-label="Volume" defaultValue={67} max={100} step={1} />
<Slider aria-label="Disabled volume" defaultValue={67} max={100} step={1} disabled />
<Slider aria-label="Vertical volume" defaultValue={67} max={100} step={1} orientation="vertical" />
```

## Examples

### With TanStack Form

Use `@tanstack/react-form` with `zod` to keep a single-thumb slider controlled. Radix emits slider values as an array, so pass the first value into `field.handleChange`.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Field, toErrorMessages } from "@ngrok/mantle/field";
import { Slider } from "@ngrok/mantle/slider";
import { useForm } from "@tanstack/react-form";
import { z } from "zod";

export const formSchema = z.object({
	volume: z.number().min(25, "Choose at least 25."),
});
function Example() {
	const defaultValues = {
		volume: 50,
	};
	const form = useForm({
		defaultValues,
		validators: {
			onSubmit: formSchema,
		},
		onSubmit: ({ value }) => {
			// Handle form submission here
		},
	});

return (
		<form
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<form.Field name="volume">
				{(field) => (
					<Field.Item name={field.name}>
						<Field.Label>Volume</Field.Label>
						<Field.Control>
							<Slider
								aria-label="Volume"
								value={field.state.value}
								onBlur={field.handleBlur}
								onValueChange={(value) => field.handleChange(value[0] ?? 0)}
								max={100}
								step={1}
							/>
						</Field.Control>
						<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
					</Field.Item>
				)}
			</form.Field>
			<Button type="submit" appearance="filled" priority="neutral">
				Submit
			</Button>
		</form>
	);
}
```

### Single Thumb

A basic slider with a single thumb for selecting a single value. You can pass a single number instead of an array.

```tsx
import { Slider } from "@ngrok/mantle/slider";

<Slider aria-label="Volume" defaultValue={75} max={100} step={1} />;
```

### Range

Use two values to create a range slider with two thumbs.

```tsx
import { Slider } from "@ngrok/mantle/slider";

<Slider aria-label="Price" defaultValue={[25, 50]} max={100} step={5} />;
```

### Multiple Thumbs

Use more than two values to create a slider with multiple thumbs.

```tsx
import { Slider } from "@ngrok/mantle/slider";

<Slider aria-label="Breakpoint" defaultValue={[10, 20, 70]} max={100} step={10} />;
```

### Color

Use the `color` prop to change the color of the slider range. Accepts any Tailwind `bg-*` class.

```tsx
import { Slider } from "@ngrok/mantle/slider";

<Slider aria-label="Warning threshold" defaultValue={67} max={100} step={1} color="bg-warning-600" />
<Slider aria-label="Danger threshold" defaultValue={67} max={100} step={1} color="bg-danger-600" />
<Slider aria-label="Success threshold" defaultValue={67} max={100} step={1} color="bg-emerald-600" />
```

### Ticks

Use the `showTicks` prop to show tick marks at each `step` interval along the track.

```tsx
import { Slider } from "@ngrok/mantle/slider";

<Slider aria-label="Volume" defaultValue={50} max={100} step={10} showTicks />
<Slider aria-label="Price" defaultValue={[20, 80]} max={100} step={20} showTicks />
```

## API Reference

### Slider

The `Slider` is built on top of [Radix Slider](https://www.radix-ui.com/primitives/docs/components/slider). It accepts all props from the Radix Slider Root component.

`defaultValue` and `value` both accept `number | number[]`, but they must be the same type — you cannot mix a single `number` with a `number[]`.

| Prop                    | Type                           | Default           | Description                                                                                                   |
| :---------------------- | :----------------------------- | :---------------- | :------------------------------------------------------------------------------------------------------------ |
| `color`                 | `` `bg-${string}` ``           | `"bg-accent-500"` | The color of the slider range. Accepts any Tailwind `bg-*` class.                                             |
| `aria-label`            | `string`                       | —                 | Accessible name forwarded to the rendered thumb. Range sliders derive per-thumb labels from it.               |
| `aria-labelledby`       | `string`                       | —                 | IDREF forwarded to the rendered thumb when another element provides the accessible name.                      |
| `defaultValue`          | `number` \| `number[]`         | —                 | The value of the slider when initially rendered. Use when you do not need to control the state of the slider. |
| `showTicks`             | `boolean`                      | `false`           | Whether to show tick marks along the track at each `step` interval.                                           |
| `value`                 | `number` \| `number[]`         | —                 | The controlled value of the slider. Must be used with `onValueChange`.                                        |
| `onValueChange`         | `(value: number[]) => void`    | —                 | Event handler called when the value changes.                                                                  |
| `onValueCommit`         | `(value: number[]) => void`    | —                 | Event handler called when the value changes at the end of an interaction (e.g. on mouse up or on blur).       |
| `name`                  | `string`                       | —                 | The name of the slider. Submitted with its owning form as part of a name/value pair.                          |
| `disabled`              | `boolean`                      | `false`           | When `true`, prevents the user from interacting with the slider.                                              |
| `orientation`           | `"horizontal"` \| `"vertical"` | `"horizontal"`    | The orientation of the slider.                                                                                |
| `min`                   | `number`                       | `0`               | The minimum value for the range.                                                                              |
| `max`                   | `number`                       | `100`             | The maximum value for the range.                                                                              |
| `step`                  | `number`                       | `1`               | The stepping interval.                                                                                        |
| `minStepsBetweenThumbs` | `number`                       | `0`               | The minimum permitted steps between multiple thumbs.                                                          |
| `inverted`              | `boolean`                      | `false`           | Whether the slider is visually inverted.                                                                      |

---

---
title: Slot
description: Merges its props onto its immediate child.
---

# Slot

Merges its props onto its immediate child. This is a utility component used internally by other components to enable the `asChild` pattern.

```tsx
import { Slot } from "@ngrok/mantle/slot";

<Slot className="rounded bg-blue-500 px-4 py-2 text-white">
	<a href="https://ngrok.com">Visit ngrok</a>
</Slot>

<Slot className="rounded bg-red-500 px-4 py-2 text-white">
	<button type="button">Click me</button>
</Slot>
```

## Usage with asChild

The `Slot` component is the foundation of the `asChild` pattern used throughout Mantle. When a component supports `asChild`, it uses `Slot` internally to merge its props onto the child element instead of rendering a wrapper.

```tsx
import { Button } from "@ngrok/mantle/button";

<Button appearance="filled" priority="neutral" asChild>
	<a href="https://ngrok.com">Visit ngrok</a>
</Button>

<Button appearance="outlined" priority="neutral" asChild>
	<a href="https://github.com/ngrok/ngrok">View on GitHub</a>
</Button>
```

## Class Name Merging

`Slot` automatically merges `className` props using Tailwind CSS's merge logic. Child classes take priority over parent classes for conflicting styles, while non-conflicting classes are preserved.

```tsx
import { Slot } from "@ngrok/mantle/slot";

<Slot className="rounded bg-blue-500 px-4 text-white">
	<div className="bg-red-500 py-2">Child bg-red-500 wins, parent px-4 and py-2 merge</div>
</Slot>;

// Result: className="bg-red-500 rounded px-4 py-2 text-white"
```

## API Reference

### Slot

Merges its props onto its immediate child element. Automatically handles className merging with Tailwind CSS merge logic.

Based on [Radix UI Slot](https://www.radix-ui.com/primitives/docs/utilities/slot).

---

---
title: Split Button
description: A button group which provides a default action with one click while revealing related alternatives through a dropdown menu.
---

# Split Button

A button group which provides a default action with one click while revealing related alternatives through a dropdown menu. Best for when users typically want one action but occasionally need variants.

```tsx
import { CopyIcon, FileTextIcon } from "@phosphor-icons/react";
import { Icon } from "@ngrok/mantle/icon";
import { SplitButton } from "@ngrok/mantle/split-button";

<SplitButton.Root>
	<SplitButton.PrimaryAction icon={<CopyIcon />}>Copy page</SplitButton.PrimaryAction>
	<SplitButton.MenuTrigger label="Open actions menu" />
	<SplitButton.MenuContent>
		<SplitButton.MenuItem>
			<Icon svg={<CopyIcon />} />
			Copy page
		</SplitButton.MenuItem>
		<SplitButton.MenuItem>
			<Icon svg={<FileTextIcon />} />
			View as Markdown
		</SplitButton.MenuItem>
	</SplitButton.MenuContent>
</SplitButton.Root>;
```

## Composition

Compose the parts of a `SplitButton` together to build your own:

```text showLineNumbers=false
SplitButton.Root
├── SplitButton.PrimaryAction
├── SplitButton.MenuTrigger
└── SplitButton.MenuContent
    └── SplitButton.MenuItem
```

## Polymorphism

When you want to render *something else* as a `SplitButton.MenuItem`, you can use the `asChild` prop to compose. This is useful for rendering links as menu items.

```tsx
import { DownloadIcon, FileTextIcon } from "@phosphor-icons/react";
import { Icon } from "@ngrok/mantle/icon";
import { SplitButton } from "@ngrok/mantle/split-button";

<SplitButton.Root>
	<SplitButton.PrimaryAction icon={<DownloadIcon />}>Download</SplitButton.PrimaryAction>
	<SplitButton.MenuTrigger label="Open download options" />
	<SplitButton.MenuContent>
		<SplitButton.MenuItem>
			<Icon svg={<DownloadIcon />} />
			Download as PDF
		</SplitButton.MenuItem>
		<SplitButton.MenuItem asChild>
			<a href="https://example.com" target="_blank">
				<Icon svg={<FileTextIcon />} />
				Open in new tab
			</a>
		</SplitButton.MenuItem>
	</SplitButton.MenuContent>
</SplitButton.Root>;
```

## API Reference

### SplitButton.Root

A button group which provides a default action with one click while revealing related alternatives through a dropdown menu.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes), plus:

| Prop            | Type                      | Default | Description                                                        |
| --------------- | ------------------------- | ------- | ------------------------------------------------------------------ |
| `dir?`          | `"ltr"` \| `"rtl"`        |         | The reading direction of the dropdown menu.                        |
| `open?`         | `boolean`                 |         | The controlled open state of the dropdown menu.                    |
| `defaultOpen?`  | `boolean`                 |         | The open state of the dropdown menu when it is initially rendered. |
| `onOpenChange?` | `(open: boolean) => void` |         | Event handler called when the open state of the dropdown changes.  |
| `modal?`        | `boolean`                 |         | Whether the dropdown menu is modal.                                |

### SplitButton.PrimaryAction

The most common action users can trigger with a single click. Renders as a `Button` with `appearance="outlined"` and `priority="neutral"`.

All props from [`Button`](/components/button), except `appearance` and `priority`.

| Prop    | Type                                  | Default    | Description                       |
| ------- | ------------------------------------- | ---------- | --------------------------------- |
| `type?` | `"button"` \| `"submit"` \| `"reset"` | `"button"` | The type attribute of the button. |

### SplitButton.MenuTrigger

The button that opens the split button dropdown menu. Renders as an `IconButton` with a caret-down icon that rotates when the menu is open.

All props from [`IconButton`](/components/icon-button), except `appearance`, `size`, `asChild`, and `icon` (which is redefined as optional below).

| Prop    | Type                                  | Default         | Description                                              |
| ------- | ------------------------------------- | --------------- | -------------------------------------------------------- |
| `icon?` | `ReactNode`                           | Caret-down icon | Custom icon to render instead of the default caret-down. |
| `type?` | `"button"` \| `"submit"` \| `"reset"` | `"button"`      | The type attribute of the button.                        |

### SplitButton.MenuContent

The container for the split button dropdown menu content. Appears in a portal with scrolling and animations. Wraps `DropdownMenu.Content`.

All props from [`DropdownMenu.Content`](/components/dropdown-menu).

| Prop     | Type                               | Default | Description                                  |
| -------- | ---------------------------------- | ------- | -------------------------------------------- |
| `align?` | `"start"` \| `"center"` \| `"end"` | `"end"` | The preferred alignment against the trigger. |

### SplitButton.MenuItem

A standard item in the split button dropdown menu that can be selected or activated. Wraps `DropdownMenu.Item` with `gap-2` styling.

All props from [`DropdownMenu.Item`](/components/dropdown-menu).

| Prop       | Type      | Default | Description                                                                                         |
| ---------- | --------- | ------- | --------------------------------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose onto alternative element types like anchors or custom components. |

---

---
title: Switch
description: A control that allows the user to toggle between checked and not checked.
---

# Switch

A control that allows the user to toggle between checked and not checked.

Pair with `Field.*` for label/description/error wiring in forms:

```tsx
import { Field } from "@ngrok/mantle/field";
import { Switch } from "@ngrok/mantle/switch";

<Field.Item name="airplane-mode-field">
	<Field.Label className="inline-flex items-center gap-2">
		<Field.Control>
			<Switch />
		</Field.Control>
		Airplane Mode
	</Field.Label>
	<Field.Description>Disables wireless radios while in flight.</Field.Description>
</Field.Item>;
```

Or render the control on its own:

```tsx
import { Label } from "@ngrok/mantle/label";
import { Switch } from "@ngrok/mantle/switch";

<Label htmlFor="airplane-mode" className="flex items-center gap-2">
	Airplane Mode
	<Switch id="airplane-mode" />
</Label>;
```

## Examples

### Switch in a form with client-side validation

In this example, the `Switch` is used in a form with client-side validation. The form is built using [`@tanstack/react-form`](https://tanstack.com/form/latest/docs) and `zod` for validation. The form accepts and validates the input before submission.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Field, toErrorMessages } from "@ngrok/mantle/field";
import { Switch } from "@ngrok/mantle/switch";
import { useForm } from "@tanstack/react-form";
import { z } from "zod";

return (
		<form
			className="space-y-4"
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<form.Field name="airplaneMode">
				{(field) => (
					<Field.Item name={field.name}>
						<Field.Label className="flex items-center gap-2">
							Airplane Mode
							<Field.Control>
								<Switch
									checked={field.state.value}
									onBlur={field.handleBlur}
									onCheckedChange={(value) => field.handleChange(value)}
								/>
							</Field.Control>
						</Field.Label>
						<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
					</Field.Item>
				)}
			</form.Field>
			<Button type="submit" appearance="filled" priority="neutral">
				Submit
			</Button>
		</form>
	);
}
```

## API Reference

### Switch

The `Switch` is built on top of [Radix Switch](https://www.radix-ui.com/primitives/docs/components/switch). It exposes the same API with the following additional props:

---

---
title: Table
description: A structured way to display data in rows and columns.
---

# Table

A structured way to display data in rows and columns.

## When to use

`Table` is the thin, semantic primitive for static tabular content — invoice summaries, pricing matrices, reference tables in documentation. Rows and cells render exactly what you put in them; there is no sorting, filtering, selection, or pagination built in.

- Prefer [`DataTable`](/components/data-table) for dynamic, application data — anywhere users need to sort, filter, paginate, select, or click rows. `DataTable` is built on top of `Table` and powered by [TanStack Table](https://tanstack.com/table/latest/docs/introduction).
- Use `Table` directly only when your data is static and none of those behaviors apply.

```tsx
import { Table } from "@ngrok/mantle/table";

## Composition

Compose the parts of a `Table` together to build your own:

```text showLineNumbers=false
Table.Root
└── Table.Element
    ├── Table.Caption
    ├── Table.Head
    │   └── Table.Row
    │       └── Table.Header
    ├── Table.Body
    │   └── Table.Row
    │       └── Table.Cell
    └── Table.Foot
```

## API Reference

The `Table` is a structured way to display data in rows and columns. The API matches the HTML `table` element 1:1. It is composed of several sub-components.

### Table.Root

Root container for all `Table` sub-components. Should be the parent of all other table sub-components. It provides styling and additional functionality, such as horizontal overflow detection.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes).

### Table.Element

The API matches the HTML `table` element 1:1.

Permitted content in this order:

1. optional: `Table.Caption`
2. 0 or more: `colgroup` elements
3. optional: `Table.Head`
4. either one of the following:
   - 0 or more: `Table.Body`
   - 0 or more: `Table.Row`
5. optional: `Table.Foot`

All props from [table](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table#attributes).

### Table.Head

Container for the table's column headers. Encapsulates a set of `Table.Row`s, indicating that they comprise the head of a table with information about the table's columns.

All props from [thead](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/thead#attributes).

### Table.Body

Encapsulates a set of `Table.Row`s, indicating that they comprise the body of a table's (main) data.

All props from [tbody](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tbody#attributes).

### Table.Foot

Encapsulates a set of `Table.Row`s, indicating that they comprise the foot of a table with information about the table's columns. This is usually a summary of the columns, e.g., a sum of the given numbers in a column.

All props from [tfoot](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tfoot#attributes).

### Table.Row

Defines a row of cells in a table. The row's cells can then be established using a mix of `Table.Cell` and `Table.Header` components.

All props from [tr](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tr#attributes).

### Table.Header

Defines a cell as the header of a group of table cells and may be used as a child of a `Table.Row`.

All props from [th](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th#attributes).

### Table.Cell

Defines a cell of a table that contains data and may be used as a child of a `Table.Row`.

All props from [td](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td#attributes).

### Table.Caption

Specifies the caption (or title) of a table, providing the table an accessible description.

All props from [caption](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption#attributes).

---

---
title: Tabs
description: A set of layered sections of content—known as tab panels—that are displayed one at a time.
---

# Tabs

A set of layered sections of content—known as tab panels—that are displayed one at a time.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Card } from "@ngrok/mantle/card";
import { Icon } from "@ngrok/mantle/icon";
import { Input, PasswordInput } from "@ngrok/mantle/input";
import { Tabs } from "@ngrok/mantle/tabs";

<Tabs.Root
	appearance="classic"
	orientation="horizontal"
	defaultValue="account"
	className="w-[400px]"
>
	<Tabs.List>
		<Tabs.Trigger value="account">
			<Icon svg={<UserIcon />} />
			Account
			<Tabs.Badge>2</Tabs.Badge>
		</Tabs.Trigger>
		<Tabs.Trigger value="password">
			<Icon svg={<ShieldCheckIcon />} />
			Password
		</Tabs.Trigger>
	</Tabs.List>
	<Tabs.Content value="account">
		<Card.Root>
			<Card.Header>
				<Card.Title>Account</Card.Title>
				<p className="text-muted">
					Make changes to your account here. Click save when you're done.
				</p>
			</Card.Header>
			<Card.Body className="space-y-2">
				<div className="space-y-1">
					<label htmlFor="name">Name</label>
					<Input id="name" defaultValue="Cody Price" />
				</div>
				<div className="space-y-1">
					<label htmlFor="username">Username</label>
					<Input id="username" defaultValue="@cody-dot-js" />
				</div>
			</Card.Body>
			<Card.Footer>
				<Button type="button" appearance="outlined" priority="neutral">
					Save changes
				</Button>
			</Card.Footer>
		</Card.Root>
	</Tabs.Content>
	<Tabs.Content value="password">
		<Card.Root>
			<Card.Header>
				<Card.Title>Password</Card.Title>
				<p className="text-muted">Change your password here. After saving, you'll be logged out.</p>
			</Card.Header>
			<Card.Body className="space-y-2">
				<div className="space-y-1">
					<label htmlFor="current">Current password</label>
					<PasswordInput id="current" />
				</div>
				<div className="space-y-1">
					<label htmlFor="new">New password</label>
					<PasswordInput id="new" />
				</div>
			</Card.Body>
			<Card.Footer>
				<Button type="button" appearance="outlined" priority="neutral">
					Save password
				</Button>
			</Card.Footer>
		</Card.Root>
	</Tabs.Content>
</Tabs.Root>;
```

## Horizontal Overflow

When there are too many tabs to fit the container, the list scrolls horizontally with scroll-position-aware fade shadows at the edges.

```tsx
import { Icon } from "@ngrok/mantle/icon";
import { Tabs } from "@ngrok/mantle/tabs";

<Tabs.Root orientation="horizontal" defaultValue="getting-started">
	<Tabs.List>
		<Tabs.Trigger value="getting-started">
			<Icon svg={<RocketLaunchIcon />} />
			Getting Started
		</Tabs.Trigger>
		<Tabs.Trigger value="traffic-policy">
			<Icon svg={<ArrowsSplitIcon />} />
			Traffic Policy
		</Tabs.Trigger>
		{/* ... more tabs */}
	</Tabs.List>
</Tabs.Root>;
```

## Pill Appearance

Use `appearance="pill"` to render each tab as a pill instead of the default classic underline style.

```tsx
import { Card } from "@ngrok/mantle/card";
import { Icon } from "@ngrok/mantle/icon";
import { Tabs } from "@ngrok/mantle/tabs";

<Tabs.Root appearance="pill" orientation="horizontal" defaultValue="account">
	<Tabs.List>
		<Tabs.Trigger value="account">
			<Icon svg={<UserIcon />} />
			Account
			<Tabs.Badge>2</Tabs.Badge>
		</Tabs.Trigger>
		<Tabs.Trigger value="password">
			<Icon svg={<ShieldCheckIcon />} />
			Password
		</Tabs.Trigger>
	</Tabs.List>
	<Tabs.Content value="account">
		<Card.Root>
			<Card.Header>
				<Card.Title>Account</Card.Title>
			</Card.Header>
		</Card.Root>
	</Tabs.Content>
</Tabs.Root>;
```

## Composition

Compose the parts of `Tabs` together to build your own:

```text showLineNumbers=false
Tabs.Root
├── Tabs.List
│   └── Tabs.Trigger
│       └── Tabs.Badge
└── Tabs.Content
```

## API Reference

The `Tabs` components accept the following props.

### Tabs.Root

The root container of the tabs component that provides context for all tab components. Based on [Radix Tabs Root](https://www.radix-ui.com/primitives/docs/components/tabs#root).

| Prop             | Type                           | Default        | Description                                                                                                                    |
| ---------------- | ------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `defaultValue?`  | `string`                       |                | The value of the tab that should be active when initially rendered. Use when you do not need to control the state of the tabs. |
| `value?`         | `string`                       |                | The controlled value of the tab to activate. Should be used in conjunction with `onValueChange`.                               |
| `onValueChange?` | `(value: string) => void`      |                | Event handler called when the value changes.                                                                                   |
| `orientation?`   | `"horizontal"` \| `"vertical"` | `"horizontal"` | The orientation of the tabs.                                                                                                   |
| `appearance?`    | `"classic"` \| `"pill"`        | `"classic"`    | The appearance of the tabs. Classic appearance shows the tab list with an underline; pill appearance shows each tab as a pill. |
| `className?`     | `string`                       |                | Additional CSS classes to apply to the tabs root element.                                                                      |

### Tabs.List

Contains the triggers that are aligned along the edge of the active content. Based on [Radix Tabs List](https://www.radix-ui.com/primitives/docs/components/tabs#list).

| Prop         | Type     | Default | Description                                               |
| ------------ | -------- | ------- | --------------------------------------------------------- |
| `className?` | `string` |         | Additional CSS classes to apply to the tabs list element. |

### Tabs.Trigger

The button that activates its associated content. Based on [Radix Tabs Trigger](https://www.radix-ui.com/primitives/docs/components/tabs#trigger).

| Prop         | Type      | Default | Description                                                                                                                          |
| ------------ | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `value`      | `string`  |         | A unique value that associates the trigger with a content.                                                                           |
| `asChild?`   | `boolean` | `false` | Use the `asChild` prop to compose the trigger styling and functionality onto alternative element types or your own React components. |
| `disabled?`  | `boolean` | `false` | When `true`, prevents the user from interacting with the tab.                                                                        |
| `className?` | `string`  |         | Additional CSS classes to apply to the trigger element.                                                                              |

### Tabs.Content

Contains the content associated with each trigger. Based on [Radix Tabs Content](https://www.radix-ui.com/primitives/docs/components/tabs#content).

| Prop         | Type     | Default | Description                                                |
| ------------ | -------- | ------- | ---------------------------------------------------------- |
| `value`      | `string` |         | A unique value that associates the content with a trigger. |
| `className?` | `string` |         | Additional CSS classes to apply to the content element.    |

### Tabs.Badge

A badge component that can be used inside tab triggers to display additional information like counts or status indicators.

| Prop         | Type        | Default | Description                                           |
| ------------ | ----------- | ------- | ----------------------------------------------------- |
| `children`   | `ReactNode` |         | The content to be rendered inside the badge.          |
| `className?` | `string`    |         | Additional CSS classes to apply to the badge element. |

---

---
title: TextArea
description: A multi-line plain-text editing control.
---

# TextArea

A multi-line plain-text editing control, useful when you want to allow users to enter a sizeable amount of free-form text, for example a comment on a review or feedback form.

Pair with `Field.*` for label/description/error wiring in forms:

```tsx
import { Field } from "@ngrok/mantle/field";
import { TextArea } from "@ngrok/mantle/text-area";

<Field.Item name="feedback">
	<Field.Label>Default TextArea</Field.Label>
	<Field.Control>
		<TextArea placeholder="Tell us about your experience…" />
	</Field.Control>
</Field.Item>
<Field.Item name="feedback-mono">
	<Field.Label>Monospaced TextArea</Field.Label>
	<Field.Control>
		<TextArea appearance="monospaced" placeholder="Tell us about your experience…" />
	</Field.Control>
</Field.Item>
<Field.Item name="feedback-error">
	<Field.Label>Error TextArea</Field.Label>
	<Field.Control>
		<TextArea placeholder="Tell us about your experience…" validation="error" />
	</Field.Control>
</Field.Item>
```

Or render the control on its own:

```tsx
import { TextArea } from "@ngrok/mantle/text-area";

<TextArea aria-label="Feedback" placeholder="Tell us about your experience…" />;
```

## Examples

### TextArea in a form with client-side validation

In this example, the `TextArea` is used in a form with client-side validation. The form is built using [`@tanstack/react-form`](https://tanstack.com/form/latest/docs) and `zod` for validation. The form accepts user feedback and validates the input before submission.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Field, toErrorMessages } from "@ngrok/mantle/field";
import { TextArea } from "@ngrok/mantle/text-area";
import { useForm } from "@tanstack/react-form";
import { z } from "zod";

return (
		<form
			className="space-y-4"
			onSubmit={(event) => {
				event.preventDefault();
				event.stopPropagation();
				void form.handleSubmit();
			}}
		>
			<form.Field name="feedback">
				{(field) => (
					<Field.Item name={field.name}>
						<Field.Label>Feedback</Field.Label>
						<Field.Control>
							<TextArea
								onBlur={field.handleBlur}
								onChange={(event) => field.handleChange(event.target.value)}
								placeholder="Tell us about your experience…"
								value={field.state.value}
							/>
						</Field.Control>
						<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />
					</Field.Item>
				)}
			</form.Field>
			<Button type="submit" appearance="filled" priority="neutral">
				Submit
			</Button>
		</form>
	);
}
```

## API Reference

### TextArea

A multi-line plain-text editing control.

All props from [textarea](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea), plus:

| Prop          | Type                                                                                                       | Default | Description                                                                                                                                                                                                                                                                                                                   |
| ------------- | ---------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appearance?` | `"monospaced"`                                                                                             |         | Defines the visual style of the `TextArea`.                                                                                                                                                                                                                                                                                   |
| `validation?` | `"error"` \| `"success"` \| `"warning"` \| `false` \| `(() => "error" \| "success" \| "warning" \| false)` |         | Use the `validation` prop to show if the textarea has a specific validation status. This will change the border and outline of the textarea. The `false` type is useful when using short-circuiting logic so that you don't need to use a ternary with `undefined`. Setting `validation` to `error` also sets `aria-invalid`. |

---

---
title: Theme
description: Theme primitives — ThemeProvider, MantleStyleSheets, and FOUC prevention — for light, dark, and high-contrast modes.
---

# Theme

Mantle's theme system provides `ThemeProvider` (context + cookie persistence), `MantleStyleSheets` (lazy-loaded dark/HC CSS via `<link media>`), and `PreventWrongThemeFlashScript` (FOUC prevention inline script) for light, dark, and high-contrast modes.

## Setup

To use the `ThemeProvider`, wrap your application's entry point. This should be done as high in the component tree as possible.

For SSR apps, add `PreventWrongThemeFlashScript` and `MantleStyleSheets` to the `<head>` to prevent a Flash of Unstyled Content (FOUC), and send font preloads as HTTP `Link` response headers using `preloadFontLink`. Delivering font hints as headers starts fetches before the browser parses any HTML, improving LCP on mobile.

`MantleStyleSheets` renders `<link rel="stylesheet">` tags for the dark, light-high-contrast, and dark-high-contrast theme CSS files. Each stylesheet is gated behind a `media` attribute matching its OS preference so it is non-render-blocking for users who do not need it. Pass `ssrCookie` (from `extractThemeCookie`) so the server can render the correct `media` attribute for users with a manually-selected theme — when a non-system theme is resolved from the cookie, the SSR HTML is already correct and no inline fix script is needed, avoiding FOUC without relying on JavaScript hydration.

The CSS URLs must be passed as props. Import them with `?url` in your app code so Vite's URL transform applies correctly:

```ts
// entry.server.tsx — send font preloads as HTTP Link headers
import { assetsCdnOrigin, preloadFontLink } from "@ngrok/mantle/theme";

responseHeaders.set(
	"Link",
	[
		`<${assetsCdnOrigin}>; rel=preconnect; crossorigin`,
		preloadFontLink("roobert"),
		preloadFontLink("jetbrains-mono"),
		preloadFontLink("family-regular"),
	].join(", "),
);
```

```tsx
// root.tsx loader — extract the theme cookie so the server can render the correct media attribute
import { extractThemeCookie } from "@ngrok/mantle/theme";

export async function loader({ request }: Route.LoaderArgs) {
	return {
		ssrCookie: extractThemeCookie(request.headers.get("Cookie")),
		// ...other loader data
	};
}
```

```tsx
// root.tsx — place PreventWrongThemeFlashScript and MantleStyleSheets in <head>
import darkCssUrl from "@ngrok/mantle/mantle-dark.css?url";
import darkHighContrastCssUrl from "@ngrok/mantle/mantle-dark-high-contrast.css?url";
import lightHighContrastCssUrl from "@ngrok/mantle/mantle-light-high-contrast.css?url";
import {
	extractThemeCookie,
	mantleStyleSheetUrls,
	MantleStyleSheets,
	PreventWrongThemeFlashScript,
	ThemeProvider,
	useInitialHtmlThemeProps,
} from "@ngrok/mantle/theme";

const themeUrls = mantleStyleSheetUrls({
	darkCssUrl,
	lightHighContrastCssUrl,
	darkHighContrastCssUrl,
});

export function Layout({ children }: PropsWithChildren) {
	const loaderData = useRouteLoaderData<typeof loader>("root");
	const initialHtmlThemeProps = useInitialHtmlThemeProps({
		className: "h-full",
	});

return (
		<html {...initialHtmlThemeProps} lang="en-US" dir="ltr" suppressHydrationWarning>
			<head>
				{/* 👇 add as early as possible in <head> to prevent FOUC */}
				<PreventWrongThemeFlashScript nonce={nonce} />
				{/* 👇 lazy-loads dark/HC theme stylesheets; media attrs prevent render-blocking */}
				<MantleStyleSheets {...themeUrls} nonce={nonce} ssrCookie={loaderData?.ssrCookie} />
				<meta charSet="utf-8" />
				<meta name="viewport" content="width=device-width, initial-scale=1" />
				<Meta />
				<Links />
			</head>
			<body>
				<ThemeProvider>{children}</ThemeProvider>
			</body>
		</html>
	);
}
```

## Non-SSR / No Header Control

If you cannot set HTTP response headers (e.g. a plain Vite SPA), omit `ssrCookie` from `MantleStyleSheets` and use `PreloadFont` elements instead of `preloadFontLink`. The inline fix script inside `MantleStyleSheets` still handles FOUC correctly at runtime.

```tsx
import darkCssUrl from "@ngrok/mantle/mantle-dark.css?url";
import darkHighContrastCssUrl from "@ngrok/mantle/mantle-dark-high-contrast.css?url";
import lightHighContrastCssUrl from "@ngrok/mantle/mantle-light-high-contrast.css?url";
import {
	mantleStyleSheetUrls,
	MantleStyleSheets,
	PreloadFont,
	PreventWrongThemeFlashScript,
} from "@ngrok/mantle/theme";

const themeUrls = mantleStyleSheetUrls({
	darkCssUrl,
	lightHighContrastCssUrl,
	darkHighContrastCssUrl,
});

<head>
	<PreventWrongThemeFlashScript nonce={nonce} />
	<MantleStyleSheets {...themeUrls} nonce={nonce} />
	<PreloadFont name="roobert" />
	<PreloadFont name="jetbrains-mono" />
	<PreloadFont name="family-regular" />
</head>;
```

## Non-React Head

If your server cannot render React components (e.g. a legacy Go service), inline the two script strings directly into your HTML `<head>`, surrounding the three theme `<link>` tags. Generate the strings via `preventWrongThemeFlashScriptContent` and `fixMediaScriptContent` from `@ngrok/mantle/theme` — run them in a Node.js build step and embed the output into your template.

The FOUC prevention script must run before `<body>` to write `html[data-applied-theme]`. The media fix script must run after the `<link>` tags so they are already in the DOM when it executes.

```html

<script nonce="...">
	(function k(e) {
		let {
			storageKey: t,
			defaultTheme: n,
			themes: r,
			resolvedThemes: i,
			prefersDarkModeMediaQuery: a,
			prefersHighContrastMediaQuery: o,
		} = e;
		function s(e) {
			return typeof e == `string` && r.includes(e);
		}
		function c(e) {
			let t = document.cookie;
			if (!t) return null;
			try {
				let n = t
					.split(`;`)
					.find((t) => t.trim().startsWith(`${e}=`))
					?.split(`=`)[1];
				return n ? decodeURIComponent(n) : null;
			} catch {
				return null;
			}
		}
		function l(e, t) {
			let n = new Date();
			n.setFullYear(n.getFullYear() + 1);
			let r = window.location.hostname,
				i = window.location.protocol,
				a = r === `ngrok.com` || r.endsWith(`.ngrok.com`) ? `; domain=.ngrok.com` : ``,
				o = i === `https:` ? `; Secure` : ``;
			return `${e}=${encodeURIComponent(t)}; expires=${n.toUTCString()}; path=/${a}; SameSite=Lax${o}`;
		}
		function u(e, t) {
			try {
				document.cookie = l(e, t);
			} catch {}
		}
		function d(e, t, n) {
			return e === `system`
				? n
					? t
						? `dark-high-contrast`
						: `light-high-contrast`
					: t
						? `dark`
						: `light`
				: e;
		}
		let f = null,
			p = null,
			m = null;
		try {
			f = c(t);
		} catch {}
		if (s(f)) m = f;
		else {
			try {
				p = window.localStorage?.getItem(t) ?? null;
			} catch {}
			s(p) && (m = p);
		}
		let h = s(m) ? m : n,
			g = matchMedia(a).matches,
			_ = matchMedia(o).matches,
			v = d(h, g, _),
			y = document.documentElement;
		if (y.dataset.appliedTheme !== v || y.dataset.theme !== h) {
			for (let e of i) y.classList.remove(e);
			(y.classList.add(v), (y.dataset.theme = h), (y.dataset.appliedTheme = v));
		}
		let b = s(f);
		try {
			if (s(p) && !b) {
				u(t, p);
				try {
					window.localStorage.removeItem(t);
				} catch {}
			} else b || u(t, h);
		} catch {}
	})({
		storageKey: "mantle-ui-theme",
		defaultTheme: "system",
		themes: ["system", "light", "dark", "light-high-contrast", "dark-high-contrast"],
		resolvedThemes: ["light", "dark", "light-high-contrast", "dark-high-contrast"],
		prefersDarkModeMediaQuery: "(prefers-color-scheme: dark)",
		prefersHighContrastMediaQuery: "(prefers-contrast: more)",
	});
</script>

<link
	id="mantle-dark-styles"
	rel="stylesheet"
	href="/path/to/mantle-dark.css"
	media="(prefers-color-scheme: dark)"
/>

<link
	id="mantle-light-high-contrast-styles"
	rel="stylesheet"
	href="/path/to/mantle-light-high-contrast.css"
	media="(prefers-contrast: more) and (prefers-color-scheme: light)"
/>
<link
	id="mantle-dark-high-contrast-styles"
	rel="stylesheet"
	href="/path/to/mantle-dark-high-contrast.css"
	media="(prefers-contrast: more) and (prefers-color-scheme: dark)"
/>

<script nonce="...">
	(function D(e) {
		let {
				darkLinkId: t,
				lightHcLinkId: n,
				darkHcLinkId: r,
				mediaDark: i,
				mediaLightHc: a,
				mediaDarkHc: o,
				forceTheme: s,
			} = e,
			c = document.documentElement.dataset.appliedTheme,
			l = s ?? c,
			u = document.getElementById(t),
			d = document.getElementById(n),
			f = document.getElementById(r);
		(u && (u.media = l === `dark` ? `all` : i),
			d && (d.media = l === `light-high-contrast` ? `all` : a),
			f && (f.media = l === `dark-high-contrast` ? `all` : o));
	})({
		darkLinkId: "mantle-dark-styles",
		lightHcLinkId: "mantle-light-high-contrast-styles",
		darkHcLinkId: "mantle-dark-high-contrast-styles",
		mediaDark: "(prefers-color-scheme: dark)",
		mediaLightHc: "(prefers-contrast: more) and (prefers-color-scheme: light)",
		mediaDarkHc: "(prefers-contrast: more) and (prefers-color-scheme: dark)",
	});
</script>
```

> \[!NOTE]
> These script strings are generated by `preventWrongThemeFlashScriptContent()` and `fixMediaScriptContent()` from `@ngrok/mantle/theme`. Re-run the generator after upgrading mantle to pick up any changes.

## Usage

In your application, you can use the `useTheme` hook to get and change the current theme:

```tsx
import {
	Select,
	SelectContent,
	SelectGroup,
	SelectItem,
	SelectLabel,
	SelectTrigger,
} from "@ngrok/mantle/select";
import { isTheme, theme, useTheme } from "@ngrok/mantle/theme";

function App() {
	const [currentTheme, setTheme] = useTheme();

return (
		<>
			<Select
				value={currentTheme}
				onValueChange={(value) => {
					const maybeNewTheme = isTheme(value) ? value : undefined;
					if (maybeNewTheme) {
						setTheme(maybeNewTheme);
					}
				}}
			>
				<div className="ml-auto">
					<span className="sr-only">Theme Switcher</span>
					<SelectTrigger className="w-min">
						<Sun className="mr-1 h-6 w-6" />
					</SelectTrigger>
				</div>
				<SelectContent>
					<SelectGroup>
						<SelectLabel>Choose a theme</SelectLabel>
						<SelectItem value={theme("system")}>System</SelectItem>
						<SelectItem value={theme("light")}>Light</SelectItem>
						<SelectItem value={theme("dark")}>Dark</SelectItem>
						<SelectItem value={theme("light-high-contrast")}>Light High Contrast</SelectItem>
						<SelectItem value={theme("dark-high-contrast")}>Dark High Contrast</SelectItem>
					</SelectGroup>
				</SelectContent>
			</Select>
			{/* The rest of your app... */}
		</>
	);
}
```

## API Reference

### ThemeProvider

The `ThemeProvider` accepts the following props in addition to the [PropsWithChildren](https://react.dev/reference/react/PropsWithChildren).

| Prop       | Type        | Default | Description                                                       |
| ---------- | ----------- | ------- | ----------------------------------------------------------------- |
| `children` | `ReactNode` |         | The React components to be wrapped by the theme provider context. |

**Note:** The `ThemeProvider` uses a hardcoded storage key of `mantle-ui-theme` and defaults to `system` theme. These values are managed internally and do not require configuration.

### MantleStyleSheets

Renders `<link rel="stylesheet">` tags for the dark, light-high-contrast, and dark-high-contrast theme CSS files. Each stylesheet uses a `media` attribute matching its OS preference — it is non-render-blocking for users whose OS does not match. Place this component in `<head>`, immediately after `<PreventWrongThemeFlashScript>`.

An inline `<script>` is also rendered after the `<link>` tags (when needed). It runs synchronously before first paint and corrects any `media` attributes for users with a manually-selected theme, preventing FOUC without needing JavaScript hydration.

When `forceTheme` is set to a non-light theme, only the link tag for that theme is rendered — the others are omitted to avoid unnecessary network requests. `forceTheme="light"` renders no link tags since light is the base theme with no dedicated lazy stylesheet.

Use [`mantleStyleSheetUrls`](#mantlestylesheeturls) to create the required CSS URL props and spread them in.

| Prop                      | Type            | Default | Description                                                                                                                                                                                                                                                                                                 |
| ------------------------- | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `darkCssUrl`              | `string`        |         | Browser-accessible URL for the dark theme stylesheet. Use `mantleStyleSheetUrls` to supply this.                                                                                                                                                                                                            |
| `lightHighContrastCssUrl` | `string`        |         | Browser-accessible URL for the light high-contrast stylesheet. Use `mantleStyleSheetUrls` to supply this.                                                                                                                                                                                                   |
| `darkHighContrastCssUrl`  | `string`        |         | Browser-accessible URL for the dark high-contrast stylesheet. Use `mantleStyleSheetUrls` to supply this.                                                                                                                                                                                                    |
| `forceTheme?`             | `ResolvedTheme` |         | Force a specific theme's stylesheet to load unconditionally (`media="all"`). Use for pages locked to a single theme (e.g. a dark-only landing page). Only the forced theme's `<link>` tag is rendered; the others are omitted. `"light"` renders no tags (light is the base theme with no lazy stylesheet). |
| `ssrCookie?`              | `string`        |         | The extracted theme cookie from the incoming HTTP request (via `extractThemeCookie`). When a non-system theme is resolved from the cookie, the server renders the correct `media` attribute directly in HTML and omits the inline fix script.                                                               |
| `nonce?`                  | `string`        |         | CSP nonce to allowlist the inline fix script. Mirror the same nonce passed to `PreventWrongThemeFlashScript`.                                                                                                                                                                                               |

### mantleStyleSheetUrls

Collects the three Vite `?url` imports for mantle's theme stylesheets into a typed object ready to spread into `<MantleStyleSheets>`. Import the CSS files with `?url` in your app code (not from a library) so Vite's asset transform applies:

```ts
import darkCssUrl from "@ngrok/mantle/mantle-dark.css?url";
import darkHighContrastCssUrl from "@ngrok/mantle/mantle-dark-high-contrast.css?url";
import lightHighContrastCssUrl from "@ngrok/mantle/mantle-light-high-contrast.css?url";
import { mantleStyleSheetUrls } from "@ngrok/mantle/theme";

const themeUrls = mantleStyleSheetUrls({
	darkCssUrl,
	lightHighContrastCssUrl,
	darkHighContrastCssUrl,
});

// <MantleStyleSheets {...themeUrls} nonce={nonce} ssrCookie={ssrCookie} />
```

| Parameter                 | Type     | Description                                                                    |
| ------------------------- | -------- | ------------------------------------------------------------------------------ |
| `darkCssUrl`              | `string` | Result of `import url from "@ngrok/mantle/mantle-dark.css?url"`                |
| `lightHighContrastCssUrl` | `string` | Result of `import url from "@ngrok/mantle/mantle-light-high-contrast.css?url"` |
| `darkHighContrastCssUrl`  | `string` | Result of `import url from "@ngrok/mantle/mantle-dark-high-contrast.css?url"`  |

**Returns:** A `MantleThemeCssUrls` object ready to spread into `<MantleStyleSheets>`.

### fixMediaScriptContent

Returns the raw JavaScript string for the inline `<script>` that fixes theme stylesheet `media` attributes after the `<link>` tags are parsed. This is the non-React equivalent of the inline fix script that `MantleStyleSheets` renders — use it when you need to embed the script directly into SSR HTML outside of a React context (e.g. a legacy Go service).

Place the output in a `<script>` tag immediately after the three theme `<link>` tags in your HTML `<head>`.

```ts
import { fixMediaScriptContent } from "@ngrok/mantle/theme";

// No forced theme — script reads html[data-applied-theme] at runtime
const scriptContent = fixMediaScriptContent();

// Force dark theme — script always sets the dark stylesheet to media="all"
const darkScriptContent = fixMediaScriptContent("dark");
```

| Parameter     | Type            | Description                                                                                                                                                    |
| ------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceTheme?` | `ResolvedTheme` | When set, the script forces that theme's stylesheet to `media="all"`. When omitted, the script reads `html[data-applied-theme]` to determine the active theme. |

**Returns:** A JavaScript string ready to embed inside a `<script>` tag.

### PreventWrongThemeFlashScript

The `PreventWrongThemeFlashScript` component renders the inline script to prevent FOUC. Place it as early as possible in `<head>`. It accepts the following props:

| Prop     | Type     | Default | Description                                                           |
| -------- | -------- | ------- | --------------------------------------------------------------------- |
| `nonce?` | `string` |         | An optional CSP nonce to allowlist the inline FOUC prevention script. |

### preloadFontLink

**Preferred for SSR.** Returns an HTTP `Link` header value that preloads a single core font by name. This is the server-side equivalent of `PreloadFont` — identical in effect, but delivered as an HTTP header so the browser can start the font fetch before it has parsed any HTML, giving better CWV scores on mobile and slow connections.

```ts
import { assetsCdnOrigin, preloadFontLink } from "@ngrok/mantle/theme";

// In your server entry (e.g. entry.server.tsx):
headers.set(
	"Link",
	[
		`<${assetsCdnOrigin}>; rel=preconnect; crossorigin`,
		preloadFontLink("roobert"),
		preloadFontLink("jetbrains-mono"),
	].join(", "),
);
```

| Parameter | Type           | Description                                 |
| --------- | -------------- | ------------------------------------------- |
| `name`    | `CoreFontName` | The name of the individual font to preload. |

**Returns:** A `Link` header value string, e.g. `<https://assets.ngrok.com/fonts/roobert/roobert-proportional-vf.woff2>; rel=preload; as=font; type="font/woff2"; crossorigin`.

### PreloadFont

The `PreloadFont` component renders a single preload `<link>` element for one named core font. Prefer [`preloadFontLink`](#preloadfontlink) in SSR apps where you can set HTTP response headers — sending the hint as a header starts the fetch earlier than HTML parsing allows. Use `PreloadFont` when you have no access to response headers.

```tsx
import { PreloadFont } from "@ngrok/mantle/theme";

<head>
	<PreloadFont name="roobert" />
	<PreloadFont name="jetbrains-mono" />
</head>;
```

| Prop   | Type           | Default | Description                                 |
| ------ | -------------- | ------- | ------------------------------------------- |
| `name` | `CoreFontName` |         | The name of the individual font to preload. |

**`CoreFontName` values:**

| Value                     | Font                                  |
| ------------------------- | ------------------------------------- |
| `"roobert"`               | Roobert proportional variable font    |
| `"jetbrains-mono"`        | JetBrains Mono variable weight        |
| `"jetbrains-mono-italic"` | JetBrains Mono italic variable weight |
| `"family-regular"`        | Family regular                        |
| `"family-italic"`         | Family italic                         |

### extractThemeCookie

Extracts just the theme cookie key-value pair from a full `Cookie` header string. Pass the result to `MantleStyleSheets` and `useInitialHtmlThemeProps` as `ssrCookie` — this avoids exposing other cookies from the request in loader data.

```ts
import { extractThemeCookie } from "@ngrok/mantle/theme";

// In your root loader:
const ssrCookie = extractThemeCookie(request.headers.get("Cookie"));
// e.g. "mantle-ui-theme=dark" or undefined
```

| Parameter      | Type                          | Description                            |
| -------------- | ----------------------------- | -------------------------------------- |
| `cookieHeader` | `string \| null \| undefined` | The raw `Cookie` request header value. |

**Returns:** The `mantle-ui-theme=<value>` pair as a string, or `undefined` if the cookie is not present.

### useInitialHtmlThemeProps

The `useInitialHtmlThemeProps` hook returns props that should be applied to the `<html>` element to prevent React hydration errors. It accepts the following options:

| Prop         | Type     | Default | Description                                                                                                                                                                                         |
| ------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string` | `""`    | Additional CSS classes to apply to the `<html>` element. These will be combined with the theme class.                                                                                               |
| `ssrCookie?` | `string` |         | Theme cookie string to read the persisted theme during SSR. Pass only the theme cookie pair (via `extractThemeCookie`) rather than the full raw `Cookie` header to avoid leaking sensitive cookies. |

**Returns:** An object with `className`, `data-theme`, and `data-applied-theme` props to spread onto your `<html>` element.

**Note:** On the server, when `ssrCookie` is provided, the hook reads the theme from the cookie to render the correct class. When omitted, it defaults to `system` theme (resolved to `light`). On the client, it reads the current theme from `document.cookie` to match what the FOUC prevention script applied, ensuring React hydration succeeds.

---

---
title: Toast
description: A succinct message that is displayed temporarily.
---

# Toast

A succinct message that is displayed temporarily. Toasts are used to provide feedback to the user without interrupting their workflow.

```tsx
import { Button } from "@ngrok/mantle/button";
import { makeToast, Toast } from "@ngrok/mantle/toast";

// Only one <Toaster /> should be rendered at a time
// add it to the root of your app
<Toaster />

<Button
	type="button"
	appearance="outlined"
	priority="neutral"
	onClick={() =>
		// make some toast! 🍞😋
		makeToast(
			<Toast.Root priority="success">
				<Toast.Icon />
				<Toast.Message>
					Laborum ea anim adipisicing in Lorem incididunt mollit ipsum reprehenderit.
				</Toast.Message>
				<Toast.Action asChild>
					<IconButton type="button" appearance="ghost" size="xs" icon={<XIcon />} label="Dismiss toast" />
				</Toast.Action>
			</Toast.Root>,
		)
	}
>
	Show Toast
</Button>
```

## Composition

Compose the parts of a `Toast` together to build your own:

```text showLineNumbers=false
Toast.Root
├── Toast.Icon
├── Toast.Message
└── Toast.Action
```

## API Reference

### Toaster

The `Toaster` component renders all toasts. It accepts the following props:

| Prop                  | Type                                                                                              | Default        | Description                                                                                                                                                                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `position?`           | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"top-center"` | The position where toasts will appear on the screen.                                                                                                                                                                                                      |
| `duration_ms?`        | `number`                                                                                          | `4000`         | Time in milliseconds that should elapse before automatically dismissing toasts. When set here, this will be the default duration for all toasts. You can keep toasts open until manually dismissed by passing a value <= 0 or `Number.POSITIVE_INFINITY`. |
| `containerAriaLabel?` | `string`                                                                                          |                | Aria label for the toast container for screen readers.                                                                                                                                                                                                    |
| `dir?`                | `"ltr" \| "rtl"`                                                                                  |                | Direction of text for internationalization support.                                                                                                                                                                                                       |

### Toast.Root

The `Toast.Root` is the container for a toast message.

All props from [div](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div), plus:

| Prop       | Type                                           | Default | Description                                                                                                                               |
| ---------- | ---------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `priority` | `"info" \| "success" \| "warning" \| "danger"` |         | The priority level of the toast, which determines the visual styling and default icon.                                                    |
| `asChild?` | `boolean`                                      | `false` | Use the `asChild` prop to compose the `Toast.Root` styling and functionality onto alternative element types or your own React components. |

### Toast.Icon

The `Toast.Icon` displays an icon representing the toast priority. If no custom icon is provided, a default icon for the priority is used.

| Prop   | Type        | Default | Description                                                                                          |
| ------ | ----------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `svg?` | `ReactNode` |         | A custom SVG icon to display. If not provided, the default icon for the toast priority will be used. |

### Toast.Message

The `Toast.Message` contains the main text content of the toast.

All props from [p](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p), plus:

| Prop       | Type      | Default | Description                                                                                                                                  |
| ---------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `Toast.Message` styling and functionality onto alternative element types or your own React components. |

### Toast.Action

The `Toast.Action` is a button that dismisses the toast when clicked.

All props from [button](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button), plus:

| Prop       | Type      | Default | Description                                                                                                                                 |
| ---------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `asChild?` | `boolean` | `false` | Use the `asChild` prop to compose the `Toast.Action` styling and functionality onto alternative element types or your own React components. |

**Note:** You can prevent the toast from being dismissed on click by calling `event.preventDefault()` in your `onClick` handler.

### makeToast

The `makeToast` function creates and displays a toast. It accepts the following parameters:

| Prop       | Type               | Default | Description                                                                                                                                                                                    |
| ---------- | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | `ReactNode`        |         | The React component to render inside the toast container. Typically a `Toast.Root` component.                                                                                                  |
| `options?` | `MakeToastOptions` |         | Optional configuration object with the following properties: `duration_ms` (number, optional) — time in milliseconds before auto-dismissal; `id` (string, optional) — custom ID for the toast. |

---

---
title: Tooltip
description: A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.
---

# Tooltip

A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.

## When to use

A `Tooltip` shows a short, non-interactive label when a control receives keyboard focus or a pointer hover. Reach for it to clarify the purpose of an icon-only button, surface a keyboard shortcut, or provide a brief hint about a control. Do NOT put buttons, links, or form controls inside a `Tooltip`.

- Prefer [`Popover`](/components/popover) when the floating content needs buttons, links, inputs, or anything else focusable.
- Prefer [`HoverCard`](/components/hover-card) for a sighted-only preview of content that already lives behind a link.

Mount `TooltipProvider` once at the app root when you want shared tooltip behavior, such as consistent delay and hover settings.

> \[!WARNING]
> Per the [WAI-ARIA tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/), tooltips must not contain interactive or focusable content — the tooltip itself never receives focus, so anything inside it is unreachable for keyboard users. If the floating content needs to be interactive, use [`Popover`](/components/popover) instead.

```tsx
import { Button } from "@ngrok/mantle/button";
import { Tooltip } from "@ngrok/mantle/tooltip";

<Tooltip.Root>
	<Tooltip.Trigger asChild>
		<Button type="button" appearance="filled" priority="neutral">
			Hover me
		</Button>
	</Tooltip.Trigger>
	<Tooltip.Content>
		<p>This feature is part of your plan</p>
	</Tooltip.Content>
</Tooltip.Root>;
```

## Composition

Compose the parts of a `Tooltip` together to build your own:

```text showLineNumbers=false
Tooltip.Root
├── Tooltip.Trigger
└── Tooltip.Content
```

## API Reference

> \[!NOTE]
> Wrap your app with `TooltipProvider` once at the root to share global tooltip behavior — such as consistent delay and hover settings — across your application.

### TooltipProvider

Wraps your app to provide global functionality to your tooltips. Only one instance of this component should be rendered in your app, preferably at the root.

| Prop                       | Type      | Default | Description                                                                                                  |
| -------------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `delayDuration?`           | `number`  | `0`     | The duration from when the mouse enters a tooltip trigger until the tooltip opens, in milliseconds.          |
| `skipDelayDuration?`       | `number`  | `300`   | How much time a user has to enter another trigger without incurring a delay again, in milliseconds.          |
| `disableHoverableContent?` | `boolean` | `false` | Prevents `Tooltip.Content` from remaining open when hovering. Disabling this has accessibility consequences. |

### Tooltip.Root

The root component that manages the open/closed state of the tooltip. Wrap your app in `TooltipProvider` when you want shared app-wide delay and hover settings.

| Prop                       | Type                      | Default | Description                                                                                                             |
| -------------------------- | ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `defaultOpen?`             | `boolean`                 | `false` | The open state of the tooltip when it is initially rendered. Use when you do not need to control its open state.        |
| `open?`                    | `boolean`                 |         | The controlled open state of the tooltip. Must be used in conjunction with `onOpenChange`.                              |
| `onOpenChange?`            | `(open: boolean) => void` |         | Event handler called when the open state of the tooltip changes.                                                        |
| `delayDuration?`           | `number`                  |         | Override the duration given to the `TooltipProvider` to customize the open delay for a specific tooltip.                |
| `disableHoverableContent?` | `boolean`                 |         | Override the `disableHoverableContent` given to the `TooltipProvider` to customize the behavior for a specific tooltip. |

### Tooltip.Trigger

The button that toggles the tooltip. By default, the `Tooltip.Content` will position itself against the trigger.

### Tooltip.Content

The component that pops out when the tooltip is open.

| Prop               | Type                                     | Default    | Description                                                                                                                             |
| ------------------ | ---------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `side?`            | `"top" \| "right" \| "bottom" \| "left"` | `"top"`    | The preferred side of the trigger to render against when open. Will be reversed when collisions occur and `avoidCollisions` is enabled. |
| `sideOffset?`      | `number`                                 | `4`        | The distance in pixels from the trigger.                                                                                                |
| `align?`           | `"start" \| "center" \| "end"`           | `"center"` | The preferred alignment against the trigger. May change when collisions occur.                                                          |
| `alignOffset?`     | `number`                                 | `0`        | An offset in pixels from the `start` or `end` alignment options.                                                                        |
| `avoidCollisions?` | `boolean`                                | `true`     | When `true`, overrides the `side` and `align` preferences to prevent collisions with boundary edges.                                    |

---

---
title: Well
description: A recessed, inset container used to group and de-emphasize content.
---

# Well

A recessed, inset container used to visually group and de-emphasize content
relative to the surrounding surface. It renders like a `Card.Root` but with an
inset shadow and the base background, making it feel sunken into the page. Reach
for it to frame empty states, code samples, supplementary notes, or read-only
summaries.

```tsx
import { Well } from "@ngrok/mantle/well";
import { Empty } from "@ngrok/mantle/empty";
import { Button } from "@ngrok/mantle/button";
import { MagnifyingGlassIcon } from "@phosphor-icons/react";

<Well>
	<Empty.Root>
		<Empty.Icon svg={<MagnifyingGlassIcon />} />
		<Empty.Title>No results found</Empty.Title>
		<Empty.Description>
			<p>Try adjusting your search or filters to find what you're looking for.</p>
		</Empty.Description>
		<Empty.Actions>
			<Button type="button" appearance="outlined" priority="neutral">
				Clear filters
			</Button>
		</Empty.Actions>
	</Empty.Root>
</Well>;
```

## Polymorphism

`Well` accepts an `asChild` prop. When `true`, it renders its single child
instead of its default `<div>`, forwarding all class names, `data-*`
attributes, and the ref onto that child. Reach for this when the recessed
container should also be a more semantic element, such as a labelled
`<section>`.

```tsx
<Well asChild>
	<section aria-label="Search results">{/* … */}</section>
</Well>
```

## API Reference

### Well

A recessed, inset container. Renders a `<div>` by default and spreads all
standard `<div>` props onto the rendered element. Supports the `asChild` prop
for polymorphic rendering.

---

---
title: For AI Agents
description: How LLMs, code-generation agents, and IDE assistants should consume @ngrok/mantle.
---

# For AI Agents

This page is the canonical entry point for AI assistants — Claude Code, Cursor, Copilot, custom agents — that need to write code against `@ngrok/mantle`.

## TL;DR for the agent

```
Use the @ngrok/mantle design system. Components live at @ngrok/mantle/<name>
(e.g. @ngrok/mantle/button). All pages have a plain-markdown twin at
<page>.md. The full library index is at /llms.txt and a structured
component manifest is at /api/components.json. Hooks and utilities have
their own manifests at /api/hooks.json and /api/utils.json.
```

## Machine-readable entry points

| URL                                                | Purpose                                                                                                                                                        |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/llms.txt`](/llms.txt)                           | Curated index of every docs page (title, description, html + markdown URLs). Follows the [llms.txt convention](https://llmstxt.org).                           |
| [`/llms-full.txt`](/llms-full.txt)                 | Concatenated plain-markdown of every docs page. Drop into a context window when full coverage is needed.                                                       |
| [`/api/components.json`](/api/components.json)     | Structured component manifest. Each entry has `name`, `slug`, `status`, `importPath`, `docsUrl`, `markdownUrl`, and a one-line `summary`.                      |
| [`/api/hooks.json`](/api/hooks.json)               | Structured hooks manifest. Each entry has `name`, `importPath`, `docsUrl`, `markdownUrl`, and an optional `summary`.                                           |
| [`/api/utils.json`](/api/utils.json)               | Structured utilities manifest. Same shape as hooks.                                                                                                            |
| [`/api/package.json`](/api/package.json)           | Curated `@ngrok/mantle` package info: version, peer/dev deps, full list of importable subpaths.                                                                |
| [`/api/changelog.json`](/api/changelog.json)       | Published changelog parsed into a structured per-version, per-bump shape with PR/commit/author metadata.                                                       |
| [`/api/search-index.json`](/api/search-index.json) | Flat searchable index across components, hooks, and utilities with keyword tokens.                                                                             |
| [`/api/schema.json`](/api/schema.json)             | JSON Schema (draft-07) definitions for every endpoint above. Use it to validate payloads.                                                                      |
| [`/changelog.md`](/changelog.md)                   | The published `@ngrok/mantle` `CHANGELOG.md` as plain markdown.                                                                                                |
| [`/migrations`](/migrations)                       | Step-by-step migration guides for new APIs/behaviors. Each is reachable as HTML and as raw markdown (append `.md`), written to feed directly to coding agents. |
| `/<page>.md`                                       | Every docs page (e.g. [`/components/button.md`](/components/button.md)) is also served as plain markdown by appending `.md`.                                   |

## Suggested system-prompt snippet

Drop this near the top of an agent's system prompt when working in a mantle codebase:

```
This project uses @ngrok/mantle, ngrok's React + TypeScript + Tailwind
design system. Conventions:

- Components are imported from @ngrok/mantle/<name>, e.g.
  `import { Button } from "@ngrok/mantle/button"`.
- Hooks are imported from @ngrok/mantle/hooks, e.g.
  `import { useBreakpoint } from "@ngrok/mantle/hooks"`.
- Utilities live at their own subpaths, e.g. @ngrok/mantle/cx,
  @ngrok/mantle/color.
- Use `== null` / `!= null` for nullish checks (covers both `null` and
  `undefined`) — never `=== undefined` / `!== undefined`.
- Compose class names with `cx` from @ngrok/mantle/cx — never use string
  interpolation inside className.
- Many components support `asChild` to swap the rendered element while
  keeping the styling and behavior. Prefer this over wrapping.
- The app must wrap children in <ThemeProvider> and <Toaster> at the root
  (see /). Add <TooltipProvider> once at the root when using shared tooltip
  delay or hover settings.
- All external dependencies must be exact-pinned (no `^` or `~`).
- Reference the canonical docs at https://mantle.ngrok.com or fetch
  https://mantle.ngrok.com/llms.txt for the full index.
```

## Conventions agents should know

- **Polymorphism via `asChild`.** Most components accept `asChild` (powered by [`Slot`](/components/slot)). Use it to render the component as a different element — for example, render a `Button` as a `react-router` `Link` — without losing the component's styling or behavior.
- **Import paths by category.** Components import from `@ngrok/mantle/<name>` (e.g. `@ngrok/mantle/button`). Hooks live at [`@ngrok/mantle/hooks`](/hooks) (e.g. `import { useBreakpoint } from "@ngrok/mantle/hooks"`). Utilities live at their own subpaths — `@ngrok/mantle/cx`, `@ngrok/mantle/color`, etc.
- **Docs slug ≠ import subpath (sometimes).** Most components import from a subpath that matches their docs slug (e.g., `Button` from `@ngrok/mantle/button`). A few are exported from a parent's subpath: `IconButton` from `@ngrok/mantle/button`, `PasswordInput` from `@ngrok/mantle/input`, `ProgressBar` and `ProgressDonut` from `@ngrok/mantle/progress`. The structured manifest at [`/api/components.json`](/api/components.json) is the source of truth — its `importPath` field is always correct.
- **`cx` over string interpolation.** Compose class names with [`cx`](/utils/cx). It merges Tailwind classes and de-duplicates conflicts.
- **Nullish checks use `== null` / `!= null`.** The codebase prefers these over `=== undefined` / `!== undefined`, since `== null` covers both `null` and `undefined`.
- **Theme + provider setup.** Apps must mount [`ThemeProvider`](/components/theme) and [`Toaster`](/components/toast) at the root. Add [`TooltipProvider`](/components/tooltip) once when using shared tooltip delay or hover settings. Without `ThemeProvider`, theme tokens are unstyled and there's a flash of unstyled content.
- **Phosphor icons by default.** Import icons from `@phosphor-icons/react/<IconName>` (e.g. `@phosphor-icons/react/Fire`). Custom ngrok icons live at [`@ngrok/mantle/icons`](/components/icons).
- **No `as` casts in app code.** Use proper null checks and type narrowing. Type assertions are restricted to `as const` and dedicated type guards (see [Conventions](https://github.com/ngrok/mantle/blob/main/CONVENTIONS.md)).
- **Exact-pinned versions.** When adding a dependency, pin it. No `^` or `~` ranges.
- **Tailwind 4.** Custom classes use the design tokens defined in `mantle.css`. Prefer semantic tokens (`text-strong`, `bg-form`, `border-accent-600`) over raw color names where they exist.

## Composition patterns

A few high-leverage compositions agents commonly need:

```tsx
// Button + react-router Link (polymorphic)
import { Button } from "@ngrok/mantle/button";
import { Link } from "react-router";

<Button asChild>
	<Link to="/dashboard">Dashboard</Link>
</Button>;
```

```tsx
// Dialog + form
import { Dialog } from "@ngrok/mantle/dialog";
import { Button } from "@ngrok/mantle/button";

<Dialog.Root>
	<Dialog.Trigger asChild>
		<Button>Edit</Button>
	</Dialog.Trigger>
	<Dialog.Content>
		<Dialog.Header>
			<Dialog.Title>Edit profile</Dialog.Title>
		</Dialog.Header>
		{/* form here */}
	</Dialog.Content>
</Dialog.Root>;
```

```tsx
// Toast on async action
import { makeToast, Toast } from "@ngrok/mantle/toast";

async function save() {
	try {
		await api.save();
		makeToast(<Toast.Root priority="success">Saved</Toast.Root>);
	} catch (error) {
		makeToast(
			<Toast.Root priority="danger">
				<Toast.Message>Could not save</Toast.Message>
				<Toast.Description>{String(error)}</Toast.Description>
			</Toast.Root>,
		);
	}
}
```

## Accessibility-first defaults

Every mantle component is built on semantic HTML and tested ARIA patterns. Agents should:

- Render real form controls (`Input`, `Checkbox`, `RadioGroup`) — never style a `<div>` with click handlers as a button.
- Pair every form control with a [`Label`](/components/label).
- Use [`SkipToMainLink`](/components/skip-to-main-link) + [`Main`](/components/main) at the top of the document tree.
- Provide accessible names for icon-only buttons via `aria-label` on [`IconButton`](/components/icon-button).
- See the [Accessibility](/accessibility) page for a full keyboard / ARIA reference per component.

## When to ask vs. when to act

- If the user asks for "a primary button," generate a `Button` with `appearance="filled" priority="default"`. The library's defaults should be safe.
- If choosing between `Tooltip`, `Popover`, and `HoverCard`, follow [the JSDoc guidance](https://mantle.ngrok.com/components/tooltip) — `Tooltip` for short label hints, `Popover` for interactive content, `HoverCard` for non-essential preview cards.
- If choosing between `DataTable` and `Table`: `DataTable` for dynamic, sortable, filterable, paginated tabular data; `Table` for static layout.
- When uncertain, prefer to fetch the relevant `/<page>.md` and read the full doc rather than guessing.

## Versioning

`@ngrok/mantle` follows semver. Breaking changes are documented in the [Changelog](/changelog). When working in a project, check `package.json` for the pinned version and prefer the docs at the matching tag on GitHub if you need to pin behavior to that version.

---

---
title: Hooks
description: Custom React hooks exported from @ngrok/mantle/hooks
---

# Hooks

Custom React hooks exported from `@ngrok/mantle/hooks`.

## Overview

| Hook                        | Description                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------- |
| `useBreakpoint`             | Returns the current responsive breakpoint based on the viewport width.              |
| `useIsBelowBreakpoint`      | Returns `true` if the viewport width is below a given breakpoint.                   |
| `useCallbackRef`            | Returns a memoized callback that always refers to the latest function passed to it. |
| `useComposedRefs`           | Composes multiple React refs into a single callback ref.                            |
| `useCopyToClipboard`        | Copies a string to the clipboard.                                                   |
| `useDebouncedCallback`      | Creates a debounced version of a callback function.                                 |
| `useIsHydrated`             | Returns whether the component tree has been hydrated on the client.                 |
| `useIsomorphicLayoutEffect` | Uses `useLayoutEffect` on the client and `useEffect` on the server.                 |
| `useMatchesMediaQuery`      | Subscribes to and returns the result of a CSS media query.                          |
| `usePrefersReducedMotion`   | Returns `true` when the user prefers reduced motion.                                |
| `useRandomStableId`         | Generates a random, stable ID safe for CSS selectors and element IDs.               |
| `useScrollBehavior`         | Returns a `ScrollBehavior` that respects the user's reduced motion preference.      |
| `useInView`                 | Returns `true` when a DOM element is visible within the viewport.                   |

## useBreakpoint

```tsx
const breakpoint = useBreakpoint();
```

Returns the current responsive breakpoint based on the viewport width. Uses a singleton subscription to a set of min-width media queries and returns the largest matching breakpoint.

```tsx
import { useBreakpoint } from "@ngrok/mantle/hooks";

function ResponsiveComponent() {
	const breakpoint = useBreakpoint();
	return <p>Current breakpoint: {breakpoint}</p>;
}
```

## useIsBelowBreakpoint

```tsx
const isMobile = useIsBelowBreakpoint("md");
```

Returns `true` if the current viewport width is below the specified breakpoint. Accepts a `TailwindBreakpoint` (`"2xs"`, `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, `"2xl"`).

```tsx
import { useIsBelowBreakpoint } from "@ngrok/mantle/hooks";

function ResponsiveSidebar() {
	const isMobile = useIsBelowBreakpoint("md");
	return isMobile ? <MobileNav /> : <DesktopNav />;
}
```

## useCallbackRef

```tsx
const stableCallback = useCallbackRef(onChange);
```

Returns a memoized callback that always refers to the latest callback passed to the hook. Useful when passing a callback that may or may not be memoized to a child component without causing re-renders.

```tsx
import { useCallbackRef } from "@ngrok/mantle/hooks";

function Example({ onChange }: { onChange?: (value: string) => void }) {
	const stableOnChange = useCallbackRef(onChange);
	// stableOnChange always calls the latest onChange
}
```

## useComposedRefs

```tsx
const ref = useComposedRefs(internalRef, forwardedRef);
```

Composes multiple React refs (callback refs and `RefObject`s) into a single stable callback ref using `useCallback`. Useful when a component needs to forward a ref while also keeping an internal one.

```tsx
import { forwardRef, useRef } from "react";
import { useComposedRefs } from "@ngrok/mantle/hooks";

## useCopyToClipboard

```tsx
const [copiedValue, copy] = useCopyToClipboard();
```

Copies a string to the clipboard. Returns a tuple of the last copied value and a copy function. Includes a fallback for older browsers.

```tsx
import { useCopyToClipboard } from "@ngrok/mantle/hooks";

function CopyButton({ text }: { text: string }) {
	const [copiedValue, copy] = useCopyToClipboard();
	return <button onClick={() => copy(text)}>{copiedValue === text ? "Copied!" : "Copy"}</button>;
}
```

## useDebouncedCallback

```tsx
const debouncedFn = useDebouncedCallback(fn, { waitMs: 300 });
```

Creates a debounced version of a callback function. Delays execution until a period of inactivity has passed (`options.waitMs`). The debounced callback is stable and safe to use in dependency arrays.

```tsx
import { useDebouncedCallback } from "@ngrok/mantle/hooks";

function SearchInput() {
	const debouncedSearch = useDebouncedCallback((query: string) => fetchResults(query), {
		waitMs: 300,
	});
	return <input onChange={(event) => debouncedSearch(event.target.value)} />;
}
```

## useIsHydrated

```tsx
const isHydrated = useIsHydrated();
```

Returns whether the component tree has been hydrated on the client. Returns `false` on the server and `true` after hydration on the client. Uses `useSyncExternalStore` to prevent hydration mismatches.

```tsx
import { useIsHydrated } from "@ngrok/mantle/hooks";
import type { PropsWithChildren } from "react";

## useIsomorphicLayoutEffect

```tsx
useIsomorphicLayoutEffect(() => {
	/* ... */
}, [deps]);
```

Uses `useLayoutEffect` on the client and `useEffect` on the server. Avoids SSR warnings about `useLayoutEffect` doing nothing on the server.

```tsx
import { useIsomorphicLayoutEffect } from "@ngrok/mantle/hooks";

function MeasureElement() {
	useIsomorphicLayoutEffect(() => {
		// safely measure DOM on client, no-op on server
	}, []);
}
```

## useMatchesMediaQuery

```tsx
const matches = useMatchesMediaQuery("(prefers-color-scheme: dark)");
```

Subscribes to and returns the result of a CSS media query string. Uses `window.matchMedia` and `useSyncExternalStore` for concurrent rendering compatibility.

```tsx
import { useMatchesMediaQuery } from "@ngrok/mantle/hooks";

function DarkModeDetector() {
	const isDark = useMatchesMediaQuery("(prefers-color-scheme: dark)");
	return <p>Dark mode: {isDark ? "Yes" : "No"}</p>;
}
```

## usePrefersReducedMotion

```tsx
const reduce = usePrefersReducedMotion();
```

Returns `true` when the user has opted out of animations (i.e., prefers reduced motion). Defaults to `true` during SSR and before hydration — animations are suppressed until the real preference is known on the client.

```tsx
import { usePrefersReducedMotion } from "@ngrok/mantle/hooks";

function AnimatedComponent() {
	const reduce = usePrefersReducedMotion();
	const duration = reduce ? 0 : 200;
	return <div style={{ transitionDuration: duration + "ms" }} />;
}
```

### getPrefersReducedMotion

```tsx
const reduce = getPrefersReducedMotion();
```

Imperatively reads the current `prefers-reduced-motion` preference. Useful in event handlers and plain functions where a hook cannot be called.

Returns `true` when the user has opted out of animations. Defaults to `true` in SSR environments (no DOM available), matching the conservative default of `usePrefersReducedMotion`.

```tsx
import { getPrefersReducedMotion } from "@ngrok/mantle/hooks";

function shakeElement(element: HTMLElement) {
	if (getPrefersReducedMotion()) {
		return;
	}
	element.animate(/* ... */);
}
```

## useRandomStableId

```tsx
const id = useRandomStableId("prefix");
```

Generates a random, stable ID. Similar to `useId`, but produces an ID that is safe for use in CSS selectors and as element IDs. Accepts an optional prefix (defaults to `"mantle"`).

```tsx
import { useRandomStableId } from "@ngrok/mantle/hooks";
import type { PropsWithChildren } from "react";

function Tooltip({ children }: PropsWithChildren) {
	const id = useRandomStableId("tooltip");
	return <div id={id}>{children}</div>;
}
```

## useScrollBehavior

```tsx
const behavior = useScrollBehavior(); // "smooth" | "auto"
```

Returns a `ScrollBehavior` (`"auto"` or `"smooth"`) that respects the user's reduced motion preference. Returns `"auto"` when the user prefers reduced motion, otherwise `"smooth"`.

```tsx
import { useScrollBehavior } from "@ngrok/mantle/hooks";

function ScrollToTop() {
	const behavior = useScrollBehavior();
	return <button onClick={() => window.scrollTo({ top: 0, behavior })}>Back to top</button>;
}
```

## useInView

React hook that tracks whether a DOM element is visible within the viewport (or a scrollable container).
Returns `true` when the element is in view, otherwise `false`.

```tsx
const isInView = useInView(ref);
const isInView = useInView(ref, { once: true, amount: 0.5 });
```

```tsx
import { useRef } from "react";
import { useInView } from "@ngrok/mantle/hooks";

function FadeIn() {
	const ref = useRef<HTMLDivElement>(null);
	const isInView = useInView(ref);

return <div ref={ref} style={{ opacity: isInView ? 1 : 0, transition: "opacity 0.5s" }} />;
}
```

Trigger once on first entry:

```tsx
import { useRef } from "react";
import { useInView } from "@ngrok/mantle/hooks";

function AnimateOnce() {
	const ref = useRef<HTMLDivElement>(null);
	const isInView = useInView(ref, { once: true });

return <div ref={ref} className={isInView ? "animate" : ""} />;
}
```

### useInView Options:

| Option    | Type                         | Default  | Description                                                                                                        |
| --------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `root`    | `RefObject<Element \| null>` | viewport | Ref to a scrollable container to use as the intersection root.                                                     |
| `margin`  | `string`                     | `"0px"`  | Expand or contract the root bounds. Same syntax as CSS `margin` (e.g. `"10px"`, `"10% 0px"`).                      |
| `amount`  | `"some" \| "all" \| number`  | `"some"` | How much of the element must be visible. `"some"` = any part, `"all"` = fully visible, or a ratio between `0`–`1`. |
| `once`    | `boolean`                    | `false`  | Stop observing after the element enters the viewport for the first time.                                           |
| `initial` | `boolean`                    | `false`  | Initial visibility state before the observer attaches.                                                             |

### useInView Example

Live demo for the useInView hook.
A scrollable container where the observed element transitions between in-view and out-of-view states as you scroll.

```tsx
"use client";

import { cx } from "@ngrok/mantle/cx";
import { useInView } from "@ngrok/mantle/hooks";
import { useRef, type ComponentRef } from "react";

export function UseInViewDemo() {
	const ref = useRef<ComponentRef<"div">>(null);
	const isInView = useInView(ref, { amount: 0.5 });

return (
		<div className="h-72 w-full overflow-y-scroll overscroll-contain">
			<div className="flex flex-col items-center gap-4 px-8 py-6">
				<p className="select-none font-mono text-sm text-muted">↓ scroll down</p>
				<div className="h-60" />
				<div
					ref={ref}
					className={cx(
						"flex h-28 w-64 items-center justify-center rounded-xl border-2 font-mono text-sm transition-all duration-500",
						isInView
							? "scale-100 border-accent-600 bg-accent-600/10 text-accent-600 opacity-100"
							: "scale-95 border-card-muted bg-gray-50 text-muted opacity-30",
					)}
				>
					isInView: {String(isInView)}
				</div>
				<div className="h-60" />
				<p className="select-none font-mono text-sm text-muted">↑ scroll up</p>
			</div>
		</div>
	);
}
```

---

---
title: Mantle
description: ngrok's UI library and design system built with React, TypeScript, and Tailwind CSS
---

# Mantle

Mantle is [ngrok](https://ngrok.com)'s UI library and design system that
powers its front-end.

## Overview

Mantle is a carefully designed system of [React](https://react.dev) components and utilities
that establishes a unified design language and consistent user experience across ngrok's web
applications. Built with flexibility, extensibility, and developer ergonomics in mind, Mantle
prioritizes accessibility, performance, and long-term maintainability. Developed in
[TypeScript](https://www.typescriptlang.org/), it offers strong typing, rich IDE support, and
increased confidence through compile-time safety. By progressively enhancing standard DOM
elements, it not only improves usability and accessibility, but also fills functional
gaps—providing a robust foundation for building cohesive, modern UIs throughout the platform.

To learn more about the design principles and architectural decisions that guide Mantle, see the
[Philosophy](/philosophy) page.

All of Mantle's components are styled using [Tailwind](https://tailwindcss.com). and we compose
around the following unstyled primitive component libraries:

- [Radix](https://www.radix-ui.com)
- [Ariakit](https://ariakit.org/components)
- [Headless UI](https://headlessui.com/)

Mantle uses [Phosphor Icons](https://phosphoricons.com/) as the primary icon library, providing
a versatile and consistent set of icons. In addition, custom-designed icons tailored to ngrok's
needs are available through the [`@ngrok/mantle/icons`](/components/icons) module.

## Status

Mantle is a living design system and the standard UI library for all ngrok user interfaces. It is
continuously evolving as new components, patterns, and improvements are added.

Mantle is available on [NPM](https://www.npmjs.com/package/@ngrok/mantle) and is open source on
[GitHub](https://github.com/ngrok/mantle).

## Setup

### Installation

> \[!NOTE]
> Mantle supports `react` and `react-dom` versions 18 and 19.

Install `@ngrok/mantle` and all required `peerDependencies`:

```sh mode=cli title="install required mantle peerDependencies"
# npm
npm install -E @ngrok/mantle @phosphor-icons/react date-fns react react-dom

# pnpm
pnpm add -E @ngrok/mantle @phosphor-icons/react date-fns react react-dom

# bun
bun add -E @ngrok/mantle @phosphor-icons/react date-fns react react-dom
```

Install `tailwindcss` as a dev dependency (all frameworks):

```sh
# npm
npm install -DE tailwindcss

# pnpm
pnpm add -DE tailwindcss

# bun
bun add -DE tailwindcss
```

### React Router

Install the additional dev dependencies for the Tailwind Vite plugin:

```sh
# npm
npm install -DE @tailwindcss/vite

# pnpm
pnpm add -DE @tailwindcss/vite

# bun
bun add -DE @tailwindcss/vite
```

Add the `@tailwindcss/vite` plugin to your Vite configuration:

```ts
// vite.config.ts
import { reactRouter } from "@react-router/dev/vite";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
	plugins: [tailwindcss(), reactRouter(), tsconfigPaths()],
});
```

In your app's `app/root.tsx`, import `mantle.css` and set up the
[Theme Provider](/components/theme), [Toaster](/components/toast), and
[Tooltip Provider](/components/tooltip).

> \[!WARNING]
> It is critical to include `PreventWrongThemeFlashScript` early in the `<head>` of your app to
> prevent a flash of unstyled content (FOUC). For SSR apps, also send font preloads as HTTP `Link`
> headers using `preloadFontLink` so fonts start fetching before the browser parses any HTML.

```ts
// app/entry.server.tsx — send font preload Link headers
import { assetsCdnOrigin, preloadFontLink } from "@ngrok/mantle/theme";

// inside your handleRequest / onShellReady:
responseHeaders.set(
	"Link",
	[
		`<${assetsCdnOrigin}>; rel=preconnect; crossorigin`,
		preloadFontLink("roobert"),
		preloadFontLink("jetbrains-mono"),
		preloadFontLink("family-regular"),
	].join(", "),
);
```

```tsx
// app/root.tsx
import {
	PreventWrongThemeFlashScript,
	ThemeProvider,
	useInitialHtmlThemeProps,
} from "@ngrok/mantle/theme";
import { Toaster } from "@ngrok/mantle/toast";
import { TooltipProvider } from "@ngrok/mantle/tooltip";
import type { PropsWithChildren } from "react";
import {
	isRouteErrorResponse,
	Links,
	Meta,
	Outlet,
	Scripts,
	ScrollRestoration,
} from "react-router";

import type { Route } from "./+types/root";
import "@ngrok/mantle/mantle.css";

export function Layout({ children }: PropsWithChildren) {
	const initialHtmlThemeProps = useInitialHtmlThemeProps({
		className: "h-full",
	});

return (
		// suppressHydrationWarning prevents React from fighting the inline
		// theme script that corrects the class before paint on prerendered/SSR pages.
		<html {...initialHtmlThemeProps} lang="en-US" dir="ltr" suppressHydrationWarning>
			<head>
				<meta charSet="utf-8" />
				<meta name="viewport" content="width=device-width, initial-scale=1" />
				{/* PreventWrongThemeFlashScript must be as early as possible in <head> */}
				<PreventWrongThemeFlashScript />
				<Meta />
				<Links />
			</head>
			<body>
				<ThemeProvider>
					<TooltipProvider>
						<Toaster />
						{children}
					</TooltipProvider>
				</ThemeProvider>
				<ScrollRestoration />
				<Scripts />
			</body>
		</html>
	);
}

export default function App() {
	return <Outlet />;
}

export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
	let message = "Oops!";
	let details = "An unexpected error occurred.";
	let stack: string | undefined;

if (isRouteErrorResponse(error)) {
		message = error.status === 404 ? "404" : "Error";
		details =
			error.status === 404 ? "The requested page could not be found." : error.statusText || details;
	} else if (import.meta.env.DEV && error && error instanceof Error) {
		details = error.message;
		stack = error.stack;
	}

return (
		<main className="pt-16 p-4 container mx-auto">
			<h1>{message}</h1>
			<p>{details}</p>
			{stack && (
				<pre className="w-full p-4 overflow-x-auto">
					<code>{stack}</code>
				</pre>
			)}
		</main>
	);
}
```

You are now ready to use mantle components in your application! For example, you can use the
[Button](/components/button).

#### SSR Theme Cookie (Optional)

For apps **behind authentication** where responses are **not publicly cached by a CDN**, you can
pass the theme cookie to `useInitialHtmlThemeProps` to eliminate the hydration mismatch entirely.
This ensures the server renders the correct theme class, so React hydration matches the inline
script without needing `suppressHydrationWarning`.

> \[!CAUTION]
> Do **not** use `ssrCookie` on publicly cached pages. React Router serializes loader data into
> the HTML, so the first visitor's theme would be baked into the CDN cache and served to everyone.
> For public/CDN-cached apps, rely on `suppressHydrationWarning` instead (shown above).

> \[!WARNING]
> Never return the full `Cookie` header from a loader — it would leak HttpOnly/session cookies
> into the HTML. Always use `extractThemeCookie` to return only the theme cookie.

```tsx
import { extractThemeCookie, useInitialHtmlThemeProps } from "@ngrok/mantle/theme";

export const loader = async ({ request }: Route.LoaderArgs) => {
	const themeCookie = extractThemeCookie(request.headers.get("Cookie"));
	return { themeCookie };
};

### Vite

Install the additional dev dependencies for the Tailwind Vite plugin:

```sh
# npm
npm install -DE @tailwindcss/vite

# pnpm
pnpm add -DE @tailwindcss/vite

# bun
bun add -DE @tailwindcss/vite
```

Add the `@tailwindcss/vite` plugin to your Vite configuration:

```ts
// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
	plugins: [tailwindcss()],
});
```

In your app's `src/main.tsx`, import `mantle.css` and set up the
[Theme Provider](/components/theme), [Toaster](/components/toast), and
[Tooltip Provider](/components/tooltip):

```tsx
// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { ThemeProvider } from "@ngrok/mantle/theme";
import { Toaster } from "@ngrok/mantle/toast";
import { TooltipProvider } from "@ngrok/mantle/tooltip";
import "@ngrok/mantle/mantle.css";
import App from "./App.tsx";

createRoot(document.getElementById("root")!).render(
	<StrictMode>
		<ThemeProvider>
			<TooltipProvider>
				<Toaster />
				<App />
			</TooltipProvider>
		</ThemeProvider>
	</StrictMode>,
);
```

To prevent a flash of unstyled content (FOUC), update your `index.html` to include the theme
script. Import `preventWrongThemeFlashScriptContent` from `@ngrok/mantle/theme` and inline its
output in a `<script>` tag in the `<head>`:

> \[!WARNING]
> While mantle supports any type of react application, vite is not the primary target. For now,
> you will need to manually include the following script in the `<head>` of your app. We plan to
> add a vite plugin in the future to automate this.

```html

<!doctype html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<link rel="icon" type="image/svg+xml" href="/vite.svg" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<title>Vite + React + TS</title>
		<script>
			// Inline the output of preventWrongThemeFlashScriptContent()
			// from "@ngrok/mantle/theme" here to prevent FOUC
		</script>
	</head>
	<body>
		<div id="root"></div>
		<script type="module" src="/src/main.tsx"></script>
	</body>
</html>
```

You are now ready to use mantle components in your application! For example, you can use the
[Button](/components/button).

### Next.js

> \[!CAUTION]
> Mantle does not yet support Next.js 15, especially with react 19 and RSC. We are working on
> adding support for it soon.

### React SPA

In your app's entry/root file, import `mantle.css` and set up the
[Theme Provider](/components/theme), [Toaster](/components/toast), and
[Tooltip Provider](/components/tooltip):

```tsx
// root.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { ThemeProvider } from "@ngrok/mantle/theme";
import { Toaster } from "@ngrok/mantle/toast";
import { TooltipProvider } from "@ngrok/mantle/tooltip";
import "@ngrok/mantle/mantle.css";
import App from "./App.tsx";

const container = window.document.getElementById("app");

if (!container) {
	throw new Error(
		"Something went wrong: cannot render application! Please refresh the page to try again.",
	);
}

const root = createRoot(container);

root.render(
	<StrictMode>
		<ThemeProvider>
			<TooltipProvider>
				<Toaster />
				<App />
			</TooltipProvider>
		</ThemeProvider>
	</StrictMode>,
);
```

To prevent a flash of unstyled content (FOUC), include the theme script in the `<head>` of your
`index.html`. Import `preventWrongThemeFlashScriptContent` from `@ngrok/mantle/theme` and inline
its output:

> \[!WARNING]
> While mantle supports any type of react application, arbitrary react SPA apps are not the
> primary target. For now, you will need to manually include the following script in the `<head>`
> of your app.

```html
<script>
	// Inline the output of preventWrongThemeFlashScriptContent()
	// from "@ngrok/mantle/theme" here to prevent FOUC
</script>
```

You are now ready to use mantle components in your application! For example, you can use the
[Button](/components/button).

---

---
title: CodeBlock Migration
description: Migrate from PrismJS-powered code blocks to @ngrok/mantle's Shiki-powered CodeBlock component.
---

# Mantle CodeBlock Migration Guide

This document describes how to migrate from PrismJS-powered code blocks to `@ngrok/mantle`'s Shiki-powered CodeBlock component. There are three packages involved:

| Package                                   | Purpose                                                                              | When to install                          |
| ----------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------- |
| `@ngrok/mantle`                           | Runtime React components (`CodeBlock.*`, `mantleCode`, `createMantleCodeBlockValue`) | Always                                   |
| `@ngrok/mantle-vite-plugins`              | Vite build-time transforms (tagged templates + MDX fenced code blocks)               | When using Vite                          |
| `@ngrok/mantle-server-syntax-highlighter` | Server-side Shiki highlighting engine                                                | When highlighting on a server at runtime |

Key design principle: **syntax highlighting never runs in the browser**. It happens at build time (Vite plugin), at request time (server highlighter), or not at all (graceful fallback to plain text).

> **Security note:** `preHtml` is rendered via `dangerouslySetInnerHTML`. Only pass HTML produced by Shiki (via the Vite plugin, server highlighter, or highlight server). Never pass unsanitized user input as `preHtml`.

---

## Migrating from PrismJS (Before → After)

If your app currently uses PrismJS (directly or via `react-syntax-highlighter`), here are the patterns you need to find and replace.

### What to search for (old patterns)

Look for these imports and usages in your codebase:

```tsx
// OLD: PrismJS imports (remove these)
import Prism from "prismjs";
import "prismjs/components/prism-typescript";
import "prismjs/themes/prism.css";
import { Prism as SyntaxHighlighter } from "react-syntax-highlighter";
import SyntaxHighlighter from "react-syntax-highlighter";
import { Light as SyntaxHighlighter } from "react-syntax-highlighter";

// OLD: PrismJS usage patterns
<SyntaxHighlighter language="typescript">{code}</SyntaxHighlighter>
<SyntaxHighlighter language="typescript" showLineNumbers>{code}</SyntaxHighlighter>

// OLD: manual Prism.highlight calls
const html = Prism.highlight(code, Prism.languages.typescript, "typescript");

// OLD: Legacy mantle CodeBlock with separate language prop
import { CodeBlock, fmtCode } from "@ngrok/mantle/code-block";
<CodeBlock.Code language="typescript" value={fmtCode`const x = 1;`} />

// OLD: useEffect-based highlighting
useEffect(() => {
  Prism.highlightAll();
}, []);
```

### Replacement patterns (new)

```tsx
// NEW: Static code known at build time (Vite plugin transforms this)
import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";

<CodeBlock.Root>
	<CodeBlock.Body>
		<CodeBlock.CopyButton />
		<CodeBlock.Code value={mantleCode("typescript")`const x = 1;`} />
	</CodeBlock.Body>
</CodeBlock.Root>;

// NEW: Dynamic code (not known at build time, no highlighting)
import { CodeBlock, createMantleCodeBlockValue } from "@ngrok/mantle/code-block";

<CodeBlock.Code value={createMantleCodeBlockValue({ code, language: "typescript" })} />;

// NEW: Dynamic code WITH highlighting (requires server highlighter or sidecar)
// See Use Cases 1 and 3 below for details
```

### Key differences from PrismJS

| PrismJS / react-syntax-highlighter                 | Mantle CodeBlock                                                         |
| -------------------------------------------------- | ------------------------------------------------------------------------ |
| Highlighting runs in the browser                   | Highlighting runs at build time or on the server, never in browser       |
| Language is a prop on the component                | Language is part of `mantleCode("lang")` or `createMantleCodeBlockValue` |
| Imports grammar files per language                 | No grammar imports needed — Shiki bundles are build/server only          |
| `useEffect` + `Prism.highlightAll()`               | No effect needed — HTML is pre-rendered                                  |
| Ships \~30-100KB+ JS to browser                    | Ships 0KB highlighting JS to browser                                     |
| `suppressHydrationWarning` needed for SSR          | No hydration mismatch — HTML is stable                                   |
| CSS classes like `.token.keyword`, `.token.string` | CSS variables like `--shiki-token-keyword`                               |

### CSS migration

Remove PrismJS theme CSS imports and any custom Prism token styles:

```tsx
// REMOVE these
import "prismjs/themes/prism.css";
import "prismjs/themes/prism-tomorrow.css";
// or any custom .token.keyword { color: ... } styles
```

Mantle's `mantle.css` already includes the Shiki CSS variable theme. Just ensure you import it:

```tsx
import "@ngrok/mantle/mantle.css";
```

### Uninstall old packages

```bash
pnpm remove prismjs react-syntax-highlighter @types/prismjs @types/react-syntax-highlighter
```

---

## Use Case 1: React 19 + Vite + Node Server (e.g. React Router 7 / Express)

This is the most common setup. You have a Vite-built React app served by a Node.js server (React Router 7, Express, Fastify, etc.). You want:

- Build-time highlighting for static code in components (via `mantleCode` tagged templates)
- Server-side highlighting for dynamic code (via an API route using `@ngrok/mantle-server-syntax-highlighter`)
- MDX fenced code block highlighting (if you use MDX)

### 1. Install dependencies

```bash
# runtime
pnpm add -E @ngrok/mantle

# build-time (Vite plugin for mantleCode tagged templates + MDX rehype plugin)
pnpm add -DE @ngrok/mantle-vite-plugins

# server-side (for dynamic/user-provided code highlighting at request time)
pnpm add -E @ngrok/mantle-server-syntax-highlighter
```

### 2. Configure Vite

```ts
// vite.config.ts
import { mantleCodeBlockPlugins } from "@ngrok/mantle-vite-plugins";
import { defineConfig } from "vite";

const codeBlockPlugins = mantleCodeBlockPlugins();

export default defineConfig({
	plugins: [
		// Vite plugin: transforms mantleCode("lang")`...` tagged templates at build time
		...codeBlockPlugins.vitePlugins,

// If using MDX, add the rehype plugin to your MDX config:
		// mdx({
		//   rehypePlugins: [...codeBlockPlugins.rehypePlugins],
		// }),
	],
});
```

#### Plugin options

`mantleCodeBlockPlugins()` accepts an options object:

```ts
mantleCodeBlockPlugins({
	runtime: true, // (default true) enables mantleCode`` tagged template transforms
	mdx: true, // (default true) enables MDX fenced code block rehype plugin
});
```

If you don't use MDX, you can disable it: `mantleCodeBlockPlugins({ mdx: false })`.
If you only use MDX and not tagged templates: `mantleCodeBlockPlugins({ runtime: false })`.

### 3. Use CodeBlock in components (build-time highlighting)

```tsx
import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";

function MyComponent() {
	return (
		<CodeBlock.Root>
			<CodeBlock.Header>
				<CodeBlock.Icon preset="file" />
				<CodeBlock.Title>example.ts</CodeBlock.Title>
			</CodeBlock.Header>
			<CodeBlock.Body>
				<CodeBlock.CopyButton />
				<CodeBlock.Code
					value={mantleCode("typescript")`
            const greeting = "Hello, world!";
            console.log(greeting);
          `}
				/>
			</CodeBlock.Body>
		</CodeBlock.Root>
	);
}
```

The Vite plugin rewrites `mantleCode("typescript")\`...\``at build time, injecting pre-rendered Shiki HTML into the`\~preHtml\` property. No Shiki code ships to the browser.

#### mantleCode options

```ts
mantleCode("typescript", {
	showLineNumbers: true,
	highlightLines: [1, "3-5"],
	lineNumberStart: 10,
	indentation: "spaces", // or "tabs" — overrides language default
})`const x = 1;`;
```

#### Indentation defaults

Languages have default indentation styles. Tab-indented by default: `csharp`, `css`, `go`, `html`, `java`, `javascript`, `js`, `jsx`, `typescript`, `ts`, `tsx`, `xml`. All other languages default to spaces unless overridden. Use the `indentation` option to override.

#### Interpolation

```tsx
mantleCode("typescript")`const name = "${userName}";`;
```

Interpolated values are replaced at runtime via placeholder substitution. The Vite plugin highlights the template with placeholders, and the component swaps in real values at render time. The copy button copies the plain-text version with real values.

**Limitation:** If an interpolated value changes the token type at that position (e.g., injecting a bare identifier where the placeholder sits inside string quotes), the syntax highlighting color of the surrounding span may be incorrect. This is acceptable for typical usage where interpolated values appear inside strings, template expressions, or command substitutions.

### 4. Server-side highlighting for dynamic code

For code that isn't known at build time (user input, API responses, database content), use the server syntax highlighter in an API route or server action.

```ts
// app/routes/api.shiki-highlight.ts (React Router 7 example)
import { createMantleServerSyntaxHighlighter } from "@ngrok/mantle-server-syntax-highlighter";

const highlighter = createMantleServerSyntaxHighlighter();

export async function action({ request }: { request: Request }) {
	const { code, language } = await request.json();

const result = await highlighter.highlight({
		code,
		language,
		// optional:
		// showLineNumbers: true,
		// highlightLines: [1, "3-5"],
		// lineNumberStart: 1,
	});

return Response.json({
		code: result.code,
		html: result.html,
		language: result.language,
		highlightLines: result.highlightLines,
		lineNumberStart: result.lineNumberStart,
		showLineNumbers: result.showLineNumbers,
	});
}
```

Then on the client, fetch from the API and construct a `MantleCodeBlockValue`:

```tsx
import {
	CodeBlock,
	createMantleCodeBlockValue,
	parseCodeBlockHighlightLines,
	parseLanguage,
} from "@ngrok/mantle/code-block";

// After fetching from your highlight API:
const value = createMantleCodeBlockValue({
	code: data.code,
	language: parseLanguage(data.language),
	preHtml: data.html,
	showLineNumbers: data.showLineNumbers,
	highlightLines: parseCodeBlockHighlightLines(data.highlightLines) ?? [],
	lineNumberStart: data.lineNumberStart,
});

// Render it:
<CodeBlock.Root>
	<CodeBlock.Body>
		<CodeBlock.CopyButton />
		<CodeBlock.Code value={value} />
	</CodeBlock.Body>
</CodeBlock.Root>;
```

### 5. MDX fenced code blocks (if using MDX)

If you use MDX, fenced code blocks are automatically highlighted at build time via the rehype plugin. You need to map the `<pre>` element to a CodeBlock component in your MDX provider:

```tsx
// components/mdx-provider.tsx
import {
	CodeBlock,
	createMantleCodeBlockValue,
	resolvePreRenderedCodeBlockProps,
	type CodeBlockPreElementInput,
} from "@ngrok/mantle/code-block";
import { MDXProvider } from "@mdx-js/react";

const components = {
	pre: (props: ComponentProps<"pre"> & CodeBlockPreElementInput) => {
		const { children, className, ...rawProps } = props;
		const { mantleCode: preRendered, props: rest } = resolvePreRenderedCodeBlockProps(rawProps);

// Fallback to plain <pre> if not a mantle-highlighted code block
		if (!preRendered) {
			return (
				<pre className={className} {...rest}>
					{children}
				</pre>
			);
		}

const { code, language, preHtml } = preRendered;
		if (!code || !language || !preHtml) {
			return (
				<pre className={className} {...rest}>
					{children}
				</pre>
			);
		}

const value = createMantleCodeBlockValue({
			language,
			code,
			preHtml,
			highlightLines: preRendered.highlightLines,
			lineNumberStart: preRendered.lineNumberStart,
			showLineNumbers: preRendered.showLineNumbers ?? true,
		});

return (
			<CodeBlock.Root>
				{preRendered.title && (
					<CodeBlock.Header>
						{preRendered.mode && <CodeBlock.Icon preset={preRendered.mode} />}
						<CodeBlock.Title>{preRendered.title}</CodeBlock.Title>
					</CodeBlock.Header>
				)}
				<CodeBlock.Body>
					<CodeBlock.CopyButton />
					<CodeBlock.Code value={value} />
				</CodeBlock.Body>
			</CodeBlock.Root>
		);
	},
};

export function MdxProvider({ children }) {
	return <MDXProvider components={components}>{children}</MDXProvider>;
}
```

MDX fenced code blocks support metadata in the opening fence:

````markdown
```tsx title="example.tsx" mode=file showLineNumbers highlight="2-3"
const x = 1;
const y = 2;
const z = x + y;
```
````

Supported meta keys: `title`, `mode` (`cli` | `file` | `traffic-policy`), `showLineNumbers`, `highlight` / `highlightLines`, `lineNumberStart`, `collapsible`, `disableCopy`.

Full example with all meta keys:

````markdown
```tsx title="example.tsx" mode=file showLineNumbers highlight="2-4" lineNumberStart=10 collapsible disableCopy
const x = 1;
const y = 2;
const z = x + y;
```
````

---

## Use Case 2: React 19 + Vite + MDX Static Content

This is for static sites or documentation sites where all code is known at build time in MDX files. No server-side highlighting is needed.

### 1. Install dependencies

```bash
# runtime
pnpm add -E @ngrok/mantle

# build-time (Vite plugin + MDX rehype plugin)
pnpm add -DE @ngrok/mantle-vite-plugins
```

You do NOT need `@ngrok/mantle-server-syntax-highlighter` because all code is static and highlighted at build time.

### 2. Configure Vite

```ts
// vite.config.ts
import mdx from "@mdx-js/rollup";
import { mantleCodeBlockPlugins } from "@ngrok/mantle-vite-plugins";
import { defineConfig } from "vite";

const codeBlockPlugins = mantleCodeBlockPlugins();

export default defineConfig({
	plugins: [
		// Vite plugin for mantleCode`` tagged templates
		...codeBlockPlugins.vitePlugins,

// MDX with the rehype plugin for fenced code block highlighting
		mdx({
			rehypePlugins: [...codeBlockPlugins.rehypePlugins],
		}),
	],
});
```

### 3. Write MDX with fenced code blocks

````markdown
# Getting Started

Install the package:

```bash mode=cli title="Command Line"
npm install @ngrok/mantle
```

Then use it:

```tsx title="app.tsx" highlight="3"
import { Button } from "@ngrok/mantle/button";

function App() {
	return <Button>Click me</Button>;
}
```
````

All fenced code blocks are pre-rendered to HTML at build time. No Shiki ships to the browser.

### 4. Set up the MDX provider

Same as Use Case 1, Step 5. Map `<pre>` to `CodeBlock` in your MDX provider using `resolvePreRenderedCodeBlockProps`.

### 5. Use mantleCode in React components (optional)

If you also have code blocks in React components (not MDX), use `mantleCode` tagged templates exactly as shown in Use Case 1, Step 3. The Vite plugin handles both MDX and tagged templates.

### What you DON'T need

- No `@ngrok/mantle-server-syntax-highlighter` — all highlighting is build-time
- No API routes for highlighting
- No `createMantleCodeBlockValue` unless you're composing values manually in React components

---

## Use Case 3: React 18 + Vite + Go Server

This is for apps where the frontend is a Vite-built React 18 SPA and the backend is a Go server. The Go server cannot run Shiki (it's JavaScript/Wasm), so you have two options for dynamic code:

**Option A:** Use `mantleCode` tagged templates for all static code (build-time, via Vite plugin) and skip server highlighting entirely. Code not known at build time renders as plain text (no syntax highlighting).

**Option B:** Run a sidecar Node.js highlighting service that the frontend calls directly for dynamic code, using `@ngrok/mantle-server-syntax-highlighter` to produce highlighted HTML.

### 1. Install dependencies

```bash
# runtime
pnpm add -E @ngrok/mantle

# build-time (Vite plugin for mantleCode tagged templates)
pnpm add -DE @ngrok/mantle-vite-plugins
```

### 2. Configure Vite

```ts
// vite.config.ts
import { mantleCodeBlockPlugins } from "@ngrok/mantle-vite-plugins";
import { defineConfig } from "vite";

const codeBlockPlugins = mantleCodeBlockPlugins({
	mdx: false, // disable MDX plugin if you don't use MDX
});

export default defineConfig({
	plugins: [...codeBlockPlugins.vitePlugins],
});
```

### 3. Use CodeBlock in components (build-time highlighting)

Exactly the same as Use Case 1, Step 3. `mantleCode` tagged templates are transformed at Vite build time — the Go server is not involved.

```tsx
import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";

function TrafficPolicyExample() {
	return (
		<CodeBlock.Root>
			<CodeBlock.Header>
				<CodeBlock.Icon preset="traffic-policy" />
				<CodeBlock.Title>traffic-policy.yaml</CodeBlock.Title>
			</CodeBlock.Header>
			<CodeBlock.Body>
				<CodeBlock.CopyButton />
				<CodeBlock.Code
					value={mantleCode("yaml")`
            on_http_request:
              actions:
                type: custom-response
                config:
                  status_code: 200
                  content: Hello, World!
          `}
				/>
			</CodeBlock.Body>
		</CodeBlock.Root>
	);
}
```

### 4. Dynamic code highlighting (Option A: plain text fallback)

If `~preHtml` is not provided, CodeBlock gracefully falls back to rendering the code as escaped plain text (no colors, but still functional with copy button, line numbers, etc.).

```tsx
import { CodeBlock, createMantleCodeBlockValue } from "@ngrok/mantle/code-block";

function DynamicCodeBlock({ code, language }: { code: string; language: string }) {
	const value = createMantleCodeBlockValue({
		code,
		language,
		// preHtml is omitted — renders as plain text
	});

return (
		<CodeBlock.Root>
			<CodeBlock.Body>
				<CodeBlock.CopyButton />
				<CodeBlock.Code value={value} />
			</CodeBlock.Body>
		</CodeBlock.Root>
	);
}
```

### 4. Dynamic code highlighting (Option B: sidecar highlight service)

Run a small Node.js sidecar alongside your Go server that uses `@ngrok/mantle-server-syntax-highlighter` to highlight code on demand. A minimal service should expose an HTTP endpoint like the following:

```bash
curl -X POST http://127.0.0.1:4444/ \
  -H 'content-type: application/json' \
  -d '{
    "code": "const sum = (a, b) => a + b;",
    "language": "typescript",
    "showLineNumbers": true
  }'
```

Response:

```json
{
	"code": "const sum = (a, b) => a + b;",
	"highlightLines": [],
	"html": "<span class=\"mantle-code-line\">...</span>",
	"language": "typescript",
	"lineNumberStart": 1,
	"showLineNumbers": true
}
```

Then fetch from the frontend and construct a `MantleCodeBlockValue`:

```tsx
import {
	CodeBlock,
	createMantleCodeBlockValue,
	parseCodeBlockHighlightLines,
	parseLanguage,
} from "@ngrok/mantle/code-block";

async function fetchHighlightedCode(code: string, language: string) {
	const response = await fetch("http://localhost:4444/", {
		method: "POST",
		headers: { "Content-Type": "application/json" },
		body: JSON.stringify({ code, language, showLineNumbers: true }),
	});
	return response.json();
}

function DynamicCodeBlock({ code, language }: { code: string; language: string }) {
	const [value, setValue] = useState(null);

useEffect(() => {
		fetchHighlightedCode(code, language).then((data) => {
			setValue(
				createMantleCodeBlockValue({
					code: data.code,
					language: parseLanguage(data.language),
					preHtml: data.html,
					showLineNumbers: data.showLineNumbers,
					highlightLines: parseCodeBlockHighlightLines(data.highlightLines) ?? [],
					lineNumberStart: data.lineNumberStart,
				}),
			);
		});
	}, [code, language]);

if (!value) {
		// Render plain text while loading
		return (
			<CodeBlock.Root>
				<CodeBlock.Body>
					<CodeBlock.Code value={createMantleCodeBlockValue({ code, language })} />
				</CodeBlock.Body>
			</CodeBlock.Root>
		);
	}

return (
		<CodeBlock.Root>
			<CodeBlock.Body>
				<CodeBlock.CopyButton />
				<CodeBlock.Code value={value} />
			</CodeBlock.Body>
		</CodeBlock.Root>
	);
}
```

### React 18 compatibility note

`@ngrok/mantle` supports React 18. The CodeBlock component uses `"use client"` directives, `useId()`, and standard hooks — all available in React 18. No React 19 features are required.

---

## Component Reference

### Compound Component Structure

```tsx
<CodeBlock.Root>
	{/* Container — manages context, applies base styles */}
	<CodeBlock.Header>
		{/* Optional — header bar with icon and title */}
		<CodeBlock.Icon /> {/* preset="file" | "cli" | "traffic-policy", or svg={<CustomIcon />} */}
		<CodeBlock.Title /> {/* Renders <h3> by default, supports asChild */}
		<CodeBlock.TabList>
			{/* Optional — pill-styled tabs in header (Radix-based) */}
			<CodeBlock.TabTrigger value="example-tab" /> {/* Individual tab trigger */}
		</CodeBlock.TabList>
	</CodeBlock.Header>
	<CodeBlock.Body>
		{/* Content wrapper — positions CopyButton */}
		<CodeBlock.CopyButton /> {/* Copy-to-clipboard with "Copied" feedback */}
		<CodeBlock.Code /> {/* Renders <pre><code> with highlighted HTML */}
		<CodeBlock.TabContent value="..." /> {/* Conditional content for each tab */}
	</CodeBlock.Body>
	<CodeBlock.ExpanderButton /> {/* Optional — "Show more" / "Show less" toggle */}
</CodeBlock.Root>
```

### Tabbed Code Blocks

Use tabs when showing the same concept in multiple languages:

```tsx
import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";

function MultiLanguageExample() {
	return (
		<CodeBlock.Root defaultTab="typescript">
			<CodeBlock.Header>
				<CodeBlock.Icon preset="file" />
				<CodeBlock.TabList>
					<CodeBlock.TabTrigger value="typescript">TypeScript</CodeBlock.TabTrigger>
					<CodeBlock.TabTrigger value="python">Python</CodeBlock.TabTrigger>
				</CodeBlock.TabList>
			</CodeBlock.Header>
			<CodeBlock.Body>
				<CodeBlock.CopyButton />
				<CodeBlock.TabContent value="typescript">
					<CodeBlock.Code value={mantleCode("typescript")`const greeting = "Hello, world!";`} />
				</CodeBlock.TabContent>
				<CodeBlock.TabContent value="python">
					<CodeBlock.Code value={mantleCode("python")`greeting = "Hello, world!"`} />
				</CodeBlock.TabContent>
			</CodeBlock.Body>
		</CodeBlock.Root>
	);
}
```

For controlled tabs, use `activeTab` and `onActiveTabChange` instead of `defaultTab`.

### Collapsible Code Blocks

Use `ExpanderButton` for long code blocks. The collapsed height is approximately 4 lines (\~13.6rem):

```tsx
<CodeBlock.Root>
	<CodeBlock.Body>
		<CodeBlock.CopyButton />
		<CodeBlock.Code
			value={mantleCode("typescript")`
			// ... many lines of code ...
		`}
		/>
	</CodeBlock.Body>
	<CodeBlock.ExpanderButton />
</CodeBlock.Root>
```

In MDX, use the `collapsible` meta key:

````markdown
```typescript collapsible
// Long code block that will be collapsed by default
```
````

### Supported Languages (28)

`bash`, `cs`, `csharp`, `css`, `go`, `html`, `java`, `javascript`, `js`, `json`, `jsx`, `plain`, `plaintext`, `py`, `python`, `rb`, `ruby`, `rust`, `sh`, `shell`, `text`, `ts`, `tsx`, `txt`, `typescript`, `xml`, `yaml`, `yml`

Many are aliases: `js`↔`javascript`, `ts`↔`typescript`, `py`↔`python`, `rb`↔`ruby`, `sh`↔`bash`↔`shell`, `cs`↔`csharp`, `yml`↔`yaml`, `plain`↔`plaintext`↔`text`↔`txt`. Unsupported languages fall back to `"text"` (plain text, no highlighting).

### Key Imports

```tsx
// Components and factories
import {
	CodeBlock,
	mantleCode,
	createMantleCodeBlockValue,
	type MantleCodeBlockValue,
} from "@ngrok/mantle/code-block";

// Utilities (for MDX provider integration)
import {
	resolvePreRenderedCodeBlockProps,
	type CodeBlockPreElementInput,
} from "@ngrok/mantle/code-block";

// Parsing helpers
import {
	parseLanguage,
	isSupportedLanguage,
	parseCodeBlockHighlightLines,
	parseCodeBlockLineNumberStart,
	parseCodeBlockShowLineNumbers,
	supportedLanguages,
} from "@ngrok/mantle/code-block";

// React-free utilities (safe for server-only code, no React dependency)
import { decorateHighlightedHtml, escapeHtml } from "@ngrok/mantle/highlight-utils";

// Vite plugins
import { mantleCodeBlockPlugins } from "@ngrok/mantle-vite-plugins";

// Server highlighter
import { createMantleServerSyntaxHighlighter } from "@ngrok/mantle-server-syntax-highlighter";
```

### Highlight Server API

The sidecar highlight server accepts `POST /` with:

| Field             | Type                 | Required | Description               |
| ----------------- | -------------------- | -------- | ------------------------- |
| `code`            | `string`             | Yes      | Source code to highlight  |
| `language`        | `string`             | Yes      | Language identifier       |
| `showLineNumbers` | `boolean`            | No       | Show line numbers         |
| `highlightLines`  | `string \| number[]` | No       | Lines/ranges to highlight |
| `lineNumberStart` | `number`             | No       | Starting line number      |

Responds with `{ code, html, language, highlightLines, lineNumberStart, showLineNumbers }`.

Health check: `GET /health` returns `200 {"status":"ok"}` when ready, `503 {"status":"starting"}` during Shiki preload.

### CSS / Theming

CodeBlock uses Mantle's built-in CSS variable theme (`mantle-css-variables`). Ensure your app imports the Mantle CSS:

```ts
import "@ngrok/mantle/mantle.css";
```

Light/dark mode is handled automatically via the Mantle `ThemeProvider`. The highlighted HTML uses CSS variable class names that respond to the active theme.

---

## Troubleshooting & Gotchas

### `mantleCode` returns plain text (no syntax highlighting)

The Vite plugin is not configured. `mantleCode` is a no-op at runtime — it requires the Vite plugin to transform tagged templates at build time. Ensure `mantleCodeBlockPlugins().vitePlugins` is in your Vite config. In development, you may see a warning in the console.

### Unsupported language silently falls back to plain text

If you pass a language string that isn't in the supported list, `parseLanguage` returns `"text"` (no highlighting, no error). Check `isSupportedLanguage(lang)` if you need to detect this.

### Highlight line `0` is silently ignored

Line numbers are 1-based. Passing `0` in `highlightLines` (e.g., `[0, 3]`) silently filters it out. Ranges like `"0-3"` are also filtered.

### `preHtml` must come from a trusted source

`preHtml` is rendered via `dangerouslySetInnerHTML`. Only pass HTML produced by Shiki through the Vite plugin, `createMantleServerSyntaxHighlighter`, or the highlight server. Never pass user-provided HTML strings.

### Tab width is hardcoded to 2 spaces

The `<pre>` element renders with `tab-size: 2`. This is not configurable via props or options.

### Title whitespace is trimmed

The `title` meta key value is trimmed — leading/trailing whitespace is removed.

### CodeBlock works without CopyButton, Header, or ExpanderButton

All sub-components besides `Root`, `Body`, and `Code` are optional. A minimal code block is:

```tsx
<CodeBlock.Root>
	<CodeBlock.Body>
		<CodeBlock.Code value={mantleCode("typescript")`const x = 1;`} />
	</CodeBlock.Body>
</CodeBlock.Root>
```

---

---
title: DataTable Action Column Migration
description: Migrate existing DataTable usages to the new DataTable.ActionHeader so the pinned action column stays aligned on horizontal scroll.
---

# Mantle DataTable Action Column Migration Guide

This document describes how to migrate existing `DataTable` usages to take advantage of the new `DataTable.ActionHeader` component, which keeps the pinned action column visually aligned across the header and every body row when the table scrolls horizontally.

**TL;DR:** If your data table has an action column whose cells use `DataTable.ActionCell`, change that column's header from `DataTable.Header` (or `<Table.Header />`, or an empty cell) to `DataTable.ActionHeader`. That's it.

---

## Why this change

Previously, a typical action column was defined like this:

```tsx
columnHelper.display({
	id: "actions",
	header: () => <DataTable.Header />, // plain, non-sticky header
	cell: () => <DataTable.ActionCell>{/* action buttons */}</DataTable.ActionCell>,
});
```

The body's `DataTable.ActionCell` was `position: sticky` and pinned to the right of the scroll container, but the header cell was a regular `<th>` that scrolled away with the rest of the row. When the table overflowed horizontally this produced two visible problems:

1. The sticky body cells stayed pinned at the right while the header's action column scrolled off, so the pinned column did not line up between the header and body.
2. There was no consistent scroll-fade treatment between the header row and the body rows — the fade indicator only appeared on body cells.

`DataTable.ActionHeader` is a sticky `<th>` that mirrors `DataTable.ActionCell`, so the action column stays pinned and aligned across the header and every body row, with a matching left-side fade that indicates content is scrolling underneath.

---

## What to search for (old patterns)

Search your codebase for any data table column definitions that use `DataTable.ActionCell` in the `cell` function. For each such column, inspect the `header` function — it is almost always one of these:

```tsx
// OLD: empty DataTable.Header
columnHelper.display({
	id: "actions",
	header: () => <DataTable.Header />,
	cell: () => <DataTable.ActionCell>{/* ... */}</DataTable.ActionCell>,
});

// OLD: no header at all (just returns null / undefined)
columnHelper.display({
	id: "actions",
	header: () => null,
	cell: () => <DataTable.ActionCell>{/* ... */}</DataTable.ActionCell>,
});

// OLD: raw Table.Header
columnHelper.display({
	id: "actions",
	header: () => <Table.Header />,
	cell: () => <DataTable.ActionCell>{/* ... */}</DataTable.ActionCell>,
});

// OLD: DataTable.Header with a label
columnHelper.display({
	id: "actions",
	header: () => <DataTable.Header>Actions</DataTable.Header>,
	cell: () => <DataTable.ActionCell>{/* ... */}</DataTable.ActionCell>,
});
```

Heuristics an agent can use to find these:

- Any `columnHelper.display({ ... })` (or `columnHelper.accessor(...)`) whose `cell` returns a `<DataTable.ActionCell>`.
- Any file that imports `DataTable` from `@ngrok/mantle/data-table` and also uses `DataTable.ActionCell`.
- Any column with `id: "actions"` (common convention but not required).

---

## Replacement pattern (new)

Change the header to `DataTable.ActionHeader`. It takes all the same props as `Table.Header` — including `children` — so you can keep labels, class names, and custom content:

```tsx
// NEW: empty sticky header (most common case)
columnHelper.display({
	id: "actions",
	header: () => <DataTable.ActionHeader />,
	cell: () => <DataTable.ActionCell>{/* ... */}</DataTable.ActionCell>,
});

// NEW: sticky header with a label
columnHelper.display({
	id: "actions",
	header: () => <DataTable.ActionHeader>Actions</DataTable.ActionHeader>,
	cell: () => <DataTable.ActionCell>{/* ... */}</DataTable.ActionCell>,
});

// NEW: sticky header with custom content (sr-only label, icon, etc.)
columnHelper.display({
	id: "actions",
	header: () => (
		<DataTable.ActionHeader>
			<span className="sr-only">Actions</span>
		</DataTable.ActionHeader>
	),
	cell: () => <DataTable.ActionCell>{/* ... */}</DataTable.ActionCell>,
});
```

No other changes are required. The styling (sticky positioning, background, and left-side fade indicator) is applied by `DataTable.ActionHeader` itself.

---

## Find/replace recipe

For most codebases a simple mechanical replacement works. Be conservative: only apply the substitution inside a column definition that also uses `DataTable.ActionCell` in its `cell` function.

1. Search for `DataTable.ActionCell` to find all action-column definitions.
2. In each match, locate the corresponding `header:` property in the same `columnHelper.display({ ... })` (or equivalent) object.
3. Replace the header JSX according to the table below:

| Before                                                 | After                                                              |
| ------------------------------------------------------ | ------------------------------------------------------------------ |
| `header: () => <DataTable.Header />`                   | `header: () => <DataTable.ActionHeader />`                         |
| `header: () => <Table.Header />`                       | `header: () => <DataTable.ActionHeader />`                         |
| `header: () => null`                                   | `header: () => <DataTable.ActionHeader />`                         |
| `header: () => <DataTable.Header>X</DataTable.Header>` | `header: () => <DataTable.ActionHeader>X</DataTable.ActionHeader>` |
| `header: () => <Table.Header>X</Table.Header>`         | `header: () => <DataTable.ActionHeader>X</DataTable.ActionHeader>` |

If the existing header passes a `className` or other props to `<DataTable.Header>`/`<Table.Header>`, forward them unchanged to `<DataTable.ActionHeader>` — the component accepts all props from `Table.Header`.

---

## Imports

No new import is required — `DataTable.ActionHeader` is exposed on the existing `DataTable` namespace object. If a file already imports `DataTable` from `@ngrok/mantle/data-table`, the migration is complete after the JSX swap:

```tsx
import { DataTable } from "@ngrok/mantle/data-table";
```

---

## Example: complete before/after

**Before:**

```tsx
import { IconButton } from "@ngrok/mantle/button";
import {
	DataTable,
	createColumnHelper,
	getCoreRowModel,
	useReactTable,
} from "@ngrok/mantle/data-table";
import { DotsThreeIcon } from "@phosphor-icons/react/DotsThree";

type Payment = { id: string; amount: number; status: string };

const columnHelper = createColumnHelper<Payment>();

const columns = [
	columnHelper.accessor("id", {
		id: "id",
		header: () => <DataTable.Header>ID</DataTable.Header>,
		cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,
	}),
	columnHelper.display({
		id: "actions",
		header: () => <DataTable.Header />,
		cell: () => (
			<DataTable.ActionCell>
				<IconButton
					appearance="ghost"
					type="button"
					size="sm"
					label="Open actions"
					icon={<DotsThreeIcon weight="bold" />}
				/>
			</DataTable.ActionCell>
		),
	}),
];
```

**After:**

type Payment = { id: string; amount: number; status: string };

const columnHelper = createColumnHelper<Payment>();

const columns = [
	columnHelper.accessor("id", {
		id: "id",
		header: () => <DataTable.Header>ID</DataTable.Header>,
		cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,
	}),
	columnHelper.display({
		id: "actions",
		header: () => <DataTable.ActionHeader />, // <-- only change
		cell: () => (
			<DataTable.ActionCell>
				<IconButton
					appearance="ghost"
					type="button"
					size="sm"
					label="Open actions"
					icon={<DotsThreeIcon weight="bold" />}
				/>
			</DataTable.ActionCell>
		),
	}),
];
```

---

## Non-breaking context

This is a purely additive change to the `DataTable` API:

- `DataTable.Header` still works as before for non-action columns.
- `DataTable.ActionCell` behavior is unchanged from the consumer's perspective — it is still a sticky `<td>` positioned at the right of the row. Internally it now renders a left-side indicator span (1px divider + soft shadow gradient) and uses `bg-inherit` for an opaque background that tracks the row's hover state.
- `DataTable.ActionHeader` is empty-state aware — when the table body has no rows, it renders as a plain `<th>` (no sticky positioning, no indicator, no right-side fade suppression) so the empty state looks natural.
- Tables without an action column need no changes.
- Tables with an action column that keep using the old `DataTable.Header` for the header will continue to render correctly — they just won't get the aligned sticky header or the matching fade indicator on the header row.

Migrating every data table that has a `DataTable.ActionCell` is recommended for visual consistency, but can be done incrementally.

---

## Related table behavior changes

Alongside `DataTable.ActionHeader`, `Table.Root` (and therefore every `DataTable.Root`) received the following internal behavior changes. Consumers typically do not need to do anything — they are listed here for completeness:

- **Scroll fade mask is now applied inside the border.** `Table.Root` now renders an outer wrapper (border, rounded corners, background) and an inner scroll container (mask + horizontal scrolling). The border and rounded corners stay crisp at every scroll position; the fade only affects the scrolling table content.
- **Bidirectional scroll fade via `scroll-fade-x`.** Both left and right edges fade based on scroll position. When the table contains a sticky right column (`DataTable.ActionCell` / `DataTable.ActionHeader`), the right-side fade is suppressed so the pinned column stays fully opaque — the pinned column provides its own left-side indicator instead.
- **Y-scroll is disabled on the scroll container.** The inner scroll container uses `overflow-x: auto; overflow-y: clip` so the table only scrolls horizontally. Tall tables grow the container; page-level scrolling handles vertical overflow as before.
- **Overscroll bounce is disabled on both axes** via `overscroll-behavior: none`.
- **Sticky cells are opaque.** `DataTable.ActionCell` and `DataTable.ActionHeader` use `background-color: inherit` so they pick up the row's current background (including hover state) and cover scrolling content behind them.
- **Scroll detection uses `useLayoutEffect` and `requestAnimationFrame` coalescing.** The horizontal overflow observer now corrects state before the browser paints (avoiding flash-of-incorrect-state) and batches rapid-fire scroll, resize, and mutation events into a single layout read per frame.

No consumer code change is required for any of the above.

---

---
title: Dialog.Footer DOM Order Migration
description: Dialog.Footer no longer reverses its children — reverse footer children to preserve their visual layout.
---

# Mantle Dialog.Footer DOM Order Migration Guide

`@ngrok/mantle`'s `Dialog.Footer` no longer reverses its children. Previously it
applied `flex-row-reverse`, which laid its children out **right-to-left** — so
the DOM order was the visual mirror of what you wrote. It now uses normal
`flex` with `justify-end`, so children render **left-to-right in DOM order**,
matching `Sheet.Footer` and `AlertDialog.Footer`.

**TL;DR:** For every `Dialog.Footer` with two or more children, **reverse the
order of its direct children**. The conventional layout is the secondary/cancel
action first and the primary action last (so the primary action stays on the
right). Footers with a single child need no change.

---

## You are an agent migrating a codebase. Do this:

1. Find every `Dialog.Footer` (the footer of `@ngrok/mantle`'s `Dialog`
   compound component). Search for `Dialog.Footer`, and for any destructured or
   renamed imports of the same component (e.g. `const { Footer } = Dialog;` or
   `import { Footer } from "@ngrok/mantle/dialog"`).
2. For each `Dialog.Footer` with **two or more direct children**, reverse the
   order of those direct children. Do not touch the children's internals — only
   their order.
3. Leave `Dialog.Footer` instances with **zero or one** direct child unchanged.
4. **Do not** touch `Sheet.Footer` or `AlertDialog.Footer`. They already render
   in DOM order and are not affected by this change.
5. After editing, re-run the project's formatter, linter, and type checker.

> **Why reverse?** The visual result must stay the same. Under the old
> `flex-row-reverse`, the first DOM child rendered on the right. Code was
> therefore written primary-action-first to put the primary action on the
> right. Now that children render in DOM order, primary-action-first would put
> the primary action on the **left**. Reversing restores the intended
> left-to-right appearance (secondary/cancel on the left, primary on the right).

---

## Before → After

### Two actions (most common)

```tsx
// BEFORE — primary action written first to land on the right under flex-row-reverse
<Dialog.Footer>
	<Button type="button" appearance="filled" priority="neutral">
		Save
	</Button>
	<Dialog.Close asChild>
		<Button type="button" appearance="outlined">
			Cancel
		</Button>
	</Dialog.Close>
</Dialog.Footer>
```

```tsx
// AFTER — DOM order matches visual order: cancel on the left, primary on the right
<Dialog.Footer>
	<Dialog.Close asChild>
		<Button type="button" appearance="outlined">
			Cancel
		</Button>
	</Dialog.Close>
	<Button type="button" appearance="filled" priority="neutral">
		Save
	</Button>
</Dialog.Footer>
```

### Destructive confirmation

```tsx
// BEFORE
<Dialog.Footer>
	<Dialog.Close asChild>
		<Button type="button" priority="danger" appearance="filled">
			Delete
		</Button>
	</Dialog.Close>
	<Dialog.Close asChild>
		<Button type="button" priority="neutral" appearance="outlined">
			Cancel
		</Button>
	</Dialog.Close>
</Dialog.Footer>
```

```tsx
// AFTER
<Dialog.Footer>
	<Dialog.Close asChild>
		<Button type="button" priority="neutral" appearance="outlined">
			Cancel
		</Button>
	</Dialog.Close>
	<Dialog.Close asChild>
		<Button type="button" priority="danger" appearance="filled">
			Delete
		</Button>
	</Dialog.Close>
</Dialog.Footer>
```

### Single action — no change

```tsx
// A footer with one child renders identically before and after. Leave it alone.
<Dialog.Footer>
	<Dialog.Close asChild>
		<Button type="button" appearance="outlined">
			Close
		</Button>
	</Dialog.Close>
</Dialog.Footer>
```

---

## Edge cases & gotchas

- **More than two children.** The rule is the same: reverse the full child
  order. A footer rendered `[A, B, C]` under the old reversal appeared as
  `[C, B, A]`; to preserve that appearance, write `[C, B, A]` now.
- **Conditional children.** When children are rendered with `&&`, ternaries, or
  `.map`, reverse the order in which they appear, not just the static JSX. For
  mapped lists, reverse the array (or render order) so the visual sequence is
  unchanged.
- **Custom `className` on `Dialog.Footer`.** If a footer overrode the layout
  (e.g. added its own `flex-row-reverse`, `flex-row`, or `justify-*`), review it
  by hand — the base class change may interact with the override. The base now
  contributes `flex justify-end`.
- **`Dialog.Footer` with non-action content** (text, links, a left-aligned
  hint alongside buttons): verify the layout visually. If it relied on the
  reversal for positioning, adjust with explicit classes rather than DOM order.
- **Single-child footers and footers you cannot confidently reorder:** leave
  them and flag them for human review rather than guessing.

---

## How to verify

1. Open each affected dialog and confirm the buttons appear in the same visual
   order as before the change (typically secondary/cancel on the left, primary
   on the right).
2. Confirm tab order now follows visual order left-to-right. (This is a
   secondary benefit of the change — under the old reversal, keyboard tab order
   did not match visual order.)
3. Run the project's formatter, linter, type checker, and tests.

---

---
title: Philosophy
description: The design principles and architectural philosophy behind mantle, ngrok's UI library and design system
---

# Philosophy

Every architectural decision in Mantle traces back to a simple premise: start with the
web platform, then layer on just enough abstraction to make it great. These principles
guide what we build, how we build it, and—just as importantly—what we choose not to build.

## Composition Over Configuration

Mantle composes around established, unstyled primitive libraries—[Radix UI](https://www.radix-ui.com),
[Ariakit](https://ariakit.org), and [Headless UI](https://headlessui.com)—rather than
reinventing interaction patterns from scratch. This gives us battle-tested accessibility
and behavior paired with ngrok's visual design language.

Components compose naturally with each other and with your own code. The `asChild`
pattern lets you swap the rendered element entirely, so Mantle never forces you into a
particular DOM structure. Configuration props handle the common case; composition
handles everything else.

## Semantic HTML, Then Everything Else

The right HTML element is always the starting point. A [Button](/components/button) renders
a `<button>`, not a styled `<div>` with click handlers. Form controls use `<input>`. Headings
follow a proper hierarchy. This isn't pedantic—it's practical.

Semantic markup gives you keyboard navigation, focus management, and screen reader
support for free. It works when CSS fails to load and when JavaScript is disabled. It
means every Mantle component is inherently accessible, compliant with WAI-ARIA patterns,
and meaningful to assistive technologies, search engines, and any tool that parses HTML.

From that foundation, Mantle progressively enhances. A button is still a button—but with
loading states, icon slots, and variant styling layered on top. The underlying element
always does the heavy lifting.

## Tailwind as Design Language

Mantle uses [Tailwind CSS](https://tailwindcss.com) as both its styling engine and its
design language. A custom theme defines ngrok's design tokens—colors, spacing,
typography—as semantic values that adapt automatically across themes and contexts.

Because the tokens are expressed as Tailwind utilities, developers extend components
with the same vocabulary they already know. Custom styling stays on-system by default.
There's no separate theming API to learn and no abstraction boundary between Mantle's
styles and yours.

## Developer Ergonomics

Every component is built with TypeScript, but Mantle avoids exposing complex generics or
internal type machinery. Type inference does the work: variant props autocomplete
through `class-variance-authority`, contracts are enforced at compile time, and the
API surface stays small enough to hold in your head.

Consistency reinforces this. Prop names, variant patterns, event handling, and
composition patterns are uniform across the library. If you understand how one Mantle
component works, you can predict how the rest behave. Learn the system once; apply it
everywhere.

## Ship Less, Ship Better

Mantle is tree-shakable and modularly exported—you pay for only what you import. Teams
can adopt the design system incrementally, one component at a time, without pulling in
the entire library.

Runtime performance is a design constraint, not an afterthought. Components minimize
re-renders, avoid unnecessary DOM nodes, and lean on the browser's native capabilities
wherever possible. The fastest code is the code that never runs, and the most
reliable code is the code that doesn't exist.

## Evolution, Not Revolution

Mantle evolves with ngrok's needs and the broader web platform. We favor incremental
improvements over sweeping rewrites, so existing code continues to work as the system
grows.

This applies equally to API design, framework compatibility, and adoption of new web
standards. Stable foundations and thoughtful migration paths beat short-term convenience
every time.

---

---
title: color
description: Color constants and type guards from @ngrok/mantle/color
---

# color

Color constants, type guards, and TypeScript types for Mantle's color system. Useful for building components that accept a `color` prop constrained to Mantle's palette.

```ts
import {
	colors,
	namedColors,
	functionalColors,
	isColor,
	isNamedColor,
	isFunctionalColor,
} from "@ngrok/mantle/color";
import type { Color, NamedColor, FunctionalColor } from "@ngrok/mantle/color";
```

## Color Categories

Mantle has two categories of colors:

**Named colors** — the 18 palette colors:

**Functional colors** — semantic role-based colors:

## Constants

### `namedColors`

Read-only array of all named colors.

```ts
import { namedColors } from "@ngrok/mantle/color";

namedColors; // readonly ["amber", "blue", "cyan", ...]
```

### `functionalColors`

Read-only array of all functional colors.

```ts
import { functionalColors } from "@ngrok/mantle/color";

functionalColors; // readonly ["info", "accent", "danger", "neutral", "success", "warning"]
```

### `colors`

Read-only array of all colors (named + functional).

```ts
import { colors } from "@ngrok/mantle/color";

colors; // readonly [...namedColors, ...functionalColors]
```

## Type Guards

### `isNamedColor(value)`

Returns `true` if `value` is a named color string.

```ts
import { isNamedColor } from "@ngrok/mantle/color";

isNamedColor("blue"); // true
isNamedColor("danger"); // false
isNamedColor("foo"); // false
```

### `isFunctionalColor(value)`

Returns `true` if `value` is a functional color string.

```ts
import { isFunctionalColor } from "@ngrok/mantle/color";

isFunctionalColor("danger"); // true
isFunctionalColor("blue"); // false
isFunctionalColor("foo"); // false
```

### `isColor(value)`

Returns `true` if `value` is any Mantle color (named or functional).

```ts
import { isColor } from "@ngrok/mantle/color";

isColor("blue"); // true
isColor("danger"); // true
isColor("foo"); // false
```

## Types

| Type              | Description                        |
| ----------------- | ---------------------------------- |
| `NamedColor`      | One of the 18 named palette colors |
| `FunctionalColor` | One of the 6 semantic role colors  |
| `Color`           | `NamedColor \| FunctionalColor`    |

## Example: Color Prop

```tsx
import { isColor } from "@ngrok/mantle/color";
import type { Color } from "@ngrok/mantle/color";

type BadgeProps = {
	color: Color;
	children: React.ReactNode;
};

function Badge({ color, children }: BadgeProps) {
	return <span data-color={color}>{children}</span>;
}
```

---

---
title: composeRefs
description: Compose multiple React refs into a single callback ref from @ngrok/mantle/utils
---

# composeRefs

A utility that composes multiple React refs (callback refs and `RefObject`s) into a single callback ref. Useful when you need to assign a DOM node to more than one ref at the same time.

For the React hook version that wraps this in `useCallback` for stability, see [`useComposedRefs`](/hooks#useComposedRefs) in `@ngrok/mantle/hooks`.

```ts
import { composeRefs } from "@ngrok/mantle/utils";
```

## Usage

### With `forwardRef`

The most common use case: forward a ref to a parent while keeping an internal ref for the component itself.

```tsx
import { forwardRef, useRef } from "react";
import { composeRefs } from "@ngrok/mantle/utils";

const MyInput = forwardRef<HTMLInputElement>((props, forwardedRef) => {
	const internalRef = useRef<HTMLInputElement>(null);

return <input ref={composeRefs(internalRef, forwardedRef)} {...props} />;
});
```

### With multiple refs

```tsx
import { useRef } from "react";
import { composeRefs } from "@ngrok/mantle/utils";

function Example() {
	const focusRef = useRef<HTMLButtonElement>(null);
	const measureRef = useRef<HTMLButtonElement>(null);

return <button ref={composeRefs(focusRef, measureRef)}>Click me</button>;
}
```

### With callback refs

`composeRefs` accepts any mix of `RefObject`s and callback refs:

```tsx
import { useRef } from "react";
import { composeRefs } from "@ngrok/mantle/utils";

function Example() {
	const objectRef = useRef<HTMLDivElement>(null);
	const callbackRef = (node: HTMLDivElement | null) => {
		if (node) {
			console.log("mounted", node);
		}
	};

return <div ref={composeRefs(objectRef, callbackRef)} />;
}
```

## API

```ts
function composeRefs<T>(...refs: PossibleRef<T>[]): (node: T) => void;

type PossibleRef<T> = React.Ref<T> | undefined;
```

Accepts any number of refs (callback refs, `RefObject`s, or `undefined`). Returns a single callback ref that, when called with a node, assigns the node to all provided refs. `undefined` refs are safely skipped.

---

---
title: cx
description: Class name composition utility from @ngrok/mantle/cx
---

# cx

A class name composition utility that combines conditional class names and resolves Tailwind CSS conflicts using left-to-right merge order.

Wraps [`clsx`](https://github.com/lukeed/clsx) for conditional class handling and [`tailwind-merge`](https://github.com/dcastil/tailwind-merge) for conflict resolution, so later classes override earlier ones (same behavior as inline styles).

```ts
import { cx } from "@ngrok/mantle/cx";
```

## Usage

```tsx
import { cx } from "@ngrok/mantle/cx";

// Strings
cx("px-4 py-2", "text-sm");
// → "px-4 py-2 text-sm"

// Conditional classes (object syntax)
cx("base", { active: isActive, disabled: isDisabled });

// Conditional classes (falsy values are ignored)
cx("base", isActive && "active", isDisabled && "disabled");

// Tailwind conflict resolution — later class wins
cx("text-red-500", "text-blue-500");
// → "text-blue-500"

// Arrays
cx(["px-4", "py-2"], "text-sm");
```

## Tailwind Conflict Resolution

`cx` uses `tailwind-merge` to resolve conflicts between Tailwind utility classes. When two classes target the same CSS property, the last one wins:

```tsx
// Without cx — both classes are applied, browser resolves by specificity (unpredictable, stinky)
<div className={`text-red-500 ${override}`} />

// With cx — later class always wins (predictable, like inline styles)
<div className={cx("text-red-500", override)} />
```

This makes `cx` safe to use for component prop overrides:

```tsx
import { cx } from "@ngrok/mantle/cx";

type ButtonProps = {
	className?: string;
};

function Button({ className }: ButtonProps) {
	return <button className={cx("bg-blue-500 text-white px-4 py-2 rounded", className)} />;
}

// The consumer's class overrides the default
<Button className="bg-red-500" />;
// → "text-white px-4 py-2 rounded bg-red-500"
```

## API

```ts
function cx(...inputs: ClassValue[]): string;

Accepts any combination of:

| Input type   | Example                                 | Notes                                |
| ------------ | --------------------------------------- | ------------------------------------ |
| `string`     | `"px-4 py-2"`                           | Added as-is                          |
| `object`     | `{ active: true, disabled: false }`     | Keys with truthy values are included |
| `array`      | `["px-4", isActive && "bg-blue-500"]`   | Recursively processed                |
| Falsy values | `false`, `null`, `undefined`, `0`, `""` | Ignored                              |

The return value is a single deduplicated, conflict-resolved class string.

## Convention

All `className` values in Mantle must be built with `cx`.
String interpolation, `+`, ternaries, or conditional expressions directly on `className` are not allowed — see [CONVENTIONS.md](https://github.com/ngrok/mantle/blob/main/CONVENTIONS.md).

---

---
title: highlight-utils
description: React-free code highlighting helpers from @ngrok/mantle/highlight-utils
---

# highlight-utils

React-free helpers for code highlighting pipelines. Use these from build tools, server-side renderers, Web Workers, or small syntax-highlighting services that need Mantle-compatible Code Block HTML without importing React components.

For ordinary React UI, prefer [`CodeBlock`](/components/code-block) and `mantleCode()` from `@ngrok/mantle/code-block`.

```ts
import {
	decorateHighlightedHtml,
	isSupportedLanguage,
	normalizeIndentation,
	parseLanguage,
} from "@ngrok/mantle/highlight-utils";
```

## Usage

### Decorate Shiki HTML

`decorateHighlightedHtml` takes trusted Shiki-highlighted HTML and wraps each line in the markup Mantle's `CodeBlock.Code` expects for line numbers and highlighted lines.

```ts
import { decorateHighlightedHtml } from "@ngrok/mantle/highlight-utils";

const html = `<span class="line">const tunnel = await ngrok.forward();</span>`;

const decoratedHtml = decorateHighlightedHtml({
	html,
	showLineNumbers: true,
	lineNumberStart: 10,
	highlightLines: [10],
});
```

Only pass HTML produced by a trusted highlighter such as Shiki. The returned string is intended to be rendered as HTML by a Code Block pipeline.

### Normalize indentation

`normalizeIndentation` trims leading and trailing blank space, removes the common indentation prefix, and rewrites leading whitespace to tabs or spaces.

```ts
import { normalizeIndentation } from "@ngrok/mantle/highlight-utils";

const code = normalizeIndentation(
	`
		function main() {
			return "ready";
		}
	`,
	{ indentation: "tabs" },
);
```

### Parse languages

Use `parseLanguage` and `isSupportedLanguage` when accepting language names from Markdown fences, user input, or service payloads.

```ts
import { isSupportedLanguage, parseLanguage } from "@ngrok/mantle/highlight-utils";

parseLanguage("language-tsx"); // "tsx"
parseLanguage(undefined); // "text"
isSupportedLanguage("python"); // true
```

## API

| Export                                 | Description                                                            |
| -------------------------------------- | ---------------------------------------------------------------------- |
| `decorateHighlightedHtml`              | Adds Mantle line wrappers, line numbers, and highlighted-line classes. |
| `normalizeIndentation`                 | Normalizes multiline code indentation to spaces or tabs.               |
| `inferIndentation`                     | Chooses an indentation style from language and optional preference.    |
| `isIndentation`                        | Type guard for `"tabs"` or `"spaces"`.                                 |
| `supportedLanguages`                   | Read-only list of languages Mantle recognizes for code highlighting.   |
| `isSupportedLanguage`                  | Type guard for supported language strings.                             |
| `parseLanguage`                        | Parses `language-*` / `lang-*` class names with a `"text"` fallback.   |
| `defaultShowLineNumbers`               | Returns Mantle's default line-number behavior for a language and code. |
| `parseCodeBlockHighlightLines`         | Parses line highlight input from arrays or comma-separated strings.    |
| `parseCodeBlockLineNumberStart`        | Parses a positive line-number start value.                             |
| `parseCodeBlockShowLineNumbers`        | Parses boolean or `"true"` / `"false"` line-number flags.              |
| `tokenizeMetastring`, `normalizeValue` | Low-level helpers for code fence metadata parsing.                     |

## Types

```ts
import type {
	DecorateHighlightedHtmlInput,
	Indentation,
	LineRange,
	SupportedLanguage,
} from "@ngrok/mantle/highlight-utils";
```

---

---
title: inView
description: Framework-agnostic IntersectionObserver utility from @ngrok/mantle/utils
---

# inView

A framework-agnostic utility that observes when a DOM element enters or leaves the viewport (or a scrollable container) using the [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver) API.

When the element enters view, `onStart` is called. If `onStart` returns a function, that function is called when the element leaves. Returns a cleanup function that disconnects the observer.

Use [`useInView`](/hooks#useInView) instead when working inside React components.

```ts
import { inView } from "@ngrok/mantle/utils";
```

## Usage

```ts
import { inView } from "@ngrok/mantle/utils";

const element = document.querySelector(".my-element");

const stop = inView(element, (el) => {
	el.classList.add("visible");
	return () => el.classList.remove("visible");
});

// Later, stop observing:
stop();
```

### One-shot (enter only)

If `onStart` returns nothing (`undefined` or `void`), the observer automatically unobserves the element after the first entry — useful for one-shot entrance animations:

```ts
import { inView } from "@ngrok/mantle/utils";

const element = document.querySelector(".fade-in");

inView(element, (el) => {
	el.classList.add("animate");
	// No return value → stops observing after first entry
});
```

### Custom threshold

```ts
import { inView } from "@ngrok/mantle/utils";

// Trigger only when 50% of the element is visible
inView(
	element,
	(el) => {
		el.classList.add("half-visible");
		return () => el.classList.remove("half-visible");
	},
	{ amount: 0.5 },
);
```

### Scoped to a scrollable container

```ts
import { inView } from "@ngrok/mantle/utils";

const container = document.querySelector(".scroll-container");

inView(
	element,
	(el) => {
		el.classList.add("in-view");
		return () => el.classList.remove("in-view");
	},
	{ root: container },
);
```

## API

```ts
function inView(
	element: Element,
	onStart: (element: Element, entry: IntersectionObserverEntry) => void | ViewChangeHandler,
	options?: InViewOptions,
): VoidFunction;
```

### Parameters

| Parameter | Type                                            | Description                                                                                                                                                 |
| --------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `element` | `Element`                                       | The DOM element to observe.                                                                                                                                 |
| `onStart` | `(element, entry) => void \| ViewChangeHandler` | Called when the element enters the viewport. Return a function to be called when the element leaves, or return nothing to stop observing after first entry. |
| `options` | `InViewOptions`                                 | Optional configuration.                                                                                                                                     |

### Options

| Option   | Type                        | Default  | Description                                                                                                        |
| -------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `root`   | `Element \| Document`       | viewport | The scrollable container to observe within.                                                                        |
| `margin` | `string`                    | `"0px"`  | Expand or contract the root bounds. Same syntax as CSS `margin` (e.g. `"10px"`, `"10% 0px"`).                      |
| `amount` | `"some" \| "all" \| number` | `"some"` | How much of the element must be visible. `"some"` = any part, `"all"` = fully visible, or a ratio between `0`–`1`. |

### Return value

Returns a `VoidFunction` that unobserves the element and disconnects the observer when called.

---

---
title: sorting
description: Sorting constants, type guards, and comparators from @ngrok/mantle/utils
---

# sorting

Sorting constants, type guards, and date comparator functions for building consistent, type-safe sort controls.

```ts
import {
	sortingModes,
	sortingDirections,
	timeSortingDirections,
	alphanumericSortingDirections,
	isSortingMode,
	isSortingDirection,
	isTimeSortingDirection,
	isAlphanumericSortingDirection,
	$sortingMode,
	$sortingDirection,
	$timeSortingDirection,
	$alphanumericSortingDirection,
	timeSortingByDirection,
	compareDatesNewestToOldest,
	compareDatesOldestToNewest,
} from "@ngrok/mantle/utils";

import type {
	SortingMode,
	SortingDirection,
	TimeSortingDirection,
	AlphanumericSortingDirection,
} from "@ngrok/mantle/utils";
```

## Types

| Type                           | Values                                     |
| ------------------------------ | ------------------------------------------ |
| `SortingMode`                  | `"alphanumeric" \| "time"`                 |
| `SortingDirection`             | `"asc" \| "desc"`                          |
| `AlphanumericSortingDirection` | `"asc" \| "desc"`                          |
| `TimeSortingDirection`         | `"newest-to-oldest" \| "oldest-to-newest"` |

## Constants

### `sortingModes`

```ts
sortingModes; // readonly ["alphanumeric", "time"]
```

### `sortingDirections`

```ts
sortingDirections; // readonly ["asc", "desc"]
```

### `alphanumericSortingDirections`

```ts
alphanumericSortingDirections; // readonly ["asc", "desc"]
```

### `timeSortingDirections`

```ts
timeSortingDirections; // readonly ["newest-to-oldest", "oldest-to-newest"]
```

### `timeSortingByDirection`

Maps a `SortingDirection` to its equivalent `TimeSortingDirection`.

```ts
timeSortingByDirection;
// { asc: "oldest-to-newest", desc: "newest-to-oldest" }

timeSortingByDirection["asc"]; // "oldest-to-newest"
timeSortingByDirection["desc"]; // "newest-to-oldest"
```

## Type Guards

### `isSortingMode(value)`

```ts
isSortingMode("alphanumeric"); // true
isSortingMode("time"); // true
isSortingMode("foo"); // false
```

### `isSortingDirection(value)`

```ts
isSortingDirection("asc"); // true
isSortingDirection("desc"); // true
isSortingDirection("foo"); // false
```

### `isAlphanumericSortingDirection(value)`

```ts
isAlphanumericSortingDirection("asc"); // true
isAlphanumericSortingDirection("desc"); // true
isAlphanumericSortingDirection("foo"); // false
```

### `isTimeSortingDirection(value)`

```ts
isTimeSortingDirection("newest-to-oldest"); // true
isTimeSortingDirection("oldest-to-newest"); // true
isTimeSortingDirection("asc"); // false
isTimeSortingDirection("foo"); // false
```

## Runtime Value Helpers (`$` prefix)

The `$`-prefixed helpers are identity functions that provide a runtime value with the correct inferred type. Useful for deriving typed values from string literals without a `as const` cast.

### `$sortingMode(value)`

```ts
$sortingMode("alphanumeric"); // "alphanumeric" (typed as SortingMode)
$sortingMode("time"); // "time"
```

### `$sortingDirection(value)`

```ts
$sortingDirection("asc"); // "asc" (typed as SortingDirection)
$sortingDirection("desc"); // "desc"
```

### `$alphanumericSortingDirection(value)`

```ts
$alphanumericSortingDirection("asc"); // "asc" (typed as AlphanumericSortingDirection)
$alphanumericSortingDirection("desc"); // "desc"
```

### `$timeSortingDirection(value)`

Accepts either a `TimeSortingDirection` or a `SortingDirection`. When given a `SortingDirection`, it converts it via `timeSortingByDirection`.

```ts
$timeSortingDirection("asc"); // "oldest-to-newest"
$timeSortingDirection("desc"); // "newest-to-oldest"
$timeSortingDirection("oldest-to-newest"); // "oldest-to-newest"
$timeSortingDirection("newest-to-oldest"); // "newest-to-oldest"
```

## Date Comparators

### `compareDatesNewestToOldest(a, b)`

Compares two `Date` values for descending (newest-first) sort order. Pass directly to `Array.prototype.sort`.

```ts
import { compareDatesNewestToOldest } from "@ngrok/mantle/utils";

const dates = [new Date("2023-01-01"), new Date("2024-06-15"), new Date("2022-12-31")];
dates.toSorted(compareDatesNewestToOldest);
// → [2024-06-15, 2023-01-01, 2022-12-31]
```

### `compareDatesOldestToNewest(a, b)`

Compares two `Date` values for ascending (oldest-first) sort order.

```ts
import { compareDatesOldestToNewest } from "@ngrok/mantle/utils";

const dates = [new Date("2023-01-01"), new Date("2024-06-15"), new Date("2022-12-31")];
dates.toSorted(compareDatesOldestToNewest);
// → [2022-12-31, 2023-01-01, 2024-06-15]
```

---