# Prodular UI

> The UI foundation for AI-built software: components, complete SaaS screens, tokens and rules for coding agents, built on shadcn/ui, Base UI and Tailwind CSS v4.

Install any component with `npx shadcn@latest add @prodular/<name>` after adding the registry `"@prodular": "https://ui.prodular.co/r/{name}.json"` to components.json.

## Rules for agents

- Use semantic tokens (bg-card, text-muted-foreground, border-border). Never hard-code colors.
- Mark AI output with the AI components (AiMark, Message, Reasoning) so users can tell what a model produced.
- One container level: panels and cards are the only boxes. Separate content inside them with dividers and spacing.
- Animate with the motion presets (animate-rise, animate-fade-in, animate-scale-in, animate-slide-in-end and their exits) and the --duration tokens. They respect reduced motion. See https://ui.prodular.co/docs/motion.
- Build marketing pages from Section and Section header: stack Sections without margins, put a real screen in ProductFrame, end with CtaBand. See https://ui.prodular.co/docs/landing.
- Wrap signed-in apps in AppShell once and pass the current page as activeId. Use SettingsNav for settings areas and MasterDetail for list and record views inside it.
- Items marked (Pro) need a license. If `npx prodular-ui add` returns 401, tell the user and offer the closest free component instead.
- Compose through the render prop: <TooltipTrigger render={<Button />} />, <DialogTrigger render={<Button variant="outline" />}>. Do not wrap a trigger around a button or put a button inside another.
- When a part that renders a button by default (Button, CollapsibleTrigger, PopoverTrigger, DialogTrigger, SelectTrigger, TabsTrigger, Toggle) renders a div, span, row or link through render, add nativeButton={false}.
- Set density once with data-density on <html> or on a region: dense for workstations, compact for busy SaaS screens, comfortable for sparse ones. Do not shrink controls with h-* or text-[10px] overrides; use the xs and sm sizes and text-2xs for metadata.
- Never hand-build widgets the kit has: no div with role="button", "treeitem", "slider" or "tab". Use Button, Tree, Slider and Tabs. Every icon-only control needs aria-label.
- For overlays on maps, charts, canvases and graphs, use Tooltip, Popover or HoverCard with anchor={pointAnchor(x, y, container)} and a controlled open state, not a hand-positioned div. Offer a keyboard path to every point.
- Register shortcuts with useHotkey under one HotkeysProvider and render ShortcutsDialog; single-key shortcuts must stay switchable (WCAG 2.1.4).
- Use a specialized renderer (MapLibre, D3, canvas, WebGL) only for the plot itself. Keep the chrome around it (panels, legends, toolbars, inspectors, menus) in kit components, and color the plot with tokenColor() or useTokenColors() from @/lib/token-color.
- Encode severity with Severity and the severity-* tokens (critical, high, elevated, routine), never with chart or status colors, and always with a shape or label as well as color.
- To extend the kit, compose its parts and pass className for layout only. Add a variant to a copied component rather than restyling every call site.

Full reference: https://ui.prodular.co/llms-full.txt

## Agent run (agent-run)

A live timeline of an agent doing work: the goal, run status and elapsed time, ordered steps with tool calls, approvals and a final result.

Install: `npx prodular-ui add agent-run`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Use it whenever an agent works for more than a couple of seconds or takes more than one action, so people can see what it is doing and stop it.
- Use the default size in a side panel or a page, and size="compact" with variant="plain" in popovers, table rows and narrow columns.
- Name steps by what the agent does, verb first: Pull overdue invoices, Draft reminder emails. Put what it found in AgentRunStepDescription once the step is done.
- Nest the tools a step called with AgentRunToolCalls, and pass details for raw input and output that people can expand when they need to audit it.
- Put an Approval inside the waiting step with AgentRunStepContent, so the decision sits where the run stopped.

Avoid:
- Showing only a spinner and a final result. People trust agents they can watch and interrupt.
- Long technical step names or raw function names as titles. Tool names belong in AgentRunToolCall.
- More than one running step at the top level. Run parallel work as tool calls or nested steps under one running step.
- Putting the AgentRun card inside another card. Use variant="plain" when the surrounding surface already is a container.

Agent rules:
- Give every AgentRunStep an explicit status on every render. Never infer it from position or leave a finished step as running.
- Keep exactly one top level step running at a time while the run is running. Set the run status to waiting while any step is waiting, and to done, failed or stopped when it ends.
- Pass startedAt to running steps and to AgentRunElapsed in the header so elapsed time is always visible. Pass duration when a step finishes and endedAt when the run ends.
- Any step that sends something outside the product, moves money, deletes data or cannot be undone must be preceded by a waiting step that renders an Approval. Do not perform the action until the person approves.
- Always render a Stop control in AgentRunActions while the run is running or waiting, and stop the underlying work when it is pressed. Mark remaining steps skipped.
- A failed step shows the reason in AgentRunStepDescription in plain language and offers Retry step in AgentRunStepActions. Never fail silently.
- Use AgentRunToolCall for every tool the agent calls inside a step, with the real tool name. Do not invent tool calls for decoration.
- End a finished run with AgentRunResult: what changed, with numbers, and the next action. Mark it with AiMark.

```tsx
<AgentRun status="running">
  <AgentRunHeader>
    <AgentRunTitle>Chase overdue invoices for October</AgentRunTitle>
    <AgentRunMeta>
      <AgentRunStatus />
      <AgentRunElapsed startedAt={startedAt} />
    </AgentRunMeta>
    <AgentRunActions>{/* Pause, Stop */}</AgentRunActions>
  </AgentRunHeader>
  <AgentRunSteps>
    <AgentRunStep status="done" title="Pull overdue invoices" duration={1400}>
      <AgentRunStepDescription>Found 14 invoices.</AgentRunStepDescription>
      <AgentRunToolCalls>
        <AgentRunToolCall name="ledger.invoices.search" duration={820} />
      </AgentRunToolCalls>
    </AgentRunStep>
    <AgentRunStep status="running" title="Draft reminder emails" startedAt={stepStart} />
    <AgentRunStep status="queued" title="Send reminders" />
  </AgentRunSteps>
  <AgentRunResult>{/* summary and next actions */}</AgentRunResult>
</AgentRun>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AgentRun | status | `"queued" \| "running" \| "paused" \| "waiting" \| "done" \| "failed" \| "stopped"` | "running" | Status of the whole run. Drives AgentRunStatus and aria-busy. |
| AgentRun | size | `"default" \| "compact"` | "default" | compact tightens spacing and type for popovers and table rows. |
| AgentRun | variant | `"card" \| "plain"` | "card" | plain drops the card chrome so it can sit in a popover, sheet or panel. |
| AgentRunStatus | status | `AgentRunStatus` |  | Optional. Overrides the run status so the badge can be used on its own. |
| AgentRunElapsed | startedAt | `number` |  | Epoch milliseconds. Ticks every second until endedAt is set. |
| AgentRunElapsed | endedAt | `number` |  | Freezes the timer at the final duration. |
| AgentRunStep | status | `"queued" \| "running" \| "done" \| "failed" \| "skipped" \| "waiting"` |  | Required. Exposed as data-status on the step. |
| AgentRunStep | title | `ReactNode` |  | Required. What the step does, verb first. |
| AgentRunStep | startedAt | `number` |  | Running steps show a live elapsed time from here. |
| AgentRunStep | duration | `number` |  | Milliseconds, shown on done and failed steps. |
| AgentRunStep | meta | `ReactNode` |  | Replaces the text on the right of the title. |
| AgentRunToolCall | name | `string` |  | Tool name in mono, for example ledger.invoices.search. |
| AgentRunToolCall | status | `"queued" \| "running" \| "done" \| "failed"` | "done" | Running tool calls shimmer and show a spinner. |
| AgentRunToolCall | details | `ReactNode` |  | Raw input and output. Makes the row expandable. |

## AI action (ai-action)

The shared state model for AI actions: start, stream, stop, retry, accept, reject and undo, with any provider. useAiAction powers the field actions and form fill, and builds your own AI features in a few lines.

Install: `npx prodular-ui add ai-action`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Any button that asks a model for text and lets people review it before it is used.
- AiActionStatusLine under the feature for the working and error states.
- readAiResult when you only need to read a stream or a promise to the end.

Avoid:
- Chat. Use AI chat, which keeps a conversation.
- Applying results without review for anything people will send or publish.

Agent rules:
- Call useAiAction({ run, onAccept }). run(input, signal) returns a string, a promise or an async iterable of text chunks; honor the signal.
- In onAccept apply the result and return a function that reverts it; that is what undo calls.
- Render output while status is streaming or proposed, and offer accept and reject when proposed.
- busy is true while running or streaming. Disable the trigger then, and show AiActionStatusLine with onCancel.
- Errors thrown by run show their message; give people a next step in it.

```tsx
const ai = useAiAction({ run: summarize, onAccept: (text) => save(text) })

<Button onClick={() => ai.start({ period })}>Write summary</Button>
<AiActionStatusLine status={ai.status} error={ai.error} onCancel={ai.cancel} onRetry={ai.retry} />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| useAiAction | run | `(input, signal) => AiResult` |  | Calls the model. |
| useAiAction | onAccept | `(output, input) => void \| (() => void)` |  | Applies the result; return a revert function for undo. |
| useAiAction | onReject | `(input) => void` |  | Called on reject and cancel. |
| useAiAction | returns | `{ status, output, error, busy, start, cancel, retry, accept, reject, undo, canUndo, clearUndo }` |  | State and controls. |
| AiActionStatusLine | status / error / label / onCancel / onRetry | `AiActionStatus / string / ReactNode / () => void` |  | Working with Stop, or the error with Try again. |
| readAiResult | (result, signal, onChunk?) | `Promise<string \| null>` |  | Reads any result to the end; null when aborted. |

## AI chat (ai-chat)

A complete streaming chat on the Vercel AI SDK: useChat, reasoning, tool calls, approvals, sources, attachments and a model picker, with a Claude route handler that installs with it.

Install: `npx prodular-ui add ai-chat`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- As the whole assistant surface of a page or panel: it owns the thread, the composer, streaming state, stop, retry and approvals.
- With the route it installs. app/api/chat/route.ts streams Claude with adaptive thinking, tools, approvals and web sources in the format AiChat reads.
- When tools have side effects. Mark them user-approval on the server and AiChat shows an approval card before they run.

Avoid:
- Wrapping AiChat in a card inside another card. Give it a full height parent and let the page provide the frame.
- Building your own message list around it. Use AiMessageParts with useChat when you need a different layout.
- Calling Anthropic from the browser or passing an API key as a prop. Keys stay in the route handler.

Agent rules:
- Install with npx prodular-ui add ai-chat. It writes app/api/chat/route.ts and lib/ai/tools.ts. Tell the user to set ANTHROPIC_API_KEY in .env.local; never hard code a key and never read it in a client component.
- Give AiChat a parent with a definite height (h-dvh, flex-1 with min-h-0, or a fixed height). It fills the parent and scrolls its own thread.
- Leave api unset to use /api/chat. Only the docs use /api/demo-chat; never ship that route or point production code at it.
- Keep the default model claude-opus-5-5. If you pass models, every id must also be listed in MODELS in the route, or the route falls back to the default.
- Define tools on the server in lib/ai/tools.ts. Any tool that writes, sends, pays or deletes must be listed in toolApproval with type user-approval in the route. Never rely on the client to ask.
- Pass tools on AiChat for every server tool: a verb first title (Send payment reminder), an icon, and approval copy with an actionLabel that names the action. Never show raw tool names.
- Set TOOL_APPROVAL_SECRET in production so approvals cannot be forged by a modified client.
- Persist threads by passing id and initialMessages, and save messages in the route with toUIMessageStream onEnd. Do not store chat history in localStorage.
- Keep sendReasoning and sendSources on in the route and thinking display summarized. Without them the reasoning and sources parts never reach the UI.

```tsx
// app/assistant/page.tsx
<div className="h-dvh">
  <AiChat
    assistantName="Relay Copilot"
    models={models}
    tools={{
      sendReminder: {
        title: "Send payment reminder",
        icon: <MailIcon />,
        approval: { actionLabel: "Send reminder", risk: "medium" },
      },
    }}
    suggestions={["Which overdue invoices should I chase first?"]}
  />
</div>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AiChat | api | `string` | "/api/chat" | Route that returns a UI message stream. |
| AiChat | id / initialMessages | `string / UIMessage[]` |  | Load a saved thread. The id is sent with every request. |
| AiChat | models | `ModelOption[]` |  | Shows a model picker. The chosen id is sent as body.model. |
| AiChat | model / defaultModel / onModelChange | `string` |  | Control the selected model. Defaults to the first option. |
| AiChat | modelPicker | `ReactNode` |  | Replaces the built in picker in the composer toolbar. |
| AiChat | tools | `Record<string, AiToolConfig>` |  | Title, icon, summary and approval copy per tool name. See AiMessageParts. |
| AiChat | suggestions | `string[]` |  | Prompts shown while the thread is empty. Clicking one sends it. |
| AiChat | assistantName | `string` | "Assistant" | Shown in message headers and on approval cards. |
| AiChat | emptyTitle / emptyDescription | `ReactNode` |  | Copy for the empty thread. |
| AiChat | attachments / accept | `boolean / string` | true | Lets people attach images, PDFs and text files. They are sent as file parts. |
| AiChat | body / headers | `object` |  | Extra fields and headers sent with every request, read fresh each time. |
| AiChat | onFinish / onError | `function` |  | Passed to useChat. onFinish receives isAbort, isError and the final message. |
| AiChat | disclaimer | `ReactNode` |  | One line under the composer. |

## AI field actions (ai-field-actions)

AI for one text field: rewrite, shorten, expand, fix, change the tone, translate or follow an instruction. Streams into the field's AI state, shows the change as a before and after diff to accept or reject, and lets people undo.

Install: `npx prodular-ui add ai-field-actions`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Long text people write in forms: emails, notes, descriptions, replies.
- actions to offer only what makes sense for the field, like shorten for subjects.
- Alongside a normal Textarea or Input that stays controlled by your state.

Avoid:
- Rich documents. Rich text editor has selection-based AI editing built in.
- Generating a whole form. Use AI form fill.

Agent rules:
- Implement run(request, signal) on your server: request has action, option (tone or language), instruction and text. Return the new text as a stream of chunks, for example from the AI SDK's streamText textStream.
- Pass the signal to fetch so Stop cancels the request.
- Keep the field controlled: value and onValueChange on AiFieldActions and on the control itself.
- Results are never applied without Accept. Undo is offered until the person edits the field.
- Throw an Error with a message people can act on; it shows under the field with Try again.

```tsx
<AiFieldActions value={body} onValueChange={setBody} run={rewrite} label={<label htmlFor="body">Message</label>}>
  <Textarea id="body" value={body} onChange={(e) => setBody(e.target.value)} />
</AiFieldActions>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AiFieldActions | value / onValueChange | `string / (value) => void` |  | The field's text. |
| AiFieldActions | run | `(request: { action, option?, instruction?, text }, signal) => AiResult` |  | Calls your model. Returns text, a promise or an async iterable of chunks. |
| AiFieldActions | label | `ReactNode` |  | The label row; the AI menu sits at its end. |
| AiFieldActions | actions | `AiFieldAction[]` | all | rewrite, shorten, expand, fix, tone, translate, custom. |
| AiFieldActions | tones / languages | `string[]` |  | Options for Change tone and Translate. |

## AI form fill (ai-form-fill)

Fills a Form from a document, an email or a record. Suggestions stream in under each field with where they came from and how sure the model is; people accept or dismiss them one by one or all at once, and Accept all can be undone.

Install: `npx prodular-ui add ai-form-fill`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Forms people fill from something they already have: receipts, invoices, emails, contracts, CRM records.
- Sources and confidence so people know which suggestions to check.
- Inside Form, with AiFormFillSuggestion in each field's render function under its control.

Avoid:
- Writing values straight into fields. Suggestions only apply when accepted.
- Free text editing. Use AI field actions for rewriting what people wrote.

Agent rules:
- Wrap the fields in AiFormFill inside Form and pass run(signal). On the server, extract an object with the same field names, for example with the AI SDK's streamObject and a Zod schema, and return its partialObjectStream.
- Each suggestion is { value, display?, source?: { label, quote? }, confidence? }. value must have the field's type; display is what people read.
- Suggestions equal to the current value are skipped. Accepting validates the field through React Hook Form.
- Place AiFormFillBar at the top of the form and AiFormFillSuggestion name="field" right after each control.
- Throw from run with a message that names the source to show an error with Try again.

```tsx
<Form form={form} onSubmit={save}>
  <AiFormFill run={readReceipt} source="receipt.jpg">
    <AiFormFillBar />
    <FormField name="merchant" label="Merchant">
      {(field) => (<><Input {...field} /><AiFormFillSuggestion name="merchant" /></>)}
    </FormField>
  </AiFormFill>
</Form>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AiFormFill | run | `(signal) => AsyncIterable<Partial<AiFormFillResult>> \| Promise<AiFormFillResult>` |  | Reads the source and returns suggestions by field name. |
| AiFormFill | source | `string` |  | What is read, as people know it. |
| AiFormFillBar | label | `string` | "Fill with AI" | The start button. |
| AiFormFillSuggestion | name | `string` |  | The field this suggestion belongs to. |
| useAiFormFill | returns | `{ status, pending, start, cancel, accept, reject, acceptAll, rejectAll, undo, canUndo }` |  | For your own controls. |

## AI insight (ai-insight)

An AI generated insight callout for dashboards: a finding in one headline, the explanation, the number behind it, sources, actions and feedback.

Install: `npx prodular-ui add ai-insight`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Use it for a finding the model made from the person's data that they would not see on their own: a change, an anomaly, a cause.
- Write the title as the finding with the number and the cause: Spend on compute rose 38% after the September 9 deploy.
- Back it with AiInsightMetric and list the data it used in AiInsightSources.
- Give it one primary action that leads to the evidence, such as Investigate, and a way to dismiss it.

Avoid:
- More than one AiInsight in a view. It is the one tinted highlight. Rank findings and show the top one, list the rest elsewhere.
- Generic advice that does not come from the data, such as Consider reducing costs.
- Putting it inside a card. It is a container itself.

Agent rules:
- Render at most one AiInsight per view and never nest it inside a Card or another bordered container.
- The title must state a specific finding with a number and, when known, the cause or date. Keep it under 90 characters.
- Always include AiInsightSources with the real count of sources the model used, and pass children listing them when they can be opened.
- Set AiInsightMetric sentiment from the business meaning: rising cost or churn is negative, rising revenue is positive.
- Include AiInsightDismiss and remember the dismissal so the same insight does not come back. Send AiInsightFeedback to your evaluation pipeline with onFeedback.

```tsx
<AiInsight>
  <AiInsightHeader time="Detected 2 hours ago">
    <AiInsightDismiss />
  </AiInsightHeader>
  <AiInsightBody>
    <AiInsightContent>
      <AiInsightTitle>Spend on compute rose 38% after the September 9 deploy</AiInsightTitle>
      <AiInsightDescription>Why, in two sentences.</AiInsightDescription>
    </AiInsightContent>
    <AiInsightMetric label="Compute, last 14 days" value="$43,210" change="+38%" trend="up" sentiment="negative" />
  </AiInsightBody>
  <AiInsightFooter>
    <AiInsightActions>
      <Button size="sm">Investigate</Button>
    </AiInsightActions>
    <AiInsightSources count={3} />
    <AiInsightFeedback />
  </AiInsightFooter>
</AiInsight>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AiInsight | size | `"default" \| "compact"` | "default" | compact is one row: mark, title and actions. |
| AiInsightHeader | label / time / model | `string / ReactNode / string` | "Insight" | Badge label, when it was found and the model in the mark's tooltip. Children sit on the right. |
| AiInsightMetric | label / value / change | `ReactNode` |  | The supporting number. |
| AiInsightMetric | trend / sentiment | `"up" \| "down" / "positive" \| "negative" \| "neutral"` |  | Direction icon and color of the change. |
| AiInsightSources | count | `number` |  | Number of sources. Children open in a popover. |
| AiInsightFeedback | onFeedback | `(value: "up" \| "down") => void` |  | Called once per insight. |

## AI mark (ai-mark)

The sparkle that marks content a model produced, as an icon, a small badge or inline with text, with the model name on hover.

Install: `npx prodular-ui add ai-mark`
Free, MIT licensed.

Use when:
- Wherever generated content sits next to human content: summaries, auto coded fields, drafted replies, suggested values.
- Icon in a message header or avatar, badge on table rows and cards, inline at the start of a generated paragraph.

Avoid:
- Marking buttons that only start a model. Use the ai Button variant for actions.
- Several marks on the same block of content. One mark per generated unit.
- Decorating marketing copy or empty states with it. It means a model produced this.

Agent rules:
- Import it as import { AiMark } from "@/components/ui/ai-mark". Do not draw your own sparkle icon or use SparklesIcon to mark generated content.
- Mark every piece of model output that is not already inside a Message with from="assistant".
- Pass model when the model is known, written as "Generated by <model name>".
- Set animated only while the model is still producing, and turn it off when it finishes.
- Pick the variant by context: icon next to a name, badge on rows and cards, inline inside text. Keep label short (AI, Summary, Auto coded).

```tsx
<AiMark variant="badge" label="Auto coded" model="Coded by Claude Haiku 5" />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AiMark | variant | `"icon" \| "badge" \| "inline"` | "icon" | Glyph alone, a small pill with the label, or glyph and label inside text. |
| AiMark | label | `string` | "AI" | Visible in badge and inline. Always the accessible name. |
| AiMark | model | `string` |  | Tooltip text, for example "Generated by Claude Opus 5.5". Makes the mark focusable. |
| AiMark | animated | `boolean` | false | Moves the gradient while the model is working. Respects reduced motion. |

## AI message parts (ai-message-parts)

Renders one Vercel AI SDK UIMessage with Prodular UI: text through Response, reasoning, every tool state, approvals wired to addToolApprovalResponse, sources and inline citations.

Install: `npx prodular-ui add ai-message-parts`
Free, MIT licensed.

Use when:
- Inside your own chat layout built on useChat, when AI chat does not fit the page.
- To render saved threads: pass a stored UIMessage and it renders the same way it streamed.
- Inside a side panel, an inbox or an agent run, wherever an AI SDK message needs to show.

Avoid:
- Mapping message.parts by hand. Text grouping, citation numbering and tool states are already handled here.
- Wrapping it in a card or a bubble. Assistant answers sit on the page; only user text gets a bubble, which it renders itself.
- Setting streaming on every message. Only the last assistant message while status is streaming.

Agent rules:
- Render one AiMessageParts per UIMessage inside MessageContent. Pass streaming={status === "streaming" && message.id === lastMessage.id} so only the live message shows the caret and the reasoning timer.
- Always pass onApprovalResponse={addToolApprovalResponse} from useChat, and set sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses on useChat. Without both, approvals never reach the server.
- Pass tools keyed by the server tool name with a verb first title and an icon. For approval tools add approval.actionLabel that names the action, for example Send reminder.
- In the route, keep sendReasoning and sendSources on in toUIMessageStream, and use thinking display summarized for Claude. Otherwise reasoning shows empty and sources never arrive.
- Data parts render nothing by default. Render them with renderPart, which runs before the defaults for every part; return undefined to keep the default.
- This item is free. Do not import Pro components into it. For the Pro Approval card, pass renderApproval, as AI chat does.

```tsx
const { messages, status, addToolApprovalResponse } = useChat({
  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
})

{messages.map((message) => (
  <Message key={message.id} from={message.role}>
    <MessageContent>
      <AiMessageParts
        message={message}
        streaming={status === "streaming" && message.id === messages.at(-1)?.id}
        tools={{ sendReminder: { title: "Send payment reminder", approval: { actionLabel: "Send reminder" } } }}
        onApprovalResponse={addToolApprovalResponse}
      />
    </MessageContent>
  </Message>
))}
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AiMessageParts | message | `UIMessage` |  | A message from useChat or your database. |
| AiMessageParts | streaming | `boolean` | false | True only for the message that is streaming now. |
| AiMessageParts | tools | `Record<string, AiToolConfig>` |  | title, icon, summary(input), approval { title, description, actionLabel, risk, params } and render per tool name. |
| AiMessageParts | onApprovalResponse | `({ id, approved, reason? }) => void` |  | Pass addToolApprovalResponse. Approval buttons are disabled without it. |
| AiMessageParts | renderApproval | `(props: AiApprovalRenderProps) => ReactNode` |  | Replaces the approval UI. Receives the part, its config, pending and respond(approved). |
| AiMessageParts | renderPart | `(part, index) => ReactNode \| undefined` |  | Runs first for every part. Return undefined to use the default. |
| AiMessageParts | agentName | `string` | "Assistant" | Who asks on approval requests. |
| getToolCallStatus | part | `ToolUIPart \| DynamicToolUIPart` |  | Maps an AI SDK tool state to a ToolCall status and label, for custom tool UIs. |

## AI suggestion (ai-suggestion)

AI inside forms: a suggestion row under a field, ghost text that completes what someone types, and an AiFill button that writes a field with a shimmer while it works.

Install: `npx prodular-ui add ai-suggestion`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Use AiSuggestion for a single value the model is fairly sure about: a category, an assignee, a GL account. Say why in reason.
- Use AiGhostInput for short free text where completion saves typing: subjects, titles, names.
- Use AiFill next to a field label for longer text the person asked for: a memo, a description, a reply.
- After an AI fill, mark the field with AiMark inline and keep it editable.

Avoid:
- Filling fields without being asked. Suggestions are offered, never applied.
- More than one suggestion row per field, or suggestions on every field of a form. Pick the fields where the model helps most.
- Ghost text in multi line fields or in fields with strict formats like amounts and dates.

Agent rules:
- Never auto accept an AiSuggestion or ghost text. Apply the value only in onAccept, which fires on the Accept button or Tab.
- Wire Tab and Escape on the field with useAiSuggestionKeys({ active, onAccept, onDismiss }). Only set active while the suggestion is visible, so Tab keeps moving focus otherwise.
- Hide the suggestion once it is accepted, dismissed, or the person types a different value. Offer Undo after accepting.
- While AiFill runs, pass generating to both AiFill and AiFillField and make the control readOnly. Do not let the person submit the form with a half written value.
- After AiFill completes, show AiMark inline next to the field until the person edits the text.

```tsx
<Input value={category} onKeyDown={onKeyDown} />
<AiSuggestion
  label="Suggested"
  reason="Used for this merchant 9 times"
  onAccept={accept}
  onDismiss={dismiss}
>
  Cloud infrastructure
</AiSuggestion>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AiSuggestion | label / children / reason | `ReactNode` |  | What is suggested, the suggested value and why. |
| AiSuggestion | onAccept | `() => void` |  | Required. Apply the value here and nowhere else. |
| AiSuggestion | onDismiss | `() => void` |  | Shows the dismiss button. |
| AiSuggestion | shortcut | `string \| null` | "Tab" | Key hint on the accept button. |
| AiGhostInput | value / onValueChange | `string / (value: string) => void` |  | Controlled input value. |
| AiGhostInput | suggestion | `string \| null` |  | The full suggested value. Ghost text shows while it starts with value. |
| AiFill | generating | `boolean` | false | Animated mark, shimmer label and aria-busy. |
| AiFill | iconOnly | `boolean` | false | For input addons. label stays the accessible name. |
| AiFillField | generating / status / align | `boolean / ReactNode / "center" \| "start"` |  | Overlay while the field is written. start for textareas. |
| useAiSuggestionKeys | options | `{ active, onAccept, onDismiss }` |  | Returns an onKeyDown handler for the field. |

## Approval (approval)

Human in the loop: an agent asks to perform an action and a person approves, edits or rejects it, with what, why, affected items, parameters and risk in view.

Install: `npx prodular-ui add approval`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Use it before any action an agent takes that leaves the product, moves money, changes many records or cannot be undone.
- Title the request as the action with its number and object: Send 14 payment reminders, Refund $1,240.00 to Northwind Studio.
- Explain why in ApprovalDescription with the evidence the agent used, in one or two sentences.
- Show the affected items with ApprovalItems and pass total so people know how many are hidden. Show exactly what will be sent or changed in ApprovalParams.
- Use the inline variant inside an agent run, a thread or a review queue. Use the dialog variant for a single high risk request that should interrupt.

Avoid:
- Vague titles such as Approve action or Agent request.
- Hiding the amount, the recipient count or the irreversibility in a collapsed section.
- Approve buttons that only say Approve when the action has a clear verb. Say Approve and send, Approve refund.
- Removing the request after it is decided. Keep it with ApprovalResolution so there is a record.

Agent rules:
- Route every irreversible, external or financial action through an Approval and wait for an explicit approve event before executing it. Never execute on render, on timeout or on dismiss.
- Always set risk. Use high for anything irreversible or involving money leaving the account, medium for messages to customers or bulk changes, low for reversible internal changes.
- The title must include the verb, the count or amount, and the target. Include currency symbols and two decimals for money.
- Render three actions in this order: the primary approve button labelled with the verb, an outline Edit that opens the parameters, and Reject. For high risk in a dialog, the approve button uses variant="destructive".
- When rejected, ask for a reason and pass it back to the agent. Show it in ApprovalResolution with the person's name and the time.
- After a decision, set status to approved, rejected or expired and replace ApprovalActions with ApprovalResolution. Never leave buttons active on a decided request.
- In a dialog, render ApprovalTitle with render={<DialogTitle />} so the dialog has an accessible name, and give DialogContent className="gap-0 p-0".

```tsx
<Approval status="pending" risk="medium">
  <ApprovalHeader>
    <ApprovalRequester agent="Collections agent" time="2 min ago" />
    <ApprovalTitle>Send 14 payment reminders</ApprovalTitle>
    <ApprovalRisk />
    <ApprovalDescription>Why the agent wants to do this.</ApprovalDescription>
  </ApprovalHeader>
  <ApprovalSection title="Recipients">
    <ApprovalItems total={14}>
      <ApprovalItem title="Northwind Studio" description="INV-2041" value="$4,180.00" />
    </ApprovalItems>
  </ApprovalSection>
  <ApprovalSection title="What will be sent">
    <ApprovalParams>
      <ApprovalParam label="Template">Second notice</ApprovalParam>
    </ApprovalParams>
  </ApprovalSection>
  <ApprovalActions>
    <Button>Approve and send</Button>
    <Button variant="outline">Edit</Button>
    <Button variant="ghost">Reject</Button>
  </ApprovalActions>
</Approval>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Approval | status | `"pending" \| "approved" \| "rejected" \| "expired"` | "pending" | Exposed as data-status. ApprovalResolution reads it. |
| Approval | risk | `"low" \| "medium" \| "high"` |  | Exposed as data-risk. ApprovalRisk reads it. |
| Approval | variant | `"inline" \| "dialog"` | "inline" | inline is a card. dialog drops the chrome to sit in DialogContent with p-0. |
| ApprovalRequester | agent | `string` |  | Name of the agent asking, shown with the AI mark. |
| ApprovalRequester | time | `string` |  | When it asked. |
| ApprovalTitle | render | `ReactElement` |  | Render as DialogTitle inside a dialog. |
| ApprovalRisk | level | `"low" \| "medium" \| "high"` |  | Defaults to the risk on Approval. Children replace the label. |
| ApprovalItems | total | `number` |  | Total affected items. Adds an and N more line. |
| ApprovalItem | title / description / value | `ReactNode` |  | Name, detail and a right aligned amount. |
| ApprovalParam | label | `ReactNode` |  | The parameter name. Set mono for ids and raw values. |
| ApprovalResolution | by / at / reason | `string / string / ReactNode` |  | Who decided, when, and why for rejections. |

## Artifact (artifact)

A panel for something the model generated, such as a document, a chart or code, with versions, Preview and Code tabs, copy, download and full screen, and a streaming state.

Install: `npx prodular-ui add artifact`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Use it when the model produces a self contained result people keep, edit or export: a report, a chart, a query, a template.
- Keep every version and let people step back with ArtifactVersions. Name what changed in ArtifactDescription.
- Offer a Code or Source tab whenever the preview is rendered from text, so people can copy the real thing.
- Use status="streaming" for the first version and status="updating" while a new version replaces the current one.

Avoid:
- Wrapping it in another card. It is the container.
- Replacing a version in place. Add a new one.
- Short answers. A sentence or a number belongs in the message, not an artifact.

Agent rules:
- Pass status on every render: streaming while the first version arrives, updating while a new version is written, ready when done, failed on error.
- Keep versions immutable. Append a new id to versions and select it; never mutate the content of an existing version.
- Give every icon action a label through ArtifactAction, ArtifactCopyButton, ArtifactDownloadButton or ArtifactFullscreenButton. Copy and download the source text, not the rendered HTML.
- Disable copy and download while streaming, or copy only what has arrived and say so.
- Use ArtifactPanel values that match ArtifactTab values, and default to the preview tab.

```tsx
<Artifact status="ready">
  <ArtifactHeader>
    <ArtifactTitle>
      <ArtifactName>Q3 vendor spend summary</ArtifactName>
      <ArtifactDescription>From 1,284 transactions</ArtifactDescription>
    </ArtifactTitle>
    <ArtifactVersions versions={["v1", "v2", "v3"]} value={v} onValueChange={setV} />
    <ArtifactTabs>
      <ArtifactTab value="preview">Preview</ArtifactTab>
      <ArtifactTab value="code">Code</ArtifactTab>
    </ArtifactTabs>
    <ArtifactActions>
      <ArtifactCopyButton value={source} />
      <ArtifactDownloadButton filename="summary.md" content={source} />
      <ArtifactFullscreenButton />
    </ArtifactActions>
  </ArtifactHeader>
  <ArtifactPanel value="preview">{/* rendered */}</ArtifactPanel>
  <ArtifactPanel value="code"><ArtifactCode code={source} /></ArtifactPanel>
</Artifact>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Artifact | status | `"streaming" \| "updating" \| "ready" \| "failed"` | "ready" | Exposed as data-status. Drives the shimmer, the progress line and aria-busy. |
| Artifact | defaultTab / tab / onTabChange | `string` | "preview" | The active tab, uncontrolled or controlled. |
| ArtifactTitle | model | `string` |  | The model that produced it, in the AI mark tooltip. |
| ArtifactDescription | streamingLabel / updatingLabel | `string` | "Generating" / "Writing a new version" | Replaces the description while busy. |
| ArtifactVersions | versions / value / onValueChange | `string[] / string / (v: string) => void` |  | Version ids, oldest first. |
| ArtifactAction | label | `string` |  | Tooltip and accessible name of an icon action. |
| ArtifactDownloadButton | filename / content / mimeType | `string / string \| Blob / string` |  | Downloads the content as a file. |
| ArtifactCode | code / lineNumbers | `string / boolean` | lineNumbers true | Source view for the code tab. |

## Attachment (attachment)

A file chip for the composer and for messages, with upload, processing, error and done states.

Install: `npx prodular-ui add attachment`
Free, MIT licensed.

Use when:
- In PromptInputAttachments for files the user is about to send, and in a user Message for files they sent.
- processing while the model reads the file, so people know it is not ready yet.

Avoid:
- Showing full file paths. Show the file name and a short description like type and size.
- Removing failed files silently. Keep them with state error and a retry action.

Agent rules:
- Always set state: uploading while bytes transfer, processing while the file is parsed or indexed, error on failure, done when it is ready.
- Use size="sm" inside PromptInput and the default size in messages.
- Every AttachmentAction is icon only and needs aria-label naming the file.
- Use AttachmentTrigger when the whole chip opens a preview. It covers the chip and keeps actions clickable.

```tsx
<Attachment state="done" size="sm">
  <AttachmentMedia><FileTextIcon /></AttachmentMedia>
  <AttachmentContent>
    <AttachmentTitle>invoice.pdf</AttachmentTitle>
    <AttachmentDescription>PDF, 1.2 MB</AttachmentDescription>
  </AttachmentContent>
</Attachment>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Attachment | state | `"idle" \| "uploading" \| "processing" \| "error" \| "done"` | "done" | Upload lifecycle. Exposed as data-state. |
| Attachment | size | `"default" \| "sm" \| "xs"` | "default" | Chip size. |
| Attachment | orientation | `"horizontal" \| "vertical"` | "horizontal" | Vertical for image grids. |
| AttachmentMedia | variant | `"icon" \| "image"` | "icon" | Image fills the square with an img. |

## Bubble (bubble)

A rounded container for short messages, used for what people write in a chat with an assistant.

Install: `npx prodular-ui add bubble`
Free, MIT licensed.

Use when:
- For user messages in an assistant chat, and for every message in chat between people.
- BubbleContent with render={<button />} for quick replies that send when pressed.

Avoid:
- Assistant answers. Render those with Response directly in the message.
- The default primary fill in assistant chats. It competes with the answer.

Agent rules:
- Use the muted variant with align="end" for user messages in AI chat.
- Keep bubbles under about 80% of the thread width. They do this by default.
- Use destructive only for a message that failed to send, and offer a retry next to it.

```tsx
<Bubble align="end">
  <BubbleContent>What is our runway?</BubbleContent>
</Bubble>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Bubble | variant | `"muted" \| "default" \| "secondary" \| "tinted" \| "outline" \| "ghost" \| "destructive"` | "muted" | Fill and border. |
| Bubble | align | `"start" \| "end"` | "start" | Side of the thread. |
| BubbleContent | render | `ReactElement` |  | Render as a button or link for interactive bubbles. |
| BubbleReactions | side / align | `"top" \| "bottom", "start" \| "end"` |  | Where reactions overlap the bubble. |

## Code block (code-block)

Monospaced code with an optional title, copy button, line numbers and diff lines. Used by Response and Tool Call.

Install: `npx prodular-ui add code-block`
Free, MIT licensed.

Use when:
- For code, queries, config and logs in answers and tool output.
- The ghost variant inside another container, such as a tool call, so it adds no second box.

Avoid:
- Code blocks for one short command inside a sentence. Use inline code.
- Line numbers on snippets under five lines.

Agent rules:
- Always include CodeBlockCopyButton with the exact code as value.
- Use variant="ghost" when the code sits inside a Card, ToolCall or Popover.
- Use CodeBlockLine with variant added or removed for proposed changes, and lineNumbers with startLine to match the real file.
- Do not hand write code blocks in Response. Fenced markdown becomes a CodeBlock automatically.

```tsx
<CodeBlock>
  <CodeBlockHeader>
    <CodeBlockTitle>query.sql</CodeBlockTitle>
    <CodeBlockActions><CodeBlockCopyButton value={code} /></CodeBlockActions>
  </CodeBlockHeader>
  <CodeBlockContent>{code}</CodeBlockContent>
</CodeBlock>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| CodeBlock | variant | `"default" \| "ghost" \| "destructive"` | "default" | Bordered, borderless or error. |
| CodeBlock | size | `"default" \| "sm"` | "default" | Text and padding. |
| CodeBlockContent | lineNumbers / startLine / wrap | `boolean, number, boolean` |  | Numbering and wrapping. |
| CodeBlockLine | variant | `"default" \| "added" \| "removed" \| "highlighted"` |  | Diff and highlight lines. |
| CodeBlockCopyButton | value | `string` |  | Text copied to the clipboard. |

## Confidence (confidence)

How sure the model is about an output, as a three bar meter and a label, with the reason in a hover card.

Install: `npx prodular-ui add confidence`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Use it next to values the model extracted, classified or predicted, where a person decides whether to trust them.
- Explain the confidence in one sentence with the evidence: Based on 3 matching invoices.
- Use low confidence to route people to review, for example a Review low confidence fields action.

Avoid:
- Showing confidence on every sentence of generated prose. It is for discrete outputs.
- Exact percentages that are not calibrated. Pass a level instead of a value when the score is not meaningful.
- Color alone. The label or the accessible name always says the level.

Agent rules:
- Always pass explanation with the concrete evidence behind the score. A confidence without a reason is not useful.
- Pass level when the model returns a category, or value (0 to 1) when it returns a calibrated score. Defaults: 0.8 and above is high, 0.5 and above is medium.
- Use hideLabel only where the column header already says Confidence. The accessible label is kept.
- Never auto apply a low confidence output. Ask for review.

```tsx
<Confidence
  level="high"
  explanation="Based on 3 matching invoices from the same sender."
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Confidence | level | `"high" \| "medium" \| "low"` |  | Exposed as data-level. |
| Confidence | value | `number` |  | Score from 0 to 1. Derives the level when level is not set and shows a percentage. |
| Confidence | explanation | `ReactNode` |  | Why. A string renders in ConfidenceExplanation inside a hover card. |
| Confidence | hideLabel | `boolean` | false | Show the meter only. |
| ConfidenceExplanation | title | `ReactNode` |  | Replaces the level as the heading of the hover card. |

## Diff (diff)

A text diff with inline and split modes, word level highlights inside changed lines and optional line numbers. Shows what an AI edit or a new version changes.

Install: `npx prodular-ui add diff`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Show a diff before anyone accepts a change the model proposed to existing text, a template or a config.
- Use mode="inline" in narrow spaces and mode="split" when there is room and lines change a lot.
- Use variant="prose" for sentences and paragraphs, variant="code" for templates, configs and code.
- Use DiffText inside running text, for example a proposed rewrite of one paragraph.

Avoid:
- Showing only the new version of a generated edit. People need to see what is removed.
- Diffs of very long documents in one view. Diff the section that changed.
- Coloring removed and added text yourself. The component uses the success and destructive subtle tokens.

Agent rules:
- Pass the original text as before and the proposed text as after, as plain strings. Do not pre mark changes.
- Pair every AI proposed edit with a diff and explicit Accept and Reject actions. Never apply the after text on render.
- Turn lineNumbers on for code and configs, off for prose.
- Put DiffHeader with DiffTitle and DiffStat inside Diff when the diff stands alone, so people know what file or document changed.

```tsx
<Diff before={original} after={proposed} lineNumbers>
  <DiffHeader>
    <DiffTitle>second-notice.tmpl</DiffTitle>
    <DiffStat />
  </DiffHeader>
</Diff>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Diff | before / after | `string` |  | The original and the changed text. |
| Diff | mode | `"inline" \| "split"` | "inline" | Stacked or side by side. Exposed as data-mode. |
| Diff | variant | `"code" \| "prose"` | "code" | Mono and no wrapping, or UI font with wrapping. |
| Diff | lineNumbers | `boolean` | false | Old and new line numbers. |
| Diff | wordLevel | `boolean` | true | Highlight changed words inside changed lines. |
| DiffText | before / after | `string` |  | A word level diff that flows inside text. |
| DiffText | showRemoved | `boolean` | true | Hide deletions to preview the result. |
| diffWords / diffLines | (before, after) | `DiffOp<string>[]` |  | The underlying diff, if you need to render it yourself. |

## Inline assist (inline-assist)

The Cmd+K inline edit for text: select a passage, ask the AI how to change it, then review the proposed change as a diff and accept, reject or try again.

Install: `npx prodular-ui add inline-assist`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Use it where people write longer text and want to change part of it: memos, replies, descriptions, release notes.
- Offer two to four quick instructions in suggestions that fit the surface, such as Make it warmer for support replies.
- Let people try again with the same instruction before they reject.

Avoid:
- Replacing the text before the person accepts. The proposal is shown as a diff in place.
- Using it for single line inputs. Use AiSuggestion or AiGhostInput there.
- Hiding what will change. The diff shows removed text struck through and added text highlighted.

Agent rules:
- Control the text with value and onValueChange. onValueChange is called only when the person accepts a proposal.
- Implement onGenerate to return only the replacement for the selection, not the whole document. Use before and after only as context.
- Respect request.signal: abort the model call when it fires and reject the promise. Stop and Escape trigger it.
- Reject the promise on failure. The component shows an error with Try again. Never resolve with an error message as text.
- Do not add your own Cmd+K, Enter or Escape handlers around InlineAssist. It handles them while a selection or proposal is active.

```tsx
<InlineAssist
  value={text}
  onValueChange={setText}
  onGenerate={async ({ instruction, selection, signal }) => {
    const res = await fetch("/api/edit", { method: "POST", body: JSON.stringify({ instruction, selection }), signal })
    return (await res.json()).text
  }}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| InlineAssist | value / onValueChange | `string / (value: string) => void` |  | Plain text. Paragraphs separated by blank lines. |
| InlineAssist | onGenerate | `(request: { instruction, selection, before, after, signal }) => Promise<string>` |  | Returns the replacement for the selection. |
| InlineAssist | suggestions | `string[]` | ["Make it shorter", "Make it more formal", "Fix grammar"] | Quick instructions under the prompt input. |
| InlineAssist | contentClassName | `string` |  | Classes for the text surface, for example a smaller size. |

## Marker (marker)

A quiet line inside a conversation for dates, system events and state changes such as a stopped response.

Install: `npx prodular-ui add marker`
Free, MIT licensed.

Use when:
- For dates, people joining, context being summarized, a response that was stopped or a conversation that moved.
- The separator variant between groups of messages.

Avoid:
- Errors that need action. Use an Alert with a retry button.
- Assistant text. Markers are for the system, not the model.

Agent rules:
- Write markers as one short sentence in sentence case without a full stop when it is a label (Yesterday) and with one when it is an event sentence.
- Render a Marker with You stopped this response after a Response that was stopped by the user.
- Use variant="separator" for date breaks, the default variant with MarkerIcon for events.

```tsx
<Marker variant="separator">
  <MarkerContent>Yesterday</MarkerContent>
</Marker>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Marker | variant | `"default" \| "separator" \| "border"` | "default" | Plain line, centered between rules, or with a bottom border. |
| Marker | render | `ReactElement` |  | Render as another element, such as a list item. |

## Message (message)

The layout of one turn in a conversation: who wrote it, where it aligns, and slots for header, content and footer.

Install: `npx prodular-ui add message`
Free, MIT licensed.

Use when:
- For every turn in a chat, an agent run log or a comment thread with an assistant in it.
- from="user" aligns to the end, from="assistant" to the start.

Avoid:
- Putting assistant answers in a Bubble. Long answers read better on the page.
- Avatars in one to one chats. A header with the AI mark is enough.

Agent rules:
- Always set from on Message. Assistant messages carry data-from="assistant", which is how generated content is marked in a thread.
- Inside an assistant message, render parts in the order they were produced: MessageHeader, Reasoning, tool calls, Response, Sources, MessageActions, follow-up Suggestions.
- Put the AI mark in MessageHeader or MessageAvatar of assistant messages, with model set to the model that produced it.
- Wrap each Message in MessageScrollerItem when the thread scrolls.

```tsx
<Message from="assistant">
  <MessageContent>
    <MessageHeader><AiMark /> Copilot</MessageHeader>
    <Response>{text}</Response>
  </MessageContent>
</Message>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Message | from | `"user" \| "assistant" \| "system"` |  | Author. Sets data-from and the default alignment. |
| Message | align | `"start" \| "end"` | end for user, start otherwise | Override the side. |
| MessageMeta | children | `ReactNode` |  | Time, model or status next to the name, 12px. |

## Message actions (message-actions)

The row of quiet icon buttons under a message: copy, regenerate, rate with a reason, share and switch between versions.

Install: `npx prodular-ui add message-actions`
Free, MIT licensed.

Use when:
- Under every assistant message: copy, regenerate and feedback at least. Under user messages: copy and edit.
- MessageVersions when a message was regenerated or edited and older versions are kept.

Avoid:
- Text buttons or filled buttons here. The actions should stay out of the way of the answer.
- More than six actions. Put the rest in a menu.

Agent rules:
- Place MessageActions inside MessageContent, after Response and Sources, so hover follows the message.
- Set visibility="always" on the latest assistant message and leave the default on older ones.
- Give every MessageAction a verb first label. It is the tooltip and the accessible name.
- Pass the raw markdown of the answer to MessageActionCopy value, not the rendered text.
- Send ratings to your backend in onValueChange and the reasons in onFeedback. Keep reasons to five or fewer and specific to the product.
- Render MessageVersions only when total is 2 or more, and keep value one based.

```tsx
<MessageActions>
  <MessageActionCopy value={markdown} />
  <MessageAction label="Regenerate" onClick={regenerate}><RefreshCwIcon /></MessageAction>
  <MessageActionFeedback onValueChange={rate} onFeedback={sendFeedback} />
  <MessageVersions value={2} total={3} onValueChange={setVersion} />
</MessageActions>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| MessageActions | visibility | `"hover" \| "always"` | "hover" | Hover reveals on pointer devices and stays visible on touch. |
| MessageAction | label | `string` |  | Tooltip and aria-label. |
| MessageActionCopy | value | `string` |  | Copied to the clipboard. Shows a check for two seconds. |
| MessageActionFeedback | value / onValueChange | `"up" \| "down" \| null` |  | Current rating. |
| MessageActionFeedback | onFeedback | `({ reasons, comment }) => void` |  | Called when the thumbs down form is sent. |
| MessageActionFeedback | reasons | `string[]` |  | Reason chips in the form. |
| MessageVersions | value / total / onValueChange | `number` |  | One based version switcher, 2 of 3. |

## Message scroller (message-scroller)

The scrolling viewport for a conversation: it follows new tokens, anchors each new question to the top and shows a jump to latest button.

Install: `npx prodular-ui add message-scroller`
Free, MIT licensed.

Use when:
- Around every chat thread or agent log that can grow past the screen.
- Inside a parent with a fixed height, usually the space between the header and the composer.

Avoid:
- Scrolling the whole page for a chat. The composer should stay in view.
- Calling scrollIntoView yourself while streaming. The scroller already follows the end.

Agent rules:
- Wrap with MessageScrollerProvider autoScroll so streamed tokens keep the latest line in view unless the user scrolls up.
- Give every MessageScrollerItem a stable messageId. Set scrollAnchor on user messages so each new question moves to the top.
- Give the MessageScroller parent a fixed or flex constrained height and min-h-0, or it will not scroll.
- Render MessageScrollerButton once inside MessageScroller. It hides itself when the view is already at the end.

```tsx
<MessageScrollerProvider autoScroll>
  <MessageScroller>
    <MessageScrollerViewport>
      <MessageScrollerContent>
        <MessageScrollerItem messageId="m1" scrollAnchor>...</MessageScrollerItem>
      </MessageScrollerContent>
    </MessageScrollerViewport>
    <MessageScrollerButton />
  </MessageScroller>
</MessageScrollerProvider>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| MessageScrollerProvider | autoScroll | `boolean` | false | Follow new content while the view is at the end. |
| MessageScrollerProvider | defaultScrollPosition | `"end" \| "start" \| "last-anchor"` | "end" | Where the view starts. |
| MessageScrollerItem | messageId | `string` |  | Stable id used for anchoring and scrollToMessage. |
| MessageScrollerItem | scrollAnchor | `boolean` | false | Scroll this item to the top when it is added. |
| MessageScrollerButton | direction | `"end" \| "start"` | "end" | Which end the button jumps to. |

## Model picker (model-picker)

Choose the model that runs a feature. Each option shows a provider glyph, a short descriptor, capabilities, context window and relative speed and cost.

Install: `npx prodular-ui add model-picker`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Use the compact variant in a composer toolbar and the full variant in settings and forms.
- Write descriptions as what the model is good for in your product, not marketing copy: Thinks longer for reconciliations and audits.
- Group options with group when there are more than four, for example Recommended and All models.
- Show models that are not on the person's plan as disabled with a tag, so they know they exist.

Avoid:
- Real provider logos. Use the monochrome letter glyph or pass a neutral icon in glyph.
- Raw model ids as names. Show the human name and keep the id in value.
- Listing more than eight models. Curate the list for the task.

Agent rules:
- Render ModelPicker controlled with value and onValueChange. Store and send the model id, never the display name.
- Pass contextWindow in tokens, speed and cost as relative 1 to 3 values, and capabilities from vision, tools, reasoning, files, web. Leave a field out rather than guessing it.
- In a composer use variant="compact" inside PromptInputTools. In a form use variant="full" with a visible label linked through id, or pass aria-label.
- When the selected model changes, update anything that depends on it, such as ContextWindow max.
- Do not use brand logos or brand colors for providers. Use ModelGlyph.

```tsx
<ModelPicker
  models={models}
  value={model}
  onValueChange={setModel}
  variant="compact"
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ModelPicker | models | `ModelOption[]` |  | id, name, provider, description, capabilities, contextWindow, speed, cost, group, tag, glyph, disabled. |
| ModelPicker | value / onValueChange | `string / (id: string) => void` |  | The selected model id. |
| ModelPicker | variant | `"compact" \| "full"` | "compact" | compact for toolbars, full for forms. |
| ModelPicker | aria-label | `string` | "Model" | Accessible name for the trigger. |
| ModelGlyph | provider | `string` |  | Its first letter becomes the mark. |
| ModelRating | kind / value | `"speed" \| "cost" / 1 \| 2 \| 3` |  | Three pips with an accessible word. |

## Prompt input (prompt-input)

The composer for AI chat: an autosizing textarea with attachments, tools and a send button that turns into a stop button while the model answers.

Install: `npx prodular-ui add prompt-input`
Free, MIT licensed.

Use when:
- One composer per conversation, pinned to the bottom of the thread and centered to the same width as the messages.
- Put attachments in PromptInputAttachments so they read as part of the message being written.
- Use PromptInputToggle for switches that change how the next answer is produced, such as web search or deep research.

Avoid:
- Disabling the textarea while the model answers. People should be able to write the next message while they read.
- More than four controls on the left. Move rarely used tools into a menu.
- A separate stop button. PromptInputSubmit becomes the stop button while streaming.

Agent rules:
- Always pass status to PromptInput: "submitting" from send until the first token, "streaming" while tokens arrive, "error" when the request fails, "idle" otherwise. Never leave it at idle during a request.
- Always pass onStop together with status="streaming" and abort the request in it.
- Use onSubmit(text) to send. It receives trimmed text, is never called for empty input and clears the field. Do not attach your own Enter key handler: Enter sends, Shift+Enter adds a line and IME composition is ignored.
- Every PromptInputButton that only holds an icon needs tooltip, which also becomes its aria-label.
- On error keep the draft (pass clearOnSubmit={false} or restore value) and show the reason in text next to the composer.
- Render the composer inside the page surface, not inside another card.

```tsx
<PromptInput status={status} onSubmit={send} onStop={abort}>
  <PromptInputAttachments>{attachments}</PromptInputAttachments>
  <PromptInputTextarea placeholder="Ask anything" />
  <PromptInputToolbar>
    <PromptInputTools>
      <PromptInputButton tooltip="Attach files"><PaperclipIcon /></PromptInputButton>
      <PromptInputToggle><GlobeIcon data-icon="inline-start" />Search</PromptInputToggle>
    </PromptInputTools>
    <PromptInputActions>
      <PromptInputButton tooltip="Dictate"><MicIcon /></PromptInputButton>
      <PromptInputSubmit />
    </PromptInputActions>
  </PromptInputToolbar>
</PromptInput>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| PromptInput | status | `"idle" \| "submitting" \| "streaming" \| "error"` | "idle" | Request state. Streaming turns the send button into a stop button. |
| PromptInput | onSubmit | `(text: string, event) => void` |  | Called with the trimmed text on Enter or send. |
| PromptInput | onStop | `() => void` |  | Called when the stop button is pressed while streaming. |
| PromptInput | value / defaultValue / onValueChange | `string` |  | Controlled or uncontrolled text. |
| PromptInput | allowEmptySubmit | `boolean` | false | Allow sending without text, for example with attachments only. |
| PromptInput | clearOnSubmit | `boolean` | true | Clear the text after sending. |
| PromptInputTextarea | maxRows | `number` | 8 | Grows from one line up to this many, then scrolls. |
| PromptInputButton | tooltip | `string` |  | Hover label and accessible name for icon buttons. |
| PromptInputToggle | pressed / onPressedChange | `boolean` |  | On and off state for tools such as web search. |

## Questionnaire (questionnaire)

Structured questions an assistant asks before it acts, one step at a time, with keyboard shortcuts for the choices.

Install: `npx prodular-ui add questionnaire`
Free, MIT licensed.

Use when:
- When the assistant needs a decision before a long or costly task: a forecast, a migration, sending emails.
- Two to four choices per question, each a complete answer.

Avoid:
- Asking what the assistant could look up itself.
- More than three questions. Ask the rest later or pick defaults and say so.

Agent rules:
- Render the questionnaire inside the assistant Message that asks it, not as a modal.
- Give every QuestionnaireItem a unique name and mark required items. Use multiple for checkbox questions.
- Write titles as questions ending in a question mark, and choices as answers, not as Yes or No alone.
- On submit, send the answers back as a user message so the thread keeps a record of what was chosen.

```tsx
<Questionnaire onSubmit={send}>
  <QuestionnaireItem name="horizon" required>
    <QuestionnaireTitle>How far ahead?</QuestionnaireTitle>
    <QuestionnaireChoices>
      <QuestionnaireChoice value="13w">13 weeks</QuestionnaireChoice>
    </QuestionnaireChoices>
    <QuestionnaireActions><QuestionnaireSubmit /></QuestionnaireActions>
  </QuestionnaireItem>
</Questionnaire>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Questionnaire | shortcuts | `"letters" \| "numbers"` |  | Keyboard shortcuts for choices. |
| Questionnaire | onSubmit | `FormEventHandler` |  | Called when the last step is sent. |
| QuestionnaireItem | name / required / multiple | `string, boolean, boolean` |  | One question. |
| QuestionnaireChoice | value | `string` |  | Choice value. |

## Reasoning (reasoning)

Collapsible model thinking: a shimmering Thinking label with a live timer while it runs, then Thought for 12s, collapsed.

Install: `npx prodular-ui add reasoning`
Free, MIT licensed.

Use when:
- When the model exposes reasoning or a summary of it, above the answer it led to.
- Keep it collapsed for history. People open it when they doubt an answer.

Avoid:
- Showing raw chain of thought your provider asks you not to show. Use a summary instead.
- Putting the answer inside Reasoning. The answer belongs in Response.

Agent rules:
- Render Reasoning before tool calls and before Response inside the same assistant Message, in the order the model produced them.
- Set streaming to true while reasoning tokens arrive and false as soon as the first answer token or tool call starts.
- Pass duration in seconds when you load a finished message from history, so the label does not read 1s.
- Do not render Reasoning for models that do not reason. No empty Thinking rows.

```tsx
<Reasoning streaming={isThinking}>
  <ReasoningTrigger />
  <ReasoningContent>{reasoningText}</ReasoningContent>
</Reasoning>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Reasoning | streaming | `boolean` | false | Shimmer, live timer and auto open while true. |
| Reasoning | duration | `number` |  | Final thinking time in seconds. Measured automatically when omitted. |
| Reasoning | openWhileStreaming | `boolean` | true | Open while thinking and collapse when it ends. |
| Reasoning | open / defaultOpen / onOpenChange | `boolean` |  | Control the expanded state. |
| ReasoningTrigger | children | `ReactNode` |  | Replaces the automatic Thinking and Thought for label. |

## Response (response)

Renders an assistant answer from markdown, with a caret and soft word fade while it streams and citations from the sources it used.

Install: `npx prodular-ui add response`
Free, MIT licensed.

Use when:
- For every assistant answer, streamed or loaded from history.
- Inside Message from="assistant", after Reasoning and tool calls.

Avoid:
- Wrapping it in a card or bubble. Assistant text sits on the page so it reads like a document.
- Long tables in chat. Over eight rows, link to a report instead.
- Rendering user messages with it. Users write plain text, show it in a Bubble.

Agent rules:
- Pass the markdown as children and set streaming only while tokens are still arriving. Set it to false the moment the stream ends, so the caret disappears.
- Never fake streaming for retrieved or cached content. Render history and saved answers with streaming={false}.
- Pass the sources the model cited as sources. [1] style markers in the text become citation chips in that order. Do not invent sources.
- Do not repair or buffer partial markdown yourself. Response closes open code fences, bold and links and holds back half written table rows.
- Render Reasoning and tool calls before Response, never after it.
- Do not add your own text size or prose classes. The type scale is set for reading.

```tsx
<Message from="assistant">
  <MessageContent>
    <Response streaming={status === "streaming"} sources={sources}>
      {text}
    </Response>
  </MessageContent>
</Message>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Response | children | `string` |  | Markdown with GitHub flavored tables, task lists and strikethrough. |
| Response | streaming | `boolean` | false | Shows the caret and repairs incomplete markdown. |
| Response | animate | `boolean` | streaming | Fades new words in. Respects reduced motion. |
| Response | sources | `SourceData[]` |  | Turns [n] markers into citation chips with a preview card. |

## Sources (sources)

Citations for generated answers: numbered inline chips with a preview card, and a collapsible list of every source used.

Install: `npx prodular-ui add sources`
Free, MIT licensed.

Use when:
- Whenever an answer relies on retrieved documents, records or web pages.
- Inline citations right after the sentence they support, and the Sources list once under the answer.

Avoid:
- Citing the model itself or sources it did not read.
- More than three citations on one sentence. Cite the strongest one.

Agent rules:
- Number citations from 1 in the order they first appear, and list Sources in the same order so numbers match.
- Only cite sources that the tool calls actually returned. Never generate URLs, titles or snippets.
- Inside Response, pass sources to Response and keep [1] markers in the text instead of rendering Citation yourself.
- Give each source a title and url. Add siteName for internal tools (Cost Explorer, Notion) and snippet with the exact supporting passage.
- Render the Sources list after the answer finishes streaming, not while it streams.

```tsx
<Sources>
  <SourcesTrigger sources={sources} />
  <SourcesContent>
    {sources.map((s, i) => <Source key={s.url} source={s} index={i + 1} />)}
  </SourcesContent>
</Sources>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Citation | index | `number` |  | One based number shown in the chip. |
| Citation | source | `SourceData` |  | { title, url, snippet?, favicon?, siteName? } |
| SourcesTrigger | sources | `SourceData[]` |  | The first four favicons are stacked in the trigger. |
| SourcesTrigger | count | `number` | sources.length | Total shown in the label. |
| Source | source / index | `SourceData, number` |  | One row in the expanded list. |

## Suggestions (suggestions)

Prompt suggestions as a scrollable row of chips for empty states, or a vertical list of follow-up questions under an answer.

Install: `npx prodular-ui add suggestions`
Free, MIT licensed.

Use when:
- Chips for an empty conversation, three to six of them, based on what the product can actually do.
- Follow-ups under the latest answer only, three or four, generated from that answer.

Avoid:
- Generic prompts like Tell me a joke. Each suggestion should name real data in the product.
- Showing follow-ups under older answers or while the answer still streams.

Agent rules:
- Pass the exact prompt text as suggestion. onSelect receives it, so you can send it or put it in the composer.
- Write suggestions as the user would type them, verb first, under 60 characters, no trailing full stop.
- Use orientation="vertical" for follow-ups and the default horizontal row for empty states.
- Render follow-ups only after the response finishes, and remove them when the user sends a new message.

```tsx
<Suggestions>
  <Suggestion suggestion="Summarize October close status" onSelect={send} />
</Suggestions>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Suggestions | orientation | `"horizontal" \| "vertical"` | "horizontal" | Chips in a scrolling row, or a list of follow-up questions. |
| Suggestion | suggestion | `string` |  | Prompt text. Shown when there are no children. |
| Suggestion | onSelect | `(suggestion: string) => void` |  | Called on click with the prompt text. |
| SuggestionsLabel | children | `ReactNode` |  | Optional heading above a vertical list. |

## Tool call (tool-call)

One tool invocation by a model: name, a short summary of its arguments and its status, with the input and output inside the same container.

Install: `npx prodular-ui add tool-call`
Free, MIT licensed.

Use when:
- For every tool the model calls, in the order it called them, between Reasoning and Response.
- Approval for anything that writes, sends, pays or deletes.

Avoid:
- Showing raw tool names like search_invoices_v2. Write a human title: Search invoices.
- Opening every call by default. Keep them collapsed unless one failed or needs approval.
- Nesting code blocks or cards inside. ToolCallSection already separates input and output with dividers.

Agent rules:
- Always pass status, and update it as the call progresses: pending, running, then done or error. Use approval when a person must allow the call before it runs.
- Write ToolCallTitle as verb plus object (Search invoices, Schedule payment) and ToolCallSummary as the two or three arguments that matter, not the full JSON.
- Pass duration to ToolCallStatus when status is done.
- Put objects in ToolCallSection value. It formats JSON and adds a copy button. Use label Input, Output or Error.
- For approval, render ToolCallApproval with one sentence that says what will happen, a ghost Deny button and a default button that names the action. Never run the tool before approval.
- Render a failed call with status error and an Error section, and let the model explain the failure in its Response.

```tsx
<ToolCall status="done">
  <ToolCallHeader>
    <ToolCallIcon><ReceiptIcon /></ToolCallIcon>
    <ToolCallTitle>Search invoices</ToolCallTitle>
    <ToolCallSummary>vendor: Northbeam</ToolCallSummary>
    <ToolCallStatus duration="0.9s" />
  </ToolCallHeader>
  <ToolCallContent>
    <ToolCallSection label="Input" value={input} />
    <ToolCallSection label="Output" value={output} />
  </ToolCallContent>
</ToolCall>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ToolCall | status | `"pending" \| "running" \| "done" \| "error" \| "approval"` | "pending" | Drives the icon, shimmer, label and border. |
| ToolCall | open / defaultOpen | `boolean` |  | Whether input and output are visible. |
| ToolCallStatus | duration | `string` |  | Replaces Done once finished, for example 1.4s. |
| ToolCallSection | label | `string` |  | Input, Output or Error. |
| ToolCallSection | value | `unknown` |  | Objects render as formatted JSON, strings as they are. |

## Trace (trace)

A quiet list of the steps an agent took, with running, error and pending states and collapsible detail.

Install: `npx prodular-ui add trace`
Free, MIT licensed.

Use when:
- For agent runs with many small steps, where a ToolCall card for each would be too heavy.
- As the base of Reasoning, which is a Trace with a timer.

Avoid:
- Long sentences. A step is a verb and an object, plus a number when it helps.
- Hiding errors inside collapsed steps. Keep failed steps visible.

Agent rules:
- Write TraceTitle in the past tense for finished steps (Read 214 invoices) and the present for running ones (Comparing rates).
- Set status="running" on the step in progress, "pending" on queued steps and "error" on failures. Leave it unset for finished steps.
- Put durations and counts in TraceDescription. They are tabular.
- Use ToolCall instead when people need to see inputs and outputs or approve the step.

```tsx
<Trace>
  <TraceLine status="running">
    <TraceIcon><SearchIcon /></TraceIcon>
    <TraceTitle>Searching invoices</TraceTitle>
    <TraceDescription>1.2s</TraceDescription>
  </TraceLine>
</Trace>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| TraceLine | status | `"running" \| "error" \| "pending"` |  | Shimmer, error color or dimmed. |
| TraceCollapsible | open / defaultOpen / onOpenChange | `boolean` |  | Expand a step to show detail. |
| TraceDescription | children | `ReactNode` |  | Duration or count after the title. |

## Usage meter (usage-meter)

Token and credit usage: a segmented bar against a limit, a context window ring that warns near the limit, and a monthly summary strip.

Install: `npx prodular-ui add usage-meter`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Show usage where people spend it: the context ring in the composer, the token meter on the feature's settings, credits on the billing page.
- Split the bar into the segments people pay for differently, such as input, output and cached tokens.
- Say what happens at the limit in description: replies pause, older turns are summarized, overage is billed.
- Put the period and reset date next to monthly numbers.

Avoid:
- Percentages without the absolute numbers. Show 1.42M of 5M tokens.
- Red before the limit is actually reached. Warning starts at warnAt, destructive only when exceeded.
- A grid of KPI cards for the summary. Use UsageSummary, one strip with dividers.

Agent rules:
- Pass raw numbers (tokens or credits as integers) and let the component format them. Do not pass preformatted strings to UsageMeter or ContextWindow.
- Always pass limit to UsageMeter and max to ContextWindow from the real plan or model. Update ContextWindow max when the selected model changes.
- Use ContextWindow variant="compact" in toolbars and variant="full" in panels. Never hide the ring once the context is above warnAt.
- Keep tabular-nums on any number you render next to these components so values do not shift as they update.
- Use chart-1 to chart-5 or muted for segment colors. Never use AI gradient colors for usage, it is not generated content.

```tsx
<UsageMeter
  label="Ledger assistant"
  limit={5_000_000}
  segments={[
    { label: "Input", value: 1_420_000 },
    { label: "Output", value: 610_000 },
    { label: "Cached", value: 880_000 },
  ]}
/>
<ContextWindow used={96_400} max={128_000} />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| UsageMeter | label | `ReactNode` |  | What is being measured. |
| UsageMeter | segments | `{ label: string; value: number; color?: "chart-1" \| ... \| "chart-5" \| "muted" }[]` |  | Parts of the total, in order. |
| UsageMeter | limit | `number` |  | The plan limit. Exposed with data-state ok, warning or exceeded. |
| UsageMeter | warnAt | `number` | 0.8 | Ratio of the limit where the warning starts. |
| UsageMeter | unit / format / description | `string / (n) => string / ReactNode` | "tokens" / formatTokens | Unit label, number formatting and a line under the bar. |
| ContextWindow | used / max | `number` |  | Tokens in context and the model's window. |
| ContextWindow | variant | `"compact" \| "full"` | "compact" | compact is a 16px ring with a tooltip, full shows numbers and a status line. |
| UsageSummaryItem | label / value / description | `ReactNode` |  | One cell of the summary strip. |

## Voice input (voice-input)

Dictation for AI features: a mic button with a listening state, live level bars, a timer, a stop button and a transcript preview with interim words.

Install: `npx prodular-ui add voice-input`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Use it where people describe something faster than they type it: visit notes, ticket replies, prompts on mobile.
- Show interim words muted and settled words in full color so people see the recognizer working.
- Let people edit the transcript before it is sent or saved.

Avoid:
- Starting to listen without a press. The microphone only opens on an explicit action.
- Sending the transcript automatically when listening stops.
- Hiding the timer. People need to know the mic is still on.

Agent rules:
- Only request microphone access with getUserMedia inside the click handler of VoiceInputButton, and stop every track of the stream when the person presses stop or leaves the view.
- Pass status on every render: listening while the mic is open, processing while the final transcript is computed, idle otherwise.
- Drive VoiceLevels from useAudioLevels(stream) with a real stream. Do not show fake levels in production.
- Always render VoiceInputStop and VoiceInputTimer while listening. Pass interim to VoiceTranscript for words the recognizer may still change.
- Put the transcript in an editable field after processing. Never submit it without the person confirming.

```tsx
<VoiceInput status={status}>
  <VoiceInputButton onClick={start} />
  <VoiceLevels levels={levels} />
  <VoiceInputTimer seconds={seconds} />
  <VoiceInputStop onClick={stop} />
</VoiceInput>
<VoiceTranscript interim={interim}>{finalText}</VoiceTranscript>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| VoiceInput | status | `"idle" \| "listening" \| "processing"` | "idle" | Exposed as data-status. Shapes the container and the parts. |
| VoiceInputButton | Button props | `ComponentProps<typeof Button>` |  | Starts listening. Pressed and pulsing while listening. |
| VoiceLevels | levels | `number[]` |  | One value from 0 to 1 per bar, newest last. |
| VoiceInputTimer | seconds | `number` |  | Elapsed listening time. |
| VoiceInputStop | Button props | `ComponentProps<typeof Button>` |  | Stops and transcribes. Shows a spinner while processing. |
| VoiceTranscript | interim | `string` |  | Words that may still change, shown muted after children. |
| useAudioLevels | (stream, bars) | `(MediaStream \| null, number) => number[]` |  | Live levels from a microphone stream. |

## Bulk action bar (bulk-action-bar)

A toolbar for the selected items: count, select all and clear, actions with single key shortcuts, a More menu for the rest, loading per action, and confirmation for destructive ones.

Install: `npx prodular-ui add bulk-action-bar`
Free, MIT licensed.

Use when:
- Lists, tables and boards where people select several items and act on all of them.
- Three visible actions for the common ones, the rest in More.
- shortcut for actions people repeat, like archive or assign.

Avoid:
- Actions for one item. Put those in the row menu.
- Hiding unavailable actions. Disable them with a reason so people learn why.

Agent rules:
- Render the bar inside the list's relative container with position floating, or inline above the list.
- Pass count and onClear; add total and onSelectAll to offer Select all.
- Make onAction async; the button shows a spinner and the others wait. Throw to show the error in the bar.
- Destructive actions confirm through Destructive confirm unless confirm is false. Put counts in the confirmation title.
- Shortcuts are single keys without modifiers and do nothing while people type in a field or a dialog is open.

```tsx
<BulkActionBar
  count={selected.length}
  total={rows.length}
  onClear={clear}
  actions={[{ id: "archive", label: "Archive", shortcut: "e", onAction: archive }]}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| BulkActionBar | count / total | `number` |  | Selected and selectable items. Hidden at 0. |
| BulkActionBar | onClear / onSelectAll | `() => void` |  | Clear selection (also Escape) and select everything. |
| BulkActionBar | noun | `[string, string]` | ["item", "items"] | Singular and plural for the count. |
| BulkActionBar | actions | `BulkAction[]` |  | { id, label, icon?, shortcut?, variant?, onAction, confirm?, disabled? }. |
| BulkActionBar | maxVisible | `number` | 3 | Buttons before More. |
| BulkActionBar | position | `"floating" \| "inline"` | "floating" | Over the bottom of the container, or in the flow. |

## Button (button)

Triggers an action. Eight variants, including an AI variant for actions that run a model.

Install: `npx prodular-ui add button`
Free, MIT licensed.

Use when:
- Use default for the single most important action in a view.
- Use ai when pressing the button runs a model and the output is generated, not retrieved.
- Use destructive only for the final confirmation of an irreversible action.

Avoid:
- Two default buttons side by side. Make one of them outline or secondary.
- The ai variant for ordinary actions that only mention AI in the label.

Agent rules:
- Label buttons with a verb and an object: Save changes, Export CSV. Never OK or Submit alone.
- Pass loading while a request is pending instead of swapping in a spinner yourself.
- Icon-only buttons need aria-label.

```tsx
<Button variant="outline" size="sm">
  <DownloadIcon data-icon="inline-start" />
  Export
</Button>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Button | variant | `"default" \| "secondary" \| "outline" \| "ghost" \| "destructive" \| "destructive-subtle" \| "ai" \| "link"` | "default" | Visual style. |
| Button | size | `"xs" \| "sm" \| "default" \| "lg" \| "xl" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"` | "default" | Height and padding. Icon sizes are square. |
| Button | loading | `boolean` | false | Shows a spinner, sets aria-busy and blocks clicks. |
| Button | render | `ReactElement` |  | Renders the button as another element, for example a link. |

## Button group (button-group)

Joins related buttons, inputs and labels into one row with shared borders.

Install: `npx prodular-ui add button-group`
Free, MIT licensed.

Use when:
- Two to four actions on the same object, such as Reply, Snooze, Archive.
- A split button: a main action with a menu of variants.
- An input with a fixed prefix and an action, or a stepper.

Avoid:
- Mixing variants inside one group, other than a split button.
- Choosing between options. Use ToggleGroup.

Agent rules:
- Use the same variant and size for every button in a group.
- Give the group an aria-label that names what the actions act on.
- Use ButtonGroupText for static text such as a protocol or a count.
- Nest ButtonGroups to put a gap between clusters.

```tsx
<ButtonGroup aria-label="Conversation actions">
  <Button variant="outline">Reply</Button>
  <Button variant="outline">Archive</Button>
</ButtonGroup>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ButtonGroup | orientation | `"horizontal" \| "vertical"` | "horizontal" | Direction. Borders and corners adjust. |
| ButtonGroupText | render | `ReactElement` |  | Render as another element, such as a Label. |
| ButtonGroupSeparator | orientation | `"vertical" \| "horizontal"` | "vertical" | A hairline between buttons that have no border. |

## Hotkeys (hotkeys)

Keyboard shortcuts for desktop apps: one listener, scopes, guards for fields and open menus, conflict detection, remapping and a shortcuts sheet that can turn single-key shortcuts off (WCAG 2.1.4).

Install: `npx prodular-ui add hotkeys`
Free, MIT licensed.

Use when:
- Apps people use all day, where the mouse slows them down.
- Single keys (G, [, ?) only for frequent actions, and always with the sheet so they can be turned off.
- useHotkeyScope for shortcuts that only make sense while a panel or editor has focus.

Avoid:
- Reimplementing shortcuts with your own keydown listeners.
- Overriding browser and screen reader keys: Cmd or Ctrl plus L, T, W, R, F, and Tab.
- Shortcuts without a description; they cannot be found or changed.

Agent rules:
- Mount HotkeysProvider once near the root and register shortcuts with useHotkey(keys, handler, { id, description, group }).
- Write keys as "mod+k", "shift+?", "g" or "escape". mod is Cmd on macOS and Ctrl elsewhere.
- Always render ShortcutsDialog and open it with shift+?. It is how people discover, remap and turn off shortcuts.
- Show shortcuts in menus and tooltips with HotkeyKeys or useHotkeyKeys(id), so they reflect the person's remapping.
- Do not set allowInInputs on single-key shortcuts.
- Open CommandDialog from useHotkey("mod+k"), not from a separate listener.

```tsx
<HotkeysProvider>
  <App />
</HotkeysProvider>

useHotkey("mod+k", openPalette, { id: "palette", description: "Open command palette" })
useHotkey("shift+?", () => setHelp(true), { id: "help", description: "Show keyboard shortcuts" })
<ShortcutsDialog open={help} onOpenChange={setHelp} />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| HotkeysProvider | storageKey | `string \| null` | "prodular-ui:hotkeys" | Where remapping and the single-key switch are saved. null keeps them in memory. |
| useHotkey | keys | `string` |  | "mod+k", "shift+?", "g", "[", "escape". |
| useHotkey | options | `{ id, description, group, scope, enabled, allowInInputs, allowInOverlays, preventDefault }` |  | id and description make it appear and remappable in the sheet. |
| useHotkeyScope | (scope, active) | `(string, boolean) => void` |  | Turns a scope on while active. |
| ShortcutsDialog | open | `boolean` |  | Controlled with onOpenChange. |
| HotkeyKeys | keys | `string` |  | Renders the keys as Kbd, with the platform's symbols. |

## Amount input (amount-input)

A money field that takes its decimals and symbol from the currency and its grouping from the locale, with an optional currency switch.

Install: `npx prodular-ui add amount-input`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Prices, limits, payments, budgets: any amount of money people type.
- currencies when the same form handles several, with onCurrencyChange to switch.

Avoid:
- Percentages or counts. Use Number input with a unit.
- Hardcoding the symbol in a prefix. The currency and locale decide it.

Agent rules:
- Always pass currency as an ISO 4217 code and the user's locale. Never hardcode $ or decimals.
- Keep the value in major units (12.50, not 1250). Convert to minor units only at the API boundary.
- Show totals and summaries with formatAmount(value, currency, locale) so they match the field.
- Label it with Field and FieldLabel, and put limits in min and max.

```tsx
<Field>
  <FieldLabel>Payment received</FieldLabel>
  <AmountInput currency="USD" locale="en-US" value={amount} onValueChange={setAmount} />
</Field>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AmountInput | currency | `string` |  | ISO 4217 code. Sets decimals and symbol. |
| AmountInput | locale | `string` |  | Grouping, decimal mark and the side the symbol sits on. |
| AmountInput | currencies / onCurrencyChange | `string[] / (code) => void` |  | Shows a currency switch at the end of the field. |
| AmountInput | display | `"symbol" \| "code"` | "symbol" | Show USD instead of $ where the symbol is ambiguous. |
| AmountInput | value / onValueChange / min / max | `number \| null` |  | Same as Number input, in major units. |
| formatAmount | (value, currency, locale) | `string` |  | Formats an amount the way the field shows it. |

## Calendar (calendar)

A month grid for picking a date or a date range, built on React DayPicker.

Install: `npx prodular-ui add calendar`
Free, MIT licensed.

Use when:
- Picking a due date, a booking date or a reporting range where the day of the week matters.

Avoid:
- Dates people know by heart, such as a birthday, as the only input. Offer a text input too or use dropdowns.
- Time of day. Pair it with an Input or Select for time.

Agent rules:
- Set mode to single, multiple or range and control selected with onSelect.
- Disable dates people cannot pick with disabled (for example { before: today }) rather than validating afterwards.
- Use numberOfMonths={2} for ranges.
- In a popover, render it without a border. Standalone, give it rounded-xl border bg-card shadow-xs.

```tsx
<Calendar mode="single" selected={date} onSelect={setDate} />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Calendar | mode | `"single" \| "multiple" \| "range"` |  | Selection behaviour. |
| Calendar | selected / onSelect | `Date \| Date[] \| DateRange` |  | Controlled selection. |
| Calendar | disabled | `Matcher \| Matcher[]` |  | Dates that cannot be picked. |
| Calendar | captionLayout | `"label" \| "dropdown"` | "label" | Static caption or month and year dropdowns. |
| Calendar | numberOfMonths | `number` | 1 | Months shown side by side. |
| Calendar | buttonVariant | `Button variant` | "ghost" | Style of the previous and next buttons. |

## Checkbox (checkbox)

An on or off choice that is saved with the rest of a form, with an indeterminate state for select all.

Install: `npx prodular-ui add checkbox`
Free, MIT licensed.

Use when:
- Choices that are saved when the form is submitted.
- Several independent options from a list, such as permissions.

Avoid:
- Settings that apply the moment they change. Use Switch.
- One choice from several. Use RadioGroup.

Agent rules:
- Put Checkbox and its FieldLabel inside Field orientation="horizontal", checkbox first. The label is linked automatically.
- Use indeterminate (not checked) on a select-all checkbox when only some children are checked.
- Write the label as the positive statement (Email me when a deal closes), never a negation.

```tsx
<Field orientation="horizontal">
  <Checkbox defaultChecked />
  <FieldLabel>Email me when a deal closes</FieldLabel>
</Field>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Checkbox | checked / defaultChecked | `boolean` |  | Controlled or initial state. |
| Checkbox | indeterminate | `boolean` | false | Shows a dash. Use for partial selection. |
| Checkbox | onCheckedChange | `(checked: boolean) => void` |  | Called when toggled. |
| Checkbox | disabled | `boolean` |  | Blocks interaction and dims the control. |

## Combobox (combobox)

A text input that filters a list as you type, for picking one or many items from long lists.

Install: `npx prodular-ui add combobox`
Free, MIT licensed.

Use when:
- Long lists people search by name: teammates, customers, projects, countries.
- Tagging, where several values can apply. Use chips.

Avoid:
- Short lists of fixed options. Use Select.
- Free text search with no list. Use Input or InputGroup.

Agent rules:
- Pass the full list as items and render ComboboxList as a function of each item.
- Always include ComboboxEmpty with a sentence that says what was not found.
- For multiple values use ComboboxChips with useComboboxAnchor and pass the anchor to ComboboxContent.
- Outside a Field, give ComboboxInput or ComboboxChipsInput an aria-label.
- Use showClear when an empty value is valid.
- Put a search icon or scope label in ComboboxInput leading instead of absolutely positioning it.

```tsx
<Combobox items={owners}>
  <ComboboxInput placeholder="Search teammates" />
  <ComboboxContent>
    <ComboboxEmpty>No teammate matches that name.</ComboboxEmpty>
    <ComboboxList>
      {(item) => <ComboboxItem key={item} value={item}>{item}</ComboboxItem>}
    </ComboboxList>
  </ComboboxContent>
</Combobox>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Combobox | items | `T[]` |  | The options to filter. |
| Combobox | multiple | `boolean` | false | Allows several values. Pair with ComboboxChips. |
| ComboboxInput | size | `"sm" \| "default" \| "lg"` | "default" | Height. Matches Button and Input. |
| ComboboxInput | showTrigger | `boolean` | true | Shows the chevron button. |
| ComboboxInput | showClear | `boolean` | false | Shows a clear button when there is a value. |
| ComboboxContent | anchor | `RefObject` |  | Positions the popup against the chips container. |
| ComboboxInput | leading | `ReactNode` |  | Content before the text, such as a search icon, in an inline-start addon. |

## Date range picker (date-range-picker)

A trigger showing the selected range that opens presets and a two-month calendar, with an optional compare to previous period toggle. Changes apply on Apply.

Install: `npx prodular-ui add date-range-picker`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Analytics and reports where people switch between standard periods and sometimes pick exact dates.
- comparable on dashboards that show deltas, so the comparison period is explicit.

Avoid:
- Picking a single date. Use Calendar in a Popover.
- Very long ranges spanning years. Add year presets or a year select instead of paging months.

Agent rules:
- Pass a fixed today when rendering on the server or in tests, and disabledDates={{ after: today }} when future data cannot exist.
- Treat onValueChange as the commit. It fires on Apply, not on every click in the calendar.
- Use getPreviousPeriod(range) to compute the comparison window for your query instead of recomputing it yourself.
- Pass presets that match the product's reporting periods. Keep them short, five at most.
- Give the trigger an aria-label or a visible label when the context does not name the period.

```tsx
<DateRangePicker
  value={range}
  onValueChange={setRange}
  comparable
  compare={compare}
  onCompareChange={setCompare}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| DateRangePicker | value / defaultValue / onValueChange | `DateRange \| undefined` |  | { from, to }. onValueChange fires on Apply. |
| DateRangePicker | comparable | `boolean` | false | Shows the Compare to previous period switch. |
| DateRangePicker | compare / defaultCompare / onCompareChange | `boolean` |  | Compare state, committed with Apply. |
| DateRangePicker | presets | `DateRangePreset[]` | Today, Last 7 days, Last 30 days, This quarter, Year to date | { id, label, range(today) }. Pass [] to hide the column. |
| DateRangePicker | today | `Date` | new Date() | Reference date for presets. |
| DateRangePicker | numberOfMonths | `number` | 2 | Months shown side by side. |
| DateRangePicker | disabledDates | `Matcher` |  | react-day-picker matcher, for example { after: today }. |
| getPreviousPeriod | (range) | `function` |  | Same-length period ending the day before range.from. |
| formatDateRange | (range) | `function` |  | Formats as Sep 22 – Oct 21, 2026. |

## Field (field)

The way to build forms: a label, a control, a description and an error, linked for assistive technology without passing ids.

Install: `npx prodular-ui add field`
Free, MIT licensed.

Use when:
- Every form control that has a visible label.
- FieldSet and FieldLegend for a group of related controls, such as notification switches.
- orientation="responsive" for settings pages with the label column on the left.

Avoid:
- Wrapping a Field in another bordered box inside a card. Use FieldSeparator between sections.

Agent rules:
- Build every form control as Field > FieldLabel + control + FieldDescription or FieldError. Field links them, so skip id, htmlFor and aria-describedby for Base UI controls (Input, Textarea, Select, Combobox, Checkbox, RadioGroup, Switch, Slider).
- NativeSelect and InputOTP are not Base UI controls: give them an id and a matching FieldLabel htmlFor. Explicit ids also keep working for every other control.
- Show errors by setting invalid on Field and rendering FieldError with a sentence that says how to fix it. Replace the description with the error rather than showing both.
- Use orientation="horizontal" for checkboxes and switches. Put switches last and checkboxes first.
- Group fields with FieldGroup and separate sections with FieldSeparator, not with nested cards.
- Write descriptions as one short sentence about consequences (Old links redirect for 30 days), not a restatement of the label.

```tsx
<Field>
  <FieldLabel>Workspace name</FieldLabel>
  <Input defaultValue="Northbeam Studio" />
  <FieldDescription>Shown in the sidebar and on invoices.</FieldDescription>
  <FieldError>Enter a name.</FieldError>
</Field>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Field | orientation | `"vertical" \| "horizontal" \| "responsive"` | "vertical" | Stacked, inline, or inline from the @md container width. |
| Field | invalid | `boolean` |  | Marks the control invalid and shows FieldError. data-invalid also works. |
| Field | disabled | `boolean` |  | Disables the control and dims the label. data-disabled also works. |
| Field | validate | `(value) => string \| null` |  | Base UI validation. Return an error message or null. |
| FieldError | errors | `{ message?: string }[]` |  | Messages from a form library. Duplicates are removed. |
| FieldLegend | variant | `"legend" \| "label"` | "legend" | Section heading or label sized legend. |
| FieldLabel | htmlFor | `string` |  | Only needed for controls Field cannot link, such as NativeSelect. |

## File upload (file-upload)

A dropzone with drag-over state, click or keyboard to browse and type and size checks, plus a file list with type icons, progress, success and error states, remove and retry.

Install: `npx prodular-ui add file-upload`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Attaching documents to a record, importing a CSV, uploading a logo.
- The list on its own to show files that are already attached.

Avoid:
- Hiding the limits. Always say which types and how large in the hint.
- Removing failed files automatically. Keep them with a reason and a retry.

Agent rules:
- FileUpload validates and hands you files in onFilesAccepted; it does not upload. Keep your own list state with progress and status, and render a FileUploadItem per file.
- Set accept and maxSize, and repeat them in plain words in the dropzone hint, for example PDF or CSV, up to 10 MB.
- Show onFilesRejected messages near the dropzone in a role="alert" paragraph using text-destructive-subtle-foreground.
- Pass currentCount together with maxFiles so the limit counts files already in the list.
- On failure set status="error" with an error message that says what happened, and pass onRetry.
- Use multiple={false} and hide the dropzone after a pick for single-file flows.

```tsx
<FileUpload accept=".pdf,.csv" maxSize={10_000_000} onFilesAccepted={startUploads}>
  <FileUploadDropzone hint="PDF or CSV, up to 10 MB" />
  <FileUploadList>
    {files.map((f) => (
      <FileUploadItem key={f.id} name={f.name} size={f.size} progress={f.progress} status={f.status} onRemove={() => remove(f.id)} />
    ))}
  </FileUploadList>
</FileUpload>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| FileUpload | accept | `string` |  | Input accept syntax: ".pdf,.csv,image/*". |
| FileUpload | maxSize | `number` |  | Largest file in bytes. |
| FileUpload | maxFiles / currentCount | `number` |  | Total file limit and how many are already listed. |
| FileUpload | multiple | `boolean` | true | Allow several files per pick. |
| FileUpload | onFilesAccepted | `(files: File[]) => void` |  | Files that passed validation. |
| FileUpload | onFilesRejected | `(rejections: FileRejection[]) => void` |  | Each rejected file with reason and message. |
| FileUploadDropzone | hint / title / browseLabel | `ReactNode` |  | Copy inside the default dropzone. Pass children to replace it entirely. |
| FileUploadItem | status | `"queued" \| "uploading" \| "complete" \| "error"` | "queued" | Drives the icon, progress bar and meta text. |
| FileUploadItem | progress | `number` | 0 | 0 to 100 while uploading. |
| FileUploadItem | onRemove / onRetry | `() => void` |  | Show remove (or cancel while uploading) and retry on error. |

## Form (form)

Forms on React Hook Form and Zod: fields wired to labels and errors, conditional fields, an error summary, server errors per field, and autosave with a status line.

Install: `npx prodular-ui add form`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Any form with more than two fields, validation or server errors: settings, billing, onboarding, create and edit dialogs.
- autosave for settings pages where every field stands on its own; a submit button where changes only make sense together.

Avoid:
- One field edited in place. Use Inline edit.
- Autosave on forms that start something irreversible, like payments or invites. Submit those.

Agent rules:
- Define the schema with Zod and create the form with useAppForm(schema, { defaultValues }). Give every field a default value.
- Put fields that depend on another field in a z.discriminatedUnion and show them with FormWhen, so hidden fields are never validated.
- Render each control through FormField: spread field onto Input and Textarea; for Select, Switch, Number input and other value APIs map value and onChange by hand, and pass field.ref so the error summary can focus it.
- Return { errors: { field: message } } from onSubmit for server validation and { formError } for anything else. Do not show toasts for field errors.
- Put FormErrorSummary at the top of long forms and FormSubmit at the end. Write error messages that say how to fix the value.

```tsx
const form = useAppForm(schema, { defaultValues })

<Form form={form} onSubmit={save}>
  <FormErrorSummary />
  <FormField name="email" label="Billing email">
    {(field) => <Input {...field} type="email" />}
  </FormField>
  <FormWhen name="payment" is="invoice">
    <FormField name="po" label="PO number">{(field) => <Input {...field} />}</FormField>
  </FormWhen>
  <FormSubmit />
</Form>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| useAppForm | (schema, { defaultValues, mode }) | `UseFormReturn<T>` |  | React Hook Form with a Zod resolver. mode defaults to onTouched. |
| Form | form | `UseFormReturn<T>` |  | The form from useAppForm. |
| Form | onSubmit | `(values) => void \| { errors?, formError? }` |  | Runs with valid values. Return errors to show them on fields or for the whole form. |
| Form | autosave | `{ onSave(values), delay? }` |  | Saves valid changes after delay ms (800). Throw to show a retry. |
| FormField | name / label / description | `path / ReactNode / ReactNode` |  | The field's path in the values and its copy. The error replaces the description. |
| FormField | children | `(field, state) => ReactNode` |  | Renders the control. field has value, onChange, onBlur, ref, name and aria-invalid. |
| FormWhen | name / is / when | `path / value or values / (value) => boolean` |  | Shows its children while the watched field matches. |
| FormErrorSummary | title | `string` | "Fix these to continue" | Listed after a failed submit. Each item focuses its field. |
| FormStatus | - | `-` |  | Autosave state: saving, saved at a time, what to fix, or retry. |
| FormSubmit | ...props | `Button props` |  | Submit button with loading while onSubmit runs. |

## Inline edit (inline-edit)

Edit text, numbers, choices and dates where they are shown, with async saving, validation errors and a saved confirmation, without opening a form.

Install: `npx prodular-ui add inline-edit`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Detail panels and tables where people change one field at a time: owner, status, due date, a name.
- type select and date for fields with a fixed set of values; they save on choice, no confirm step.

Avoid:
- Several fields that must change together or be checked together. Use a form with a Save button.
- Long text. Use a Textarea in a form or a dedicated editor.

Agent rules:
- Always pass label naming the field (Due date, Account owner). It becomes the accessible name of the trigger and the field.
- Make onSave async and return a message string (or throw) when the server rejects the value; the field stays in edit mode and shows it.
- Only update your state after the save succeeds, inside onSave, so the shown value is always the saved one.
- Use validate for checks that need no server, like required text.
- Give empty fields a placeholder that invites action: Add a due date, Assign an owner.

```tsx
<InlineEdit
  type="select"
  label="Account owner"
  value={owner}
  options={owners}
  onSave={async (v) => { await api.update({ owner: v }); setOwner(v) }}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| InlineEdit | type | `"text" \| "number" \| "select" \| "date"` | "text" | Which editor opens. |
| InlineEdit | value | `string \| number \| Date \| null` |  | The saved value, matching the type. |
| InlineEdit | onSave | `(value) => void \| string \| Promise<void \| string>` |  | Persist the value. Return a message or throw to reject it. |
| InlineEdit | label | `string` |  | The field's name for assistive tech. |
| InlineEdit | placeholder | `string` |  | Shown when the value is empty. |
| InlineEdit | validate | `(value) => string \| null` |  | Text only. Client-side check before saving. |
| InlineEdit | min / max / step / format / unit / locale | `number props` |  | Number only. Passed to Number input. |
| InlineEdit | options | `{ value, label }[]` |  | Select only. |
| InlineEdit | locale / formatDate / disabledDates | `date props` |  | Date only. How the date reads and which days can be picked. |

## Input (input)

A single-line text field for names, emails, numbers and files, in three sizes that line up with Button.

Install: `npx prodular-ui add input`
Free, MIT licensed.

Use when:
- Short free text: names, emails, URLs, amounts, ids.
- Use size sm in dense toolbars and table filters, lg on sign-in and onboarding screens.

Avoid:
- Text that runs past one line. Use Textarea.
- Choosing from a known list. Use Select or Combobox.
- Placeholder text as the only label. It disappears as soon as someone types.

Agent rules:
- Wrap every input in Field with a FieldLabel. Field links the label, description and error to the input, so do not pass id or htmlFor by hand.
- Set type and autoComplete (email, current-password, one-time-code) so browsers and password managers can help.
- Mark errors with Field invalid plus a FieldError message. Do not color the input yourself.
- Match the size prop to the Button next to it: Input size sm with Button size sm.
- Use tabular-nums on inputs that hold amounts or counts.
- Use size="xs" on Input for dense toolbars and inspectors instead of overriding its height.

```tsx
<Field>
  <FieldLabel>Work email</FieldLabel>
  <Input type="email" placeholder="maya@northbeam.studio" />
  <FieldDescription>We send the sign-in link here.</FieldDescription>
</Field>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Input | size | `"xs" \| "sm" \| "default" \| "lg"` | "default" | Height and text size. 28, 32 or 36px at default density. |
| Input | type | `string` | "text" | Native input type. |
| Input | aria-invalid | `boolean` |  | Shows the error border and ring. Set automatically inside an invalid Field. |

## Input group (input-group)

An input with icons, text, keyboard hints or buttons attached inside the same border.

Install: `npx prodular-ui add input-group`
Free, MIT licensed.

Use when:
- A fixed prefix or suffix: a URL host, a currency, a unit.
- A search field with an icon or a keyboard shortcut.
- An inline action that belongs to the value, such as copy or show.

Avoid:
- Separate buttons that act on the whole form. Put them next to the group, or use ButtonGroup.

Agent rules:
- Use InputGroupInput, not Input, inside the group. It inherits the group size.
- Put addons in InputGroupAddon with align inline-start or inline-end. Text goes in InputGroupText.
- Icon-only InputGroupButton needs aria-label.
- Set size on InputGroup, not on the input.

```tsx
<InputGroup>
  <InputGroupAddon>
    <InputGroupText>tidewater.app/</InputGroupText>
  </InputGroupAddon>
  <InputGroupInput defaultValue="northbeam" />
</InputGroup>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| InputGroup | size | `"sm" \| "default" \| "lg"` | "default" | Height of the group and its input. |
| InputGroupAddon | align | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | "inline-start" | Where the addon sits. |
| InputGroupButton | size | `"xs" \| "sm" \| "icon-xs" \| "icon-sm"` | "xs" | Compact sizes that fit inside the group. |

## Input OTP (input-otp)

Enter a one-time code digit by digit, with paste and autofill support.

Install: `npx prodular-ui add input-otp`
Free, MIT licensed.

Use when:
- Verification and recovery codes of four to eight characters.

Avoid:
- Passwords or anything longer than eight characters. Use Input.

Agent rules:
- Set maxLength to the code length and render one InputOTPSlot per index.
- Use pattern={REGEXP_ONLY_DIGITS} from input-otp for numeric codes.
- Give InputOTP an id and pass it to FieldLabel htmlFor.
- Say where the code was sent in FieldDescription.

```tsx
<InputOTP maxLength={6}>
  <InputOTPGroup>
    <InputOTPSlot index={0} />
    <InputOTPSlot index={1} />
    <InputOTPSlot index={2} />
  </InputOTPGroup>
  <InputOTPSeparator />
  <InputOTPGroup>
    <InputOTPSlot index={3} />
    <InputOTPSlot index={4} />
    <InputOTPSlot index={5} />
  </InputOTPGroup>
</InputOTP>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| InputOTP | maxLength | `number` |  | Number of characters. |
| InputOTP | pattern | `string` |  | Allowed characters as a regular expression string. |
| InputOTPSlot | index | `number` |  | Which character this slot shows. |

## Label (label)

A text label for a form control. Inside forms, use FieldLabel, which links itself.

Install: `npx prodular-ui add label`
Free, MIT licensed.

Use when:
- Labelling a control outside a Field, for example in a toolbar or a custom layout.

Avoid:
- Labels inside forms built with Field. Use FieldLabel.

Agent rules:
- Always pass htmlFor matching the control id.
- Place Label right after a Checkbox or Switch so peer-disabled dims it.
- Labels are 14px medium and sentence case. Do not add uppercase or tracking.

```tsx
<Label htmlFor="company">Company name</Label>
<Input id="company" />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Label | htmlFor | `string` |  | The id of the control it labels. |

## Multi-select (multi-select)

Pick several values from a list as chips, with groups, descriptions, select all and options that load from a server as people type.

Install: `npx prodular-ui add multi-select`
Free, MIT licensed.

Use when:
- Choosing several items from a known set: people, customers, labels, channels, regions.
- loadOptions when the list is long or lives on the server.
- selectAll when picking everything is a real case, like notifying every team.

Avoid:
- Two to five options that all fit on screen. Use a Checkbox group, it is faster to scan.
- Free-form values people type, like email addresses. Use Tag input.

Agent rules:
- Give it a visible label with Field and FieldLabel, or aria-label.
- Keep values as stable ids and labels as display names. onValueChange returns ids.
- With loadOptions, honor the AbortSignal and return at most 20 results; ask people to type more instead of returning thousands.
- Set maxChips so the field stays one or two lines tall; the rest collapse into +N.
- Mark options people cannot pick as disabled and explain why in FieldDescription, do not hide them.

```tsx
<Field>
  <FieldLabel>Approvers</FieldLabel>
  <MultiSelect options={people} value={ids} onValueChange={setIds} selectAll />
</Field>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| MultiSelect | options | `{ value, label, description?, group?, icon?, disabled? }[]` |  | A fixed list, filtered as people type. Options with a group are listed under a heading. |
| MultiSelect | loadOptions | `(query, signal) => Promise<Option[]>` |  | Loads options for a query instead of options. |
| MultiSelect | value / defaultValue / onValueChange | `string[]` |  | Selected option values. |
| MultiSelect | maxChips | `number` | 3 | Chips shown before the rest collapse into +N. |
| MultiSelect | selectAll | `boolean` | false | Select all and Clear selection above the list. |
| MultiSelect | emptyText / placeholder | `string` |  | Copy for no matches and for an empty field. |
| MultiSelect | name | `string` |  | Renders one hidden input per value for form posts. |

## Native select (native-select)

The browser's own select element with the Prodular surface, for forms where the system picker works best.

Install: `npx prodular-ui add native-select`
Free, MIT licensed.

Use when:
- Mobile-heavy flows, where the operating system picker is faster.
- Plain HTML forms that post without JavaScript.

Avoid:
- Options with icons, descriptions or custom rendering. Use Select.

Agent rules:
- NativeSelect is not linked by Field automatically. Give it an id and pass the same value to FieldLabel htmlFor.
- className goes on the wrapper, so set width with className (w-full) and the select fills it.
- Use NativeSelectOptGroup with a label to group options.

```tsx
<NativeSelect id="format" defaultValue="csv">
  <NativeSelectOption value="csv">CSV</NativeSelectOption>
  <NativeSelectOption value="pdf">PDF report</NativeSelectOption>
</NativeSelect>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| NativeSelect | size | `"sm" \| "default" \| "lg"` | "default" | Height. Matches Button and Input. |
| NativeSelect | className | `string` |  | Applied to the wrapper. Use it for width. |

## Number input (number-input)

A numeric field with steppers, units, precision and locale formatting, that steps with the arrow keys and can be scrubbed by dragging its label.

Install: `npx prodular-ui add number-input`
Free, MIT licensed.

Use when:
- Quantities, limits, percentages and durations: anything people type as a number and sometimes nudge up or down.
- steppers split for small counts people adjust by one, end for compact forms, none when values are usually typed.
- unit for what the number means (%, ms, seats). It is never part of the value.

Avoid:
- Money. Use Amount input, which takes decimals and the symbol from the currency.
- Identifiers that only look numeric, like phone numbers, postcodes or card numbers. Use Input.

Agent rules:
- Always give the field a name people can read: wrap it in Field with FieldLabel, or pass aria-label.
- Set min and max whenever the backend has limits, and step to the real increment. Do not validate ranges yourself after the fact.
- Set precision with format (maximumFractionDigits), not by rounding in onValueChange.
- Use onValueChange for live updates and onValueCommitted to save, so a request is not sent on every keystroke.
- The value can be null when the field is empty. Handle it.

```tsx
<Field>
  <FieldLabel>Seats</FieldLabel>
  <NumberInput value={seats} onValueChange={setSeats} min={1} max={500} />
</Field>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| NumberInput | value / defaultValue / onValueChange | `number \| null` |  | Controlled or uncontrolled value. Null when empty. |
| NumberInput | min / max | `number` |  | Clamp the value and disable the steppers at the limits. |
| NumberInput | step / smallStep / largeStep | `number` | 1 / 0.1 / 10 | Arrow keys step by step, with Alt by smallStep and with Shift by largeStep. |
| NumberInput | format | `Intl.NumberFormatOptions` |  | Precision and style, for example { maximumFractionDigits: 1 }. |
| NumberInput | locale | `string` |  | Grouping and decimal marks, for example de-DE. |
| NumberInput | steppers | `"split" \| "end" \| "none"` | "split" | Where the minus and plus controls sit. |
| NumberInput | unit / prefix | `ReactNode` |  | Shown after or before the number, outside the value. |
| NumberInput | scrubLabel | `ReactNode` |  | A label that changes the value when dragged horizontally. |
| NumberInput | onValueCommitted | `(value) => void` |  | Fires on blur, Enter or a finished stepper press. Save here. |
| NumberInput | size | `"sm" \| "default" \| "lg"` | "default" | Height. Matches Input and Button sizes. |

## Password input (password-input)

A password field with a show and hide toggle and a Caps Lock hint, plus a strength meter and a requirements checklist for choosing a new password.

Install: `npx prodular-ui add password-input`
Free, MIT licensed.

Use when:
- Every password field. The toggle cuts typos, the Caps Lock hint cuts failed sign ins.
- PasswordStrength and PasswordRequirements together when people set a new password.

Avoid:
- Strength or requirements on a sign in form. They only make sense when choosing a password.
- Treating scorePassword as a security check. It is a hint; enforce rules on the server.

Agent rules:
- Set autoComplete="new-password" on sign up and change password forms, keep the default current-password on sign in.
- Pass requirements that match the backend's real rules, and disable submit until they are all met.
- Do not add a second confirm password field; the visibility toggle replaces it.
- Label the field with Field and FieldLabel. Put server errors in FieldDescription and set aria-invalid on the input.

```tsx
<Field>
  <FieldLabel>New password</FieldLabel>
  <PasswordInput autoComplete="new-password" value={pw} onChange={(e) => setPw(e.target.value)} />
  <PasswordStrength value={pw} />
</Field>
<PasswordRequirements value={pw} />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| PasswordInput | defaultVisible | `boolean` | false | Start with the password shown. |
| PasswordInput | autoComplete | `string` | "current-password" | Use new-password when people choose one. |
| PasswordInput | ...props | `Input props` |  | value, onChange, name, size and the rest pass to the input. |
| PasswordStrength | value | `string` |  | The password to score. |
| PasswordStrength | score | `0 \| 1 \| 2 \| 3 \| 4` |  | Your own estimate, for example from zxcvbn. Overrides the built-in score. |
| PasswordRequirements | value / requirements | `string / { id, label, test }[]` |  | Rules to tick off. Defaults to length, case, number and symbol. |

## Plan picker (plan-picker)

Picks a plan, seats and a billing period, with a summary of the price, what is due today, and whether the change is an upgrade or a downgrade. Prices and proration come from your billing backend.

Install: `npx prodular-ui add plan-picker`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Billing settings where people change plan, seats or period, and in-app checkout.
- proration from your billing provider's preview endpoint, so Due today matches the invoice.
- seatsInUse so nobody buys fewer seats than people who already sign in.

Avoid:
- Marketing pricing pages. Use the pricing block, which sells; this one changes a subscription.
- Working out proration in the browser for real charges. Show what the backend returns.

Agent rules:
- Prices are per seat per month for each period; yearly is billed as twelve months.
- Keep the selection in state and, when it changes, fetch a proration preview from the billing provider (for example Stripe or Polar upcoming invoice) and pass it with prorationLoading while it loads.
- Pass current for existing subscriptions. The button says Upgrade, Downgrade, Switch or Update, and is disabled when nothing changed.
- Downgrades that wait for renewal return effective "period_end" and nextInvoice; the summary explains when the change happens.
- Throw from onConfirm with a clear message on payment failures; nothing else changes.

```tsx
<PlanPicker
  plans={plans}
  value={selection}
  onValueChange={setSelection}
  current={subscription}
  seatsInUse={members.length}
  proration={preview}
  onConfirm={changePlan}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| PlanPicker | plans | `PricingPlan[]` |  | { id, name, description?, price: { monthly, yearly }, badge?, features?, minSeats?, maxSeats? }. A null price means talk to sales. |
| PlanPicker | value / onValueChange | `{ planId, seats, period }` |  | The selection, controlled. |
| PlanPicker | current | `PlanSelection` |  | The subscription today. |
| PlanPicker | seatsInUse | `number` | 0 | Minimum seats. |
| PlanPicker | proration / prorationLoading | `{ credit?, dueToday, nextInvoice?, effective? } / boolean` |  | What the change costs today. |
| PlanPicker | onConfirm / onContactSales | `(value) => Promise<void> / (plan) => void` |  | Applies the change, or contacts sales for custom plans. |
| PlanPicker | currency / locale / timeZone | `string` | "USD" / "en-US" | Formatting. |
| PlanPicker | yearlyNote | `string` |  | Beside the period switch, like Save 17%. |

## Radio group (radio-group)

Pick exactly one option from a small set that people should see side by side, as a list or as choice cards.

Install: `npx prodular-ui add radio-group`
Free, MIT licensed.

Use when:
- Two to five options people should compare before choosing: plans, frequencies, visibility.

Avoid:
- More than six options. Use Select.
- A single yes or no. Use Checkbox or Switch.

Agent rules:
- Always set defaultValue or value. A radio group with nothing selected is hard to undo.
- Wrap each RadioGroupItem and its FieldLabel in Field orientation="horizontal". Field links them, so ids are optional.
- Label the group with FieldSet and FieldLegend variant="label".
- For choice cards, put Field orientation="horizontal" inside FieldLabel, with FieldContent first and the item last.

```tsx
<RadioGroup defaultValue="hourly">
  <Field orientation="horizontal">
    <RadioGroupItem value="hourly" />
    <FieldLabel>Hourly digest</FieldLabel>
  </Field>
</RadioGroup>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| RadioGroup | value / defaultValue | `unknown` |  | Controlled or initial selection. |
| RadioGroup | onValueChange | `(value) => void` |  | Called when the selection changes. |
| RadioGroupItem | value | `unknown` |  | The value this item selects. |

## Rich text editor (rich-text-editor)

A Tiptap editor with headings, lists, quotes, code, links and tables, a toolbar, a slash menu, a selection menu, and AI editing that streams a rewrite as a diff before it replaces anything.

Install: `npx prodular-ui add rich-text-editor`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Long form text people format: notes, descriptions, policies, emails, comments.
- ai when the product has a model and people edit prose: rewrite, shorten, change tone, translate, or draft at the cursor.

Avoid:
- Short plain fields like a title or a name. Use Input.
- Code. Use a code editor; the code block here is for snippets inside prose.

Agent rules:
- Store the HTML from onChange, and sanitize it on the server before rendering it anywhere else.
- Give it aria-label describing the document (Month end notes, Reply).
- For ai, implement onRun as an async generator that reads your model route's text stream and yields chunks. Pass the AbortSignal to fetch. With the AI SDK, return result.toTextStreamResponse() from the route.
- Never apply AI output without the review step: the editor shows a diff and only changes the document on Replace or Insert.
- Use toolbar={false} for comments and replies; keep the toolbar for documents.

```tsx
<RichTextEditor
  value={html}
  onChange={setHtml}
  aria-label="Policy"
  ai={{
    onRun: async function* (request, signal) {
      const res = await fetch("/api/edit", { method: "POST", body: JSON.stringify(request), signal })
      const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader()
      for (;;) { const { value, done } = await reader.read(); if (done) return; yield value }
    },
  }}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| RichTextEditor | value / defaultValue / onChange | `string (HTML)` |  | Controlled or uncontrolled content. |
| RichTextEditor | placeholder | `string` | "Write, or press / for blocks" | Shown in an empty document. |
| RichTextEditor | toolbar | `boolean` | true | Hide the toolbar for compact uses. |
| RichTextEditor | editable | `boolean` | true | Read only when false. |
| RichTextEditor | minHeight | `number` | 180 | Minimum height of the writing area in px. |
| RichTextEditor | ai.onRun | `(request, signal) => AsyncIterable<string> \| Promise<string>` |  | request has action (improve, fix, shorter, longer, tone, translate, custom, write), option, prompt, text and context. |
| RichTextEditor | ai.tones / ai.languages | `string[]` |  | Choices under Change tone and Translate. |

## Search input (search-input)

A search field with a clear button, a global keyboard shortcut, a loading state and recent searches while it is empty.

Install: `npx prodular-ui add search-input`
Free, MIT licensed.

Use when:
- Searching a list, a table or the whole product.
- shortcut on the one main search of a page, so keyboard users can reach it from anywhere.
- recent when people repeat searches, like customer names or invoice numbers.

Avoid:
- Two inputs on one page with the same shortcut.
- Picking a value for a form. Use Combobox, which keeps the choice.

Agent rules:
- Give it aria-label (or a visible label) that says what is searched, for example Search invoices.
- Use onValueChange for search as you type, debounced, and set loading while the request is in flight.
- Use onSearch for searches that run on Enter, and add the term to recent there.
- Keep recent to five or fewer items, newest first, and offer onClearRecent.

```tsx
<SearchInput
  aria-label="Search invoices"
  value={query}
  onValueChange={setQuery}
  onSearch={run}
  shortcut="/"
  recent={recent}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| SearchInput | value / defaultValue / onValueChange | `string` |  | Controlled or uncontrolled text. |
| SearchInput | onSearch | `(value) => void` |  | Enter, or picking a recent search. |
| SearchInput | shortcut | `"/" \| "mod+k"` |  | Focuses the field from anywhere. Shows a key hint while empty. |
| SearchInput | recent / onClearRecent | `string[] / () => void` |  | Recent searches shown while focused and empty. |
| SearchInput | loading | `boolean` | false | Shows a spinner in place of the search icon. |
| SearchInput | size | `"sm" \| "default" \| "lg"` | "default" | Height. Matches Input sizes. |

## Select (select)

Choose one option from a short list in a popup, styled to match the rest of the form.

Install: `npx prodular-ui add select`
Free, MIT licensed.

Use when:
- Five to fifteen known options where only one can apply: role, timezone, status, date range.

Avoid:
- Two or three options that people should compare. Use RadioGroup.
- Long or searchable lists such as people or countries. Use Combobox.
- Mobile-first forms where the system picker is better. Use NativeSelect.

Agent rules:
- Pass the options to Select as items={[{ label, value }]} so SelectValue shows the label, not the raw value.
- Use SelectValue placeholder for the empty state. Do not add a fake first option.
- Give the trigger a width (w-full inside forms, a fixed width in toolbars) so it does not jump when the value changes.
- Inside Field the label is linked automatically. Outside Field, add aria-label to SelectTrigger.
- Match SelectTrigger size to nearby Buttons and Inputs.
- Use size="xs" on SelectTrigger for dense toolbars and inspectors instead of overriding its height.

```tsx
<Select items={roles} defaultValue="member">
  <SelectTrigger className="w-full">
    <SelectValue />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="member">Member</SelectItem>
  </SelectContent>
</Select>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Select | items | `{ label: ReactNode; value: unknown }[]` |  | Options used to render the selected label. |
| Select | value / defaultValue | `unknown` |  | Controlled or initial value. |
| Select | onValueChange | `(value) => void` |  | Called when the selection changes. |
| SelectTrigger | size | `"xs" \| "sm" \| "default" \| "lg"` | "default" | Height. Matches Button and Input. |
| SelectContent | alignItemWithTrigger | `boolean` | true | Overlays the selected item on the trigger. Set false to open below it. |

## Slider (slider)

Pick a value or a range by dragging, for settings where the rough position matters more than the exact number.

Install: `npx prodular-ui add slider`
Free, MIT licensed.

Use when:
- Bounded values that people adjust by feel: retention, thresholds, volume, price ranges.

Avoid:
- Exact values such as a price or a quantity. Use Input type="number".
- Unbounded values.

Agent rules:
- Pass a number for one thumb or an array of two numbers for a range.
- Always show the current value as text next to the label, with tabular-nums and the unit.
- Set min, max and step to real units (days, ms), never 0 to 100 by default.
- Inside Field the label is linked automatically. Outside Field, add aria-label.

```tsx
<Field>
  <FieldLabel>Log retention</FieldLabel>
  <Slider defaultValue={30} min={7} max={90} />
</Field>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Slider | value / defaultValue | `number \| number[]` |  | One number for a single thumb, two for a range. |
| Slider | onValueChange | `(value: number \| number[]) => void` |  | Called while dragging. |
| Slider | min / max / step | `number` | 0 / 100 / 1 | Bounds and increment. |
| Slider | orientation | `"horizontal" \| "vertical"` | "horizontal" | Direction of the track. |

## Switch (switch)

Turns a setting on or off immediately, like a light switch.

Install: `npx prodular-ui add switch`
Free, MIT licensed.

Use when:
- Settings that take effect as soon as they change, with no save button.

Avoid:
- Choices inside a form that is saved later. Use Checkbox.
- Labels that describe both states (On or off). Name the setting instead.

Agent rules:
- Place it in Field orientation="horizontal" with FieldContent (label and description) first and the Switch last, so switches line up on the right.
- Save the change right away and show a toast if it fails. Do not wait for a submit button.
- Use size sm only in dense tables and toolbars.

```tsx
<Field orientation="horizontal">
  <FieldContent>
    <FieldLabel>Auto-assign new tickets</FieldLabel>
    <FieldDescription>Round robin across agents who are online.</FieldDescription>
  </FieldContent>
  <Switch defaultChecked />
</Field>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Switch | checked / defaultChecked | `boolean` |  | Controlled or initial state. |
| Switch | onCheckedChange | `(checked: boolean) => void` |  | Called when toggled. |
| Switch | size | `"sm" \| "default"` | "default" | Track size. |

## Tag input (tag-input)

A multi-value text input that turns entries into removable chips, with keyboard support, a suggestions list, a maximum count and validation.

Install: `npx prodular-ui add tag-input`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Free-form lists of short values: email recipients, labels, allowed domains, keywords.
- suggestions when there is a known vocabulary, with restrictToSuggestions when only those values are valid.

Avoid:
- Picking from a short fixed list. Use a multi-select combobox or checkboxes.
- Long values like sentences. Chips truncate.

Agent rules:
- Always connect a visible label with id, and describe the delimiters in helper text linked with aria-describedby.
- Validate with validate and return a plain-language message. Rejected entries stay in the input so people can fix them.
- Normalize with transform (trim, lowercase) instead of post-processing onValueChange.
- Set max when the backend has a limit; the input shows a counter and disables itself at the limit.
- Pass name to submit with a native form. One hidden input is rendered per tag.

```tsx
<label htmlFor="emails">Invite teammates</label>
<TagInput
  id="emails"
  value={emails}
  onValueChange={setEmails}
  max={8}
  validate={(t) => (isEmail(t) ? null : `${t} is not a valid email address.`)}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| TagInput | value / defaultValue / onValueChange | `string[]` |  | Controlled or uncontrolled list of tags. |
| TagInput | suggestions | `string[]` |  | Shown in a listbox that filters as people type. |
| TagInput | restrictToSuggestions | `boolean` | false | Reject values that are not in suggestions. |
| TagInput | max | `number` |  | Maximum number of tags. Shows a counter. |
| TagInput | validate | `(tag, tags) => string \| null` |  | Return a message to reject the tag. |
| TagInput | transform | `(tag) => string` | trim | Normalizes each tag before validation. |
| TagInput | delimiters | `string[]` | ["Enter", ","] | Keys that commit the typed text. |
| TagInput | allowDuplicates | `boolean` | false | Duplicates are compared case-insensitively. |
| TagInput | name | `string` |  | Renders hidden inputs for form posts. |

## Textarea (textarea)

A multi-line text field that grows with its content, for notes, descriptions and messages.

Install: `npx prodular-ui add textarea`
Free, MIT licensed.

Use when:
- Text that can run to several sentences: descriptions, release notes, feedback, welcome messages.

Avoid:
- Single values like a name or a title. Use Input.
- Rich text editing. Textarea is plain text only.

Agent rules:
- Wrap it in Field with a FieldLabel. The label and description are linked automatically.
- It grows with its content through field-sizing. Set a max height with className (for example max-h-64) when the text can get long.
- Say in FieldDescription if Markdown or a character limit applies.

```tsx
<Field>
  <FieldLabel>Release notes</FieldLabel>
  <Textarea placeholder="What changed in this release?" />
</Field>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Textarea | rows | `number` |  | Initial visible rows in browsers without field-sizing support. |
| Textarea | aria-invalid | `boolean` |  | Error border and ring. Set automatically inside an invalid Field. |

## Time picker (time-picker)

A time field that understands what people type, offers a list of times at a fixed step and follows the locale's 12 or 24 hour clock.

Install: `npx prodular-ui add time-picker`
Free, MIT licensed.

Use when:
- Picking a time of day: meetings, schedules, cut-offs, reminders.
- step to match how precise the time needs to be: 15 or 30 minutes for meetings, 5 for reminders.

Avoid:
- Durations like 45 minutes. Use Number input with a unit.
- A time that always comes with a date. Put a Calendar and the Time picker side by side in one Field group.

Agent rules:
- Store and pass the value as 24 hour "HH:mm". Only the display follows the locale.
- Pass the user's locale, and hourCycle only when the product overrides it.
- Set min and max for business hours; typed times outside them are marked invalid instead of being clamped silently.
- For a start and end pair, check end after start yourself and show the message in FieldDescription with aria-invalid on the end field.
- Time zones are not part of the value. Show the zone next to the field when it is not the user's own.

```tsx
<Field>
  <FieldLabel>Starts</FieldLabel>
  <TimePicker value={start} onValueChange={setStart} step={15} min="07:00" max="20:00" />
</Field>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| TimePicker | value / defaultValue / onValueChange | `string \| null` |  | 24 hour "HH:mm". Null when empty. |
| TimePicker | step | `number` | 15 | Minutes between listed times, and the arrow key step. |
| TimePicker | min / max | `"HH:mm"` | "00:00" / "23:59" | The range offered and accepted. |
| TimePicker | hourCycle | `12 \| 24` |  | Defaults to the locale. |
| TimePicker | locale | `string` |  | Formats the display, for example en-US or en-GB. |
| TimePicker | name | `string` |  | Renders a hidden input with the HH:mm value for form posts. |
| parseTime | (text, hourCycle) | `number \| null` |  | The parser the field uses, returning minutes after midnight. |

## Toggle (toggle)

A button that stays pressed, for turning a view option or a format on and off.

Install: `npx prodular-ui add toggle`
Free, MIT licensed.

Use when:
- Editor formatting (bold, italic) and view options (pin, star) that are either on or off.

Avoid:
- Saved settings. Use Switch.
- Choosing one of several views. Use ToggleGroup.

Agent rules:
- Icon-only toggles need aria-label naming the action (Bold), not the state.
- Use defaultPressed or pressed with onPressedChange. Do not swap the variant to show state.
- Mark icons with data-icon when there is a text label.
- Use size="xs" on Toggle for dense toolbars and inspectors instead of overriding its height.

```tsx
<Toggle aria-label="Bold">
  <BoldIcon />
</Toggle>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Toggle | variant | `"default" \| "outline"` | "default" | Ghost or bordered. |
| Toggle | size | `"xs" \| "sm" \| "default" \| "lg"` | "default" | Height. Matches Button. |
| Toggle | pressed / defaultPressed | `boolean` |  | Controlled or initial state. |
| Toggle | onPressedChange | `(pressed: boolean) => void` |  | Called when toggled. |

## Toggle group (toggle-group)

A set of toggles where one or several can be pressed. With spacing 0 and the outline variant it is a segmented control.

Install: `npx prodular-ui add toggle-group`
Free, MIT licensed.

Use when:
- Switching views (list, board, calendar) or ranges (7, 30, 90 days) in place.
- Formatting groups where several can be on.

Avoid:
- More than five options. Use Select.
- Navigation between pages. Use Tabs or links.

Agent rules:
- The value is always an array, even for single selection. Read value[0].
- For a segmented control use variant="outline" spacing={0} and ignore empty changes so one option stays pressed.
- Pass multiple when several items can be pressed at once.
- Give the group an aria-label and icon-only items their own aria-label.

```tsx
<ToggleGroup variant="outline" spacing={0} defaultValue={["board"]}>
  <ToggleGroupItem value="list">List</ToggleGroupItem>
  <ToggleGroupItem value="board">Board</ToggleGroupItem>
</ToggleGroup>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ToggleGroup | value / defaultValue | `string[]` |  | Pressed items. |
| ToggleGroup | onValueChange | `(value: string[]) => void` |  | Called when the pressed items change. |
| ToggleGroup | multiple | `boolean` | false | Allows several pressed items. |
| ToggleGroup | spacing | `number` | 2 | Gap on the spacing scale. 0 joins the items. |
| ToggleGroup | variant / size | `"default" \| "outline" / "sm" \| "default" \| "lg"` |  | Applied to every item. |
| ToggleGroup | orientation | `"horizontal" \| "vertical"` | "horizontal" | Direction of the items. |

## API keys (api-keys)

API keys for a workspace: create with scopes and an expiry, see the secret once, rotate and revoke with confirmation, and see when and where each key was last used. Every change goes through your callbacks.

Install: `npx prodular-ui add api-keys`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Developer settings where customers create keys for their own integrations.
- One key per service, with only the scopes it needs, so one can be rotated without touching the rest.
- Expiry by default; never only when people choose it on purpose.

Avoid:
- Showing or storing the full secret after creation. The list only ever shows the prefix.
- Personal access tokens with sign in semantics. Those belong in the account security page.

Agent rules:
- Store only a hash of the secret and its prefix on the server. onCreate and onRotate return { key, secret } once; never return the secret again.
- Pass keys as { id, name, prefix, scopes, createdAt, createdBy?, expiresAt?, lastUsedAt?, lastUsedFrom? } and scopes as { id, label, description?, group? }.
- Throw from onCreate, onRotate or onRevoke to show the error in the dialog; the dialog stays open.
- Rotate replaces the secret at once. If you support a grace period, say so in your own docs and keep the old hash valid server side.
- Pass now and timeZone in tests and demos so expiry warnings and relative times are stable.

```tsx
<ApiKeysManager
  keys={keys}
  scopes={scopes}
  onCreate={createKey}
  onRotate={rotateKey}
  onRevoke={revokeKey}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ApiKeysManager | keys / scopes | `ApiKey[] / ApiScope[]` |  | Existing keys and the scopes people can grant. |
| ApiKeysManager | onCreate | `(input: { name, scopes, expiresInDays }) => Promise<{ key, secret }>` |  | Creates a key. The secret shows once. |
| ApiKeysManager | onRotate | `(key) => Promise<{ key, secret }>` |  | Replaces a key's secret. |
| ApiKeysManager | onRevoke | `(key) => Promise<void>` |  | Revokes after typing the key name. |
| ApiKeysManager | expiryOptions | `(number \| null)[]` | [30, 90, 365, null] | Days a new key lasts; null never expires. |
| ApiKeysManager | defaultScopes | `string[]` | [] | Ticked when the create dialog opens. |
| ApiKeysManager | now / timeZone | `Date / string` |  | Clock and zone for dates and warnings. |

## Audit log (audit-log)

Who did what, to which record, and when. Events group by day and expand to their before and after values and request context; filter by actor, record type and time, and search across everything.

Install: `npx prodular-ui add audit-log`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Security, compliance and admin pages: role changes, key creation, exports, sign ins and settings.
- A record's own history, filtered to that resource.
- Agent actions, with the approval that allowed them in metadata.

Avoid:
- Activity feeds for collaboration. Use Timeline with comments and attachments.
- Application logs and errors. They need levels and streaming, not actors and records.

Agent rules:
- Map each server event to { id, action, actor, resource, at, changes?, ip?, location?, userAgent?, metadata?, severity? }. Keep action dotted, like invoice.updated.
- The sentence is built from actor, the last part of action and the resource; pass summary only when that reads wrong.
- Record changes as { field, before, after } with display values, not raw ids.
- For large logs, page on the server: pass onLoadMore and hasMore and append events. Otherwise pageSize reveals more rows locally.
- Pass timeZone="UTC" for compliance views and a fixed now in tests so relative ranges stay stable.
- Mark security relevant events with severity warning or critical. Never put secrets in metadata.

```tsx
<AuditLog
  events={events}
  onLoadMore={loadOlder}
  hasMore={cursor !== null}
  timeZone="UTC"
  actions={<Button variant="outline" size="sm">Export</Button>}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AuditLog | events | `AuditEvent[]` |  | Events in any order; they sort newest first. |
| AuditLog | pageSize | `number` | 25 | Rows before Show more, when everything is loaded. |
| AuditLog | onLoadMore / hasMore | `() => Promise<void> / boolean` |  | Server paging. Load older events calls onLoadMore. |
| AuditLog | loading | `boolean` | false | Skeleton rows. |
| AuditLog | now / timeZone | `Date / string` |  | The clock for ranges and the zone for times and days. |
| AuditLog | actions | `ReactNode` |  | Right side of the toolbar, like Export. |

## Avatar (avatar)

A person or workspace image with an initials fallback, four sizes, a presence dot and overlapping groups.

Install: `npx prodular-ui add avatar`
Free, MIT licensed.

Use when:
- Show who owns, created or is assigned to something.
- Use AvatarGroup to show who has access or who is viewing, capped at four or five faces.
- Use AvatarStatus where presence changes what people do next, such as assigning a ticket.

Avoid:
- Avatars as the only label for a person. Show the name next to it, or in a tooltip.
- Presence dots on lists where presence is not live.
- Groups of more than five avatars. Show four and a count.

Agent rules:
- Always include AvatarFallback with one or two initials. Use one initial at size xs.
- Give AvatarImage an alt with the person's full name.
- Set size on AvatarGroup, not on each Avatar inside it.
- End a group with AvatarGroupCount, labeled with aria-label, for example aria-label="3 more members".
- Map presence with AvatarStatus status: online, away, busy, offline. Do not draw your own dot.
- On a surface that is not a card, set [--avatar-ring:var(--color-background)] on a parent so the rings match the background.

```tsx
<Avatar>
  <AvatarImage src="/maya.jpg" alt="Maya Okafor" />
  <AvatarFallback>MO</AvatarFallback>
  <AvatarStatus status="online" />
</Avatar>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Avatar | size | `"xs" \| "sm" \| "default" \| "lg"` | "default" | 20, 24, 32 or 40px. Inherits from AvatarGroup. |
| AvatarGroup | size | `"xs" \| "sm" \| "default" \| "lg"` |  | Size for every avatar and the count in the group. |
| AvatarStatus | status | `"online" \| "away" \| "busy" \| "offline"` |  | Presence. Colored with success, warning, destructive or gray. |
| AvatarStatus | label | `string` |  | Accessible label. Defaults to the status name. |
| AvatarBadge | children | `ReactNode` |  | A small primary badge at the bottom right, optionally with an icon. |

## Badge (badge)

A compact label for status, counts and metadata, with tinted status variants, a status dot and an AI variant.

Install: `npx prodular-ui add badge`
Free, MIT licensed.

Use when:
- Show the state of a record: Paid, Past due, Failed, Live.
- Show short metadata next to a title: a version, a plan, a count.
- Use the ai variant on content a model wrote or suggested, so people can tell it apart from their own.

Avoid:
- Badges as buttons. If clicking it does something, use a Button or a Toggle.
- More than one or two badges per row in a table. Pick the one that matters.
- default (solid) badges for status. Solid fills are loud. Keep them for one highlighted label, such as a plan name.

Agent rules:
- Map status to variant consistently: success for completed or healthy, warning for needs attention, destructive for failed or blocked, info for scheduled or neutral system states.
- Use BadgeDot for live or ongoing states (Operational, Building). Add pulse only while the state is actively changing.
- Inside outline or secondary badges, set BadgeDot status to color the dot. Never color the badge text yourself.
- Use size="sm" inside table cells and next to 14px text. Use the default size next to headings.
- Keep badge text to one or two words in sentence case. No uppercase.
- Use the ai variant only for model output, never for features that merely mention AI.

```tsx
<Badge variant="success">
  <BadgeDot />
  Operational
</Badge>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Badge | variant | `"default" \| "secondary" \| "outline" \| "ghost" \| "link" \| "success" \| "warning" \| "info" \| "destructive" \| "ai"` | "default" | Visual style. Status variants are tinted. |
| Badge | size | `"sm" \| "default"` | "default" | Height: 20px or 24px. |
| Badge | render | `ReactElement` |  | Renders the badge as another element, for example a link. |
| BadgeDot | status | `"success" \| "warning" \| "info" \| "destructive" \| "ai" \| "neutral"` |  | Dot color. Defaults to the badge variant color. |
| BadgeDot | pulse | `boolean` | false | Adds a pulsing ring for live states. Hidden with reduced motion. |

## Bar list (bar-list)

Ranked horizontal bars with the label on the bar and the value on the right. For top sources, pages, countries or customers.

Install: `npx prodular-ui add bar-list`
Free, MIT licensed.

Use when:
- Rankings of one measure across many categories: top pages, sources, countries, customers.
- Next to a chart in a dashboard card, for the breakdown behind a headline number.
- onValueChange when picking a row filters the rest of the page.

Avoid:
- Values over time. Use Chart with an area or line.
- Comparing two measures per row. Use a table or a grouped bar chart.
- Negative values. Bars grow from the left only.

Agent rules:
- Pass data as { name, value }[] and let sortOrder sort it. Keep sortOrder="none" only when the order means something, like funnel steps.
- Format values with valueFormatter (currency, percentages), never by passing strings as value.
- Use limit={5} for long lists so the card keeps its height. Show more expands in place.
- Set color to a chart token, var(--chart-N), never a hex value.
- Show loading while data is fetched and pass empty with a sentence that names the period.

```tsx
<BarList
  data={[{ name: "Google search", value: 18420 }]}
  label="Source"
  valueLabel="Visitors"
  limit={5}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| BarList | data | `{ name, value, key?, href?, icon?, color? }[]` |  | Rows. The longest bar is the largest value. |
| BarList | valueFormatter | `(value: number) => ReactNode` |  | Formats the value on the right. |
| BarList | sortOrder | `"descending" \| "ascending" \| "none"` | "descending" | How rows are ordered. |
| BarList | showShare | `boolean` | false | Adds each value's percent of the total. |
| BarList | limit | `number` |  | Rows shown before Show more. |
| BarList | onValueChange | `(item) => void` |  | Makes rows buttons. |
| BarList | activeKey | `string` |  | Key of the selected row. |
| BarList | color | `string` | "var(--chart-1)" | Bar color for every row. |
| BarList | loading | `boolean` | false | Shows skeleton bars. |
| BarList | label / valueLabel | `ReactNode` |  | Column headers over labels and values. |

## Carousel (carousel)

A horizontal slider for a small set of cards or previews, with arrow buttons, dots and keyboard support.

Install: `npx prodular-ui add carousel`
Free, MIT licensed.

Use when:
- A short set of optional, browsable items: templates, release notes, onboarding tips.
- Previews where seeing a few at once is enough.

Avoid:
- Content people must see. Items after the first are easy to miss.
- More than about ten items. Use a grid or a list.
- Autoplay. It moves content away while people read.

Agent rules:
- Always include CarouselPrevious and CarouselNext. They sit outside the content, so leave about 48px of space on each side.
- Add CarouselDots when there are fewer than ten slides.
- For several items per view, set className="basis-1/2 sm:basis-1/3" on CarouselItem and opts={{ align: "start" }} on Carousel.
- Make slides the same height. Use h-full on the slide content.
- Do not add autoplay plugins unless the user asks for them.

```tsx
<Carousel>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
  <CarouselDots />
</Carousel>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Carousel | opts | `EmblaOptionsType` |  | Embla options such as align and loop. |
| Carousel | orientation | `"horizontal" \| "vertical"` | "horizontal" | Scroll direction. |
| Carousel | setApi | `(api: CarouselApi) => void` |  | Receives the Embla API for custom controls. |
| CarouselItem | className | `string` |  | Set basis-* to show several items per view. |
| CarouselDots | className | `string` |  | One dot per snap point. Hidden when there is only one. |

## Chart (chart)

A themed wrapper for Recharts: series colors from the chart tokens, hairline grids, 12px muted axes, a popover tooltip, and built-in loading and empty states.

Install: `npx prodular-ui add chart`
Free, MIT licensed.

Use when:
- Trends over time: area for one cumulative metric, lines for comparing two or three series.
- Composition over time: stacked bars for parts of a total, such as seats by plan.
- Put every chart in a Card with the metric name and the current value in the header.
- Horizontal bars when category names are long or there are more than six categories.
- A combo chart only when the two measures explain each other, like amount and rate.

Avoid:
- More than five series. Group the rest into Other.
- Pie charts for more than three parts. Use a stacked bar.
- Raw colors in series. Use var(--chart-N) or leave color out of the config.
- A spinner or blank card while data loads. Use loading so the layout does not jump.
- Two axes for measures that share a unit. Put them on one axis.

Agent rules:
- Wrap every Recharts chart in ChartContainer with a config. Reference series colors as var(--color-<key>), never as hex or Tailwind palette colors.
- Leave color out of the config to get the theme chart tokens in order, or set color: "var(--chart-2)" to pick one.
- Give ChartContainer an explicit height: className="aspect-auto h-64 w-full".
- Use <CartesianGrid vertical={false} /> and hide axis and tick lines (axisLine={false} tickLine={false}).
- Format axis ticks short ($40k, 200 ms) with tickFormatter and tooltip values in full with valueFormatter on ChartTooltipContent.
- Add ChartLegend with ChartLegendContent when there are two or more series.
- Use a linearGradient from the series color at 0.28 opacity to 0 for area fills. Give each gradient a unique id.
- While fetching, pass loading (bars) or loading="line" to ChartContainer and keep the chart children; they render once loading is false.
- When the query returns no rows, pass empty, or a node with your own sentence, instead of rendering an empty chart.
- For progress toward targets use RadialBarChart with PolarAngleAxis domain [0, 100] and background on RadialBar.

```tsx
const config = { mrr: { label: "MRR" } } satisfies ChartConfig

<ChartContainer config={config} className="aspect-auto h-64 w-full">
  <AreaChart data={data}>
    <CartesianGrid vertical={false} />
    <XAxis dataKey="month" tickLine={false} axisLine={false} />
    <ChartTooltip content={<ChartTooltipContent />} />
    <Area dataKey="mrr" stroke="var(--color-mrr)" fill="var(--color-mrr)" />
  </AreaChart>
</ChartContainer>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ChartContainer | config | `ChartConfig` |  | Labels, icons and colors per series key. Sets --color-<key> for each. |
| ChartTooltipContent | indicator | `"dot" \| "line" \| "dashed"` | "dot" | Series marker in the tooltip. |
| ChartTooltipContent | valueFormatter | `(value) => ReactNode` |  | Formats each value, for example as currency. |
| ChartTooltipContent | hideLabel | `boolean` | false | Hides the x value heading. |
| ChartLegendContent | nameKey | `string` |  | Payload key to look up labels in the config. |
| ChartContainer | loading | `boolean \| "bars" \| "line"` | false | Shows a skeleton in the chart's place. |
| ChartContainer | empty | `boolean \| ReactNode` | false | Shows the empty state. Pass a node for your own message. |

## Data grid (data-grid)

A dense, virtualized grid for large datasets: resizable and pinnable columns, keyboard navigation like a spreadsheet, inline editing with validation and a totals row.

Install: `npx prodular-ui add data-grid`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Thousands of rows that people scan, compare and edit in place: ledgers, inventories, price lists, bulk data cleanup.
- Spreadsheet-style work where the keyboard matters more than the mouse.
- Pinning the identifying column at the start and the key number at the end, so both stay visible while scrolling.

Avoid:
- Lists under a few hundred rows with row actions, filters and bulk selection. Use Data table.
- Editing that needs more than one field at a time. Open a sheet or dialog for the record.
- Rich content in cells, like long text or images. Rows have a fixed height.

Agent rules:
- Define columns with createDataGridColumnHelper and give each a size. Numbers get meta.align "end".
- Make a column editable with meta.editor: "text", "number" or "select" (with meta.options), and pass onCellEdit to DataGrid.
- In onCellEdit, validate and return a message string to reject the value; the editor stays open with the message. Otherwise save, then update your data immutably.
- Pin columns with initialState.columnPinning { start: [...], end: [...] }. People can pin, sort and hide from each header menu.
- Add totals with meta.aggregate (sum, avg, count, min, max) and meta.formatAggregate for currency.
- Set height on DataGrid; only visible rows render, so keep data as a stable array and update it immutably.
- Keyboard: arrows, Page Up and Down, Home and End move; Enter or F2 edits; typing replaces; Escape cancels; Enter saves and moves down; Tab saves and moves right; Cmd or Ctrl+C copies the cell.

```tsx
const table = useDataGrid({ data, columns, initialState: { columnPinning: { start: ["id"], end: [] } } })

<DataGrid table={table} height={480} onCellEdit={save} rowNumbers />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| useDataGrid | options | `{ data, columns, getRowId?, initialState? }` |  | Creates the table with sizing, resizing, pinning, visibility and sorting. |
| DataGrid | table | `DataGridInstance` |  | The table from useDataGrid. |
| DataGrid | height | `number \| string` | 480 | Height of the scroll area. |
| DataGrid | rowHeight | `number` | 36 | Fixed row height in pixels. |
| DataGrid | onCellEdit | `({ row, rowId, columnId, value }) => void \| string \| Promise<void \| string>` |  | Saves an edit. Return a string to reject it. |
| DataGrid | rowNumbers | `boolean` | false | A sticky row numbers column. |
| DataGrid | empty | `ReactNode` |  | Shown when there are no rows. |
| Column meta | editor / options / aggregate / align | `DataGridColumnMeta` |  | Per column editing, totals and alignment. |

## Data table (data-table)

A full data grid on TanStack Table v9: sorting, search, faceted filters with chips, column visibility, row selection with a bulk action bar, pagination, and loading and empty states.

Install: `npx prodular-ui add data-table`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Lists of records people scan, compare and act on: invoices, customers, deployments, tickets.
- Up to a few thousand rows on the client. Beyond that, switch on manualSorting, manualFiltering and manualPagination and let the server do the work.
- Faceted filters for columns with a small set of known values (status, owner, plan). Search for free text.

Avoid:
- Wrapping the table in another Card. DataTableContent already is the surface.
- More than one primary button in the bulk action bar.
- Faceted filters on columns with hundreds of unique values. Use search, or a dedicated combobox.
- Center-aligned numbers. Amounts, counts and comparable dates are right-aligned with meta.align set to end.

Agent rules:
- Create columns with createDataTableColumnHelper<TData>() and helper.columns([...]) at module scope, never inline in render.
- Always pass getRowId with a stable id from the data. Index ids break selection after sorting.
- Set filterFn: "facet" on every column used by DataTableFacetedFilter or DataTableFilterBar, and pass the same filters config to DataTableFilterChips.
- Set meta.align to "end" on money, counts and dates people compare. Set meta.label when the header is a component.
- Use dataTableSelectColumn<TData>() for selection instead of writing checkbox cells. Put DataTableBulkActions inside DataTableContent.
- Render status columns with Status appearance="pill", people with Avatar plus name, and ids in font-mono at 13px.
- Pass loading while fetching instead of swapping in a spinner. Do not wrap DataTableContent in a Card.
- Give each DataTableRowActions a label that names the record.

```tsx
const helper = createDataTableColumnHelper<Invoice>()
const columns = helper.columns([
  dataTableSelectColumn<Invoice>(),
  helper.accessor("status", {
    header: ({ column }) => <DataTableColumnHeader column={column} title="Status" />,
    filterFn: "facet",
  }),
  helper.accessor("amount", { header: "Amount", meta: { align: "end" } }),
])

const table = useDataTable({ data, columns, getRowId: (r) => r.id })

<DataTable table={table}>
  <DataTableToolbar>
    <DataTableSearch placeholder="Search invoices" />
    <DataTableFilterBar filters={filters} />
    <DataTableToolbarSpacer />
    <DataTableViewOptions />
  </DataTableToolbar>
  <DataTableFilterChips filters={filters} />
  <DataTableContent>
    <DataTableBulkActions>
      <Button size="sm">Mark as paid</Button>
    </DataTableBulkActions>
  </DataTableContent>
  <DataTablePagination />
</DataTable>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| useDataTable | data | `TData[]` |  | Rows. Keep the array stable (state or memo); a new array every render recomputes every row model. |
| useDataTable | columns | `ColumnDef[]` |  | Build with createDataTableColumnHelper<TData>().columns([...]) at module scope. |
| useDataTable | getRowId | `(row: TData) => string` |  | Stable ids keep selection correct across sorting and pages. Always pass it. |
| useDataTable | initialState | `Partial<TableState>` | { pagination: { pageIndex: 0, pageSize: 10 } } | Starting sort, filters, hidden columns and page size. |
| DataTable | table | `DataTableInstance` |  | The instance from useDataTable. Every part below reads it from context. |
| DataTableContent | loading | `boolean` | false | Shows skeleton rows in place of data and sets aria-busy. |
| DataTableContent | stickyHeader | `boolean` | false | Pins the header row. Use with maxHeight. |
| DataTableContent | maxHeight | `number \| string` |  | Height of the scroll area. |
| DataTableContent | empty | `ReactNode` |  | Replaces the default empty state. The default adapts to whether filters are active. |
| DataTableContent | onRowClick | `(row) => void` |  | Makes rows clickable. Clicks on the checkbox and actions cells are ignored. |
| DataTableFilterBar | filters | `DataTableFilterConfig[]` |  | { column, title, options, pinned }. Pinned filters always show; the rest sit under Add filter until used. |
| DataTableFilterChips | filters | `DataTableFilterConfig[]` |  | Pass the same config so chips show titles and option labels. |
| DataTableColumnHeader | column / title | `Column / string` |  | A sort button with a direction icon. Sets aria-sort on the header cell. |
| DataTablePagination | pageSizes | `number[]` | [10, 20, 50, 100] | Options for Rows per page. |
| DataTableRowActions | label | `string` | "Row actions" | Accessible name of the trigger. Include the record, for example Actions for INV-2041. |
| Column meta | align | `"start" \| "end"` |  | end right-aligns header and cells and turns on tabular numbers. |
| Column meta | label | `string` |  | Name used in the View menu and filter chips when the header is a component. |

## Donut chart (donut-chart)

A donut or pie with the total in the center and a legend with values and shares. Hovering a segment or legend row shows that part in the center.

Install: `npx prodular-ui add donut-chart`
Free, MIT licensed.

Use when:
- Parts of one total with five or fewer parts: seats by plan, spend by category, tickets by status.
- The center for the total, so the chart answers how much and how it splits at once.
- onValueChange when choosing a part should filter a table or report next to it.

Avoid:
- More than five parts. Group the smallest into Other, or use Bar list.
- Comparing parts across periods. Use a stacked bar chart.
- variant="pie" for more than three parts, since angles are hard to compare.

Agent rules:
- Pass data as { name, value }[]. Leave color out to get chart-1 to chart-5 in order; set color only to a var(--chart-N) token.
- Format the center and legend values with valueFormatter, for example compact currency.
- Use legend="bottom" in narrow cards and legend="right" from about 420px wide.
- Set centerLabel to the unit (Seats, Invoices). centerValue overrides the total, for example 62% used.
- Show loading while data is fetched and pass empty with what is missing, like No invoices.

```tsx
<DonutChart
  data={[{ name: "Enterprise", value: 1840 }, { name: "Team", value: 1215 }]}
  centerLabel="Seats"
  legend="right"
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| DonutChart | data | `{ name, value, key?, color? }[]` |  | Segments in drawing order, clockwise from the top. |
| DonutChart | variant | `"donut" \| "pie"` | "donut" | Pie fills the center and drops the center text. |
| DonutChart | size | `number` | 176 | Diameter in pixels. |
| DonutChart | thickness | `number` | 22 | Ring width in pixels. |
| DonutChart | valueFormatter | `(value: number) => ReactNode` |  | Formats the center and legend values. |
| DonutChart | centerLabel / centerValue | `ReactNode` | "Total" / the total | Center text when nothing is hovered. |
| DonutChart | legend | `"right" \| "bottom" \| "none"` | "right" | Legend placement. Right stacks under the chart on small screens. |
| DonutChart | activeKey / onValueChange | `string \| null / (item \| null) => void` |  | Makes segments and legend rows selectable. |
| DonutChart | loading | `boolean` | false | Shows a skeleton ring and legend. |
| DonutChart | empty | `ReactNode` | "No data" | Center text when the total is zero. |

## Filter builder (filter-builder)

Nested AND/OR conditions over typed fields: text, number, date, select and yes/no, each with its own operators. The value is plain JSON, with helpers to apply it to rows and describe it in a sentence.

Install: `npx prodular-ui add filter-builder`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Lists and reports where people combine conditions across fields, like overdue invoices over $5,000 for one region.
- Building segments, audiences and automation rules that are saved and run later.
- FilterBuilderPopover in a table toolbar; the inline FilterBuilder on a page or in a dialog where the filter is the main task.

Avoid:
- One or two fixed filters on a single field. Use the faceted filters in Data table.
- Free text search. Use Search input and keep the builder for structured conditions.
- Groups deeper than one level. maxDepth=1 covers almost every real query.

Agent rules:
- Describe each filterable column once as a FilterField with id, label and type. Give select fields their options, and number fields a unit when it helps.
- Keep the value in state as FilterGroup JSON and pass value with onValueChange. Store it as is in saved views or the URL.
- Filter rows on the client with applyFilter(rows, filter, fields). On the server, walk the same JSON into your query; operators map one to one to SQL.
- Show describeFilter(filter, fields) next to the trigger or in a saved view so people can read the filter without opening it.
- To let a model build filters, give it the field list and the FilterGroup shape and ask for JSON. Validate field ids and operators before applying.
- Incomplete conditions are ignored by applyFilter and countConditions, so never block typing with validation.

```tsx
const [filter, setFilter] = useState(createFilter())

<FilterBuilderPopover fields={fields} value={filter} onValueChange={setFilter} />

const rows = applyFilter(invoices, filter, fields)
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| FilterBuilder | fields | `FilterField[]` |  | Filterable fields: { id, label, type, options?, unit?, icon?, accessor? }. |
| FilterBuilder | value / onValueChange | `FilterGroup / (value) => void` |  | The filter tree, controlled. |
| FilterBuilder | maxDepth | `number` | 1 | How deep groups can nest. 0 hides Add group. |
| FilterBuilderPopover | label | `string` | "Filter" | Trigger text. The trigger shows the count of active conditions. |
| applyFilter | (rows, filter, fields, today?) | `TRow[]` |  | Rows that pass. Pass today to make date conditions deterministic. |
| describeFilter | (filter, fields) | `string` |  | The filter as one sentence. |
| countConditions | (filter) | `number` |  | Complete conditions, nested groups included. |
| createFilter | (combinator?) | `FilterGroup` |  | An empty filter. |

## Item (item)

A row with media, a title, a description and actions, for lists of integrations, files, people and settings.

Install: `npx prodular-ui add item`
Free, MIT licensed.

Use when:
- Lists where each row has a name, a short description and one or two actions.
- Standalone rows on a page, such as a setting that needs attention (outline).

Avoid:
- outline or muted items inside a card. Inside a card use the default variant with separators.
- Data with several comparable columns. Use a Table.
- More than two actions per row. Move the rest into a menu.

Agent rules:
- Inside a Card, use the default variant and separate rows with ItemSeparator. Never use variant="outline" inside a card.
- Wrap rows in ItemGroup and give each Item role="listitem".
- Use ItemMedia variant="icon" for lucide icons and variant="image" for logos or thumbnails.
- To make the whole row a link, pass render={<a href="..." />}. Do not nest buttons inside a linked row.
- Keep ItemTitle to one line and ItemDescription to two.

```tsx
<ItemGroup>
  <Item role="listitem">
    <ItemMedia variant="icon"><DatabaseIcon /></ItemMedia>
    <ItemContent>
      <ItemTitle>Snowflake</ItemTitle>
      <ItemDescription>Syncs every hour</ItemDescription>
    </ItemContent>
    <ItemActions>
      <Button size="sm" variant="ghost">Configure</Button>
    </ItemActions>
  </Item>
  <ItemSeparator />
</ItemGroup>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Item | variant | `"default" \| "outline" \| "muted"` | "default" | Plain row, raised bordered row or quiet tinted row. |
| Item | size | `"default" \| "sm" \| "xs"` | "default" | Padding and gap. |
| Item | render | `ReactElement` |  | Renders the row as another element, for example a link. |
| ItemMedia | variant | `"default" \| "icon" \| "image"` | "default" | Sizing for the leading media. |

## Kbd (kbd)

A keyboard key or shortcut, styled to sit in text, menus, buttons and tooltips.

Install: `npx prodular-ui add kbd`
Free, MIT licensed.

Use when:
- Teaching shortcuts next to the action they trigger: search fields, menu items, tooltips.
- Help pages that list shortcuts.

Avoid:
- Shortcuts that do not exist on the current platform. Show Ctrl on Windows and Linux.
- Code or values. Use inline code for those.

Agent rules:
- Use symbols for modifier keys on macOS (⌘, ⌥, ⇧, ⌃) and words elsewhere (Ctrl, Alt, Shift).
- Wrap multi key shortcuts in KbdGroup, one Kbd per key. A compact shortcut inside a button can be a single Kbd, such as ⌘K.
- Inside a Button, place Kbd last and add ml-auto when the button is wider than its label.
- Never use Kbd as a clickable element. It has pointer-events-none.
- Use variant="mono" when keys sit next to monospace readouts; HotkeyKeys renders mono keys for registered shortcuts.

```tsx
<KbdGroup>
  <Kbd>⌘</Kbd>
  <Kbd>K</Kbd>
</KbdGroup>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Kbd | children | `ReactNode` |  | A key name or symbol: ⌘, ⇧, ↵, Esc, K. |
| KbdGroup | children | `ReactNode` |  | Several Kbd elements that make up one shortcut. |
| Kbd | variant | `"default" \| "mono"` | "default" | mono sets the key in the monospace face, next to other technical readouts. |

## Legend (legend)

The key to a chart, map, graph or timeline: colors, shapes and line styles with labels, grouping and optional toggles.

Install: `npx prodular-ui add legend`
Free, MIT licensed.

Use when:
- Any visual where color, shape or line style carries meaning.
- onActiveChange to let people hide a series.
- LegendGroup when one visual has more than one encoding.

Avoid:
- Color as the only difference between items. Give each a shape or line style too.
- Legends for a single series. Label it in the title.

Agent rules:
- Use the same color token and shape as the visual draws, for example color="severity-high" with shape="triangle".
- Give Legend an aria-label when there is more than one on screen.
- Toggles need onActiveChange and active; they render as buttons with aria-pressed.

```tsx
<Legend aria-label="Payment methods">
  <LegendItem color="chart-1" shape="line" label="Card" active={on} onActiveChange={setOn} />
</Legend>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Legend | orientation | `"horizontal" \| "vertical"` | "horizontal" | Wraps in a row, or stacks. |
| LegendItem | color | `string` |  | A token name ("chart-1", "severity-high") or a CSS color. |
| LegendItem | shape | `"circle" \| "square" \| "diamond" \| "triangle" \| "line" \| "dashed" \| "dotted"` | "circle" | The mark. |
| LegendItem | active | `boolean` | true | Inactive items dim and strike through. |
| LegendItem | onActiveChange | `(active: boolean) => void` |  | Makes the item a toggle. |

## Permissions matrix (permissions-matrix)

Roles across, permissions down, a level in every cell: no access, read, write or admin. Granting a permission adds what it requires, removing one takes away what depends on it, and roles and groups change in bulk.

Install: `npx prodular-ui add permissions-matrix`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Role based access for a workspace or an organization: the settings page where admins define what each role can do.
- levels per permission when not every level makes sense, like an audit log that is only none or read.
- requires for real dependencies, so a role can never hold a permission that would not work without another.

Avoid:
- Assigning roles to people. Use the members list with a role select.
- More than about eight roles. Add a role filter or split the matrix by product area.
- Per-record sharing. Use a share dialog on the record.

Agent rules:
- Describe permissions as groups of { id, label, description?, levels?, requires? } and roles as { id, label, members?, locked?, custom? }.
- Keep value as { [roleId]: { [permissionId]: level } } and pass onValueChange. Missing entries mean none.
- Pass the saved value as initialValue and an async onSave to get change markers and the Save bar; throw from onSave to show an error.
- Mark built-in owner roles locked: they show every permission at its highest level and cannot be edited.
- Use setPermission(value, groups, role, permission, level) on the server too, so dependency rules hold however permissions change.
- Cells are a grid: arrow keys move, Enter opens the level menu. Every cell's accessible name includes the permission, the role and the level.

```tsx
<PermissionsMatrix
  groups={groups}
  roles={roles}
  value={value}
  onValueChange={setValue}
  initialValue={saved}
  onSave={save}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| PermissionsMatrix | groups | `PermissionGroup[]` |  | Groups of permissions with levels and requirements. |
| PermissionsMatrix | roles | `PermissionRole[]` |  | Columns, in order. |
| PermissionsMatrix | value / onValueChange | `PermissionValue / (value) => void` |  | Levels by role and permission. |
| PermissionsMatrix | readOnly | `boolean` | true without onValueChange | Hides the controls. |
| PermissionsMatrix | initialValue / onSave | `PermissionValue / (value) => Promise<void>` |  | Change markers, Discard and Save. |
| setPermission | (value, groups, role, permission, level) | `{ value, changes }` |  | Applies one change with its dependencies. |
| diffPermissions | (before, after, roles, groups) | `{ role, permission, from, to }[]` |  | Every changed cell, for review or an audit entry. |

## Property list (property-list)

Key-value pairs for inspectors and detail panels on one grid, with empty values, descriptions, monospace values and copy actions.

Install: `npx prodular-ui add property-list`
Free, MIT licensed.

Use when:
- The fields of one record in an inspector, a side panel or a detail card.
- copy on identifiers people paste elsewhere: IDs, hashes, coordinates.
- mono for IDs and coordinates.

Avoid:
- Editable forms. Use Field and the inputs, or InlineEdit per value.
- Comparing many records. Use Table.
- Writing a dash or an empty cell for missing values. The empty text does that.

Agent rules:
- Wrap each pair in Property with one PropertyLabel and one PropertyValue.
- Leave PropertyValue empty for missing data; do not write placeholders like "-" or "N/A".
- Pass copyLabel naming what is copied, for example "Copy invoice number".
- Set labelWidth so the longest common label fits; it truncates beyond that.

```tsx
<PropertyList>
  <Property>
    <PropertyLabel>Invoice</PropertyLabel>
    <PropertyValue mono copy copyLabel="Copy invoice number">INV-2103</PropertyValue>
  </Property>
</PropertyList>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| PropertyList | labelWidth | `string` | "8rem" | Width of the label column. |
| PropertyLabel | description | `ReactNode` |  | A second line under the label in tertiary text. |
| PropertyValue | empty | `ReactNode` | "Not set" | Shown when there is no value. |
| PropertyValue | copy | `boolean \| string` |  | Adds a copy button. A string copies that string. |
| PropertyValue | copyLabel | `string` | "Copy" | Accessible name of the copy button. |
| PropertyValue | mono | `boolean` | false | Monospace value. |

## Saved views (saved-views)

A bar of saved views over a table or report. Picking a view restores its filters, sorting and columns; changing them marks the view modified, with Save, Save as new and Reset.

Install: `npx prodular-ui add saved-views`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Tables, boards and reports that people revisit with the same filters, like Overdue or My accounts.
- Locked presets for the views every team needs, and personal or shared views on top.
- The same state object for the URL, so a view can be linked and shared.

Avoid:
- One-off filtering. The filter bar and chips are enough until people repeat themselves.
- More than about eight views in the bar. Keep the rest behind search or a menu.
- Saving row selection or scroll position. Views hold how to look at data, not where you were.

Agent rules:
- Define a ViewState type with everything a view restores (search, filters, sorting, column visibility, grouping) and keep it JSON.
- Build the current state from the table on every render and pass it as state. SavedViews compares it with the active view to show Modified.
- In onActiveChange, set the active id and apply view.state to the table: setGlobalFilter, setColumnFilters, setSorting, setColumnVisibility, then go to the first page.
- Start the table with the default view's state, or it opens as modified.
- Mark built-in presets locked. They can be duplicated but not renamed, saved over or deleted.
- useSavedViews keeps views in React state, or in localStorage with storageKey. For shared views, load and save them through your API with onViewsChange.

```tsx
const { views, setViews, activeId, setActiveId } = useSavedViews({ initialViews })

<SavedViews
  views={views}
  onViewsChange={setViews}
  activeId={activeId}
  onActiveChange={(id, view) => { setActiveId(id); applyToTable(view.state) }}
  state={currentState}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| SavedViews | views / onViewsChange | `SavedView<T>[] / (views) => void` |  | Views: { id, name, state, shared?, locked? }. |
| SavedViews | activeId / onActiveChange | `string / (id, view) => void` |  | The selected view. Apply view.state in the callback. |
| SavedViews | state | `T` |  | The current state, compared with the active view. |
| SavedViews | shareable | `boolean` | false | Adds Share with team when saving and in the view menu. |
| SavedViews | isEqual | `(a: T, b: T) => boolean` |  | Custom comparison. The default ignores key order. |
| useSavedViews | ({ initialViews, initialActiveId?, storageKey? }) | `{ views, setViews, activeId, setActiveId, activeView }` |  | View state, optionally persisted in localStorage. |

## Severity (severity)

A four-level threat or impact scale (critical, high, elevated, routine) with its own tokens and a shape per level, separate from system status.

Install: `npx prodular-ui add severity`
Free, MIT licensed.

Use when:
- How serious something is: incidents, threats, risks, findings.
- The same level and shape on the map, the graph, the table and the legend.
- severityOf(level).token with tokenColor() for canvas and map renderers.

Avoid:
- Severity for system state (Running, Failed). Use Status.
- Chart colors for severity. Use the severity tokens.
- Solid for more than one item in a view.

Agent rules:
- Map impact to levels consistently: critical acts now, high acts today, elevated needs watching, routine needs nothing.
- Keep the label. SeverityIcon alone only next to text that names the level.
- Draw the same shape as SeverityIcon on maps and graphs (severityOf(level).shape), so severity never relies on color alone.
- Use the severity-* color tokens (bg-severity-high-subtle, text-severity-critical) instead of red or orange classes.

```tsx
<Severity level="high" appearance="pill" />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Severity | level | `"critical" \| "high" \| "elevated" \| "routine"` |  | The level. |
| Severity | appearance | `"plain" \| "pill" \| "solid"` | "plain" | Text with a shape, a tinted pill, or a solid pill. |
| Severity | size | `"default" \| "sm" \| "xs"` | "default" | Type size. |
| severityOf | (level) | `{ label, token, shape }` |  | Token and shape for custom renderers. |

## Sparkline (sparkline)

A tiny line, area or bar trend drawn in SVG without a chart library, colored with chart tokens through currentColor.

Install: `npx prodular-ui add sparkline`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Next to a number, to show which way it has been moving.
- In table cells and KPI strips where a full chart would be too much.

Avoid:
- Anything people need to read exact values from. Use Chart with axes and tooltips.
- Fewer than five points. A delta says more.

Agent rules:
- Size it with classes (h-6 w-20, or w-full) and color it with text-chart-1 to text-chart-5, or a status text token such as text-warning-subtle-foreground. Never pass hex colors.
- Pass label when the trend matters to the reader; without it the sparkline is hidden from screen readers.
- Pass data oldest first. Use variant="bar" for counts per period and line or area for continuous metrics.
- Set min to 0 when the baseline matters, otherwise small changes look dramatic.

```tsx
<Sparkline data={[12, 18, 15, 22, 28]} className="h-8 w-24 text-chart-1" showLastPoint />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Sparkline | data | `number[]` |  | The series, oldest first. |
| Sparkline | variant | `"line" \| "area" \| "bar"` | "line" | Shape. |
| Sparkline | curved | `boolean` | true | Monotone curve that never overshoots the data. |
| Sparkline | showLastPoint | `boolean` | false | Dot on the latest value. |
| Sparkline | strokeWidth | `number` | 1.5 | Line width in px. It does not scale with the box. |
| Sparkline | min / max | `number` |  | Fix the y range, for example min={0}. |
| Sparkline | label | `string` |  | Accessible description. Without it the element is aria-hidden. |

## Stat (stat)

A KPI strip: one surface with dividers between metrics, each with a label, a large value, a colored delta, an optional sparkline and a comparison line.

Install: `npx prodular-ui add stat`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- The top of a dashboard or report, for three to five numbers people check every day.
- Pair every delta with a comparison line so the number has a reference: vs last 30 days, vs target.
- Sparklines when the shape of the trend matters more than the exact history.

Avoid:
- A grid of separate cards, one per metric. Use one Stats strip.
- More than five metrics in one strip. Split them into two strips with headings.
- Coloring the value itself. Only the delta carries color.

Agent rules:
- Render one Stats container with one Stat per metric. Never wrap a Stat in a Card.
- Pass the raw signed change to StatDelta value. Set invert for metrics where down is good: churn, latency, cost, open tickets, errors.
- Use format on StatDelta for units that are not percentages, for example points or minutes.
- Put StatValue and StatDelta inside StatContent so they share a baseline.
- Give StatSparkline a label when the trend carries meaning, and color it with text-chart-1 to text-chart-5. Do not use raw colors.
- Use variant="plain" when the strip sits inside an existing Card.

```tsx
<Stats>
  <Stat>
    <StatLabel>Monthly recurring revenue</StatLabel>
    <StatContent>
      <StatValue>$184,320</StatValue>
      <StatDelta value={8.4} />
    </StatContent>
    <StatComparison>vs last 30 days</StatComparison>
    <StatSparkline data={series} />
  </Stat>
</Stats>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Stats | variant | `"card" \| "plain"` | "card" | card draws the surface. plain is for use inside an existing card. |
| StatDelta | value | `number` |  | The signed change. The sign sets the arrow. |
| StatDelta | invert | `boolean` | false | Down is good. A negative value turns green. |
| StatDelta | format | `(abs: number) => string` |  | Formats the absolute change. Defaults to one decimal with a percent sign. |
| StatSparkline | data | `number[]` |  | The series, oldest first. |
| StatSparkline | variant | `"area" \| "line" \| "bar"` | "area" | Shape of the sparkline. |
| StatSparkline | label | `string` |  | Screen reader description of the trend. |

## Status (status)

A colored dot with a label for system and record states, with an optional live pulse and a pill appearance for tables.

Install: `npx prodular-ui add status`
Free, MIT licensed.

Use when:
- The state of a system, a sync, a deploy or a record: Operational, Degraded, Syncing, Paid, Failed.
- pulse for states that are actively changing right now: Syncing, Deploying, Live.

Avoid:
- Color as the only signal. Always keep the label.
- Pulsing more than one or two items in a view. Motion stops meaning anything when everything moves.
- Badge for states. Badge is for counts and tags; Status is for state.

Agent rules:
- Map states to variants consistently: success for healthy or done, warning for degraded or needs attention, destructive for failed or down, info for in progress, neutral for paused, draft or archived.
- Always pass a text label as children. Use StatusIndicator alone only next to text that already names the state.
- Use appearance="pill" inside data table cells and appearance="plain" in headers, lists and sentences.
- Use pulse only for live or in-progress states. It is motion-reduce safe; do not add your own animation.
- Use size="xs" on Status for dense toolbars and inspectors instead of overriding its height.

```tsx
<Status variant="success">Operational</Status>
<Status variant="info" appearance="pill" pulse>Syncing</Status>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Status | variant | `"success" \| "warning" \| "info" \| "destructive" \| "neutral"` | "neutral" | Color of the dot, and of the tint for pills. |
| Status | appearance | `"plain" \| "pill"` | "plain" | plain is a dot and text. pill adds a tinted rounded background. |
| Status | size | `"default" \| "sm" \| "xs"` | "default" | sm uses 13px text. |
| Status | pulse | `boolean` | false | A soft ping around the dot. Hidden with prefers-reduced-motion. |
| Status | indicator | `boolean` | true | Set false to place StatusIndicator yourself. |
| StatusIndicator | variant / pulse | `StatusVariant / boolean` |  | The dot on its own, for filter options or next to text that already names the state. |

## Table (table)

A data table with hairline rows, muted 13px headers, numeric alignment, selected rows and an optional sticky header.

Install: `npx prodular-ui add table`
Free, MIT licensed.

Use when:
- Records people scan, compare and act on: invoices, members, requests, deployments.
- Put tables inside a Card with a title and the primary table action in CardAction.
- Right align every numeric column, including its header, so digits line up.

Avoid:
- A border or a tinted wrapper around the table inside a card. The card is the only box.
- Zebra striping. Hairline row dividers and hover are enough.
- More than one badge or more than two lines of text per cell.

Agent rules:
- Place Table directly inside CardContent. Do not wrap it in another bordered div. The edge padding aligns with the card automatically.
- Pass numeric to both TableHead and TableCell for amounts, counts, durations and percentages.
- Format currency with Intl.NumberFormat and put units in the cell (184 ms), not in a separate column.
- Mark the selected row with data-state="selected" or aria-selected. Do not add your own background classes.
- Use font-mono only for ids and hashes, never for names or dates.
- For long tables, pass containerClassName="max-h-96" to Table and sticky to TableHeader.
- Use Badge size="sm" inside cells.

```tsx
<Card>
  <CardHeader>
    <CardTitle>Invoices</CardTitle>
  </CardHeader>
  <CardContent>
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead>Customer</TableHead>
          <TableHead numeric>Amount</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        <TableRow>
          <TableCell>Pinecrest Health</TableCell>
          <TableCell numeric>$12,480.00</TableCell>
        </TableRow>
      </TableBody>
    </Table>
  </CardContent>
</Card>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Table | containerClassName | `string` |  | Classes for the scrolling wrapper. Set a max height here for a sticky header. |
| TableHeader | sticky | `boolean` | false | Keeps the header row visible while the container scrolls. |
| TableHead | numeric | `boolean` | false | Right aligns the header to match numeric cells. |
| TableCell | numeric | `boolean` | false | Right aligns the cell with tabular figures. |
| TableRow | data-state | `"selected"` |  | Highlights the row with the brand tint. aria-selected works too. |

## Time track (time-track)

A time axis with swimlanes, point and span events, a playhead, zoom, pan and range selection, for incident reviews, signal timelines and playback.

Install: `npx prodular-ui add time-track`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Events that happen at a time across a few sources: deploys, alerts, sensor readings, messages.
- A playhead when the rest of the screen shows the state at one moment.
- Range selection to filter other panels to a window.

Avoid:
- The activity feed of a record. That is Timeline.
- More than about ten lanes. Group sources or let people pick lanes.
- Color as the only difference between events. Use labels, lanes and a Legend with shapes.

Agent rules:
- Pass times as numbers in milliseconds (Date.getTime()).
- Give every TimeTrackEvent a label. It names the event for screen readers and shows on hover.
- Color events with tokens, for example color="chart-2" or color="severity-high". Never raw colors.
- Control view, time and range when other panels depend on them; leave them uncontrolled otherwise.
- Do not hijack plain scrolling. Zoom stays on Ctrl or Cmd and the wheel, which is how TimeTrack works.
- Put a Legend next to the track when colors or shapes carry meaning.
- Pass timeZone="UTC" (or the zone your data is in) when labels must match logs or render on the server; otherwise labels use the viewer's zone and render after hydration.

```tsx
<TimeTrack aria-label="Incident" domain={[start, end]} time={time} onTimeChange={setTime}>
  <TimeTrackAxis />
  <TimeTrackLanes>
    <TimeTrackLane label="Alerts">
      <TimeTrackEvent at={t} label="Error rate above 2%" color="severity-high" />
    </TimeTrackLane>
  </TimeTrackLanes>
</TimeTrack>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| TimeTrack | domain | `[number, number]` |  | The full time extent in ms. The view never leaves it. |
| TimeTrack | view | `[number, number]` |  | The visible window. Controlled with onViewChange, or defaultView. |
| TimeTrack | time | `number \| null` |  | Playhead position. Controlled with onTimeChange, or defaultTime. |
| TimeTrack | range | `[number, number] \| null` |  | Selected range. Controlled with onRangeChange, or defaultRange. |
| TimeTrack | minSpan | `number` | 10000 | Shortest span the view zooms to, in ms. |
| TimeTrack | labelWidth | `string` | "7rem" | Width of the lane label column. |
| TimeTrack | timeZone | `string` |  | IANA zone for labels, such as "UTC". Without it labels use the viewer's zone and appear after hydration. |
| TimeTrackLanes | now | `number` |  | Draws a dashed now line. |
| TimeTrackEvent | at | `number` |  | Start time. Add end for a span. |
| TimeTrackEvent | color | `string` | "chart-1" | A token name. |

## Timeline (timeline)

An activity feed with avatars or icons, actor, action, target and relative time, optional comments and attachments, grouped by day with sticky labels and a connector line.

Install: `npx prodular-ui add timeline`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- The history of a record: who changed what and when. Accounts, invoices, tickets, deploys.
- System and human events in one stream, with avatars for people and icons for systems.

Avoid:
- Comment threads people reply to. Use a chat or comments component.
- Wrapping comments in tinted bubbles inside a card. TimelineBody uses a hairline.
- Tinting every icon. Reserve success, warning and destructive for outcomes.

Agent rules:
- Write each title as actor, action, target: wrap the person or system in TimelineActor and the object in TimelineTarget, keep the verb plain.
- Use TimelineMedia variant="avatar" with an Avatar size="sm" for people, variant="icon" for neutral system events, and success, warning, destructive or info only for outcomes.
- Pass dateTime to TimelineTime. Pass a fixed now when rendering on the server so relative times match after hydration.
- Group by calendar day with TimelineGroup and TimelineGroupLabel (Today, Yesterday, then dates). Set --timeline-surface to the background the timeline sits on, for example [--timeline-surface:var(--card)] inside a card, so sticky labels cover the content.
- List newest first.

```tsx
<Timeline>
  <TimelineGroup>
    <TimelineGroupLabel>Today</TimelineGroupLabel>
    <TimelineList>
      <TimelineItem>
        <TimelineMedia variant="avatar"><Avatar size="sm">...</Avatar></TimelineMedia>
        <TimelineContent>
          <TimelineHeader>
            <TimelineTitle>
              <TimelineActor>Maya Okafor</TimelineActor> commented on <TimelineTarget>INV-2094</TimelineTarget>
            </TimelineTitle>
            <TimelineTime dateTime={event.at} />
          </TimelineHeader>
          <TimelineBody>Payment is scheduled for Friday.</TimelineBody>
        </TimelineContent>
      </TimelineItem>
    </TimelineList>
  </TimelineGroup>
</Timeline>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| TimelineMedia | variant | `"avatar" \| "icon" \| "success" \| "warning" \| "destructive" \| "info" \| "brand"` | "icon" | The circle to the left of each event. |
| TimelineTime | dateTime | `Date \| string \| number` |  | When it happened. Shown relative to now unless children are passed. |
| TimelineTime | now | `Date \| number` | Date.now() | Reference time for the relative label. |
| TimelineGroupLabel | children | `ReactNode` |  | The day. Sticky inside the nearest scroll container. |
| Timeline | --timeline-surface | `CSS variable` | var(--background) | Background of the sticky day labels. |
| formatRelativeTime | (date, now) | `function` |  | The formatter TimelineTime uses, exported for other places. |

## Token color (token-color)

Resolves color tokens to sRGB for canvas, WebGL, MapLibre, D3 and chart libraries, and updates them when the theme or mode changes.

Install: `npx prodular-ui add token-color`
Free, MIT licensed.

Use when:
- Renderers that take color strings or numbers instead of CSS: canvas 2D, WebGL, MapLibre styles, D3 scales.
- useTokenColors in React, so colors update with the theme.
- tokenColor(token, { format: "array" }) for WebGL and image data.

Avoid:
- Hard-coding hex values that only match one theme.
- Painting a pixel and reading it back to convert colors.
- Calling tokenColor during server rendering; it returns null there.

Agent rules:
- Resolve colors in an effect or with useTokenColors, and redraw when they change.
- Pass token names without var(): "chart-1", "severity-high", "--border".
- Pass element to read a token under a scoped data-theme or .dark.

```tsx
const colors = useTokenColors(["chart-1", "border"])
useEffect(() => {
  if (colors) map.setPaintProperty("sites", "circle-color", colors["chart-1"])
}, [colors])
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| tokenColor | (token, options) | `string \| [r, g, b, a] \| null` |  | options: format ("hex" | "rgb" | "rgba" | "array"), element, alpha. |
| useTokenColors | (tokens, options) | `Record<token, string> \| null` |  | Resolved colors, null until mounted. |
| onTokensChange | (callback, element?) | `() => void` |  | Subscribes to theme, mode and OS color scheme changes. Returns the unsubscribe. |

## Alert (alert)

An inline message about the state of the page or the account, with status variants, an AI variant and room for actions.

Install: `npx prodular-ui add alert`
Free, MIT licensed.

Use when:
- Tell people about something that affects the page they are on: a failed payment, a quota, maintenance.
- Place it at the top of the content it is about, not in a corner of the screen.
- Use ai for a model generated insight that people should review.

Avoid:
- Confirming an action the person just took. Use a Toast.
- Stacking more than two alerts. Combine them or move the rest to a notifications view.
- Alerts inside cards. An alert is its own surface. Put it above the card instead.

Agent rules:
- Choose the variant by consequence: destructive when something failed or will stop working, warning when action is needed soon, success to confirm a lasting state, info for neutral notices, default for tips.
- Always include a lucide icon as the first child so the layout aligns: InfoIcon, CircleCheckIcon, TriangleAlertIcon, CircleAlertIcon, SparklesIcon for ai.
- Write AlertTitle as the outcome in one line. Put the reason and the next step in AlertDescription.
- The default role is alert, which interrupts screen readers. Pass role="status" for info, success and ai alerts that are not urgent.
- Use AlertAction for a dismiss button (Button variant="ghost" size="icon-sm" with aria-label). Use AlertActions for up to two sm buttons, outline first.
- Use variant="ai" only for content a model generated, and say so in the description.

```tsx
<Alert variant="warning">
  <TriangleAlertIcon />
  <AlertTitle>Webhook endpoint is failing</AlertTitle>
  <AlertDescription>28 deliveries returned 503.</AlertDescription>
  <AlertActions>
    <Button size="sm" variant="outline">View deliveries</Button>
  </AlertActions>
</Alert>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Alert | variant | `"default" \| "info" \| "success" \| "warning" \| "destructive" \| "ai"` | "default" | Color and border. Also set as data-variant. |
| Alert | role | `"alert" \| "status"` | "alert" | Use status for messages that should not interrupt. |
| AlertAction | children | `ReactNode` |  | One control pinned to the top right, usually a dismiss button. |
| AlertActions | children | `ReactNode` |  | A row of buttons under the description. |

## Banner (banner)

A full-width announcement or system message with an icon, one line of text, an action link and an optional dismiss button.

Install: `npx prodular-ui add banner`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Messages about the whole account or app: maintenance windows, billing problems, outages, launches.
- brand for product announcements, ai for things a model did that people should review.
- warning and destructive for problems that block work until someone acts.

Avoid:
- Feedback on a single action. Use a toast.
- Problems with one form or record. Use an Alert next to it.
- Stacking several banners. Show the most urgent one.

Agent rules:
- Keep it to one line: BannerTitle plus a short BannerDescription. Put the details behind BannerAction.
- Label BannerAction with a verb: Update payment method, View logs. Pass render={<a href=... />} for navigation.
- Add BannerClose only for messages that are safe to ignore. Do not make destructive banners dismissible while the problem lasts.
- Control open with onOpenChange and persist the dismissal so it does not come back on reload.
- Use layout="bar" at the very top of the app shell and layout="inset" inside page content.
- Use variant="ai" only when a model produced the thing the banner talks about.

```tsx
<Banner variant="info">
  <BannerIcon><InfoIcon /></BannerIcon>
  <BannerContent>
    <BannerTitle>Scheduled maintenance</BannerTitle>
    <BannerDescription>Exports pause on Oct 26.</BannerDescription>
  </BannerContent>
  <BannerAction render={<a href="/status" />}>Details</BannerAction>
  <BannerClose />
</Banner>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Banner | variant | `"neutral" \| "info" \| "warning" \| "destructive" \| "brand" \| "ai"` | "neutral" | Color and role. warning and destructive set role="alert". |
| Banner | layout | `"bar" \| "inset"` | "bar" | bar spans the full width with a bottom border. inset is rounded with a full border. |
| Banner | align | `"start" \| "center"` | "start" | center centers the content on wide screens; the close button moves to the edge. |
| Banner | open / defaultOpen / onOpenChange | `boolean / boolean / (open) => void` |  | Visibility. BannerClose calls onOpenChange(false). |
| BannerAction | render | `ReactElement` |  | Renders the action as a link or router Link. |

## Empty (empty)

A calm, centered placeholder for views with nothing to show yet, with an icon, a title, a description and actions.

Install: `npx prodular-ui add empty`
Free, MIT licensed.

Use when:
- A list, table or view that has no data yet, or no results for the current filters.
- First run states where the next step is clear.

Avoid:
- Errors. Use an Alert that says what failed and how to retry.
- Illustrations or emoji. One muted icon is enough.
- More than two actions.

Agent rules:
- Write EmptyTitle as a plain statement: No invoices yet, No customers match these filters.
- Use EmptyDescription to say what will appear here and how to make it appear, in one or two sentences.
- Put buttons in EmptyActions, primary first. For no results states use a single outline Clear filters button.
- Use EmptyMedia variant="icon" with a lucide icon that names the content type.
- Inside a card, place Empty in CardContent and reduce padding with className="py-6". Do not add a border.

```tsx
<Empty>
  <EmptyHeader>
    <EmptyMedia variant="icon"><ReceiptTextIcon /></EmptyMedia>
    <EmptyTitle>No invoices yet</EmptyTitle>
    <EmptyDescription>Invoices appear here once a customer is charged.</EmptyDescription>
  </EmptyHeader>
  <EmptyActions>
    <Button>Create invoice</Button>
  </EmptyActions>
</Empty>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| EmptyMedia | variant | `"default" \| "icon"` | "default" | icon puts a lucide icon on a muted tile. |
| EmptyActions | children | `ReactNode` |  | A centered row of buttons. |
| EmptyContent | children | `ReactNode` |  | Free form content under the header, such as a search field or a link. |

## Progress (progress)

A determinate bar for tasks and quotas, with a label and value row and status colors for thresholds.

Install: `npx prodular-ui add progress`
Free, MIT licensed.

Use when:
- A task with a known end: an import, an upload, a sync.
- Usage against a limit: seats, storage, API quota.

Avoid:
- Unknown durations. Use Spinner, or Skeleton for content.
- Status colors for decoration. Every bar in a list should be default until it crosses a threshold.

Agent rules:
- Always pass value (0 to 100) and a ProgressLabel so the bar has an accessible name.
- Use ProgressValue for the right side. Pass a function child to show units, for example {() => "16 of 25"}.
- Pick variant by threshold: default under 80%, warning from 80% to 99%, destructive at the limit, success when a task completes.
- Use variant="ai" only for AI credits or a model run in progress.
- Use size="sm" in dense lists and cards, size="lg" for a single prominent task.

```tsx
<Progress value={64}>
  <ProgressLabel>Seats</ProgressLabel>
  <ProgressValue>{() => "16 of 25"}</ProgressValue>
</Progress>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Progress | value | `number \| null` |  | 0 to 100. null for indeterminate. |
| Progress | variant | `"default" \| "success" \| "warning" \| "info" \| "destructive" \| "ai"` | "default" | Indicator color. Also set as data-variant. |
| Progress | size | `"sm" \| "default" \| "lg"` | "default" | Track height: 4, 6 or 8px. |
| ProgressValue | children | `(formatted, value) => ReactNode` |  | Custom value text. Defaults to a percentage. |

## Skeleton (skeleton)

A pulsing placeholder in the shape of content that is loading, so the layout does not jump.

Install: `npx prodular-ui add skeleton`
Free, MIT licensed.

Use when:
- Loading content whose layout you know: lists, tables, cards, profile headers.
- First loads of a page. For refreshes, keep the old content visible.

Avoid:
- Short actions like saving. Use the Button loading state.
- Skeletons for every single word. Approximate lines and blocks.

Agent rules:
- Size each Skeleton to the element it replaces: h-4 for 14px text, h-3.5 for 13px text, size-8 rounded-full for a default avatar, h-6 rounded-full for a badge.
- Set aria-busy="true" and an aria-label on the container that is loading. Skeleton itself is aria-hidden.
- Render the same number of rows the real content usually has, three to five at most.
- Do not color skeletons. They use bg-muted and stop pulsing with reduced motion.

```tsx
<div aria-busy="true" aria-label="Loading members">
  <Skeleton className="size-8 rounded-full" />
  <Skeleton className="h-4 w-32" />
</div>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Skeleton | className | `string` |  | Size and shape. Default radius is rounded-md. |

## Spinner (spinner)

An indeterminate loading indicator for short waits.

Install: `npx prodular-ui add spinner`
Free, MIT licensed.

Use when:
- Waits under a few seconds where the layout of the result is unknown.

Avoid:
- Loading whole pages. Use Skeleton so the layout does not jump.

## Upgrade gate (upgrade-gate)

Locks a feature behind a plan and says how to get it: over a dimmed preview, as a row in settings, or in place of the feature, with a plan comparison and a custom upgrade action. PlanBadge marks locked items in menus and nav.

Install: `npx prodular-ui add upgrade-gate`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Features people can see but their plan does not include: show what they get, then how to get it.
- inline in settings lists and forms, overlay over a preview of a report or chart, replace for a whole section.
- blockedReason for members who cannot change billing, so they know who can.

Avoid:
- Hiding features entirely. People cannot want what they never see.
- Gating on every click. Gate once at the feature's entrance.

Agent rules:
- Decide locked from the workspace's entitlements on the server and pass it in; the gate does no checks of its own.
- Name the feature and plan exactly as on the pricing page. description says what the feature does for them, in one sentence.
- onUpgrade opens checkout or changes the plan; throw with a message to show a failure. Use PlanPicker for seat and period choices.
- Pass comparison with the current and target plans and only the rows that differ, plus one or two they already have for context.
- The overlay preview is inert and hidden from assistive tech; keep real data out of it if the plan should not reveal it.

```tsx
<UpgradeGate locked={!entitlements.forecast} feature="Cash flow forecast" plan="Scale" onUpgrade={openCheckout}>
  <Forecast />
</UpgradeGate>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| UpgradeGate | locked | `boolean` |  | Shows the gate; false renders children. |
| UpgradeGate | feature / plan / description | `string / string / ReactNode` |  | What is locked, which plan has it and why it matters. |
| UpgradeGate | variant | `"overlay" \| "inline" \| "replace"` | "overlay" | How the lock shows. |
| UpgradeGate | onUpgrade / upgradeLabel | `() => Promise<void> / string` | Upgrade to {plan} | The upgrade action. |
| UpgradeGate | comparison | `PlanComparison` |  | Adds Compare plans with a feature table. |
| UpgradeGate | blockedReason | `ReactNode` |  | Replaces the button for people who cannot upgrade. |
| PlanBadge | plan | `string` |  | A lock with the plan name for menus and nav. |

## Alert dialog (alert-dialog)

A modal confirmation that interrupts the user before an irreversible or costly action and requires an explicit answer.

Install: `npx prodular-ui add alert-dialog`
Free, MIT licensed.

Use when:
- Use before deleting, revoking access, cancelling a subscription or discarding unsaved work.
- Name the object and the consequence in the title: Delete Billing migration?
- Use AlertDialogMedia with a status variant to make the stakes visible at a glance.

Avoid:
- Routine confirmations the user makes many times a day. Offer undo in a toast instead.
- Forms or extra content. Use Dialog.
- Generic buttons like OK and Yes. Both buttons should say what they do.

Agent rules:
- Always include AlertDialogTitle and AlertDialogDescription. The description is read to screen readers when the dialog opens.
- Label the confirm button with the action (Delete project) and the cancel button with the safe outcome (Keep project).
- Use AlertDialogAction variant="destructive" only when data is lost. Otherwise keep the default variant.
- Match AlertDialogMedia variant to the action: destructive for deletion, warning for data loss that can be recovered, info for neutral checks.
- Close it yourself after the action succeeds, by controlling open. AlertDialogAction does not close on its own.

```tsx
<AlertDialog>
  <AlertDialogTrigger render={<Button variant="destructive-subtle" />}>Delete project</AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogMedia variant="destructive"><Trash2Icon /></AlertDialogMedia>
      <AlertDialogTitle>Delete Billing migration?</AlertDialogTitle>
      <AlertDialogDescription>This removes 148 issues. You cannot undo this.</AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Keep project</AlertDialogCancel>
      <AlertDialogAction variant="destructive">Delete project</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AlertDialogContent | size | `"default" \| "sm"` | "default" | sm is narrow and centered, with a two column footer. |
| AlertDialogMedia | variant | `"default" \| "destructive" \| "warning" \| "info" \| "success"` | "default" | Tint of the icon tile. |
| AlertDialogAction | variant | `Button variant` | "default" | Usually destructive for the confirm button. |
| AlertDialogCancel | variant | `Button variant` | "outline" | Closes the dialog. |

## Command (command)

A searchable list of actions and destinations, used inline or as a cmd+K palette, with groups, shortcuts and a hint footer.

Install: `npx prodular-ui add command`
Free, MIT licensed.

Use when:
- Use as a global cmd+K palette for navigation and actions in apps with many pages.
- Use inline inside a Popover for searchable pickers with more than about ten options.

Avoid:
- Short lists. Use Dropdown menu or Select.
- Free text search over content that needs filters and pagination. Build a search page.

Agent rules:
- Inside CommandDialog, render a Command with CommandInput, CommandList and optionally CommandFooter.
- Always include CommandEmpty with a sentence that suggests what to search for.
- Group results with CommandGroup heading in sentence case: Actions, Go to, Recent.
- Set value on CommandItem when the visible label is not what people type, for example an issue id plus its title.
- Close the dialog in onSelect after running the action.
- Register the cmd+K and ctrl+K listener once at the app level, not per page.

```tsx
<CommandDialog open={open} onOpenChange={setOpen}>
  <Command>
    <CommandInput placeholder="Search or run a command" />
    <CommandList>
      <CommandEmpty>No results.</CommandEmpty>
      <CommandGroup heading="Actions">
        <CommandItem>
          <PlusIcon />
          Create issue
          <CommandShortcut>C</CommandShortcut>
        </CommandItem>
      </CommandGroup>
    </CommandList>
    <CommandFooter>{/* keyboard hints */}</CommandFooter>
  </Command>
</CommandDialog>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| CommandDialog | open / onOpenChange | `boolean / (open: boolean) => void` |  | Controlled state of the palette. |
| CommandDialog | title / description | `string` | "Command palette" | Screen reader title and description. |
| CommandItem | value | `string` |  | Text used for filtering. Defaults to the item's text. |
| CommandItem | onSelect | `(value: string) => void` |  | Runs on click or Enter. |
| Command | shouldFilter | `boolean` | true | Set to false when you filter on the server. |

## Context menu (context-menu)

A menu that opens on right click or long press, with the same items, shortcuts and variants as Dropdown menu.

Install: `npx prodular-ui add context-menu`
Free, MIT licensed.

Use when:
- Use on dense surfaces where right click is expected: file lists, tables, canvases, editors.
- Mirror the actions from the object's visible menu button so mouse users find them in both places.

Avoid:
- Being the only way to reach an action. Touch and keyboard users may never open it.
- Menus on plain text or links, where the browser menu is more useful.

Agent rules:
- Give every item a verb or a destination as its label. Put the icon first, then the label, then ContextMenuShortcut.
- Use variant="destructive" on the item that deletes or signs out, and put it last, after a separator.
- Group related items with ContextMenuGroup and a ContextMenuLabel in sentence case. Labels must be inside a group.
- Icons are 16px and muted automatically. Do not add size or color classes to them.
- Wrap the target area in ContextMenuTrigger. It renders a div, so pass layout classes to it directly.
- Every action in a context menu must also be reachable from a visible button or a keyboard shortcut.

```tsx
<ContextMenu>
  <ContextMenuTrigger className="rounded-xl border border-dashed p-6">Q4 board update.pdf</ContextMenuTrigger>
  <ContextMenuContent className="w-56">
    <ContextMenuItem>
      <PencilIcon />
      Rename
      <ContextMenuShortcut>F2</ContextMenuShortcut>
    </ContextMenuItem>
    <ContextMenuSeparator />
    <ContextMenuItem variant="destructive">
      <Trash2Icon />
      Move to trash
    </ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ContextMenuItem | variant | `"default" \| "destructive"` | "default" | destructive colors the item and its hover state. |
| ContextMenuItem | inset | `boolean` | false | Indents the label to line up with items that have icons. |
| ContextMenuContent | alignOffset / sideOffset | `number` | 4 / 0 | Offset from the pointer. |

## Destructive confirm (destructive-confirm)

Confirms an action that cannot be undone: it names what is lost, can ask people to type a name first, waits for the async action, shows its error without closing, and explains when the action is blocked.

Install: `npx prodular-ui add destructive-confirm`
Free, MIT licensed.

Use when:
- Deleting or revoking things people cannot get back: workspaces, projects, keys, data.
- confirmText for the biggest actions, with a name people have to read: the workspace slug or the key name.
- consequences to list what goes with it, in counts people recognize.

Avoid:
- Reversible actions. Do them at once and offer Undo in a toast.
- Typing to confirm for every delete. Keep it for actions that destroy a lot.

Agent rules:
- Write the title as a question that names the thing: Delete Halcyon Labs?
- Make onConfirm async and throw an Error with a message people can act on; the dialog stays open and shows it.
- Pass disabledReason instead of hiding the action when it is not allowed right now, and say how to unblock it.
- The confirm button stays disabled until the typed text matches exactly; do not lowercase or trim the expected value.

```tsx
<DestructiveConfirm
  trigger={<Button variant="destructive-subtle">Delete workspace</Button>}
  title="Delete Halcyon Labs?"
  consequences={["4,128 invoices"]}
  confirmText="halcyon-labs"
  onConfirm={deleteWorkspace}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| DestructiveConfirm | trigger / open / onOpenChange | `ReactElement / boolean / (open) => void` |  | Uncontrolled with a trigger, or controlled. |
| DestructiveConfirm | title / description | `ReactNode` |  | The question and what happens. |
| DestructiveConfirm | consequences | `ReactNode[]` |  | What is lost, one line each. |
| DestructiveConfirm | confirmText | `string` |  | Text to type before the action is enabled. |
| DestructiveConfirm | confirmLabel / cancelLabel | `string` | "Delete" / "Cancel" | Button labels. |
| DestructiveConfirm | onConfirm | `() => void \| Promise<void>` |  | Runs the action. Throw to show an error. |
| DestructiveConfirm | disabledReason | `ReactNode` |  | Blocks the action and says why. |

## Dialog (dialog)

A modal window for a focused task, such as a short form or a review step, that blocks the page until it is done or dismissed.

Install: `npx prodular-ui add dialog`
Free, MIT licensed.

Use when:
- Use for a short task that must be finished or cancelled before the user goes back to the page: invite people, rename, connect an integration.
- Use size sm for a single field, default for forms up to about six fields, lg for previews, tables or two column layouts.
- Put the primary action last in DialogFooter so it sits on the right, with Cancel to its left.

Avoid:
- Confirming a destructive action. Use Alert dialog, which cannot be dismissed by clicking outside.
- Long multi step flows or anything the user wants to compare with the page behind. Use a Sheet or a full page.
- Nesting cards or tinted panels inside the dialog. Separate sections with border-t or divide-y.

Agent rules:
- Always render DialogTitle. If the design has no visible title, keep it and add className="sr-only".
- Add DialogDescription when the title alone does not explain what happens.
- Open from a DialogTrigger with render={<Button />}, or control it with open and onOpenChange. Do not toggle it with conditional rendering.
- Use DialogClose render={<Button variant="outline" />} for Cancel. Do not write your own close handler for it.
- Wrap long content in DialogBody. Never make the whole DialogContent scroll.
- Pick size from the content: sm, default or lg. Do not set a max-w class yourself unless a size does not fit.

```tsx
<Dialog>
  <DialogTrigger render={<Button variant="outline" />}>Invite teammates</DialogTrigger>
  <DialogContent size="default">
    <DialogHeader>
      <DialogTitle>Invite teammates</DialogTitle>
      <DialogDescription>They get access to every shared project.</DialogDescription>
    </DialogHeader>
    <DialogBody>{/* fields */}</DialogBody>
    <DialogFooter>
      <DialogClose render={<Button variant="outline" />}>Cancel</DialogClose>
      <Button>Send invites</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Dialog | open / onOpenChange | `boolean / (open: boolean) => void` |  | Controlled state. Omit both for uncontrolled with defaultOpen. |
| DialogContent | size | `"sm" \| "default" \| "lg"` | "default" | Max width: 24rem, 32rem or 42rem. |
| DialogContent | showCloseButton | `boolean` | true | Renders the icon button in the top right corner. |
| DialogFooter | showCloseButton | `boolean` | false | Adds an outline Close button before the other actions. |
| DialogTrigger | render | `ReactElement` |  | Renders the trigger as another element, usually a Button. |

## Drawer (drawer)

A swipeable panel from the bottom or side of the screen, built for touch, with snap points and nested drawers.

Install: `npx prodular-ui add drawer`
Free, MIT licensed.

Use when:
- Use on mobile and touch first surfaces for pickers, filters and short forms.
- Use showSwipeHandle on bottom drawers so people know they can swipe it away.
- Use snapPoints when the drawer has a peek state and a full state.

Avoid:
- Desktop editing flows. Use Sheet, which has no swipe physics.
- Long forms. Content taller than the viewport fights with the swipe gesture.

Agent rules:
- Always render DrawerTitle inside DrawerHeader.
- Set swipeDirection on Drawer, not on DrawerContent. down is the default.
- Compose as DrawerHeader, DrawerBody, DrawerFooter. Put scrolling content in DrawerBody.
- On bottom drawers, constrain the inner content with mx-auto max-w-md so it reads well on tablets.

```tsx
<Drawer showSwipeHandle>
  <DrawerTrigger render={<Button variant="outline" />}>Move deal</DrawerTrigger>
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle>Move deal</DrawerTitle>
      <DrawerDescription>Pick the stage this deal is in now.</DrawerDescription>
    </DrawerHeader>
    <DrawerBody>{/* options */}</DrawerBody>
    <DrawerFooter>
      <DrawerClose render={<Button />}>Done</DrawerClose>
    </DrawerFooter>
  </DrawerContent>
</Drawer>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Drawer | swipeDirection | `"down" \| "up" \| "left" \| "right"` | "down" | Direction that dismisses the drawer. Also sets the edge it opens from. |
| Drawer | showSwipeHandle | `boolean` | false | Renders the grab handle. |
| Drawer | snapPoints | `(number \| string)[]` |  | Heights the drawer settles at. |
| Drawer | modal | `boolean` | true | Shows the backdrop and traps focus. |

## Dropdown menu (dropdown-menu)

A list of actions or options that opens from a button, with groups, shortcuts, submenus, checkboxes and radio items.

Install: `npx prodular-ui add dropdown-menu`
Free, MIT licensed.

Use when:
- Use for actions on an object (Edit, Duplicate, Archive) or for view options behind one button.
- Use checkbox items for independent toggles and radio items for a single choice.

Avoid:
- Choosing a value in a form. Use Select or Combobox.
- More than about 12 items. Split them into groups or a submenu, or use Command.
- Navigation between pages. Use Navigation menu or Sidebar.

Agent rules:
- Give every item a verb or a destination as its label. Put the icon first, then the label, then DropdownMenuShortcut.
- Use variant="destructive" on the item that deletes or signs out, and put it last, after a separator.
- Group related items with DropdownMenuGroup and a DropdownMenuLabel in sentence case. Labels must be inside a group.
- Icons are 16px and muted automatically. Do not add size or color classes to them.
- Open from DropdownMenuTrigger with render={<Button />}. Icon only triggers need aria-label.
- Set a width on DropdownMenuContent with w-56 or similar. It never gets narrower than the trigger.
- Pass closeOnClick={false} on checkbox items when people usually toggle several at once.

```tsx
<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline" />}>Options</DropdownMenuTrigger>
  <DropdownMenuContent className="w-56">
    <DropdownMenuGroup>
      <DropdownMenuLabel>Issue</DropdownMenuLabel>
      <DropdownMenuItem>
        <CopyIcon />
        Duplicate
        <DropdownMenuShortcut>⌘D</DropdownMenuShortcut>
      </DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuItem variant="destructive">
      <Trash2Icon />
      Delete
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| DropdownMenuContent | align | `"start" \| "center" \| "end"` | "start" | Alignment against the trigger. |
| DropdownMenuContent | side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | Preferred side. |
| DropdownMenuItem | variant | `"default" \| "destructive"` | "default" | destructive colors the item and its hover state. |
| DropdownMenuItem | inset | `boolean` | false | Indents the label to line up with items that have icons. |
| DropdownMenuCheckboxItem | checked / onCheckedChange | `boolean / (checked: boolean) => void` |  | Controlled check state. |
| DropdownMenuRadioGroup | value / onValueChange | `string / (value: string) => void` |  | Controlled selection for radio items. |

## Hover card (hover-card)

A preview card that appears when hovering or focusing a link, for people, issues or pull requests mentioned in text.

Install: `npx prodular-ui add hover-card`
Free, MIT licensed.

Use when:
- Use to preview a person, issue, pull request or document mentioned inline, so people do not have to open it.
- Keep it to a title, a subtitle and two or three facts.

Avoid:
- Content people must interact with to finish a task. Hover cards do not open on touch.
- Short labels for icon buttons. Use Tooltip.

Agent rules:
- HoverCardTrigger renders a link. Give it a real href so it works without hover.
- Never put the only copy of important information in a hover card.
- Separate the header from details with border-t pt-3, not with a nested box.
- Use side="top" when the trigger sits near the bottom of a scroll area.
- For map markers, chart points and graph nodes, pass anchor={pointAnchor(x, y, container)} to HoverCardContent and control open, instead of hand-positioning a div with popover classes.

```tsx
<HoverCard>
  <HoverCardTrigger href="/people/priya">Priya Raman</HoverCardTrigger>
  <HoverCardContent>
    {/* avatar, name, role */}
  </HoverCardContent>
</HoverCard>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| HoverCard | delay / closeDelay | `number` | 600 / 300 | Milliseconds before opening and closing. |
| HoverCardContent | side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | Preferred side. |
| HoverCardContent | align | `"start" \| "center" \| "end"` | "center" | Alignment against the trigger. |
| HoverCardContent | anchor | `Element \| VirtualAnchor \| RefObject` |  | Positions against something other than the trigger: pointAnchor() for map markers, chart points and the pointer. |
| HoverCardContent | collisionPadding | `number \| Padding` | 5 | Space kept from the viewport edge. |
| HoverCardContent | sticky | `boolean` | false | Keeps the popup in view after the anchor scrolls away. |

## Point anchor (point-anchor)

Anchors Tooltip, Popover and HoverCard to a point instead of a trigger: a map marker, a chart datum, a graph node or the pointer.

Install: `npx prodular-ui add point-anchor`
Free, MIT licensed.

Use when:
- Overlays over canvas, WebGL, SVG or map content that has no DOM element per item.
- pointAnchor(x, y, container) with coordinates relative to the canvas or map container.
- A new anchor when the point moves, for example on the map's move event.

Avoid:
- Hand-positioned divs that copy popover styles. They miss collision handling, focus and dismissal.
- Hover as the only way to reach the information. Offer the same items as a list or in an inspector.

Agent rules:
- Pass anchor to TooltipContent, PopoverContent or HoverCardContent; keep the Root controlled with open.
- Use variant="surface" on tooltips over maps and dark canvases.
- Provide a keyboard path to every marker: a list of buttons, the command palette or an inspector.
- Build anchors with pointAnchor, rectAnchor or pointerAnchor from @/components/ui/point-anchor, not by hand.

```tsx
<Popover open={Boolean(site)} onOpenChange={(o) => !o && setSite(null)}>
  <PopoverContent anchor={pointAnchor(x, y, mapRef.current)}>…</PopoverContent>
</Popover>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| pointAnchor | (x, y, relativeTo?) | `VirtualAnchor` |  | A point, relative to an element when given. |
| rectAnchor | (rect, relativeTo?) | `VirtualAnchor` |  | A rectangle such as a node's bounds. |
| pointerAnchor | (event) | `VirtualAnchor` |  | The pointer position of a mouse or pointer event. |
| TooltipContent | anchor | `Element \| VirtualAnchor \| RefObject` |  | Also on PopoverContent and HoverCardContent. |

## Popover (popover)

A small floating panel anchored to a trigger for quick settings, sharing or filters that do not need a modal.

Install: `npx prodular-ui add popover`
Free, MIT licensed.

Use when:
- Use for a few related controls tied to one button: share settings, a filter, a date, a color.
- Use PopoverHeader with PopoverTitle when the purpose is not obvious from the trigger.

Avoid:
- Lists of actions. Use Dropdown menu, which has keyboard navigation for items.
- Help text on hover. Use Tooltip or Hover card.
- Anything longer than about six controls. Use a Sheet or Dialog.

Agent rules:
- Open from PopoverTrigger with render={<Button variant="outline" />}.
- Set align to match where the trigger sits: start for left aligned toolbars, end for buttons on the right.
- Change width with a w-* class on PopoverContent. The default is w-72.
- Use PopoverClose for buttons that should dismiss the popover, such as Apply.
- Separate sections inside with border-t, never with nested cards.
- For map markers, chart points and graph nodes, pass anchor={pointAnchor(x, y, container)} to PopoverContent and control open, instead of hand-positioning a div with popover classes.

```tsx
<Popover>
  <PopoverTrigger render={<Button variant="outline" />}>Share</PopoverTrigger>
  <PopoverContent align="end">
    <PopoverHeader>
      <PopoverTitle>Share Q4 pricing review</PopoverTitle>
      <PopoverDescription>Anyone in Halcyon with the link can view.</PopoverDescription>
    </PopoverHeader>
    {/* controls */}
  </PopoverContent>
</Popover>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| PopoverContent | side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | Preferred side. Flips when there is no room. |
| PopoverContent | align | `"start" \| "center" \| "end"` | "center" | Alignment against the trigger. |
| PopoverContent | sideOffset | `number` | 6 | Gap to the trigger in px. |
| Popover | modal | `boolean \| "trap-focus"` | false | Locks page scroll and outside clicks when true. |
| PopoverContent | anchor | `Element \| VirtualAnchor \| RefObject` |  | Positions against something other than the trigger: pointAnchor() for map markers, chart points and the pointer. |
| PopoverContent | collisionPadding | `number \| Padding` | 5 | Space kept from the viewport edge. |
| PopoverContent | sticky | `boolean` | false | Keeps the popup in view after the anchor scrolls away. |

## Sheet (sheet)

A panel that slides in from an edge of the screen for editing or inspecting a record without leaving the page.

Install: `npx prodular-ui add sheet`
Free, MIT licensed.

Use when:
- Use right side sheets to edit or inspect one record from a list, so the list stays in context.
- Use bottom sheets on small screens for short pickers. Consider Drawer when swipe to dismiss matters.
- Use the floating variant for quick, read mostly peeks.

Avoid:
- Short confirmations. Use Alert dialog.
- Very wide content such as tables with many columns. Use a page.
- Stacking a sheet on top of a dialog.

Agent rules:
- Always render SheetTitle inside SheetHeader. Use className="sr-only" if it must be hidden.
- Compose as SheetHeader, SheetBody, SheetFooter. Only SheetBody scrolls.
- Use side="right" by default. Use left only for navigation.
- Put Cancel as SheetClose render={<Button variant="outline" />} before the primary action in SheetFooter.
- Override width with a max-w class on SheetContent (for example sm:max-w-lg), never with a pixel width.

```tsx
<Sheet>
  <SheetTrigger render={<Button variant="outline" />}>Edit customer</SheetTrigger>
  <SheetContent side="right">
    <SheetHeader>
      <SheetTitle>Northgate Logistics</SheetTitle>
      <SheetDescription>Changes sync to the CRM.</SheetDescription>
    </SheetHeader>
    <SheetBody>{/* fields */}</SheetBody>
    <SheetFooter>
      <SheetClose render={<Button variant="outline" />}>Cancel</SheetClose>
      <Button>Save changes</Button>
    </SheetFooter>
  </SheetContent>
</Sheet>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| SheetContent | side | `"top" \| "right" \| "bottom" \| "left"` | "right" | Edge the sheet slides in from. |
| SheetContent | variant | `"default" \| "floating"` | "default" | floating adds a margin, a full border and rounded corners. |
| SheetContent | showCloseButton | `boolean` | true | Renders the icon close button. |

## Toast (toast)

A brief notification in a stack at the corner of the screen, with status icons, an optional action and progress for async work.

Install: `npx prodular-ui add toast`
Free, MIT licensed.

Use when:
- Use to confirm that something happened in the background: saved, sent, exported, archived.
- Offer Undo with actionProps instead of asking for confirmation first.
- Use promise() for work that takes more than a second.

Avoid:
- Errors that block the user. Show them inline next to the field or as an Alert.
- More than one toast for the same event.
- Long text. One title of a few words, one sentence of description.

Agent rules:
- Mount <Toaster /> once near the root of the app. Then call toast.add({ title, description, type }) from anywhere.
- Use type success, info, warning, error or loading. destructive is accepted as an alias of error.
- Write the title as the outcome in past tense: Invoice sent, 3 issues archived.
- Add actions with actionProps: { children: "Undo", onClick }. Do not render buttons inside description.
- For a separate stack, create one with createToastManager() and pass it to Toaster as toastManager.

```tsx
// Once, in the root layout
<Toaster />

// Anywhere
toast.add({
  type: "success",
  title: "Invoice sent",
  description: "Northgate Logistics will get it at ap@northgate.co.",
  actionProps: { children: "Undo", onClick: undoSend },
})
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| toast.add | type | `"success" \| "info" \| "warning" \| "error" \| "destructive" \| "loading"` |  | Picks the status icon. |
| toast.add | title / description | `ReactNode` |  | One short title and an optional sentence. |
| toast.add | actionProps | `ButtonProps` |  | Renders an outline action button below the description. |
| toast.add | timeout | `number` | 5000 | Milliseconds before it closes. 0 keeps it open. |
| Toaster | toastManager | `ToastManager` | toast | The manager this stack listens to. |
| Toaster | limit | `number` | 3 | Visible toasts before older ones are hidden. |

## Tooltip (tooltip)

A short, high contrast label that appears on hover or focus, mostly for icon buttons and keyboard shortcuts.

Install: `npx prodular-ui add tooltip`
Free, MIT licensed.

Use when:
- Use on every icon only button to name it, and to teach keyboard shortcuts.
- Keep the text to a few words. Sentence case, no full stop.

Avoid:
- Essential information or anything interactive. Tooltips do not open on touch and cannot hold links.
- Repeating the visible label of a text button.

Agent rules:
- Wrap the app once in TooltipProvider. It is already in the root layout of the docs.
- Use TooltipTrigger render={<Button size="icon" aria-label="..." />}. The aria-label is still required, the tooltip is not a label for screen readers.
- Add shortcuts with Kbd or KbdGroup after the text. Do not style them yourself.
- Pass showArrow={false} only when the tooltip sits flush against a toolbar edge.
- Use variant="surface" for readouts over maps, charts and dark canvases.
- For points without a DOM element, pass anchor={pointAnchor(x, y, container)} from @/components/ui/point-anchor and control open, instead of positioning a div yourself.

```tsx
<Tooltip>
  <TooltipTrigger render={<Button variant="ghost" size="icon-sm" aria-label="Bold" />}>
    <BoldIcon />
  </TooltipTrigger>
  <TooltipContent>
    Bold
    <KbdGroup><Kbd>⌘</Kbd><Kbd>B</Kbd></KbdGroup>
  </TooltipContent>
</Tooltip>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| TooltipContent | side | `"top" \| "right" \| "bottom" \| "left"` | "top" | Preferred side. |
| TooltipContent | showArrow | `boolean` | true | Draws an arrow pointing at the trigger. |
| TooltipContent | sideOffset | `number` | 6 | Gap to the trigger in px. |
| TooltipProvider | delay | `number` | 0 | Shared open delay in ms for every tooltip inside. |
| TooltipContent | variant | `"default" \| "surface"` | "default" | default is the inverted label; surface uses the popover surface, for dark and dense screens and readouts. |
| TooltipContent | anchor | `Element \| VirtualAnchor \| RefObject` |  | Positions against something other than the trigger: pointAnchor() for map markers and chart points. |

## Breadcrumb (breadcrumb)

Shows where the current page sits in the hierarchy and links back to each parent.

Install: `npx prodular-ui add breadcrumb`
Free, MIT licensed.

Use when:
- Pages two or more levels deep: a customer, then an invoice of that customer.
- The top of a detail page, above the title.

Avoid:
- Top level pages. The sidebar already says where you are.
- Showing more than four levels. Collapse the middle ones.

Agent rules:
- End with BreadcrumbPage for the current page. Never make the last item a link.
- Put a BreadcrumbSeparator between items, not after the last one.
- To use a router link, pass render={<Link href="..." />} to BreadcrumbLink.
- Collapse levels beyond four with BreadcrumbEllipsis, wrapped in a DropdownMenuTrigger if the hidden levels should be reachable.
- Use the same labels as the pages they point to.

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/customers">Customers</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Pinecrest Health</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| BreadcrumbLink | render | `ReactElement` |  | Renders the link as another element, such as a framework Link. |
| BreadcrumbSeparator | children | `ReactNode` |  | Custom separator icon. Defaults to a chevron. |
| BreadcrumbPage | children | `ReactNode` |  | The current page. Marked with aria-current="page". |

## Menubar (menubar)

A horizontal bar of menus, like a desktop app's File and Edit menus, for editors and tools with many commands.

Install: `npx prodular-ui add menubar`
Free, MIT licensed.

Use when:
- Use in document editors, design tools and admin consoles where people expect desktop style menus.
- Keep top level labels to one word: File, Edit, View, Help.

Avoid:
- Website navigation. Use Navigation menu.
- Fewer than three menus. Use one or two Dropdown menus instead.

Agent rules:
- Each MenubarMenu needs exactly one MenubarTrigger and one MenubarContent.
- Items, shortcuts, separators, checkbox and radio items behave and look exactly like Dropdown menu. Follow the same rules.
- Show the platform shortcut with MenubarShortcut. Use the symbols ⌘ ⇧ ⌥ on macOS.
- Put MenubarLabel inside a MenubarGroup.
- Use variant="inline" inside a toolbar or command bar instead of overriding the border, background and padding with className.

```tsx
<Menubar>
  <MenubarMenu>
    <MenubarTrigger>File</MenubarTrigger>
    <MenubarContent>
      <MenubarItem>
        New document
        <MenubarShortcut>⌘N</MenubarShortcut>
      </MenubarItem>
    </MenubarContent>
  </MenubarMenu>
</Menubar>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| MenubarContent | align | `"start" \| "center" \| "end"` | "start" | Alignment against the trigger. |
| MenubarItem | variant | `"default" \| "destructive"` | "default" | Same as DropdownMenuItem. |
| Menubar | loopFocus | `boolean` | true | Arrow keys wrap from the last menu to the first. |
| Menubar | variant | `"default" \| "inline"` | "default" | inline drops the card surface, for a menubar inside a toolbar or command bar. |

## Navigation menu (navigation-menu)

The top navigation of a marketing site or docs, with dropdown panels of links that animate between each other.

Install: `npx prodular-ui add navigation-menu`
Free, MIT licensed.

Use when:
- Use for the header of a marketing site, docs or a public app with a few top level sections.
- Use NavigationMenuLinkText inside links to show a title and one line of description.

Avoid:
- In app navigation. Use Sidebar or Tabs.
- More than five or six top level items. Group them into panels.

Agent rules:
- Every link must be a NavigationMenuLink with a real href. Pass render={<NextLink href="..." />} for client routing.
- Top level links without a panel use className={navigationMenuTriggerStyle()} so they match the triggers.
- Set active and aria-current="page" on the link for the current page.
- Give each NavigationMenuContent list a width with sm:w-* so panels do not jump between sizes.
- Keep descriptions to one short line.

```tsx
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Product</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink href="/inbox">
          <InboxIcon />
          <NavigationMenuLinkText title="Shared inbox" description="Email, chat and forms in one queue." />
        </NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink href="/pricing" className={navigationMenuTriggerStyle()}>Pricing</NavigationMenuLink>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| NavigationMenu | align | `"start" \| "center" \| "end"` | "start" | Alignment of the panel against the active trigger. |
| NavigationMenuLink | active | `boolean` | false | Marks the current page. |
| NavigationMenuLinkText | title / description | `ReactNode` |  | Title and one line of copy inside a link. |
| NavigationMenu | value / onValueChange | `string \| null` |  | Controls which panel is open. |

## Pagination (pagination)

Page links for long lists and tables, with previous and next controls and a raised current page.

Install: `npx prodular-ui add pagination`
Free, MIT licensed.

Use when:
- Tables and lists with more rows than fit comfortably, where people need to know their position.
- The footer of a table card, aligned right.

Avoid:
- Feeds and activity logs that people scroll through. Load more on scroll instead.
- Showing every page number. Show at most seven slots.

Agent rules:
- Mark the current page with isActive. It renders aria-current="page".
- Show the first page, the last page and one page on each side of the current one. Fill gaps with PaginationEllipsis.
- Give every PaginationLink an href, or render it with a router link.
- In a table card, put Pagination in CardFooter with className="mx-0 w-auto" and a 13px range summary on the left.
- Format totals with thousands separators: 1,284.

```tsx
<Pagination>
  <PaginationContent>
    <PaginationItem><PaginationPrevious href="?page=3" /></PaginationItem>
    <PaginationItem><PaginationLink href="?page=4" isActive>4</PaginationLink></PaginationItem>
    <PaginationItem><PaginationNext href="?page=5" /></PaginationItem>
  </PaginationContent>
</Pagination>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| PaginationLink | isActive | `boolean` | false | Marks the current page. |
| PaginationLink | size | `Button size` | "icon" | Button size for the link. |
| PaginationPrevious | text | `string` | "Previous" | Label. Hidden below the sm breakpoint. |
| PaginationNext | text | `string` | "Next" | Label. Hidden below the sm breakpoint. |

## Settings nav (settings-nav)

The section list of a settings area: grouped pages, search across labels, descriptions and keywords, and the open page marked. Becomes a native select on phones. SettingsLayout puts it beside the page.

Install: `npx prodular-ui add settings-nav`
Free, MIT licensed.

Use when:
- Settings and preferences with more than four pages.
- keywords for the words people search for that are not in the label, like SSO, 2FA or invite.
- SettingsLayout inside the App shell page area, never as a second app sidebar.

Avoid:
- Fewer than four pages. Use Tabs over the content.
- Putting actions in the nav. Each item opens a page.

Agent rules:
- Describe pages as sections of { id, label, icon?, href?, description?, keywords?, badge? } and pass the open page id as value.
- With routing, give items an href and pass linkComponent={Link}; onValueChange still fires.
- Write descriptions as what people find on the page; they show under results while searching.
- Wrap the page in SettingsLayout so the nav stays sticky on wide screens and becomes a select on phones.

```tsx
<SettingsLayout nav={<SettingsNav sections={sections} value={page} onValueChange={setPage} />}>
  {settingsPage}
</SettingsLayout>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| SettingsNav | sections | `SettingsNavSection[]` |  | Groups of { id, label, items }. |
| SettingsNav | value / onValueChange | `string / (id, item) => void` |  | The open page. |
| SettingsNav | searchable | `boolean` | true | Shows the search field. |
| SettingsNav | linkComponent | `ElementType` | "a" | Renders items with an href. |
| SettingsLayout | nav / children | `ReactNode` |  | The nav column and the page. |

## Sidebar (sidebar)

The main navigation of an app: workspace switcher, sections with counts, projects and the user menu, collapsible to icons.

Install: `npx prodular-ui add sidebar`
Free, MIT licensed.

Use when:
- Use as the primary navigation of an app with more than four sections.
- Put the workspace or account switcher in SidebarHeader and the user menu in SidebarFooter.
- Show counts that need attention with SidebarMenuBadge: unread, assigned, failing.

Avoid:
- Marketing sites. Use Navigation menu.
- Badges on every item. Only show counts people act on.
- Deep nesting. One level of SidebarMenuSub is the limit.

Agent rules:
- Wrap the app in SidebarProvider and put Sidebar and SidebarInset inside it, as siblings.
- Use collapsible="icon" for apps people use all day, and give every SidebarMenuButton a tooltip so the icon rail stays usable.
- Mark the current page with isActive on SidebarMenuButton. Only one item is active.
- Render links with render={<a href="..." />} or your router's Link. The default element is a button.
- Every SidebarMenuButton starts with a 16px lucide icon followed by a <span> label, so the label truncates and hides in icon mode.
- Place SidebarMenuBadge and SidebarMenuAction after the button inside the same SidebarMenuItem.
- To show the sidebar inside a framed preview instead of the full viewport, give SidebarProvider a fixed height with className="relative h-120 min-h-0" and Sidebar className="absolute h-full".

```tsx
<SidebarProvider>
  <Sidebar collapsible="icon">
    <SidebarHeader>{/* workspace switcher */}</SidebarHeader>
    <SidebarContent>
      <SidebarGroup>
        <SidebarGroupLabel>Projects</SidebarGroupLabel>
        <SidebarMenu>
          <SidebarMenuItem>
            <SidebarMenuButton render={<a href="/inbox" />} isActive tooltip="Inbox">
              <InboxIcon />
              <span>Inbox</span>
            </SidebarMenuButton>
            <SidebarMenuBadge>24</SidebarMenuBadge>
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter>{/* user menu */}</SidebarFooter>
    <SidebarRail />
  </Sidebar>
  <SidebarInset>{/* page */}</SidebarInset>
</SidebarProvider>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| SidebarProvider | defaultOpen / open / onOpenChange | `boolean` | true | Expanded state. Persisted in the sidebar_state cookie. |
| Sidebar | collapsible | `"offcanvas" \| "icon" \| "none"` | "offcanvas" | How it collapses on desktop. |
| Sidebar | variant | `"sidebar" \| "floating" \| "inset"` | "sidebar" | floating and inset detach it from the edge. |
| Sidebar | side | `"left" \| "right"` | "left" | Screen edge. |
| SidebarMenuButton | isActive | `boolean` | false | Current page. Adds the accent fill and medium weight. |
| SidebarMenuButton | size | `"sm" \| "default" \| "lg"` | "default" | lg (48px) is for the workspace switcher and the user row. |
| SidebarMenuButton | tooltip | `string \| TooltipContentProps` |  | Shown only when the sidebar is collapsed to icons. |
| SidebarMenuAction | showOnHover | `boolean` | false | Hides the action until the item is hovered or focused. |

## Stepper (stepper)

Shows progress through an ordered flow, horizontal or vertical, with complete, current, upcoming and error states and clickable completed steps.

Install: `npx prodular-ui add stepper`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Flows of three to six steps that must happen in order: onboarding, payout setup, an integration checklist.
- Vertical when steps need a description or the flow lives in a sidebar.

Avoid:
- Steps that can be done in any order. Use a checklist or tabs.
- More than six steps. Group them into stages.
- Letting people jump ahead to upcoming steps. Only completed steps are clickable.

Agent rules:
- Pass value as the zero-based index of the current step and give every StepperItem its step index.
- Pass onValueChange to make completed steps clickable. Without it the stepper is display only.
- Render StepperSeparator in every item except the last.
- Set status="error" on the step that failed and say why in StepperDescription. Do not use color alone.
- Give the Stepper an aria-label that names the flow. The current item gets aria-current="step" automatically.
- Keep titles to one or two words and descriptions to one short line.

```tsx
<Stepper value={step} onValueChange={setStep} aria-label="Payout setup">
  <StepperItem step={0}>
    <StepperTrigger>
      <StepperIndicator />
      <StepperText>
        <StepperTitle>Company</StepperTitle>
        <StepperDescription>Legal name and address</StepperDescription>
      </StepperText>
    </StepperTrigger>
    <StepperSeparator />
  </StepperItem>
</Stepper>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Stepper | value | `number` |  | Zero-based index of the current step. |
| Stepper | onValueChange | `(step: number) => void` |  | Makes completed steps clickable. |
| Stepper | orientation | `"horizontal" \| "vertical"` | "horizontal" | Layout. Horizontal stacks below the sm breakpoint. |
| StepperItem | step | `number` |  | Index of this step. |
| StepperItem | status | `"complete" \| "current" \| "upcoming" \| "error"` |  | Overrides the status derived from value. |
| StepperIndicator | children | `ReactNode` |  | Replaces the number or icon inside the circle. |

## Tabs (tabs)

Switches between views of the same content. A segmented control for short sets and a line variant for page sections.

Install: `npx prodular-ui add tabs`
Free, MIT licensed.

Use when:
- Segmented (default) for two to four short options that filter one view: time ranges, chart modes.
- Line for sections of a page or a panel: Members, Invites, Roles.
- Vertical line tabs for settings with many sections.

Avoid:
- Tabs for steps in a sequence. Use a stepper or a multi step form.
- More than six tabs in one row. Group them or use a vertical list.
- Segmented tabs with long labels or icons only.

Agent rules:
- Give every TabsTrigger a value that matches one TabsContent, and set defaultValue on Tabs.
- Use variant="line" on TabsList for page level navigation, the default variant for in-card filters.
- Mark icons inside triggers with data-icon="inline-start".
- Put counts in a Badge size="sm" variant="secondary" inside the trigger, after the label.
- Pass orientation="vertical" on Tabs, not on TabsList.
- Keep labels to one or two words in sentence case.
- Use width="fit" for content-width tabs and size="sm" in dense panels instead of overriding flex-1 and heights on TabsTrigger.

```tsx
<Tabs defaultValue="members">
  <TabsList variant="line">
    <TabsTrigger value="members">Members</TabsTrigger>
    <TabsTrigger value="invites">Invites</TabsTrigger>
  </TabsList>
  <TabsContent value="members">...</TabsContent>
  <TabsContent value="invites">...</TabsContent>
</Tabs>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Tabs | defaultValue | `string` |  | The tab that is open on first render. |
| Tabs | orientation | `"horizontal" \| "vertical"` | "horizontal" | Lays the list out in a row or a column. |
| TabsList | variant | `"default" \| "line"` | "default" | Segmented track or line with an indicator. |
| TabsTrigger | value | `string` |  | Identifies the tab. Required. |
| TabsTrigger | disabled | `boolean` | false | Shows the tab but blocks selection. |
| TabsList | width | `"fill" \| "fit"` | "fill" | fill stretches segmented tabs across the list; fit sizes each tab to its label. |
| TabsList | size | `"default" \| "sm"` | "default" | sm for toolbars, inspectors and dense panels. |

## Tree (tree)

A hierarchical list with expand and collapse, roving focus, type-ahead, selection, icons, metadata and context menus, for explorers, entity browsers and outlines.

Install: `npx prodular-ui add tree`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Hierarchies people browse and act on: services, folders, accounts, investigations.
- contextMenu for actions on a node, so right click and the keyboard menu key both work.
- useTree with a virtualizer above a few thousand visible rows.

Avoid:
- A Tree for one level of items. Use a list or Item group.
- Navigation between pages. Use Sidebar or SettingsNav.
- Putting buttons inside rows. Use contextMenu or the inspector for row actions.

Agent rules:
- Give Tree an aria-label or aria-labelledby.
- Every node id must be unique in the whole tree. When one record appears in two branches, give each occurrence its own id, for example "case-12/entity-4", and map selection back to the record yourself.
- Put plain text in textValue when label is not a string, so type-ahead and the accessible name work.
- Do not build a tree from Collapsible and divs with role="treeitem". Use Tree or useTree, which handle roving focus, aria-level, aria-setsize and aria-posinset.
- Use selectionMode="none" when rows only open things, and onAction for Enter and double click.
- When rendering rows yourself, spread getItemProps(row) on each TreeItem and keep role="tree" on the container.

```tsx
<Tree
  aria-label="Services"
  items={items}
  defaultExpanded={["prod"]}
  onAction={(node) => open(node.id)}
  contextMenu={(node) => <ContextMenuContent>…</ContextMenuContent>}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Tree | items | `TreeNode[]` |  | Nodes: id, label, textValue, icon, meta, children, disabled. |
| Tree | expanded | `string[]` |  | Open node ids. Use defaultExpanded for uncontrolled. |
| Tree | selectionMode | `"none" \| "single" \| "multiple"` | "single" | multiple sets aria-multiselectable; Cmd or Ctrl click and Space add to the selection. |
| Tree | selected | `string[]` |  | Selected node ids. Use defaultSelected for uncontrolled. |
| Tree | onAction | `(node: TreeNode) => void` |  | Enter or double click. |
| Tree | contextMenu | `(node: TreeNode) => ReactNode` |  | Returns a ContextMenuContent for the node. |
| useTree | returns | `{ rows, getItemProps, toggle, select, focus, activeId }` |  | Flat visible rows and props for each row, for custom or virtualized rendering. |

## Workspace switcher (workspace-switcher)

Switches between organizations and workspaces: searchable, grouped by organization, recent ones first, with create and settings actions. Sizes itself for the App shell sidebar, its collapsed rail and a top navigation.

Install: `npx prodular-ui add workspace-switcher`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Apps where one person belongs to several workspaces, teams or client accounts.
- In the brand slot of App shell, or at the start of a top bar.
- meta for the plan, member count or region, so people pick the right one at a glance.

Avoid:
- Switching between projects inside one workspace. Use a Select or the page nav.
- Hiding create behind the switcher when creating workspaces is rare. Keep onCreate for apps where it is common.

Agent rules:
- Pass workspaces as { id, name, organization?, meta?, logo?, color? }[] and the active id as value.
- Keep recent as the ids of the last workspaces used, newest first; the list shows three.
- On onValueChange, switch the data scope and route to the same page in the new workspace, not to its home.
- Without a logo the initial shows on a tint of a chart color; set color to a var(--chart-N) token for a fixed one.
- The trigger has an accessible name with the active workspace. The list is a combobox: arrows move, Enter switches, typing searches.

```tsx
<WorkspaceSwitcher
  workspaces={workspaces}
  value={workspaceId}
  onValueChange={(id) => router.push(`/${id}/invoices`)}
  recent={recentIds}
  onCreate={openCreateDialog}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| WorkspaceSwitcher | workspaces | `Workspace[]` |  | { id, name, organization?, meta?, logo?, color? }. |
| WorkspaceSwitcher | value / onValueChange | `string / (id, workspace) => void` |  | The active workspace, controlled. |
| WorkspaceSwitcher | recent | `string[]` |  | Recently used ids, newest first. |
| WorkspaceSwitcher | onCreate / onSettings | `() => void` |  | Adds Create workspace and Workspace settings. |
| WorkspaceSwitcher | searchFrom | `number` | 6 | Search appears from this many workspaces. |
| WorkspaceLogo | workspace / size | `Workspace / "sm" \| "md"` |  | The square mark on its own, for lists and settings. |

## Accordion (accordion)

A stack of sections separated by hairlines that expand one or several at a time.

Install: `npx prodular-ui add accordion`
Free, MIT licensed.

Use when:
- FAQs and help content where people read one answer at a time.
- Long settings or details that most people do not need to see at once.

Avoid:
- Hiding content people need to compare side by side. Show it in a table.
- Nesting accordions inside accordions.
- A single item. Use Collapsible instead.

Agent rules:
- Give every AccordionItem a unique value. Pass defaultValue as an array of values to open items on load.
- Pass multiple on Accordion when sections are independent, such as settings. Leave it off for FAQs.
- Write triggers as questions or nouns in sentence case. Keep them to one line.
- Do not add borders or backgrounds to items. Items are separated by hairlines already.
- Put the accordion directly in CardContent when it lives in a card. Add border-t on Accordion if it follows other content.
- Use variant="section" for inspector and property sections instead of restyling AccordionTrigger.
- className on AccordionContent styles the content wrapper, text color included; use panelClassName for the animated panel itself.

```tsx
<Accordion defaultValue={["seats"]}>
  <AccordionItem value="seats">
    <AccordionTrigger>How are seats billed?</AccordionTrigger>
    <AccordionContent>...</AccordionContent>
  </AccordionItem>
</Accordion>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Accordion | multiple | `boolean` | false | Allows more than one item to be open. |
| Accordion | defaultValue | `any[]` |  | Values of the items open on first render. |
| AccordionItem | value | `any` |  | Identifies the item. |
| AccordionItem | disabled | `boolean` | false | Blocks opening the item. |
| Accordion | variant | `"default" \| "section"` | "default" | section gives compact headers for inspector panels and property editors. |
| AccordionContent | panelClassName | `string` |  | Classes for the animated panel. className styles the content inside it, text color included. |

## App shell (app-shell)

The frame of an app: navigation, top bar and the scrolling page. Four layouts share one nav model: collapsible sidebar, a rail that peeks open on hover, a double sidebar and top navigation. Phones get a sheet, and the collapsed state is remembered.

Install: `npx prodular-ui add app-shell`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- The outer frame of a SaaS or AI app, once, around every signed-in page.
- sidebar for most apps; rail when the page needs the width, like editors and boards; double for products with modules that each have several pages; topnav for apps with five or fewer areas.
- brand for a WorkspaceSwitcher or a logo, user for AppShellUser, actions for search, notifications and one primary action.

Avoid:
- Nesting shells. Settings and detail pages go inside the page, with Settings nav or Master detail.
- More than about nine items in a section. Group them, or move rare pages to a module in the double layout.
- Rebuilding the nav per page. Keep one nav model and change activeId.

Agent rules:
- Describe navigation once as AppNavSection[] with id, label, icon, href, badge and items for child pages, and pass the current page id as activeId.
- For client routing pass linkComponent={Link} from next/link. onNavigate receives every click; call event.preventDefault() only when you route yourself.
- Set storageKey (for example "app") so the collapsed sidebar and the double sidebar's page list survive reloads.
- Use contained when the shell sits inside another layout or a preview; otherwise it takes the full viewport height.
- Put WorkspaceSwitcher in brand and AppShellUser in user. Both size themselves for the expanded sidebar, the collapsed rail and the top navigation.
- Cmd or Ctrl+B toggles the sidebar. Every icon-only button has a tooltip and an accessible name; do not remove labels from nav items.
- Use fill with a Workspace or a full-bleed map or canvas, so the page area does not scroll.

```tsx
<AppShell
  layout="sidebar"
  nav={nav}
  activeId={pathname}
  linkComponent={Link}
  brand={<WorkspaceSwitcher ... />}
  user={<AppShellUser name="Maya Okafor" initials="MO">...</AppShellUser>}
  breadcrumb={<Breadcrumb>...</Breadcrumb>}
  storageKey="app"
>
  {page}
</AppShell>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AppShell | layout | `"sidebar" \| "rail" \| "double" \| "topnav"` | "sidebar" | Where the navigation goes. |
| AppShell | nav | `AppNavSection[]` |  | Sections of { id, label, icon, href, badge, items, description }. |
| AppShell | footerNav | `AppNavItem[]` |  | Pinned to the bottom of the sidebar, like Help and Settings. |
| AppShell | activeId | `string` |  | The current page. Its parents open and highlight. |
| AppShell | onNavigate | `(item, event) => void` |  | Every nav click. |
| AppShell | linkComponent | `ElementType` | "a" | Renders links, for example Next.js Link. |
| AppShell | brand / user / breadcrumb / actions | `ReactNode` |  | Slots for the workspace, the account, the page path and top bar actions. |
| AppShell | storageKey | `string` |  | Remembers collapsed states in localStorage. |
| AppShell | defaultCollapsed | `boolean` | true for rail | Starts with the nav as icons. |
| AppShell | contained | `boolean` | false | Fills the parent instead of the viewport. |
| AppShellUser | name / email / initials / image | `string` |  | The signed-in person. Put DropdownMenuItems inside for the menu. |
| AppShell | fill | `boolean` | false | The page area fills the space under the top bar and does not scroll, for a Workspace or a full-bleed canvas. |

## Aspect ratio (aspect-ratio)

Keeps media and previews at a fixed width to height ratio as the layout resizes.

Install: `npx prodular-ui add aspect-ratio`
Free, MIT licensed.

Use when:
- Images, videos, maps and document previews whose space must be reserved before they load.
- Rows of thumbnails that must line up.

Avoid:
- Text content. Let it set its own height.

Agent rules:
- Pass ratio as a division, for example ratio={16 / 9} or ratio={3 / 4}.
- Put rounding, border and overflow-hidden on AspectRatio itself, not on a wrapper.
- A direct img child fills the box with object-cover. Always give it an alt.

```tsx
<AspectRatio ratio={16 / 9} className="overflow-hidden rounded-xl">
  <img src="/cover.jpg" alt="Usage pricing walkthrough" />
</AspectRatio>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AspectRatio | ratio | `number` |  | Width divided by height. Required. |

## Card (card)

The one container for grouped content: a header, a body and an optional footer on a raised surface.

Install: `npx prodular-ui add card`
Free, MIT licensed.

Use when:
- Group content that belongs together and is read or acted on as a unit: a plan, a chart, a settings section.
- Put the single most relevant control for the card in CardAction, top right.
- Use CardFooter for the actions that commit or leave the card. It always gets a top divider.

Avoid:
- Cards inside cards, or bordered and tinted boxes inside a card. Separate content with divide-y, border-t and spacing.
- A grid of small cards for KPIs. Use one card with a divided strip.
- Cards for every element on a page. If it has no header and no clear boundary, it probably does not need one.

Agent rules:
- Never nest Card inside Card. Inside a card, split sections with border-t or divide-y on the content.
- Give every card a CardTitle. Add CardDescription only when it says something the title does not.
- Place a Table directly in CardContent. The content drops its side padding and the table aligns its first and last columns with the card.
- Use size="sm" for cards narrower than about 320px.
- Do not override the card padding with p-* classes. The spacing comes from --card-spacing so density themes keep working.
- Use size="xs" for dense surfaces such as map cards and inspector sections instead of overriding --card-spacing.
- Use variant="plain" for a card-shaped section inside a surface that already is one.

```tsx
<Card>
  <CardHeader>
    <CardTitle>Team plan</CardTitle>
    <CardDescription>Billed annually</CardDescription>
    <CardAction>
      <Badge variant="success">Active</Badge>
    </CardAction>
  </CardHeader>
  <CardContent>...</CardContent>
  <CardFooter>
    <Button>Upgrade plan</Button>
  </CardFooter>
</Card>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| CardHeader | className | `string` |  | Add border-b to divide the header from the content. The bottom padding follows. |
| CardAction | children | `ReactNode` |  | One button, badge or menu, aligned to the top right of the header. |
| CardFooter | children | `ReactNode` |  | Actions. Rendered below a hairline divider. |
| Card | size | `"default" \| "sm" \| "xs"` | "default" | Padding and gaps. xs is for inspectors, map cards and dense panels. |
| Card | variant | `"default" \| "plain"` | "default" | plain drops the border, background and shadow. |

## Collapsible (collapsible)

Shows and hides one section of content with a trigger, animating its height.

Install: `npx prodular-ui add collapsible`
Free, MIT licensed.

Use when:
- One optional section: advanced settings, more rows, payment details.
- Building blocks for custom disclosures, such as a step in an agent trace.

Avoid:
- Several related sections. Use Accordion.
- Hiding errors or required fields.

Agent rules:
- Render the trigger as a Button with render={<Button variant="ghost" size="icon-sm" aria-label="..." />} when it is icon only.
- Rotate trigger chevrons with group-data-panel-open on the trigger, not with your own state.
- Keep the content's layout the same as the visible part so it reads as a continuation.
- Height animates automatically and respects reduced motion. Do not add your own transition.

```tsx
<Collapsible>
  <CollapsibleTrigger>Payment details</CollapsibleTrigger>
  <CollapsibleContent>...</CollapsibleContent>
</Collapsible>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Collapsible | open | `boolean` |  | Controlled open state. |
| Collapsible | defaultOpen | `boolean` | false | Uncontrolled initial state. |
| Collapsible | onOpenChange | `(open: boolean) => void` |  | Called when the trigger toggles. |
| CollapsibleTrigger | render | `ReactElement` |  | Renders the trigger as another element, usually a Button. |

## Master detail (master-detail)

A list beside the selected record. Side by side and resizable on wide screens, with empty and loading states; on phones the record takes the screen with a Back button.

Install: `npx prodular-ui add master-detail`
Free, MIT licensed.

Use when:
- Inboxes, queues and lists where people go through records one by one: approvals, tickets, messages, leads.
- storageKey so the list width people chose survives reloads.
- loading while the selected record is fetched, so the pane does not flash empty.

Avoid:
- Records that need the full page to edit. Open them on their own route.
- Comparing many columns. Use Data table or Data grid, and open the record in a Sheet.

Agent rules:
- Pass the list as rows of buttons with aria-current on the selected one, and the selected record as detail, or null when nothing is selected.
- Set onBack to clear the selection; on phones it is the only way back to the list.
- Give MasterDetail a height through its parent (h-full in a page, or a fixed height in a card); both panes scroll on their own.
- Keep listHeader for the title, count, search or filters of the list.

```tsx
<MasterDetail
  list={rows}
  detail={selected ? <Record id={selected} /> : null}
  onBack={() => setSelected(null)}
  storageKey="approvals"
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| MasterDetail | list / detail | `ReactNode / ReactNode \| null` |  | The list and the selected record. |
| MasterDetail | listHeader | `ReactNode` |  | A bar over the list. |
| MasterDetail | onBack / backLabel | `() => void / string` | "Back" | Back to the list on phones. |
| MasterDetail | empty | `ReactNode` |  | Shown when nothing is selected. |
| MasterDetail | loading | `boolean` | false | A skeleton in the detail pane. |
| MasterDetail | resizable / defaultListSize / storageKey | `boolean / number / string` | true / 38 | The draggable divider, the list width in percent and where to remember it. |

## Page header (page-header)

The title area of an app screen: breadcrumb, title, description, a meta row for status and owners, actions on the right and optional tabs on the bottom border.

Install: `npx prodular-ui add page-header`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- The top of every app screen, so titles, actions and tabs sit in the same place everywhere.
- The meta row for two to four facts people look for first on a record: status, owner, plan, dates.

Avoid:
- More than one primary action. Move the rest to outline buttons or a More menu.
- A description longer than two lines. Link to docs instead.
- Putting the page header inside a Card.

Agent rules:
- Render exactly one PageHeaderTitle per screen. It is the h1.
- Put actions in PageHeaderActions with the primary button last. Icon-only buttons need aria-label.
- Use PageHeaderTabs with a Tabs list set to variant="line" for sub-navigation of the record. Do not also pass bordered.
- Use PageHeaderMetaItem for each fact, with a lucide icon or Avatar first and plain text after. Use Status for state, never a colored text span.
- Use bordered on list pages without tabs so the header separates from the content below.

```tsx
<PageHeader>
  <PageHeaderBreadcrumb>{breadcrumb}</PageHeaderBreadcrumb>
  <PageHeaderRow>
    <PageHeaderContent>
      <PageHeaderTitle>Northwind Logistics</PageHeaderTitle>
      <PageHeaderMeta>
        <PageHeaderMetaItem><CreditCardIcon />Scale plan</PageHeaderMetaItem>
      </PageHeaderMeta>
    </PageHeaderContent>
    <PageHeaderActions>
      <Button variant="outline">Edit</Button>
      <Button>Create invoice</Button>
    </PageHeaderActions>
  </PageHeaderRow>
  <PageHeaderTabs>{tabs}</PageHeaderTabs>
</PageHeader>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| PageHeader | bordered | `boolean` | false | Bottom border and padding. Leave off when using PageHeaderTabs. |
| PageHeaderBreadcrumb | children | `Breadcrumb` |  | Sits above the title. |
| PageHeaderHeading | children | `ReactNode` |  | Title with an optional avatar, logo or Status on the same line. |
| PageHeaderMeta | children | `PageHeaderMetaItem[]` |  | A wrapping row of 13px facts. |
| PageHeaderActions | children | `Button[]` |  | Right-aligned on wide screens, below the title on small ones. |
| PageHeaderTabs | children | `Tabs` |  | Line tabs whose underline sits on the header border. |

## Panel header (panel-header)

The strip at the top of a panel: icon, title, count, status and actions in one row the height of a control, with an optional fold toggle.

Install: `npx prodular-ui add panel-header`
Free, MIT licensed.

Use when:
- The top of every pane in a Workspace, and of sidebars and inspectors.
- PanelHeaderCount for the number of items in the pane.
- Icon buttons in PanelHeaderActions for filtering, sorting and more.

Avoid:
- PanelHeader as a page title. Use PageHeader.
- More than three actions. Move the rest into a DropdownMenu.
- Long titles. The title truncates; keep it to a word or two.

Agent rules:
- Use PanelHeaderTitle with the right level for the outline: 2 under the page title, 3 inside a panel.
- Every icon-only action needs aria-label.
- Give PanelHeaderCount an aria-label when the number alone is ambiguous, for example "128 signals".
- Use PanelHeaderToggle only inside a Collapsible, and pass label.

```tsx
<PanelHeader>
  <PanelHeaderIcon><RadarIcon /></PanelHeaderIcon>
  <PanelHeaderTitle>Signals</PanelHeaderTitle>
  <PanelHeaderCount>128</PanelHeaderCount>
  <PanelHeaderActions>
    <Button variant="ghost" size="icon-xs" aria-label="Filter"><FilterIcon /></Button>
  </PanelHeaderActions>
</PanelHeader>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| PanelHeader | bordered | `boolean` | true | Draws the bottom border. |
| PanelHeaderTitle | level | `2 \| 3 \| 4` | 2 | Heading level. |
| PanelHeaderToggle | label | `string` | "Toggle panel" | Accessible name of the fold button. |

## Resizable (resizable)

Panels that people can resize by dragging a hairline handle, with keyboard support.

Install: `npx prodular-ui add resizable`
Free, MIT licensed.

Use when:
- Split views where people decide how much space each side gets: inbox and detail, editor and preview, query and results.
- Inside one container. The panels share its border.

Avoid:
- Layouts that never need resizing. Use a fixed grid.
- Borders or cards inside each panel. The handle is the divider.

Agent rules:
- Give the parent of ResizablePanelGroup a fixed height. Panels fill it.
- Pass orientation="horizontal" or "vertical" to ResizablePanelGroup.
- Set defaultSize and minSize on every ResizablePanel as percentage strings, for example defaultSize="40%".
- Add withHandle on handles between panels that people are likely to drag. Leave it off for subtle splits.
- Put the group inside one bordered container (rounded-xl border bg-card) and do not add borders inside the panels.

```tsx
<ResizablePanelGroup orientation="horizontal">
  <ResizablePanel defaultSize="40%">...</ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize="60%">...</ResizablePanel>
</ResizablePanelGroup>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ResizablePanelGroup | orientation | `"horizontal" \| "vertical"` |  | Direction the panels are laid out in. |
| ResizablePanel | defaultSize | `number \| string` |  | Initial size, for example "40%". |
| ResizablePanel | minSize | `number \| string` |  | Smallest size the panel can be dragged to. |
| ResizableHandle | withHandle | `boolean` | false | Shows a visible grip on the divider. |

## Scroll area (scroll-area)

A scroll container with a slim themed scrollbar that stays out of the way until you hover or scroll.

Install: `npx prodular-ui add scroll-area`
Free, MIT licensed.

Use when:
- Fixed height regions inside a layout: a side panel, a popover list, a log.
- Horizontal rows of items that do not wrap.

Avoid:
- The whole page. Let the document scroll natively.
- Nested scroll areas in the same direction.

Agent rules:
- Give ScrollArea a fixed height (h-72) or max height for vertical scrolling. Without it nothing scrolls.
- For horizontal scrolling, add <ScrollBar orientation="horizontal" /> as a child and make the content w-max.
- Put padding on the content inside the ScrollArea, not on the ScrollArea itself, so the scrollbar sits at the edge.
- The viewport is focusable for keyboard scrolling. Do not remove its focus ring.

```tsx
<ScrollArea className="h-72">
  <div className="p-4">...</div>
</ScrollArea>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ScrollArea | className | `string` |  | Size of the scroll region, for example h-72. |
| ScrollBar | orientation | `"vertical" \| "horizontal"` | "vertical" | Which scrollbar to render. The vertical one is included by default. |

## Separator (separator)

A 1px hairline that divides content inside a container, horizontally or vertically.

Install: `npx prodular-ui add separator`
Free, MIT licensed.

Use when:
- Splitting sections inside a card, popover or panel instead of adding another box.
- Dividing inline metadata such as counts and dates.

Avoid:
- Separators between every element. Spacing alone often groups better.
- Thicker or colored rules. Hierarchy comes from type and spacing.

Agent rules:
- Prefer divide-y or border-t on a list over many Separator elements.
- For a vertical Separator, give the parent a fixed height (h-4 or h-5) and items-center.
- Separator is decorative by default. Do not use it to convey meaning.

```tsx
<Separator />
<Separator orientation="vertical" />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Separator | orientation | `"horizontal" \| "vertical"` | "horizontal" | Direction of the line. |

## Status bar (status-bar)

The strip along the bottom of a desktop app for connection state, background work, counts and keyboard hints.

Install: `npx prodular-ui add status-bar`
Free, MIT licensed.

Use when:
- Desktop apps and workspaces that run background work or hold a connection.
- Short readings: Connected, 3 selected, Synced 14:31.
- live on items that change on their own.

Avoid:
- Actions people need often. Put them in the toolbar or command palette.
- Notifications. Use Toast.
- More than five or six items. It truncates on small screens.

Agent rules:
- Put StatusBar as the last child of the app frame, under the Workspace.
- Group related items in StatusBarGroup; use StatusBarSpacer to push the rest right.
- Use Status for connection state, not colored text.
- Give StatusBarProgress a label naming the work.

```tsx
<StatusBar>
  <StatusBarGroup>
    <StatusBarItem live><Status variant="success" size="xs">Connected</Status></StatusBarItem>
  </StatusBarGroup>
  <StatusBarSpacer />
  <StatusBarItem>3 selected</StatusBarItem>
</StatusBar>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| StatusBarItem | live | `boolean` | false | Announces changes politely to screen readers. |
| StatusBarProgress | value | `number` |  | 0 to 100. |
| StatusBarProgress | label | `string` |  | Names the work, for example "Ledger sync". |

## Workspace (workspace)

Docked, resizable panes for workstation screens: explorer, canvas, inspector and a bottom panel, collapsible to rails, remembered across reloads and stacked on small screens.

Install: `npx prodular-ui add workspace`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Screens people keep open all day and arrange to their task: consoles, editors, investigation tools.
- AppShell with fill around it, so the page area does not scroll.
- PanelHeader at the top of each panel.

Avoid:
- Workspace for regular SaaS pages. Use the page layouts and MasterDetail.
- More than four panes. Put secondary views in tabs inside a pane.
- Collapsing by dragging only. Add WorkspacePanelToggle buttons, and a hotkey if the app has them.

Agent rules:
- Alternate panes and WorkspaceHandle: panel, handle, main, handle, panel.
- Give every WorkspacePanel a unique id and a label; the label names the rail and the toggle.
- Set storageKey so sizes and collapsed panes persist.
- Wrap the screen in AppShell fill (or a parent with a fixed height). Workspace fills its parent and never scrolls itself; panes scroll inside.
- Use WorkspacePanelToggle or useWorkspacePanel(id).toggle for buttons and shortcuts instead of resizing panels yourself.
- Pass sizes in rem or px strings ("18rem"), numbers for pixels, or unitless strings for percentages.

```tsx
<AppShell layout="rail" fill nav={nav}>
  <Workspace storageKey="ops">
    <WorkspacePanel id="explorer" label="Explorer" collapsible>…</WorkspacePanel>
    <WorkspaceHandle />
    <WorkspaceMain>
      <WorkspaceArea>…</WorkspaceArea>
      <WorkspaceHandle />
      <WorkspacePanel id="timeline" label="Timeline" side="bottom" collapsible>…</WorkspacePanel>
    </WorkspaceMain>
    <WorkspaceHandle />
    <WorkspacePanel id="inspector" label="Inspector" side="end" collapsible>…</WorkspacePanel>
  </Workspace>
</AppShell>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Workspace | storageKey | `string` |  | Keeps sizes and collapsed panes in localStorage. |
| Workspace | stackBelow | `number` | 768 | Viewport width in px under which panes stack vertically. |
| WorkspacePanel | id | `string` |  | Unique id, also used by WorkspacePanelToggle. |
| WorkspacePanel | label | `string` |  | Names the pane, its rail and its toggle. |
| WorkspacePanel | side | `"start" \| "end" \| "bottom"` | "start" | Where it docks. |
| WorkspacePanel | collapsible | `boolean` | false | Folds to a rail below minSize or from its toggle. |
| WorkspacePanel | defaultSize | `number \| string` | "18rem" | Also minSize and maxSize. |
| WorkspacePanelToggle | panel | `string` |  | The id of the panel it folds and opens. |
| AppShell | fill | `boolean` | false | The page area fills the space under the top bar and does not scroll. |

## Announcement (announcement)

A small pill above a hero pointing to news: a release, a beta or a post. A link when it has an href.

Install: `npx prodular-ui add announcement`
Free, MIT licensed.

Use when:
- One piece of news above the hero title.
- badge for a single word like New or Beta.

Avoid:
- More than one announcement on a page.
- Long sentences. It truncates on small screens.

Agent rules:
- Place it directly above SectionHeader in the hero, centered with it.
- Keep the text under about 50 characters and link to the full story.

```tsx
<Announcement badge="New" href="/blog/ai-form-fill">AI form fill reads receipts</Announcement>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Announcement | badge | `ReactNode` |  | A word in front. |
| Announcement | href | `string` |  | Makes it a link with an arrow. |

## Backdrop (backdrop)

A quiet pattern behind a section: a hairline grid, dots or a glow in the theme's AI colors, faded toward the edges. Pure CSS, nothing moves.

Install: `npx prodular-ui add backdrop`
Free, MIT licensed.

Use when:
- Behind a hero or a closing call to action, once or twice per page.
- grid-glow for heroes, dots for quiet sections.

Avoid:
- Behind text-heavy sections, where it competes with reading.
- Animating it. It is meant to sit still.

Agent rules:
- Put Backdrop first inside a Section; Section isolates it so it stays behind the content.
- Pick fade bottom for patterns that should end where the next section starts.

```tsx
<Section size="lg">
  <Backdrop variant="grid-glow" />
  <SectionHeader as="h1" size="lg" title="..." />
</Section>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Backdrop | variant | `"grid" \| "dots" \| "glow" \| "grid-glow"` | "grid" | The pattern. |
| Backdrop | fade | `"radial" \| "bottom" \| "none"` | "radial" | Where it fades out. |

## Bento grid (bento-grid)

A grid of cards of different sizes for showing what a product does, each with a live visual on top and a title and sentence below.

Install: `npx prodular-ui add bento-grid`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- The product's few best ideas, with a live glimpse of each.
- Rows that add up to six columns: lg plus sm, md plus md, or full.

Avoid:
- Text only cards. Use Feature grid.
- More than six cards.

Agent rules:
- Sizes are sm (a third), md (half), lg (two thirds) and full. Make each row add up to the full width.
- Fill visual with real components scaled down, not screenshots.

```tsx
<BentoGrid>
  <BentoCard size="lg" title="..." visual={...} />
  <BentoCard size="sm" title="..." visual={...} />
</BentoGrid>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| BentoCard | size / tall | `"sm" \| "md" \| "lg" \| "full" / boolean` | "sm" | Width and two rows. |
| BentoCard | title / description / visual | `ReactNode` |  | Content. |
| BentoCard | delay | `number` | 0 | Stagger when scrolling in. |

## Changelog (changelog)

Release notes on a page: the date and version in a column that stays in view, then tags, the title, a live picture, the story and smaller changes. Every entry has its own link.

Install: `npx prodular-ui add changelog`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- New, Improved and Fixed as the first tag; they get their own colors.
- A sentence on why the change matters, not only what changed.

Avoid:
- Internal ticket numbers and code names.
- A picture on every entry. Save it for changes people can see.

Agent rules:
- Use a stable id per entry; it is the anchor people link to.
- Pass timeZone so dates do not shift by a day on the server.

```tsx
<Section>
  <Changelog timeZone="UTC" entries={releases} />
</Section>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Changelog | entries | `{ id, date, version?, title, tags?, summary, media?, items? }[]` |  | Newest first. |
| Changelog | timeZone | `string` |  | Time zone for the dates, like UTC. |

## CTA band (cta-band)

The closing call to action of a page: one sentence, a line of support and the buttons, in a panel with a soft glow so it reads as the end.

Install: `npx prodular-ui add cta-band`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Once, at the end of a page, before the footer.

Avoid:
- In the middle of a page.
- More than two actions.

Agent rules:
- Repeat the hero's primary action; do not invent a new one.
- It is a Section itself; place it directly in the page, not inside another Section.

```tsx
<CtaBand title="..." actions={<Button size="lg">Start free trial</Button>} />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| CtaBand | title / lead / actions / note | `ReactNode` |  | Content. |

## FAQ (faq)

Questions people ask before buying, answered in place: the heading and a way to ask more on one side, the questions in an accordion on the other.

Install: `npx prodular-ui add faq`
Free, MIT licensed.

Use when:
- Near the end of landing and pricing pages.
- contact with a way to reach a person.

Avoid:
- Marketing claims dressed as questions.
- More than about eight questions. Link to a help center instead.

Agent rules:
- Write questions the way customers ask them, answers in two or three plain sentences.
- Put it in a Section; it lays out its own two columns.

```tsx
<Section>
  <Faq items={faqs} contact={<a href="/contact">Talk to us</a>} />
</Section>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Faq | items | `{ question, answer }[]` |  | Questions and answers. |
| Faq | title / lead / contact | `ReactNode` | "Questions, answered" | The side column. |

## Feature grid (feature-grid)

Features in a grid separated by hairlines rather than boxes: an icon, a title and a sentence each, optionally a link. Cells rise in one after another.

Install: `npx prodular-ui add feature-grid`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- What the product does, in three or six short items.
- href on items that have their own page.

Avoid:
- More than nine items.
- Paragraphs. One sentence per feature.

Agent rules:
- Pass features as { icon, title, description, href? }. Keep titles to four words or fewer.
- columns 3 by default; 2 for longer descriptions.

```tsx
<FeatureGrid features={features} />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| FeatureGrid | features | `{ icon?, title, description, href? }[]` |  | The features. |
| FeatureGrid | columns | `2 \| 3 \| 4` | 3 | Columns on wide screens. |

## Feature rows (feature-rows)

Features told one at a time: the text on one side and a live picture on the other, switching sides row by row. Stacks on phones with the picture under the text.

Install: `npx prodular-ui add feature-rows`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- For the three or four features that sell the product, each with a picture worth looking at.
- Live components in media, so the picture matches the product and themes with it.

Avoid:
- More than four rows. Use a Feature grid for the rest.
- Screenshots of text. Build the picture from components or leave it out.

Agent rules:
- Put it in a Section. Keep bullets to four short lines.
- Give media its own padding; the panel around it has none.

```tsx
<Section>
  <FeatureRows rows={[{ title, description, bullets, media: <Preview /> }]} />
</Section>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| FeatureRows | rows | `{ eyebrow?, title, description, bullets?, action?, media }[]` |  | One row per feature. Odd rows put the picture first on wide screens. |

## Hero section (hero-section)

The first section of a landing page: announcement, h1, lead, actions and a note, with the product beside or below it over a quiet backdrop. Parts rise in one after another.

Install: `npx prodular-ui add hero-section`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- The top of a landing page, once.
- centered with a wide ProductFrame; split when the media is a card or an illustration.

Avoid:
- More than two actions.
- Long leads. Two sentences at most.

Agent rules:
- Title is the promise in one sentence; lead says how in one or two.
- Put the primary action first and a quiet secondary one second.
- note is for reassurance like a free trial line, not features.

```tsx
<HeroSection
  announcement={<Announcement badge="New" href="/blog">...</Announcement>}
  title="..."
  lead="..."
  actions={<Button size="lg">Start free trial</Button>}
  media={<ProductFrame tilt fade>...</ProductFrame>}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| HeroSection | variant | `"centered" \| "split"` | "centered" | Layout. |
| HeroSection | announcement / title / lead / actions / note | `ReactNode` |  | The text parts. |
| HeroSection | media | `ReactNode` |  | The product. |
| HeroSection | backdrop | `Backdrop variant or "none"` | "grid-glow" | The pattern behind it. |

## Logo cloud (logo-cloud)

Customer or partner logos under a line of proof: a calm grid, or a marquee that pauses on hover, off screen and for reduced motion.

Install: `npx prodular-ui add logo-cloud`
Free, MIT licensed.

Use when:
- Right under the hero, as proof.
- The grid for six logos, the marquee for eight or more.

Avoid:
- Logos you do not have permission to show.
- Color logos. They are shown muted and grayscale on purpose.

Agent rules:
- Pass logos as { name, logo } with an SVG logo; name is what screen readers hear.
- Write the title as a fact with a number, like Finance teams at 2,400 companies run on Relay.

```tsx
<LogoCloud variant="marquee" title="..." logos={logos} />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| LogoCloud | logos | `{ name, logo }[]` |  | Logos and their names. |
| LogoCloud | variant | `"grid" \| "marquee"` | "grid" | Layout. |
| LogoCloud | title | `ReactNode` |  | The line of proof. |

## Marketing footer (marketing-footer)

The footer of a marketing site: brand and a line about the product, link columns, an optional newsletter signup, and a bottom row with legal text, small links and social profiles.

Install: `npx prodular-ui add marketing-footer`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- The bottom of every marketing page.
- Three or four columns of links people look for: product, company, developers, resources.
- newsletter only if someone will actually send it.

Avoid:
- Repeating the whole navbar.
- More than about six links per column.

Agent rules:
- Pass columns as { title, links: [{ label, href }] }[].
- newsletter.onSubscribe(email) calls your email provider; throw with a message to show an error.
- Social items need an icon and a label; the label is the accessible name.
- It shares Section's container, so pass the same width as your sections.

```tsx
<MarketingFooter brand={<Logo />} columns={columns} legal="© 2026 Relay" bottomLinks={legalLinks} />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| MarketingFooter | brand / description | `ReactNode` |  | Logo and one line about the product. |
| MarketingFooter | columns | `{ title, links }[]` |  | Link columns. |
| MarketingFooter | newsletter | `{ title?, description?, onSubscribe }` |  | Email signup with states. |
| MarketingFooter | legal / bottomLinks / social | `ReactNode / FooterLink[] / { label, href, icon }[]` |  | The bottom row. |
| FooterNewsletter | onSubscribe | `(email) => Promise<void>` |  | The signup on its own. |

## Marketing navbar (marketing-navbar)

The header of a marketing site: brand, links with menus and descriptions, and actions like Sign in and a call to action. Sticks to the top and shows its edge once the page scrolls; on phones the links move into a panel.

Install: `npx prodular-ui add marketing-navbar`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- The top of every marketing page, once.
- Menus for groups of three or more pages; plain links for the rest.
- Two actions at most: a quiet Sign in and one call to action.

Avoid:
- More than five top level items.
- Inside the app. Use App shell there.

Agent rules:
- Describe links as { label, href } or { label, items: [{ label, href, description?, icon? }] }.
- Pass linkComponent={Link} from next/link for client routing.
- Keep sticky on; the edge and shadow appear only after scrolling, so the hero stays clean.
- Its width matches Section; pass the same width as your sections if you change it.

```tsx
<MarketingNavbar
  brand={<Logo />}
  links={links}
  actions={<><Button variant="ghost">Sign in</Button><Button>Start free</Button></>}
  linkComponent={Link}
/>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| MarketingNavbar | brand | `ReactNode` |  | The logo, usually a link home. |
| MarketingNavbar | links | `MarketingNavLink[]` |  | Links and menus. |
| MarketingNavbar | actions | `ReactNode` |  | Right side buttons, also shown in the phone panel. |
| MarketingNavbar | sticky | `boolean` | true | Sticks to the top. |
| MarketingNavbar | width / linkComponent | `Section width / ElementType` |  | Container width and the link element. |

## Newsletter signup (newsletter-signup)

An email signup as its own band: the pitch on one side and the field on the other, with sending, done and error states.

Install: `npx prodular-ui add newsletter-signup`
Free, MIT licensed.

Use when:
- At the end of a changelog or blog, where people already want more.
- note to say how often you send.

Avoid:
- A second signup on the same page as the footer newsletter.
- Promising content you do not send.

Agent rules:
- Throw an Error with a readable message from onSubscribe; it is shown as is.
- Put it in a Section with size sm.

```tsx
<Section size="sm">
  <NewsletterSignup title="Product updates" onSubscribe={subscribe} />
</Section>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| NewsletterSignup | onSubscribe | `(email: string) => Promise<void> \| void` |  | Subscribes the address. Throw to show the error. |
| NewsletterSignup | title / lead / note | `ReactNode` |  | The pitch and the line under the field. |
| NewsletterSignup | action | `string` | "Subscribe" | The button text. |

## Pricing table (pricing-table)

Plans side by side for a pricing page: monthly and yearly, one highlighted plan, features as plain lines, and an optional comparison table below. Prices and buttons line up across plans.

Install: `npx prodular-ui add pricing-table`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Pricing pages and the pricing section of a landing page.
- compare for the full table under the cards.

Avoid:
- Changing a subscription in the app. Use Plan picker.
- More than four tiers.

Agent rules:
- Pass tiers with price.monthly and price.yearly as numbers, or a string like Custom.
- action is your own Button or link; keep the highlighted tier's button solid and the others outline.
- Keep descriptions to about two lines; the table reserves two lines so prices align.

```tsx
<PricingTable tiers={tiers} compare={compare} yearlyNote="2 months free" />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| PricingTable | tiers | `PricingTier[]` |  | { id, name, description, price, unit?, action, highlight?, featuresIntro?, features }. |
| PricingTable | compare | `{ group, rows }[]` |  | The comparison table. |
| PricingTable | defaultPeriod / yearlyNote / currency | `string` | "yearly" / "" / "USD" | Period and formatting. |

## Product frame (product-frame)

Shows a real screen of your product on a marketing page: the content renders at app width and scales to fit inside a quiet window frame, with optional tilt and fade. Live components, never a stale screenshot.

Install: `npx prodular-ui add product-frame`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Heroes and feature sections that show the product.
- tilt and fade in a centered hero.

Avoid:
- Small frames under about 400px wide; the scaled text gets too small to read.
- Interactive demos. The content is inert on purpose.

Agent rules:
- Render live components or an iframe of your app inside. Pick contentWidth as the width your screen was designed for.
- Pass label with what the screen shows; the content itself is hidden from assistive tech.

```tsx
<ProductFrame address="app.relay.com" tilt fade label="The overview">
  <DashboardPreview />
</ProductFrame>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| ProductFrame | contentWidth / aspect | `number` | 1280 / 16:10 | Layout width before scaling and the frame's shape. |
| ProductFrame | chrome / address | `"window" \| "none" / string` | "window" | The top bar and its address. |
| ProductFrame | tilt / fade | `boolean` | false | Lean back and fade into the page. |
| ProductFrame | label | `string` |  | What the screen shows. |

## Reveal (reveal)

Lets content rise into place the first time it scrolls into view, with an optional delay for staggering. Content shows at once with reduced motion or without scripts.

Install: `npx prodular-ui add reveal`
Free, MIT licensed.

Use when:
- Section headers, cards and media on marketing pages.
- delay to stagger items in a row, around 60 to 90ms apart.

Avoid:
- Inside the app. Work screens should not move as people scroll.
- Wrapping a whole page in one Reveal.

Agent rules:
- Wrap each block that should rise, not its container and its children both.
- useInView returns a ref and a flag for your own scroll-triggered effects.

```tsx
<Reveal delay={70}>
  <Card />
</Reveal>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Reveal | delay | `number` | 0 | Milliseconds before it rises. |
| useInView | (options?) | `[ref, inView]` |  | True once the element is 10% visible. |

## Section (section)

A band of a marketing page with one vertical rhythm and one content width, plus Section header for the eyebrow, title, lead and actions. Stacked sections keep even spacing without margins of their own.

Install: `npx prodular-ui add section`
Free, MIT licensed.

Use when:
- Every band of a landing or marketing page, so spacing and widths stay the same from top to bottom.
- size lg for the hero and the final call to action, default for the rest, sm for logo strips.
- SectionHeader at the top of each section; size lg and as h1 only in the hero.

Avoid:
- Margins between sections. Section's padding is the rhythm.
- Inside the app. Use Page header and the App shell there.

Agent rules:
- Build pages as a stack of Section elements. Do not add margin or padding classes for vertical spacing.
- Use width narrow for text-heavy sections like FAQ, wide for bento grids and product frames.
- tone muted alternates bands; add divider when two sections share the same tone.
- SectionHeader adds space under itself only when content follows, so headers alone stay tight.
- Write titles as sentences in sentence case, leads as one or two plain sentences. For a dark band, wrap the section in an element with className dark and the page's data-theme.

```tsx
<Section size="lg">
  <SectionHeader as="h1" size="lg" align="center" title="..." lead="..." actions={<Button>Start</Button>} />
</Section>
<Section tone="muted">
  <SectionHeader eyebrow="Collections" title="..." />
  {content}
</Section>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Section | size | `"sm" \| "default" \| "lg" \| "none"` | "default" | Vertical padding that scales with the screen. |
| Section | width | `"narrow" \| "default" \| "wide" \| "full"` | "default" | Content width: 48, 72 or 80rem, or the full screen. |
| Section | tone / divider | `"default" \| "muted" / boolean` |  | Background and a hairline on top. |
| SectionHeader | eyebrow / title / lead / actions | `ReactNode` |  | The parts of the heading. |
| SectionHeader | align / size / as | `"start" \| "center" / "default" \| "lg" / "h1" \| "h2" \| "h3"` | "start" / "default" / "h2" | Alignment, title scale and heading level. |
| sectionContainer | ({ width }) | `string` |  | The container classes, for your own full-width parts. |

## Stats strip (stats-strip)

Three or four numbers that prove the point, side by side with hairlines between them. They count up the first time they scroll into view.

Install: `npx prodular-ui add stats-strip`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Proof with numbers people can check.
- detail for where the number comes from.

Avoid:
- Vanity numbers without a source.
- More than four items.

Agent rules:
- Pass value as a number with prefix, suffix and decimals; never a preformatted string.
- Labels finish the sentence the number starts.

```tsx
<StatsStrip items={[{ value: 87, suffix: "%", label: "of invoices paid on time" }]} />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| StatsStrip | items | `{ value, label, prefix?, suffix?, decimals?, detail? }[]` |  | The numbers. |

## Team grid (team-grid)

The people behind the product: a photo or initials, name, role and an optional line each, in three or four columns.

Install: `npx prodular-ui add team-grid`
Free, MIT licensed.

Use when:
- On about and careers pages.
- A line about each person for the founders and leads.

Avoid:
- Stock photos. Initials are better than a fake face.
- Job titles nobody outside the company understands.

Agent rules:
- Give every photo the same crop and background.
- columns 3 for teams of six or nine.

```tsx
<Section>
  <TeamGrid members={team} />
</Section>
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| TeamGrid | members | `{ name, role, initials?, photo?, bio?, href? }[]` |  | The people, in the order shown. |
| TeamGrid | columns | `3 \| 4` | 4 | Columns on wide screens. |

## Testimonials (testimonials)

Quotes from customers: TestimonialHighlight for the one that matters most, large and centered, and TestimonialWall for many short ones in columns.

Install: `npx prodular-ui add testimonials`
Requires a Prodular UI Pro license: https://ui.prodular.co/pricing. Run `npx prodular-ui login` first.

Use when:
- Proof from named people with roles.
- One highlight and a wall of three to nine.

Avoid:
- Quotes you made up or edited beyond recognition.
- Star ratings without names.

Agent rules:
- Pass { quote, name, role, company?, avatar?, initials?, logo? }. Quotes in the wall stay under about 40 words.
- Only use real quotes with permission; demos use fictional people.

```tsx
<TestimonialHighlight testimonial={featured} />
<TestimonialWall testimonials={quotes} />
```

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| TestimonialHighlight | testimonial | `Testimonial` |  | One large quote. |
| TestimonialWall | testimonials | `Testimonial[]` |  | Many short quotes. |