@create-ui/cli 0.5.8 → 0.6.0

package/dist/skills/createui/reference/input-otp.md

@@ -0,0 +1,130 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/input-otp.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/input-otp.md -->
+
+# input-otp
+
+One-time passcode input with per-character slots; outline/filled variants and rounded/pill/square/underline shapes
+
+Install: `npx @create-ui/cli add input-otp`
+
+## Import
+
+```tsx
+import { InputOTP } from "@/components/ui/input-otp"
+```
+
+Also exported: `InputOTPGroup`, `InputOTPSlot`, `InputOTPSeparator`, `inputOTPSlotVariants`
+
+## InputOTP props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| shape | `rounded \| pill \| square \| underline` | `rounded` |
+| size | `lg \| md \| sm` (Resolution chain: explicit prop ?? wrapping Field's size ?? lg. Do not set it manually inside a Field.) | `lg` |
+| variant | `outline \| filled` | `outline` |
+| containerClassName | `string` (Merged onto the visible flex wrapper (default gap-component-lg). Disabled state auto-adds opacity-50 here.) | - |
+| invalid | `boolean` (Falls back to Field's invalid; flips every slot to data-state=error at once, overriding filled/typing/focused visuals (disabled still wins).) | `false` |
+| children | `ReactNode` | - |
+
+Extends `Omit< React.ComponentProps<typeof OTPInput>, "containerClassName" | "size" | "render" | "ref" >`.
+
+## Examples
+
+From `input-otp-demo`:
+
+```tsx
+"use client"
+
+import { REGEXP_ONLY_DIGITS } from "input-otp"
+
+import {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSeparator,
+  InputOTPSlot,
+} from "@/components/ui/input-otp"
+
+export default function InputOTPDemo() {
+  return (
+    <InputOTP maxLength={6} pattern={REGEXP_ONLY_DIGITS}>
+      <InputOTPGroup>
+        <InputOTPSlot index={0} />
+        <InputOTPSlot index={1} />
+        <InputOTPSlot index={2} />
+        <InputOTPSeparator />
+        <InputOTPSlot index={3} />
+        <InputOTPSlot index={4} />
+        <InputOTPSlot index={5} />
+      </InputOTPGroup>
+    </InputOTP>
+  )
+}
+```
+
+From `input-otp-with-field`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+import { REGEXP_ONLY_DIGITS } from "input-otp"
+
+import {
+  Field,
+  FieldContent,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@/components/ui/field"
+import {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSeparator,
+  InputOTPSlot,
+} from "@/components/ui/input-otp"
+
+export default function InputOTPWithField() {
+  const [value, setValue] = React.useState("")
+  const invalid = value.length > 0 && value.length < 6
+
+  return (
+    <Field size="md" invalid={invalid}>
+      <FieldLabel>Verification code</FieldLabel>
+      <FieldContent>
+        <InputOTP
+          maxLength={6}
+          value={value}
+          onChange={setValue}
+          pattern={REGEXP_ONLY_DIGITS}
+        >
+          <InputOTPGroup>
+            <InputOTPSlot index={0} />
+            <InputOTPSlot index={1} />
+            <InputOTPSlot index={2} />
+            <InputOTPSeparator />
+            <InputOTPSlot index={3} />
+            <InputOTPSlot index={4} />
+            <InputOTPSlot index={5} />
+          </InputOTPGroup>
+        </InputOTP>
+        <FieldDescription>
+          Enter the 6-digit code sent to your phone.
+        </FieldDescription>
+        <FieldError>Please enter all 6 digits.</FieldError>
+      </FieldContent>
+    </Field>
+  )
+}
+```
+
+More: `npx @create-ui/cli view input-otp` or MCP `get_item_examples_from_registries` with "input-otp-demo" / "input-otp-example".
+
+## When to use
+Fixed-length verification codes: 2FA, SMS/email confirmation, recovery codes. One hidden input drives per-character visual slots. Not for variable-length text (use Input), formatted values like card numbers, phone numbers, or dates (CreditCardInput, PhoneInput, DateInput), or bounded numeric values (InputStepper).
+
+## Gotchas
+- Children composition is mandatory; the upstream `render` prop is Omit-ted from the type. Render one `InputOTPSlot` per character with a zero-based `index` covering `maxLength`, wrapped in `InputOTPGroup` (a layout-only div; slots read state from the upstream OTPInputContext).
+- `shape`/`size`/`variant`/`disabled`/`invalid` are set only on the root `InputOTP` and reach slots via internal context. `InputOTPSlot` accepts only div props plus `index`; variant props on it do nothing.
+- Slots are NOT fused like shadcn's. Each slot is a standalone bordered box and `InputOTPGroup` just lays them out with `gap-component-lg`. Do not add shadcn-style `first:rounded-l` / shared-border / divide hacks.
+- Field cascade covers all three of `size`, `disabled`, `invalid` (prop ?? Field ctx ?? default). `<Field invalid>` alone puts the whole OTP in error state; pair it with `FieldError` for the message.
+- `InputOTPSeparator` defaults to the Remix `RiSubtractLine` minus icon and scales its text size from the root size context (default svg stays `size-6`). Pass children to replace it; never import a lucide icon for this.
+- The component sets no input `pattern` itself; examples always pass `pattern={REGEXP_ONLY_DIGITS}` imported from the `input-otp` package to restrict input to digits.

package/dist/skills/createui/reference/input-stepper.md

@@ -0,0 +1,120 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/input-stepper.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/input-stepper.md -->
+
+# input-stepper
+
+Numeric input with increment and decrement buttons; connected or separated variant, min/max/step clamping
+
+Install: `npx @create-ui/cli add input-stepper`
+
+## Import
+
+```tsx
+import { InputStepper } from "@/components/ui/input-stepper"
+```
+
+## InputStepper props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `connected \| separated` | - |
+| value | `number` (Clamped to [min, max] on every render in controlled mode; out-of-range state is never displayed) | - |
+| defaultValue | `number` | - |
+| onValueChange | `(value: number) => void` (Receives the clamped number, not an event; fires only when the clamped result differs from the current value) | - |
+| min | `number` | - |
+| max | `number` | - |
+| step | `number` (Drives +/- clicks AND native ArrowUp/ArrowDown stepping; both move by the same amount) | - |
+| size | `xs \| sm \| md` (Resolves explicit prop ?? parent Field size ?? md; the effective default is md, not sm) | - |
+| invalid | `boolean` | - |
+| disabled | `boolean` | - |
+| decrementLabel | `string` | - |
+| incrementLabel | `string` | - |
+
+Extends `React.ComponentProps<"input">`.
+
+## Examples
+
+From `input-stepper-demo`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+
+import { InputStepper } from "@/components/ui/input-stepper"
+
+export default function InputStepperDemo() {
+  const [value, setValue] = React.useState(1)
+
+  return (
+    <div className="w-[240px]">
+      <InputStepper
+        value={value}
+        onValueChange={setValue}
+        min={0}
+        max={10}
+        aria-label="Quantity"
+      />
+    </div>
+  )
+}
+```
+
+From `input-stepper-in-field`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+
+import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
+import { InputStepper } from "@/components/ui/input-stepper"
+
+export default function InputStepperInField() {
+  const [quantity, setQuantity] = React.useState(1)
+
+  return (
+    <div className="flex w-[320px] flex-col gap-6">
+      <Field size="md">
+        <FieldLabel htmlFor="qty">Quantity</FieldLabel>
+        <InputStepper
+          id="qty"
+          value={quantity}
+          onValueChange={setQuantity}
+          min={1}
+          max={10}
+        />
+        <FieldDescription>
+          Inherits size from <code>{'<Field size="md" />'}</code>.
+        </FieldDescription>
+      </Field>
+
+      <Field size="sm" invalid>
+        <FieldLabel htmlFor="qty-invalid">Quantity (invalid)</FieldLabel>
+        <InputStepper id="qty-invalid" defaultValue={3} />
+        <FieldDescription>
+          Inherits <code>invalid</code> from Field.
+        </FieldDescription>
+      </Field>
+
+      <Field size="xs" disabled>
+        <FieldLabel htmlFor="qty-disabled">Quantity (disabled)</FieldLabel>
+        <InputStepper id="qty-disabled" defaultValue={3} variant="separated" />
+      </Field>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view input-stepper` or MCP `get_item_examples_from_registries` with "input-stepper-demo" / "input-stepper-example".
+
+## When to use
+A number-only input flanked by -/+ buttons for bounded counts: cart quantities, seats, tickets. Do NOT use it for free-form or unbounded numeric entry (use Input with type="number"), for picking from a fixed list (Select), or for boolean toggles (Switch/Checkbox).
+
+## Gotchas
+- Closed composite: only `InputStepper` is exported; the buttons, cell, and inner input are internal. Never rebuild it shadcn-style from `Input` + two `Button`s; restyle via `className` on the root or the `data-slot="input-stepper-*"` attributes.
+- The state API is `onValueChange(value: number)`; native `value`/`defaultValue`/`onChange` are Omit-ed from the prop type. `defaultValue` is clamped to `[min, max]` at mount and `value` on every render.
+- The -/+ buttons auto-disable at `min`/`max`, but only while a value is present; with an empty input both stay enabled.
+- `size`/`invalid`/`disabled` resolve as explicit prop ?? parent `Field` context ?? default, so inside a `Field` do not repeat them on the stepper (see input-stepper-in-field). The fallback `"sm"` visible in the source is unreachable; the real default size is `md`.
+- The -/+ buttons are `tabIndex={-1}` and call `preventDefault` on mousedown, so clicking them never moves focus and Tab reaches only the input. This is intentional; do not "fix" the tab order.
+- Clearing the input (uncontrolled) sets the value to `undefined` without firing `onValueChange`; in controlled mode the clear is ignored. From empty, the next +/- click seeds from `clamp(0, min, max)`, not from the last value.
+- Native browser spinners are hidden via CSS, but ArrowUp/ArrowDown still step the native `<input type="number">` by `step`.

package/dist/skills/createui/reference/input.md

@@ -0,0 +1,118 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/input.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/input.md -->
+
+# input
+
+Single-line text input rendered in a focusable InputShell; size and invalid/disabled/loading state inherit from Field
+
+Install: `npx @create-ui/cli add input`
+
+## Import
+
+```tsx
+import { Input, InputProvider, InputShell } from "@/components/ui/input"
+```
+
+Also exported: `inputVariants`, `inputShellVariants`, `useInputContext`
+
+## Input props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution is prop ?? InputProvider context ?? Field context ?? sm; inside a Field omit it and let the Field's size cascade.) | `sm` |
+
+Extends `React.ComponentProps<"input">`.
+
+## InputProvider props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution is prop ?? InputProvider context ?? Field context ?? sm; inside a Field omit it and let the Field's size cascade.) | `md` |
+| invalid | `boolean` | `false` |
+| disabled | `boolean` | `false` |
+| loading | `boolean` | `false` |
+| children | `ReactNode` | - |
+
+## Examples
+
+From `input-demo`:
+
+```tsx
+import { Input } from "@/components/ui/input"
+
+export default function InputDemo() {
+  return (
+    <div className="w-100">
+      <Input type="email" placeholder="Email" />
+    </div>
+  )
+}
+```
+
+From `input-states`:
+
+```tsx
+import { Field, FieldLabel } from "@/components/ui/field"
+import { Input } from "@/components/ui/input"
+
+export default function InputStates() {
+  return (
+    <div className="flex w-100 flex-col gap-10 py-4">
+      <Field>
+        <FieldLabel htmlFor="input-states-default">Default</FieldLabel>
+        <Input
+          id="input-states-default"
+          type="email"
+          placeholder="name@example.com"
+        />
+      </Field>
+      <Field invalid>
+        <FieldLabel htmlFor="input-states-invalid">Invalid</FieldLabel>
+        <Input
+          id="input-states-invalid"
+          type="email"
+          defaultValue="not-an-email"
+        />
+      </Field>
+      <Field disabled>
+        <FieldLabel htmlFor="input-states-disabled">Disabled</FieldLabel>
+        <Input
+          id="input-states-disabled"
+          type="email"
+          placeholder="name@example.com"
+        />
+      </Field>
+      <Field loading>
+        <FieldLabel htmlFor="input-states-loading">Loading</FieldLabel>
+        <Input
+          id="input-states-loading"
+          type="email"
+          placeholder="Checking availability…"
+        />
+      </Field>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view input` or MCP `get_item_examples_from_registries` with "input-demo" / "input-example".
+
+## When to use
+Single-line text values: emails, names, search queries, URLs, file pickers. It is a one-element drop-in (`<Input />` wraps itself in a styled shell) that inherits size/invalid/disabled/loading from a surrounding `Field`. Do NOT use it for multi-line text (`Textarea`), option picking (`Select`), fields with icons/buttons/addons (`InputGroup` + `InputGroupControl`), OTP codes (`InputOTP`), step-controlled numbers (`InputStepper`), or dates/phones/cards (`DateInput` / `PhoneInput` / `CreditCardInput`).
+
+## Gotchas
+- Shell is auto-conditional: standalone `<Input />` wraps itself in `InputProvider` + `InputShell`; when any input context already exists it renders only the bare `<input>`. So in manual composition state props must go on `InputProvider`, not on `Input`, or the shell never sees them:
+
+```tsx
+<InputProvider size="md" invalid>
+  <InputShell>
+    <Input placeholder="Email" />
+  </InputShell>
+</InputProvider>
+```
+
+- Unlike shadcn, the border/focus/disabled visuals are on the shell `<div>`, not the input element. `className` on `Input` cannot change the border or radius; target `InputShell` (or `[data-slot="input-shell"]`) instead. Focus uses `outline-*`, never `ring-*`.
+- `loading` is not an `Input` prop; it arrives from `Field` (or `InputProvider`) context. It silently forces `readOnly` on the input and `pointer-events-none` + `aria-busy` on the shell.
+- For the error treatment prefer `<Field invalid>`. On a standalone `Input`, only a boolean `aria-invalid` is forwarded to the shell; the string form `aria-invalid="true"` sets the attribute on the inner input (red text via `aria-invalid:` CSS) but the shell keeps its normal border.
+- Clicking empty shell space focuses the input via mousedown delegation; clicks on nested interactive elements (input, button, a, [role='button'], etc.) are skipped. Mark custom interactive children with `data-input-control` so the shell does not steal their clicks.
+- Inside `InputGroup` use `InputGroupControl`, not raw `Input`: the control re-renders `Input` with `h-auto p-0` so the group shell owns spacing, and adds the password show/hide toggle for `type="password"`. A raw `Input` there renders bare but keeps its own size padding.
+- Hidden cleanups baked in: browser autofill background is suppressed and the native webkit clear (X) button for `type="search"` is hidden, so add your own clear affordance (e.g. an `InputGroup` button) if one is needed.

package/dist/skills/createui/reference/label.md

@@ -0,0 +1,121 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/label.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/label.md -->
+
+# label
+
+Form label with companion slots like LabelRequired, LabelOptional, LabelDescription and LabelCount; size follows Field
+
+Install: `npx @create-ui/cli add label`
+
+## Import
+
+```tsx
+import { Label, LabelBlock, LabelMain, LabelIcon, LabelRequired, LabelOptional, LabelDescription, LabelBadgeSlot, LabelInfoSlot, LabelCount } from "@/components/ui/label"
+```
+
+Also exported: `useLabelSize`
+
+## Label props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<typeof LabelPrimitive.Root>`.
+
+## LabelBlock props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+| asChild | `boolean` | `false` |
+
+Extends `React.ComponentProps<"div">`.
+
+## LabelIcon props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## LabelRequired props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## LabelOptional props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## LabelDescription props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<"p">`.
+
+## LabelInfoSlot props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## LabelCount props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## Examples
+
+From `label-demo`:
+
+```tsx
+import { Field } from "@/components/ui/field"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+
+export default function LabelDemo() {
+  return (
+    <Field className="w-full max-w-xs">
+      <Label htmlFor="label-demo">Full name</Label>
+      <Input id="label-demo" placeholder="Ada Lovelace" />
+    </Field>
+  )
+}
+```
+
+More: `npx @create-ui/cli view label` or MCP `get_item_examples_from_registries` with "label-demo" / "label-example".
+
+## When to use
+Caption for a form control (Input, Textarea, Select, Checkbox), with optional slots for an icon, required/optional marker, badge, info tooltip, description, and counter. For the full field stack with error wiring, compose `Field` with `FieldLabel` / `FieldDescription` / `FieldError` instead; for helper text rendered below the control use `FieldDescription`, not `LabelDescription` (which belongs in the label row).
+
+## Gotchas
+- Invalid/disabled looks are not props on Label. They are driven entirely by the wrapping `Field`'s `data-invalid` / `data-disabled` group attributes (`group-data-[...]/field`); a standalone Label cannot show those states.
+- `Label` and `LabelBlock` both re-provide the resolved size to nested slots via context, so `LabelIcon`, `LabelRequired`, `LabelCount`, etc. auto-match. Setting `size` on each slot is redundant and fights the cascade.
+- `LabelIcon` and `LabelRequired` are `aria-hidden` decoration: a `LabelRequired` asterisk does not make the field required, so still set `required` on the control. `LabelOptional` is NOT `aria-hidden`; its "(Optional)" text is announced.
+- Rich rows have a fixed composition: `LabelDescription` is a sibling of `Label` inside `LabelMain`, never a child of `Label`; `LabelCount` sits as `LabelBlock`'s trailing child, outside `LabelMain`.
+
+```tsx
+<LabelBlock>
+  <LabelMain>
+    <Label htmlFor="bio"><LabelIcon>...</LabelIcon>Bio<LabelRequired /></Label>
+    <LabelDescription>Shown on your profile.</LabelDescription>
+  </LabelMain>
+  <LabelCount>0/300</LabelCount>
+</LabelBlock>
+```
+- This is not shadcn's one-element Label: no `peer-disabled` styling, no CVA. State styling cascades from `Field`'s group attributes, and slots replace ad-hoc spans.

package/dist/skills/createui/reference/pagination.md

@@ -0,0 +1,157 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/pagination.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/pagination.md -->
+
+# pagination
+
+Page navigation with first/prev/next/last actions and ellipsis; compact or ButtonGroup-backed compact-grouped variant
+
+Install: `npx @create-ui/cli add pagination`
+
+## Import
+
+```tsx
+import { Pagination, PaginationContent, PaginationLink, PaginationFirst, PaginationPrevious, PaginationNext, PaginationLast, PaginationEllipsis } from "@/components/ui/pagination"
+```
+
+## Pagination props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `compact \| compact-grouped` (compact-grouped renders PaginationContent as a soft md ButtonGroup (one fused surface); compact renders standalone buttons with gap-1.) | `compact-grouped` |
+| shape | `rounded \| pill` (Settable on the root Pagination only; children have no shape prop and pick it up from context.) | `rounded` |
+
+Extends `React.ComponentProps<"nav">`.
+
+## PaginationLink props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| asChild | `boolean` | - |
+| isActive | `boolean` (Writes aria-current=page and data-active; in compact-grouped it maps to ButtonGroupItem active with aria-pressed deliberately stripped.) | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## PaginationFirst props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| asChild | `boolean` | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## PaginationPrevious props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| asChild | `boolean` | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## PaginationNext props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| asChild | `boolean` | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## PaginationLast props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| asChild | `boolean` | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## Examples
+
+From `pagination-demo`:
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from "@/components/ui/pagination"
+
+export default function PaginationDemo() {
+  return (
+    <Pagination>
+      <PaginationContent>
+        <PaginationPrevious />
+        <PaginationLink>1</PaginationLink>
+        <PaginationLink>2</PaginationLink>
+        <PaginationLink isActive>3</PaginationLink>
+        <PaginationEllipsis />
+        <PaginationLink>10</PaginationLink>
+        <PaginationNext />
+      </PaginationContent>
+    </Pagination>
+  )
+}
+```
+
+From `pagination-with-link`:
+
+```tsx
+"use client"
+
+import {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from "@/components/ui/pagination"
+
+export default function PaginationWithLink() {
+  return (
+    <Pagination>
+      <PaginationContent>
+        <PaginationPrevious asChild>
+          <a href="?page=2" />
+        </PaginationPrevious>
+        <PaginationLink asChild>
+          <a href="?page=1">1</a>
+        </PaginationLink>
+        <PaginationLink asChild>
+          <a href="?page=2">2</a>
+        </PaginationLink>
+        <PaginationLink asChild isActive>
+          <a href="?page=3" aria-current="page">
+            3
+          </a>
+        </PaginationLink>
+        <PaginationEllipsis />
+        <PaginationLink asChild>
+          <a href="?page=10">10</a>
+        </PaginationLink>
+        <PaginationNext asChild>
+          <a href="?page=4" />
+        </PaginationNext>
+      </PaginationContent>
+    </Pagination>
+  )
+}
+```
+
+More: `npx @create-ui/cli view pagination` or MCP `get_item_examples_from_registries` with "pagination-demo" / "pagination-example".
+
+## When to use
+Numbered page navigation for long tables, search results, and archives where users jump between page ranges. Do not use it for switching sibling panels in place (use TabMenu), hierarchical trails (use Breadcrumb), or a plain prev/next pair without page numbers (use two Buttons). For a value-picking segmented control, use SegmentedControl or ButtonGroup directly.
+
+## Gotchas
+- There is no PaginationItem wrapper (shadcn habit): controls are direct children of PaginationContent. PaginationContent is mandatory; in the default compact-grouped variant it IS the ButtonGroup, so dropping it loses the fused surface and sizing.
+- PaginationLink renders a `<button type="button">` by default, not an `<a>` like shadcn. For URL navigation use asChild with an anchor or router Link; isActive keeps working because aria-current and active styling are forwarded onto the slotted element (see pagination-with-link).
+- First/Previous/Next/Last inject their default arrow icon even with asChild: pass an empty anchor and the icon plus the built-in "Go to ... page" aria-label are supplied automatically; any children of the slotted element are replaced by the icon. Without asChild, `children` replaces the icon instead.
+```tsx
+<PaginationNext asChild>
+  <a href="?page=4" />
+</PaginationNext>
+```
+- With asChild, `disabled` is not forwarded as a native attribute; the slotted element gets `aria-disabled` plus `tabIndex={-1}` and pointer-events-none styling, so disabled links stay in the DOM but become inert and unfocusable.
+- No size prop exists anywhere; compact-grouped is hard-wired to ButtonGroup soft/md and compact items to a fixed h-8. Do not try to pass size to the content or items.
+- PaginationEllipsis is presentational (`role="presentation"`, `aria-hidden`) with a built-in sr-only "More pages" hint; `children` only swaps the visible glyph. Render real PaginationLinks for clickable pages (see pagination-controlled for the windowing pattern).