# Iconiq UI > Detailed AI-readable product index for Iconiq UI ## Product Summary Iconiq UI is an open-source React component library built around the shadcn registry workflow. Browse motion-powered UI primitives, install them as local files, and adapt them directly inside modern interfaces. ## Discovery Endpoints - Overview: https://iconiqui.com/llms.txt - Full index: https://iconiqui.com/llms-full.txt - JSON catalog: https://iconiqui.com/ai-index.json ## Guides - Overview URL: https://iconiqui.com Summary: Homepage with the full live component playground and the primary installation path for the registry. - Introduction URL: https://iconiqui.com/introduction Summary: Product overview, design principles, and the delivery model behind the Iconiq component library. - Installation URL: https://iconiqui.com/installation Summary: Installation guide for the shadcn registry flow, direct registry JSON URLs, and sample component entries. - Marketplace URL: https://iconiqui.com/marketplace Summary: VS Code Marketplace install page for the Iconiq UI extension, with links to the extension README and registry guides. - MCP URL: https://iconiqui.com/mcp Summary: MCP setup guide for connecting Iconiq to AI coding tools through the shadcn registry workflow. ## Component Catalog ## Bento Builder - URL: https://iconiqui.com/builder/bento-builder - Package: @iconiq/bento-builder - Install: npx shadcn@latest add @iconiq/bento-builder - Registry JSON: https://iconiqui.com/r/bento-builder.json - Summary: Interactive bento-grid layout tool — drag tiles to reposition, tap to rename, drag a corner to resize, add tiles, then export the generated grid layout code to drop straight into your own project. - Dependencies: motion, lucide-react ### Documented APIs ## AI Input - URL: https://iconiqui.com/blocks/ai-input - Package: @iconiq/ai-input - Install: npx shadcn@latest add @iconiq/ai-input - Registry JSON: https://iconiqui.com/r/ai-input.json - Summary: Chat-style composer that stacks sent messages above the input as bubbles, exposes agent and model selector chips, and plays an Apple Intelligence-style gradient wave inside the surface when a message is sent. - Dependencies: @base-ui/react, motion, lucide-react ### Documented APIs - AIInput: Chat-style composer that stacks sent messages above the input as bubbles, exposes agent and model selector chips, and plays an Apple Intelligence-style gradient wave inside the surface when a message is sent. - agents (type: AIInputOption[]): Options for the agent chip on the left of the footer. Each option has `value` and `label`. Omit to hide the chip. - defaultAgent (type: string): Initially selected agent value. Falls back to the first agent option. - models (type: AIInputOption[]): Options for the model chip on the right of the footer. Omit to hide the chip. - defaultModel (type: string): Initially selected model value. Falls back to the first model option. - menuItems (type: AIInputMenuItem[]): Items for the plus menu. Each item has `value`, `label`, and optional `icon`. Set `type` to `"toggle"` for a switch row (with optional `defaultChecked`) or `"separator"` for a divider. Action items accept a per-item `onClick` and toggles a per-item `onCheckedChange`, firing alongside the component-level callbacks. Pass nested `items` to turn an action into a one-level submenu with a slide transition and back button. Omit to make the plus button a plain attachment button. - placeholder (type: string, default: "Ask for follow-up changes"): Placeholder copy for the textarea. - showMessages (type: boolean, default: true): Render sent messages as right-aligned chat bubbles above the composer. Disable when you render your own thread. - onSend (type: (message: string, meta: { agent: string; model: string }) => void): Called with the trimmed message and the current agent and model picks when the user presses Enter or clicks send. - onMicClick (type: () => void): Called when the microphone button is clicked. - onPlusClick (type: () => void): Called when the plus button is clicked and no `menuItems` are provided. - onMenuSelect (type: (value: string) => void): Called with the item's `value` when an action item — top-level or inside a submenu — is selected in the plus menu. - onMenuToggle (type: (value: string, checked: boolean) => void): Called when a toggle item in the plus menu is switched on or off. - onAgentChange (type: (value: string) => void): Called with the new agent value when the agent chip selection changes. - onModelChange (type: (value: string) => void): Called with the new model value when the model chip selection changes. - className (type: string): Extra classes for the outer wrapper. ## Banner - URL: https://iconiqui.com/blocks/banner - Package: @iconiq/banner - Install: npx shadcn@latest add @iconiq/banner - Registry JSON: https://iconiqui.com/r/banner.json - Summary: Top-of-screen announcement banner with four gradient tones, a left-aligned ringed icon and message, a right-aligned outlined action, a dismiss collapse, and a fluid spring morph that melts the bar into a confirmation pill when its action is clicked. - Dependencies: motion, lucide-react ### Documented APIs ## Code Block - URL: https://iconiqui.com/blocks/code-block - Package: @iconiq/code-block - Install: npx shadcn@latest add @iconiq/code-block - Registry JSON: https://iconiqui.com/r/code-block.json - Summary: Editor-style code block with a filename tab, a top-right spring-crossfade copy button, a bottom status bar with language and line count, line numbers, built-in theme-aware syntax highlighting, and line emphasis. - Dependencies: motion, lucide-react ### Documented APIs ## Contribution Graph - URL: https://iconiqui.com/blocks/contribution-graph - Package: @iconiq/contribution-graph - Install: npx shadcn@latest add @iconiq/contribution-graph - Registry JSON: https://iconiqui.com/r/contribution-graph.json - Summary: GitHub-style contribution calendar with compound calendar, block, total-count, and legend parts — pass raw Activity data or just a GitHub username and it fetches and caches the last year of contributions itself, shimmers a skeleton grid while loading, then fades the muted grid in and lights the greens up level by level — lightest to darkest — with springy pops, plus custom per-day tooltips and reduced-motion aware behavior. - Dependencies: date-fns ### Documented APIs ## Feedback Form - URL: https://iconiqui.com/blocks/feedback-form - Package: @iconiq/feedback-form - Install: npx shadcn@latest add @iconiq/feedback-form - Registry JSON: https://iconiqui.com/r/feedback-form.json - Summary: Feedback Form component documentation. ### Documented APIs ## Logo Carousel - URL: https://iconiqui.com/blocks/logo-carousel - Package: @iconiq/logo-carousel - Install: npx shadcn@latest add @iconiq/logo-carousel - Registry JSON: https://iconiqui.com/r/logo-carousel.json - Summary: Logo Carousel component documentation. ### Documented APIs ## Message - URL: https://iconiqui.com/blocks/message - Package: @iconiq/message - Install: npx shadcn@latest add @iconiq/message - Registry JSON: https://iconiqui.com/r/message.json - Summary: Composable chat message primitives — group, row, avatar, bubble, header, and footer — where each message slides in beside its composer with a bouncy spring: sent messages arrive from the right, received from the left, morphing up from the bubble's tail corner and bouncing back once as they land, plus reduced-motion aware behavior. - Dependencies: motion ### Documented APIs ## Reasoning Steps - URL: https://iconiqui.com/blocks/reasoning-steps - Package: @iconiq/reasoning-steps - Install: npx shadcn@latest add @iconiq/reasoning-steps - Registry JSON: https://iconiqui.com/r/reasoning-steps.json - Summary: Base UI collapsible reasoning trace for AI replies with a shimmering trigger label and no status icon, per-step dots that pop into checkmarks once done, a self-timing elapsed-seconds readout, a crossfading collapsed preview of the current step, and a staggered vertical timeline once expanded. - Dependencies: @base-ui/react, motion, lucide-react ### Documented APIs ## Scroll Progress - URL: https://iconiqui.com/blocks/scroll-progress - Package: @iconiq/scroll-progress - Install: npx shadcn@latest add @iconiq/scroll-progress - Registry JSON: https://iconiqui.com/r/scroll-progress.json - Summary: Ruler-style scroll indicator with tick marks that fill in as the page scrolls and a live percentage readout, dockable to either side or bottom corner of the viewport or a scrollable container. ### Documented APIs ## Setup Checklist - URL: https://iconiqui.com/blocks/setup-checklist - Package: @iconiq/setup-checklist - Install: npx shadcn@latest add @iconiq/setup-checklist - Registry JSON: https://iconiqui.com/r/setup-checklist.json - Summary: Animated onboarding checklist card with staggered task rows, a drawn checkmark badge, and a floating progress pill with a spring-smoothed pie. - Dependencies: motion, lucide-react ### Documented APIs ## Streaming Text - URL: https://iconiqui.com/blocks/streaming-text - Package: @iconiq/streaming-text - Install: npx shadcn@latest add @iconiq/streaming-text - Registry JSON: https://iconiqui.com/r/streaming-text.json - Summary: Word-by-word AI text streaming where each word fades in crisply wearing a blue gradient, then crossfades into the theme foreground once settled — black in light mode, white in dark — with a pulsing gradient dot at the stream head, natural prose wrapping, sr-only full-text announcement, and reduced-motion aware behavior. - Dependencies: motion ### Documented APIs ## Team Invitation - URL: https://iconiqui.com/blocks/team-invitation - Package: @iconiq/team-invitation - Install: npx shadcn@latest add @iconiq/team-invitation - Registry JSON: https://iconiqui.com/r/team-invitation.json - Summary: Team invitation block with fluid morphing variants for inviting members, managing the team, assigning roles, and tracking pending invites. - Dependencies: motion, lucide-react ### Documented APIs ## Testimonials - URL: https://iconiqui.com/blocks/testimonials - Package: @iconiq/testimonials - Install: npx shadcn@latest add @iconiq/testimonials - Registry JSON: https://iconiqui.com/r/testimonials.json - Summary: Inline testimonial wall where hovering one quote blurs and dims the rest while the author attribution reveals beside the highlighted quote. Pure CSS :has()-driven hover state — no per-frame JS animation. ### Documented APIs ## Thinking Indicator - URL: https://iconiqui.com/blocks/thinking-indicator - Package: @iconiq/thinking-indicator - Install: npx shadcn@latest add @iconiq/thinking-indicator - Registry JSON: https://iconiqui.com/r/thinking-indicator.json - Summary: AI loading state with a sparkle glyph that wobbles through liquid blob keyframes into a circle while a companion twinkle blooms on the same timeline, cycling status words that slide through a soft blur, a per-word shimmer sweep, layout-stable width, and reduced-motion aware behavior. - Dependencies: motion ### Documented APIs ## Button - URL: https://iconiqui.com/buttons-and-actions/button - Package: @iconiq/b-button - Install: npx shadcn@latest add @iconiq/b-button - Registry JSON: https://iconiqui.com/r/b-button.json - Summary: Base UI button with embedded Iconiq theme tokens, shadcn-style variants, spring press feedback, optional loading state, link rendering, and Motion ripple layer. - Dependencies: @base-ui/react, class-variance-authority, lucide-react, motion ### Documented APIs - Button: Base UI button with embedded Iconiq theme tokens, shadcn-style variants, spring press feedback, optional loading state, link rendering, and Motion ripple layer. - variant (type: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link", default: default): Chooses the visual recipe from the exported buttonVariants map. - linkUnderline (type: "motion" | "static", default: "motion" (when variant is link)): Link variant only. motion keeps foreground text with a grey baseline underline that fills darker on hover. static uses the same text size as other variants with hover:underline. - size (type: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg", default: default): Controls the shadcn-style height, padding, gap, radius, and icon sizing for text and icon-only buttons. - animateSize (type: boolean, default: false): Animates the button width with a spring as its intrinsic content changes, which is useful for labels like Continue, Saving..., and Saved on the same control. - loading (type: boolean, default: false): Locks the control, sets aria-busy, crossfades the label and icon into a spring-animated spinner, and suppresses ripples until loading finishes. - loadingIcon (type: ReactNode): Optional spinner or status icon shown while loading is true. Defaults to a Lucide Loader2 icon with animate-spin. - href (type: string): When set, renders an animated anchor instead of a button. Disabled and loading states use aria-disabled, tabIndex -1, and click prevention. - target (type: string): Anchor target such as "_blank". When the target opens a new tab, rel automatically gains noopener and noreferrer unless you already supplied them. - rel (type: string): Optional anchor rel attribute. Merged with noopener noreferrer when target includes _blank. - disableRipple (type: boolean, default: false): Skips the pointer ripple when you want only the press-state feedback. Link buttons also skip the ripple by default to avoid a contained splash on text-only actions. - type (type: "button" | "submit" | "reset", default: button): Passed to the underlying button element so the component does not submit forms accidentally by default. Ignored for href links. - children (type: ReactNode): Label content rendered above the ripple layer inside a z-10 span. - icon (type: ReactNode): Optional icon rendered inline with the label. Nested SVGs inherit the built-in size utility and variant-aware icon color. - iconLabel (type: string): Convenience prop that sets aria-label, which is required for icon-only sizes when no visible text children are present. - iconPosition (type: "start" | "end", default: "start"): Chooses whether the optional icon renders before or after the button text inside the same inline content row. Loading always renders at the start. - className (type: string): Merged after the generated CVA classes, making it the main escape hatch for one-off layout changes. - disabled (type: boolean): Native disabled state. Combines with loading to lock interaction and prevent ripple creation. - buttonVariants: The CVA recipe exported alongside the component so matching button classes can be reused on links or custom wrappers. - variant (type: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link", default: "default"): Visual recipe passed to the CVA helper when composing classes outside the Button component. - linkUnderline (type: "motion" | "static", default: "motion" (when variant is link)): Link variant only. Pass through the same underline mode used by the Button component. - size (type: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg", default: "default"): Size token passed to the CVA helper for text and icon-only button recipes. - className (type: string): Optional classes merged after the generated variant and size classes. ## Button Group - URL: https://iconiqui.com/buttons-and-actions/button-group - Package: @iconiq/button-group - Install: npx shadcn@latest add @iconiq/button-group - Registry JSON: https://iconiqui.com/r/button-group.json - Summary: Compact bordered action button with muted idle text, darker hover text, optional ripple feedback, variants, and shadcn-style size controls. - Dependencies: @base-ui/react, motion, class-variance-authority ### Documented APIs - Button: Compact bordered action button with muted idle text, darker hover text, optional ripple feedback, variants, and shadcn-style size controls. - children (type: ReactNode, required): Button content rendered inside an inline span so icon-and-label pairs keep consistent spacing across sizes. - className (type: string): Merged onto the root button. Use it for local width, spacing, or surface overrides. - size (type: "sm" | "md" | "lg", default: "md"): Compacts or expands the control. Inherits the ButtonGroup size when the button is rendered inside a group. - variant (type: "default" | "destructive" | "ghost" | "outline", default: "default"): Visual treatment for the action. Destructive is useful for delete or irreversible actions inside a toolbar. - disableRipple (type: boolean, default: false): Turns off the click ripple while preserving the rest of the hover and focus styling. - showBorder (type: boolean, default: true): Adds a standalone border when the button is used outside ButtonGroup. Inside ButtonGroup, the wrapper supplies the outer border and dividers instead. - IconButton: Icon-only toolbar action that shares the same compact border, muted idle tone, variants, and optional ripple behavior as Button. - children (type: ReactNode, required): Icon content rendered inside the inline content span. SVG children inherit the built-in size utilities for the active size variant. - className (type: string): Merged onto the icon button root for size or surface overrides. - size (type: "sm" | "md" | "lg", default: "md"): Controls the square footprint of the icon button. Inherits the ButtonGroup size when rendered inside a group. - variant (type: "default" | "destructive" | "ghost" | "outline", default: "default"): Matches the Button variant surface for icon-only actions. - disableRipple (type: boolean, default: false): Disables the click ripple for quieter toolbar actions. - showBorder (type: boolean, default: true): Removes the outer border when set to false so the icon action can sit more quietly beside a borderless group. - ButtonGroup: Slot-aware flex wrapper for arranging adjacent controls with horizontal or vertical rounding rules and shared size context. - children (type: ReactNode, required): Buttons, icon buttons, ButtonGroupText, ButtonGroupSeparator, ButtonGroupItems, or any other data-slot controls you want to keep together. - orientation (type: "horizontal" | "vertical", default: "horizontal"): Chooses the grouped rounding and shared-border direction used by buttonGroupVariants. - size (type: "sm" | "md" | "lg", default: "md"): Shared density for Button, IconButton, and ButtonGroupText children unless a child overrides size locally. - className (type: string): Merged onto the outer group. Use it for wrapping, alignment, or local spacing overrides. - ButtonGroupText: Non-interactive text segment for labeling a group without leaving the shared button-group surface. - children (type: ReactNode, required): Short label or inline content rendered inside the grouped text segment. - render (type: useRender render prop): Optional Base UI render override when you need a different element while keeping the same merged props. - className (type: string): Merged with the default muted bordered text segment classes. - ButtonGroupSeparator: Separator segment for splitting labels, buttons, inputs, and grouped actions inside ButtonGroup. - orientation (type: "horizontal" | "vertical", default: "vertical"): Controls the separator axis. Vertical separators are the default for horizontal button groups. - className (type: string): Merged with the self-stretching separator classes for custom color or spacing. - ButtonGroupItems: Segmented button shell that converts valid child elements into compact internal buttons with muted idle text and darker hover states. - children (type: ReactNode, required): Pass plain button-like elements as children. Their props and children are hoisted into the internal motion buttons rendered by the group. - className (type: string): Merged onto the outer segmented wrapper for width or surface overrides. - size (type: "sm" | "md" | "lg", default: "md"): Sets the shared height, padding, and typography of the grouped buttons. - showDividers (type: boolean, default: true): Removes the internal separator lines and the outer wrapper border when set to false, then switches the group to a smoother shared hover surface. - disableRipple (type: boolean, default: false): Turns off the ripple for every internal button rendered by the group. - SegmentedControl: Segmented selector with string or rich option objects, compact sizing, keyboard support, RTL-aware navigation, form name support, and a spring-driven selected indicator. - options (type: Array, required): Ordered list of segments. Each entry can be a plain string or an object with a stable value, optional label, icon, and disabled flag. - value (type: string): Controlled selected value. When provided, the internal state syncs to this prop through an effect. - onChange (type: (value: string) => void): Called with the selected value whenever a segment is pressed or moved to with the keyboard. - ariaLabel (type: string): Accessible name for the radiogroup. Provide this or ariaLabelledBy so screen readers can identify the control. - ariaLabelledBy (type: string): ID of an external label element that names the radiogroup. Use when a visible label already exists in the page. - name (type: string): When provided, renders a hidden input so the selected value can participate in native form submission. - disabled (type: boolean, default: false): Disables the entire control and every segment inside it. - orientation (type: "horizontal" | "vertical", default: "horizontal"): Layout direction for the segmented shell and the primary arrow-key axis. - className (type: string): Merged onto the segmented wrapper for width, alignment, or spacing overrides. - layoutId (type: string): Optional Motion layout id for the selected indicator. When omitted, a unique id is generated per instance so multiple controls on one page do not share indicator motion. - size (type: "sm" | "md" | "lg", default: "md"): Controls the overall density of the segmented control shell and each segment inside it. - Motion and interaction: Each export keeps the same tactile feel, but the default presentation is now much more compact and toolbar-like. ## Flux Button - URL: https://iconiqui.com/buttons-and-actions/flux-button - Package: @iconiq/flux-button - Install: npx shadcn@latest add @iconiq/flux-button - Registry JSON: https://iconiqui.com/r/flux-button.json - Summary: Async button with idle, loading, and success states, plus b-button visual variants. - Dependencies: @base-ui/react/button, class-variance-authority, lucide-react, motion ### Documented APIs - FluxButton: Async button with idle, loading, and success states, plus b-button visual variants. - idleLabel (type: string, required): Label shown before the action starts. - loadingLabel (type: string, required): Label shown with the built-in loader while onAction is in progress. - successLabel (type: string, required): Label shown after onAction resolves. - successIcon (type: React.ReactNode): Optional icon shown on success. Pass any node, such as a Lucide checkmark. Omit for text-only success. - onAction (type: () => void | Promise, required): Runs when the button is pressed, drives loading and success states, then returns to idle after successHold. - variant (type: "default" | "outline" | "secondary" | "ghost" | "destructive" | "link", default: default): Visual style variant. Matches the b-button variant set. - successHold (type: number, default: 1000): Milliseconds to hold the success state before returning to the idle label. - size (type: "xs" | "sm" | "default" | "lg", default: default): Height and horizontal padding preset. Matches b-button sizes. - type (type: "button" | "submit", default: button): Native button type. Use submit inside forms; defaults to button so the control does not submit unless you opt in. - disabled (type: boolean, default: false): Native disabled state. Also blocks the action flow while true. - className (type: string): Optional class names merged onto the root button element. - onClick (type: React.MouseEventHandler): Native click handler forwarded to the underlying button. ## Icon Bar - URL: https://iconiqui.com/buttons-and-actions/icon-bar - Package: @iconiq/icon-bar - Install: npx shadcn@latest add @iconiq/icon-bar - Registry JSON: https://iconiqui.com/r/icon-bar.json - Summary: Horizontal toolbar of compact icon chips. Hover or focus previews labels; clicking selects one item and keeps it expanded. - Dependencies: @base-ui/react/toggle, @base-ui/react/toggle-group, motion, lucide-react ### Documented APIs - IconBar: Horizontal toolbar of compact icon chips. Hover or focus previews labels; clicking selects one item and keeps it expanded. - value (type: string | null): Controlled selected item value. Pair with onValueChange for fully controlled selection. - defaultValue (type: string | null): Optional initial selected item when uncontrolled. Omit to start with every chip collapsed until the user clicks one. - onValueChange (type: (value: string | null) => void): Called when selection changes. Receives null when the active chip is clicked again to deselect. - className (type: string): Optional class names applied to the outer flex container. - children (type: React.ReactNode): One or more IconBarItem elements rendered in a single row with consistent spacing. - IconBarItem: Individual pill chip with a Lucide icon and animated label reveal on hover, focus, or selection. - icon (type: LucideIcon, required): Lucide icon component rendered inside the fixed 36px icon well. - label (type: string, required): Short text revealed when the chip expands. Keep labels concise so the width animation stays smooth. - value (type: string): Selection identity for this chip. Defaults to label when omitted. - onClick (type: (event: React.MouseEvent) => void): Optional click handler fired after selection updates. - disabled (type: boolean, default: false): Disables interaction, hover preview, and selection. - className (type: string): Optional class names merged onto the chip button. ## Toggle - URL: https://iconiqui.com/buttons-and-actions/toggle - Package: @iconiq/toggle - Install: npx shadcn@latest add @iconiq/toggle - Registry JSON: https://iconiqui.com/r/toggle.json - Summary: Two-state button with spring press feedback and a muted fill that bounces in when pressed. - Dependencies: @base-ui/react, class-variance-authority, motion ### Documented APIs - Toggle: Two-state button with spring press feedback and a muted fill that bounces in when pressed. - pressed (type: boolean): Controlled pressed state. Pass this when the parent owns whether the toggle is on. - defaultPressed (type: boolean, default: false): Initial pressed state for uncontrolled usage. The component manages future toggles internally. - onPressedChange (type: (pressed: boolean) => void): Called with the next pressed state whenever the toggle is activated or deactivated. - variant (type: "default" | "outline", default: "default"): Visual treatment. Outline adds a border for toolbar or segmented layouts. - disabled (type: boolean): Disables interaction and dims the control while preserving its pressed appearance. - children (type: React.ReactNode): Icon, text label, or icon-plus-label content. Children sit in normal document flow so labels expand the control width naturally. - className (type: string): Merged onto the root button for local spacing, width, or color overrides. - Motion and interaction behavior: Pressed state drives a horizontal liquid wipe, a one-shot light sheen, and tactile icon motion. ## Toggle Group - URL: https://iconiqui.com/buttons-and-actions/toggle-group - Package: @iconiq/toggle-group - Install: npx shadcn@latest add @iconiq/toggle-group - Registry JSON: https://iconiqui.com/r/toggle-group.json - Summary: Root container for toggle buttons with shared variant, spacing, and orientation. Use spacing={0} for a connected segmented layout. - Dependencies: @base-ui/react, class-variance-authority, motion ### Documented APIs - ToggleGroup: Root container for toggle buttons with shared variant, spacing, and orientation. Use spacing={0} for a connected segmented layout. - type (type: "single" | "multiple", default: "multiple"): Radix selection mode. Multiple allows several active items by default; single keeps one pressed item at a time. - multiple (type: boolean, default: true): Base UI selection mode. Pass multiple={false} for single selection; true keeps several active items. - value (type: string | string[]): Controlled selection. Radix uses a string in single mode and a string array in multiple mode. Base UI always uses a string array. - defaultValue (type: string | string[]): Initial selection for uncontrolled usage. Match the selection mode and value shape for your installed primitive. - onValueChange (type: (value: string | string[]) => void): Called with the next selection whenever an item is pressed or released. - variant (type: "default" | "outline", default: "default"): Shared visual treatment applied to every item unless an item overrides it locally. - spacing (type: number, default: 1): Gap between items in spacing units. Defaults to 1 (4px). Set to 0 for a connected outline shell with one outer border and internal dividers. - orientation (type: "horizontal" | "vertical", default: "horizontal"): Layout direction for the group. Also sets aria-orientation and connected divider direction when spacing={0}. - disabled (type: boolean): Disables the entire group and all nested items. - aria-label (type: string): Accessible name for the group. Required when items are icon-only and no visible group label is present. - className (type: string): Merged onto the root group wrapper for local layout or width overrides. - ToggleGroupItem: Individual toggle button inside the group with the same fluid motion as the standalone toggle. - value (type: string, required): Stable identifier used when reading or updating the group selection. - variant (type: "default" | "outline"): Optional local override for the shared group variant treatment. - disabled (type: boolean): Disables this item without affecting the rest of the group. - aria-label (type: string): Accessible name for icon-only items. Omit when the item already contains visible text. - className (type: string): Merged onto the item button for local width, color, or spacing overrides. - children (type: ReactNode): Icon or label content rendered inside the item. ## Avatar - URL: https://iconiqui.com/display-and-content/avatar - Package: @iconiq/avatar - Install: npx shadcn@latest add @iconiq/avatar - Registry JSON: https://iconiqui.com/r/avatar.json - Summary: Base UI avatar root with shared sizing and an optional tooltip for hover or focus status hints. - Dependencies: @base-ui/react, @radix-ui/react-slot, motion ### Documented APIs - Avatar: Base UI avatar root with shared sizing and an optional tooltip for hover or focus status hints. - children (type: ReactNode): Compose AvatarImage, AvatarFallback, and an optional AvatarBadge inside the root. - size (type: "default" | "sm" | "lg", default: "default"): Controls the root size and drives badge/fallback sizing through data-size selectors. - tooltip (type: string): Optional short label shown in the Iconiq tooltip surface when the entire avatar is hovered or focused. - tooltipSide (type: "top" | "bottom" | "left" | "right", default: "right"): Preferred side for the avatar tooltip bubble. The default collision order is right, left, top, then bottom. - tooltipDelay (type: number, default: 0.15): Delay in seconds before the avatar tooltip opens. - tooltipClassName (type: string): Merged onto the tooltip bubble when the avatar tooltip is enabled. - name (type: string): Optional display name used by AvatarFallback to auto-generate initials when children are omitted. - asChild (type: boolean, default: false): Merge avatar props onto the child element via Radix Slot, useful for link or button triggers. - aria-label (type: string): Accessible name for the avatar. Defaults to the tooltip string when tooltip is set. - className (type: string): Merged onto the Base UI avatar root. Use it for local radius, ring, or size overrides. - AvatarImage: Image slot for the compound avatar, backed by Base UI's image loading behavior. - src (type: string, required): Image URL passed to the underlying Base UI image primitive. - alt (type: string, required): Accessible text for the image. Pass an empty string only when the avatar is decorative. - className (type: string): Merged with the full-size rounded image classes. - AvatarFallback: Fallback slot shown by Base UI while the image is loading, missing, or failed. - children (type: ReactNode, required): Initials, icon, or other compact fallback content centered inside the avatar. - className (type: string): Merged with the muted circular fallback classes. - AvatarBadge: Absolute status badge that scales with the root Avatar size. Use variant for preset presence colors or tooltip for badge-only status hints. - variant (type: "online" | "offline" | "busy" | "away", default: "online"): Preset status color mapped to theme-friendly green, muted, destructive, and amber tokens. - aria-label (type: string): Accessible status label. Defaults to the tooltip string or the variant label such as Online or Busy. - children (type: ReactNode): Optional icon or status mark. Icons scale down on small avatars instead of disappearing. - tooltip (type: string): Optional short label shown in the Iconiq tooltip surface when only the badge should be the trigger. - tooltipSide (type: "top" | "bottom" | "left" | "right", default: "right"): Preferred side for the tooltip bubble. The default collision order is right, left, top, then bottom. - tooltipDelay (type: number, default: 0.15): Delay in seconds before the tooltip opens. - tooltipClassName (type: string): Merged onto the tooltip bubble when the badge tooltip is enabled. - className (type: string): Merged with the green status badge background, foreground, and ring classes. - AvatarGroup: Stack wrapper for overlapping avatars and matching overflow count chips. - children (type: ReactNode, required): Avatar and AvatarGroupCount children rendered in an overlapping row. - className (type: string): Merged with the negative-space group classes and child avatar rings. - AvatarGroupCount: Overflow count part that follows the largest avatar size used in the group. - children (type: ReactNode, required): Count label or icon shown after the visible avatars. - className (type: string): Merged with the muted circular count chip classes. ## Badge - URL: https://iconiqui.com/display-and-content/badge - Package: @iconiq/badge - Install: npx shadcn@latest add @iconiq/badge - Registry JSON: https://iconiqui.com/r/badge.json - Summary: Compact label pill with tinted fills, a shimmer-enabled default variant, a quieter dot variant, semantic color aliases, and optional icon or dismiss controls. - Dependencies: motion, class-variance-authority, @radix-ui/react-slot ### Documented APIs - Badge: Compact label pill with tinted fills, a shimmer-enabled default variant, a quieter dot variant, semantic color aliases, and optional icon or dismiss controls. - children (type: ReactNode, required): Badge content rendered above the optional shimmer layer so labels stay readable while the default variant animates. - className (type: string, default: ""): Appended directly to the root badge element. Useful for radius, spacing, or local border overrides. - variant (type: "default" | "dot", default: "default"): Chooses between the animated filled badge and the quieter outlined badge with a leading status dot. - size (type: "sm" | "md" | "lg", default: "md"): Controls height, horizontal padding, gap, and label size for denser or roomier badge treatments. - color (type: BadgeColorProp, default: "gray"): Picks a preset palette token or semantic alias (`success`, `warning`, `error`, `info`). Each token sets matched background and foreground tones for light and dark mode. - icon (type: ReactNode): Optional leading icon rendered before the label on the default variant only. Ignored when `variant="dot"` or when `onDismiss` is provided. - onDismiss (type: () => void): When provided on the default variant, renders a dismiss button after the label for removable filter chips. Ignored when `variant="dot"` or when `icon` is provided. - dismissLabel (type: string, default: "Remove"): Accessible label for the dismiss button when `onDismiss` is enabled. - animate (type: boolean, default: true): Controls the default variant mount fade/scale entrance and the dot variant status pulse. Use with `shimmer={false}` on the default variant when you want a one-time entrance without the looping sweep. Automatically disabled when `prefers-reduced-motion` is set. - shimmer (type: boolean, default: true): Controls the default variant shimmer sweep independently of the mount entrance. Automatically disabled when `prefers-reduced-motion` is set. - asChild (type: boolean, default: false): Merges badge styles onto the child element, such as an anchor, via Radix Slot. - waveColor (type: string): Optional shimmer midpoint override for the default variant. When omitted, the sweep derives a subtle tone from the current text color. - badgeVariants: CVA recipe exported alongside Badge for reusing badge layout, color tokens, and interactive focus styles on custom elements. - variant (type: "default" | "dot", default: "default"): Chooses between the filled badge and dot badge recipes. - size (type: "sm" | "md" | "lg", default: "md"): Controls height, padding, gap, and label size. - color (type: BadgeColor): Resolved palette token passed to `getBadgeColorVariables()` when reusing badge color tokens outside the component. - interactive (type: boolean, default: false): Adds pointer cursor and focus ring styles for clickable badge roots. - className (type: string): Optional classes merged after the generated recipe classes. - badgeColors: Preset color hex map used by Badge tone generation for palette-consistent fills and dot treatments. - keys (type: BadgeColor): Named palette tokens such as gray, blue, green, amber, red, and purple. - Visual behavior: The default variant keeps the spring-in shimmer treatment, while the dot variant adds a subtle status pulse. Motion respects reduced-motion preferences. ## Calendar - URL: https://iconiqui.com/display-and-content/calendar - Package: @iconiq/calendar - Install: npx shadcn@latest add @iconiq/calendar - Registry JSON: https://iconiqui.com/r/calendar.json - Summary: Animated monthly calendar with single-day or range selection, bounds, modifiers, locale-aware labels, and direct month/year picking. - Dependencies: motion, lucide-react, date-fns ### Documented APIs - Calendar: Animated monthly calendar with single-day or range selection, bounds, modifiers, locale-aware labels, and direct month/year picking. - mode (type: "single" | "range", default: "single"): Selection model. Use single for one date or range for start/end selection. - selected (type: Date | null): Controlled selected day for single mode. Pass null to clear the highlight. - defaultSelected (type: Date | null): Initial selected day for uncontrolled single mode when selected is not provided. - onSelect (type: (date: Date | null) => void): Called when the user picks a day in single mode, including visible outside-month days. - range (type: CalendarRange): Controlled range for range mode. Shape is `{ from?: Date; to?: Date }`. - defaultRange (type: CalendarRange): Initial range for uncontrolled range mode. - onRangeSelect (type: (range: CalendarRange) => void): Called when the user updates the range in range mode. - month (type: Date): Controlled visible month. Prev/next, outside-day, and month/year picker navigation requests flow through onMonthChange. - defaultMonth (type: Date): Initial visible month for uncontrolled usage when month is not provided. - onMonthChange (type: (month: Date) => void): Called whenever the user navigates with prev/next, an outside day, or the month/year picker. - disabled (type: (date: Date) => boolean): Marks dates as non-interactive in addition to minDate/maxDate bounds. - minDate (type: Date): Earliest selectable day. Also disables month navigation into fully out-of-range months. - maxDate (type: Date): Latest selectable day. Also disables month navigation into fully out-of-range months. - locale (type: Locale): Optional date-fns locale used for month labels, weekday headers, and spoken date labels. - labels (type: Partial): Override built-in English UI and accessibility strings such as Today, Clear, and picker labels. - size (type: "sm" | "md" | "lg"): Controls the overall calendar scale, including the card width, spacing, nav controls, weekday row, and day cell sizing. Defaults to sm. - weekStartsOn (type: 0 | 1 | 2 | 3 | 4 | 5 | 6): Overrides the first day of the week for both the weekday header and rendered month grid. - minYear (type: number): Optional lower bound for selectable years in the year picker. - maxYear (type: number): Optional upper bound for selectable years in the year picker. - showOutsideDays (type: boolean, default: true): Whether leading and trailing days from adjacent months are rendered in the grid. - fixedWeeks (type: boolean, default: false): Pads the month grid to six weeks for consistent height. Only applies when showOutsideDays is true. - modifiers (type: Record boolean>): Named matchers that render marker dots under matching days. - modifierLabels (type: Record): Human-readable names for modifier keys, appended to spoken day labels. - id (type: string): Optional root id used for heading and live-region relationships. - name (type: string): Optional native form field name. Renders a hidden input in single mode. - className (type: string): Optional class names applied to the root surface. - Date math and layout behavior: The grid is rebuilt with date-fns whenever the visible month changes. - Motion and accessibility: Motion, keyboard support, and screen-reader semantics are built into the grid and picker overlays. ## Card - URL: https://iconiqui.com/display-and-content/card - Package: @iconiq/card - Install: npx shadcn@latest add @iconiq/card - Registry JSON: https://iconiqui.com/r/card.json - Summary: Compound card surface with slot-based sections, optional interactive lift, and layout-aware motion between content states. - Dependencies: motion, @radix-ui/react-slot ### Documented APIs - Card: Compound card surface with slot-based sections, optional interactive lift, and layout-aware motion between content states. - children (type: ReactNode, required): Compose CardHeader, CardContent, CardFooter, media, or custom blocks inside the shared card shell. - interactive (type: boolean, default: false): Enables the restrained hover lift and stronger surface response intended for clickable or focusable cards. - asChild (type: boolean, default: false): Merges the card surface classes and interaction handlers onto the single child element, which is useful for link or button cards. - className (type: string): Merged onto the root card surface for local spacing, border, or layout adjustments without replacing the slot API. - onHoverStart (type: () => void): Called when interactive hover feedback begins from pointer, focus, or keyboard focus within the card. - onHoverEnd (type: () => void): Called when interactive hover feedback ends after pointer leave and focus exits the card. - CardHeader: Top header grid for title, description, and an optional trailing CardAction. - children (type: ReactNode, required): Compose CardTitle, CardDescription, and optional CardAction inside the header grid. - className (type: string): Merged onto the header grid wrapper. - CardTitle: Primary heading slot with default title typography. - children (type: ReactNode, required): Heading content for the card. Works with links, badges, metrics, or richer inline content. - className (type: string): Merged with the default title typography classes. - as (type: "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "div" | "span", default: "h3"): Semantic heading element used for the title. Defaults to h3 for accessible card headings. - CardDescription: Secondary supporting copy beneath the title. - children (type: ReactNode, required): Supporting description or excerpt text rendered with muted body styling. - className (type: string): Merged with the muted description typography classes. - as (type: "p" | "div" | "span", default: "p"): Semantic text element used for the description. Defaults to p for accessible supporting copy. - CardAction: Optional trailing action slot aligned to the top-right of CardHeader. - children (type: ReactNode, required): Action content such as a menu trigger, status pill, or compact control. - className (type: string): Merged with the default action placement classes. - CardContent: Flexible middle section for body copy, media, stats, and custom layouts. - children (type: ReactNode, required): Main card body content rendered inside the padded content slot. - className (type: string): Merged with the default horizontal padding classes. - CardFooter: Bottom section for supporting actions, metadata, or contextual labels. - children (type: ReactNode, required): Footer content rendered on a quieter separated surface beneath the body. - className (type: string): Merged with the default footer surface and spacing classes. - CardImage: Next.js Image slot with the shared inset media frame, default fill sizing, and card-aware radius handling. Always renders next/image. - alt (type: string, required): Accessible alternative text for the image. - src (type: string, required): Image source passed through to next/image. - inset (type: boolean, default: true): When true, wraps the image in the padded card media frame. Set false for edge-to-edge media. - fill (type: boolean): Uses fill layout when true. Defaults to fill when width and height are both omitted. - sizes (type: string, default: "(max-width: 768px) 100vw, 400px"): Responsive sizes hint forwarded to next/image for better loading performance. - className (type: string): Merged onto the rendered image element. - CardMedia: Media slot for video, charts, embeds, or other custom leading media blocks. - children (type: ReactNode, required): Non-image media content such as video, a chart container, or an embed. - inset (type: boolean, default: true): When true, wraps children in the padded card media frame. Set false for edge-to-edge media. - className (type: string): Merged onto the outer media wrapper. - Clickable card recipes: Patterns for whole-card navigation and cards that contain separate interactive controls. - Motion and interaction model: Layout changes are animated through Motion so expanding or swapping card content feels fluid rather than abrupt. ## Carousel - URL: https://iconiqui.com/display-and-content/carousel - Package: @iconiq/carousel - Install: npx shadcn@latest add @iconiq/carousel - Registry JSON: https://iconiqui.com/r/carousel.json - Summary: Root carousel region wired to Embla. Exposes scroll state through `useCarousel`, supports responsive nav placement, optional autoplay, and keyboard navigation for horizontal and vertical layouts. - Dependencies: embla-carousel-react, lucide-react ### Documented APIs - Carousel: Root carousel region wired to Embla. Exposes scroll state through `useCarousel`, supports responsive nav placement, optional autoplay, and keyboard navigation for horizontal and vertical layouts. - orientation (type: "horizontal" | "vertical", default: horizontal): Sets the Embla scroll axis and the spacing applied between slides. - aspectRatio (type: "square" | "video" | "4/3" | "3/2" | "portrait" | string, default: video): Sets the slide viewport shape on `CarouselContent`. Use presets like `video` (16:9) and `square`, or pass a custom ratio string such as `21/9`. - navPlacement (type: "outside" | "responsive", default: responsive): Positions previous and next controls. `responsive` places controls below the carousel on the right on mobile and outside the track from `sm` upward. - autoplay (type: boolean | number): When enabled, advances slides on a timer. Pass a number for the delay in milliseconds. Pair with `opts={{ loop: true }}` for continuous playback. - opts (type: CarouselOptions): Forwarded Embla options such as `align`, `loop`, or `slidesToScroll`. The root merges `axis` from `orientation`. - plugins (type: CarouselPlugin): Optional Embla plugins passed to `useEmblaCarousel`, such as `embla-carousel-autoplay`. - setApi (type: (api: CarouselApi) => void): Optional callback that receives the Embla API instance after mount for external index or dot indicators. - aria-label (type: string, default: Carousel): Accessible label for the root `role="region"` carousel wrapper. - className (type: string): Optional class names merged onto the root `role="region"` wrapper. - CarouselContent: Overflow-hidden viewport that hosts the Embla ref and the flex track of slides. - className (type: string): Optional class names merged onto the inner flex container that holds slides. - CarouselItem: Single slide wrapper sized to `basis-full` with directional padding between siblings. Inactive slides are marked `aria-hidden`. - className (type: string): Optional class names merged onto each slide group. - CarouselPrevious / CarouselNext: Self-contained icon buttons that call `scrollPrev` and `scrollNext` and disable when Embla cannot scroll further. - className (type: string): Optional class names merged onto the control for local offsets or sizing. - useCarousel: Hook for custom indicators or synced UI. Must be used inside `Carousel`. - selectedIndex (type: number): Zero-based index of the active scroll snap. - scrollSnapCount (type: number): Total number of scroll snaps reported by Embla. - scrollTo (type: (index: number) => void): Scrolls directly to the requested snap index. - scrollPrev / scrollNext (type: () => void): Moves to the previous or next snap. - api (type: CarouselApi): Underlying Embla API instance when you need lower-level control. ## Charts - URL: https://iconiqui.com/display-and-content/charts - Package: @iconiq/charts - Install: npx shadcn@latest add @iconiq/charts - Registry JSON: https://iconiqui.com/r/charts.json - Summary: Theme-aware Recharts shell that maps ChartConfig tokens to CSS variables, applies registry chart colors, and fades the surface in on mount. - Dependencies: recharts, motion ### Documented APIs - ChartContainer: Theme-aware Recharts shell that maps ChartConfig tokens to CSS variables, applies registry chart colors, and fades the surface in on mount. - config (type: ChartConfig, required): Series labels, optional icons, and colors. Use var(--chart-1) style tokens or per-key theme overrides; scoped --color-{key} variables are generated for this chart instance. - children (type: ReactNode, required): Recharts chart markup, usually a BarChart, LineChart, AreaChart, PieChart, RadarChart, or RadialBarChart rendered inside ResponsiveContainer. - id (type: string): Optional stable id for the generated data-chart attribute and scoped CSS variables. - seriesCount (type: number): Overrides inferred series count for animation timing when ChartConfig keys do not match plotted series. - initialDimension (type: { width: number; height: number }): Optional fallback size for ResponsiveContainer before the first measure. By default the chart fills its parent with a debounced resize handler. - className (type: string): Merged onto the chart shell alongside the chart component's local theme tokens. - ChartBar: Thin Recharts Bar wrapper with restrained ease-out growth timing tuned for the Iconiq motion profile. - seriesIndex (type: number, default: 0): Offsets bar growth start time for multi-series charts so each series eases in with a short stagger. - ...props (type: Recharts Bar props): Forwards the full Bar API. animationDuration (~480ms), ease-out easing, and isAnimationActive inherit calm defaults unless you override them. - ChartLine: Recharts Line wrapper that shares the same ease-out timing and stagger defaults as ChartBar. - seriesIndex (type: number, default: 0): Offsets line draw start time for multi-series charts so each stroke eases in with a short stagger. - ...props (type: Recharts Line props): Forwards the full Line API. animationDuration, easing, and isAnimationActive inherit calm defaults unless you override them. - ChartArea: Recharts Area wrapper that shares the same ease-out timing and stagger defaults as ChartBar. - seriesIndex (type: number, default: 0): Offsets area reveal start time for multi-series charts so each fill eases in with a short stagger. - ...props (type: Recharts Area props): Forwards the full Area API. animationDuration, easing, and isAnimationActive inherit calm defaults unless you override them. - ChartTooltip: Recharts tooltip primitive that defaults to ChartTooltipContent when content is omitted. - content (type: ReactNode | ComponentType): Tooltip renderer. Defaults to ChartTooltipContent when omitted. - cursor (type: boolean | object): Recharts cursor configuration for hover feedback. - ChartTooltipContent: Styled tooltip content shell with a calm fade entrance and dashed, dot, or line indicators. - indicator (type: "dot" | "line" | "dashed", default: "dot"): Marker style rendered beside each tooltip row. - hideLabel (type: boolean, default: false): Suppresses the formatted label block above the value rows. - hideIndicator (type: boolean, default: false): Hides the color marker when you only want text values. - nameKey (type: string): Payload key used to resolve ChartConfig labels and colors for each tooltip row. - labelKey (type: string): Payload key used to resolve the tooltip label row from ChartConfig. - label (type: string): Optional label key override when you want the tooltip header to read from ChartConfig directly. - labelClassName (type: string): Classes merged onto the tooltip label row. - className (type: string): Classes merged onto the tooltip shell. - color (type: string): Optional shared indicator color override for every tooltip row. - labelFormatter (type: (value, payload) => ReactNode): Custom formatter for the tooltip label row. - formatter (type: Recharts formatter): Optional per-row formatter; when omitted, the default label and value layout is used. - ChartLegend: Recharts legend primitive that defaults to ChartLegendContent when content is omitted. - content (type: ReactNode | ComponentType): Legend renderer. Defaults to ChartLegendContent when omitted. - verticalAlign (type: "top" | "bottom", default: "bottom"): Adjusts legend spacing relative to the chart. - ChartLegendContent: Legend content shell with a quiet fade-and-rise entrance that matches the chart surface motion. - hideIcon (type: boolean, default: false): Hides config icons and falls back to the color swatch derived from the series color. - nameKey (type: string): Payload key used to resolve ChartConfig labels and swatch colors for each legend row. - verticalAlign (type: "top" | "bottom", default: "bottom"): Adjusts legend spacing relative to the chart. - className (type: string): Classes merged onto the legend shell. - ChartEmptyState: Centered empty placeholder for charts with no data yet or while a dataset is loading. - label (type: ReactNode, default: "No data available"): Primary empty-state message. - description (type: ReactNode): Optional supporting copy beneath the label. - className (type: string): Classes merged onto the empty-state shell. - useChart: Reads ChartContainer context, including ChartConfig and whether the initial series animation is still active. - config (type: ChartConfig): The ChartConfig passed to ChartContainer. - chartAnimationActive (type: boolean): True during the first ease-out series animation window, then false after resize-safe timing completes. ## Date Picker - URL: https://iconiqui.com/display-and-content/date-picker - Package: @iconiq/date-picker - Install: npx shadcn@latest add @iconiq/date-picker - Registry JSON: https://iconiqui.com/r/date-picker.json - Summary: Collapsible date field with a read-only Base UI input trigger and a portaled Iconiq Calendar panel. - Dependencies: @base-ui/react/input, motion, lucide-react, date-fns ### Documented APIs - DatePicker: Collapsible date field with a read-only Base UI input trigger and a portaled Iconiq Calendar panel. - value (type: Date | null): Controlled selected date. When provided, the trigger and embedded Calendar both reflect this value. - defaultValue (type: Date | null, default: null): Initial selected date for uncontrolled usage when `value` is omitted. - placeholder (type: string, default: Select a date): Copy shown in the trigger when no date is selected. - onChange (type: (date: Date | null) => void): Called when the user picks or clears a date from the embedded Calendar or clear control. - className (type: string): Optional class names applied to the outer wrapper. - defaultOpen (type: boolean, default: false): Whether the Calendar panel starts expanded on first render. - open (type: boolean): Controlled open state for the Calendar panel. Pair with `onOpenChange`. - onOpenChange (type: (open: boolean) => void): Called when the panel opens or closes from the trigger, selection, Escape, or outside click. - disabled (type: boolean, default: false): Disables the trigger and prevents the panel from opening. - clearable (type: boolean, default: false): Shows a clear button when a date is selected so users can reset to `null`. - closeOnSelect (type: boolean, default: true): Whether picking a date closes the panel automatically. - dateFormat (type: string, default: EEE, MMM d, yyyy): date-fns format string for the trigger label. Uses `calendarProps.locale` when provided. - name (type: string): Optional form field name. Renders a hidden input with the selected ISO date. - id (type: string): Optional id applied to the trigger button. - aria-invalid (type: boolean): Marks the trigger as invalid for assistive tech and applies error styling. - side (type: "top" | "bottom", default: bottom): Preferred panel side relative to the trigger. Flips when there is not enough space. - align (type: "start" | "end", default: start): Horizontal alignment of the portaled panel to the trigger. - calendarProps (type: Omit): Props forwarded to the embedded Calendar, such as size, locale, disabled, bounds, modifiers, weekStartsOn, minYear, and maxYear. Range mode is not supported on DatePicker. ## Favicon Badge - URL: https://iconiqui.com/display-and-content/favicon-badge - Package: @iconiq/favicon-badge - Install: npx shadcn@latest add @iconiq/favicon-badge - Registry JSON: https://iconiqui.com/r/favicon-badge.json - Summary: Inline circular badge that resolves a website favicon from a domain or URL, with an optional text label and spring entrance animation. - Dependencies: motion, lucide-react ### Documented APIs - FaviconBadge: Inline circular badge that resolves a website favicon from a domain or URL, with an optional text label and spring entrance animation. - website (type: string, required): Domain or full URL used to resolve the favicon. Values such as `iconiqui.com` or `https://www.iconiqui.com` are normalized to a hostname. - label (type: string): Optional label rendered beside the circular favicon badge. When omitted, only the badge is shown and the domain is exposed to screen readers. - faviconUrl (type: string): Optional favicon URL that bypasses Google and DuckDuckGo resolution. Use for self-hosted icons or strict CSP environments. - faviconSize (type: 16 | 32 | 64 | 128, default: 64): Pixel size requested from Google's favicon service. Higher values can improve clarity on retina displays. - size (type: "sm" | "md" | "lg", default: "md"): Visual scale for the circular favicon badge container. Label text scales with size: `text-sm` on small, `text-base` on medium, and `text-lg` on large. - className (type: string): Merged onto the root inline-flex wrapper. - badgeClassName (type: string): Merged onto the circular favicon container for local border, background, or sizing overrides. - labelClassName (type: string): Merged onto the optional label when `label` is provided. - onFaviconLoad (type: (url: string) => void): Called after a favicon URL resolves successfully, including when `faviconUrl` is provided. - onFaviconError (type: () => void): Called when every provider fails or an override URL fails to load. ## Marker - URL: https://iconiqui.com/display-and-content/marker - Package: @iconiq/marker - Install: npx shadcn@latest add @iconiq/marker - Registry JSON: https://iconiqui.com/r/marker.json - Summary: Hand-drawn text annotations — wavy, circle, highlight, underline, and more — that draw themselves in like ink as they scroll into view, with an optional animate prop for a fully static render. - Dependencies: motion ### Documented APIs ## Progress - URL: https://iconiqui.com/display-and-content/progress - Package: @iconiq/progress - Install: npx shadcn@latest add @iconiq/progress - Registry JSON: https://iconiqui.com/r/progress.json - Summary: Determinate and indeterminate progress—with subtle motion. - Dependencies: @radix-ui/react-progress, motion ### Documented APIs - Progress: Determinate and indeterminate progress—with subtle motion. - value (type: number | null, default: 0): Current progress value. Pass null to switch into the indeterminate motion state instead of rendering a measured fill width. - min (type: number, default: 0): Lower bound used to normalize the fill width and the visible value text. - max (type: number, default: 100): Upper bound used to normalize the fill width and the visible value text. - label (type: string): Optional title rendered above the bar and linked to the progress semantics when present. - helper (type: string): Optional supporting copy rendered near the label for extra task context. When omitted, the header collapses down to just the label and trailing value readout. - showValue (type: boolean, default: true): Controls whether the trailing inline readout with the live formatted value or indeterminate label is shown. - formatValue (type: (value: number, percent: number) => string): Optional formatter for the visible value readout. Receives the current normalized value and percent so you can render units, fractions, or custom labels. - getValueLabel (type: (value: number, percent: number) => string): Optional formatter for screen-reader announcements when the accessible text should be more explicit than the visible readout. - indeterminateLabel (type: string, default: "In progress"): Text used for the visible value readout and accessible status when value is null. - ariaLabel (type: string): Accessible name used when no visible label is rendered. When omitted, unlabeled installs fall back to a generic Progress label. - className (type: string): Merged onto the root wrapper so you can control width, spacing, or placement in your layout. - variant (type: "default" | "circular", default: "default"): Linear bar (default) or circular gauge layout with a dual-stroke ring, 5% gap, and CSS-smoothed arc transitions. Circular mode renders the value readout centered inside the ring. - size (type: "sm" | "md" | "lg", default: "md"): Track height preset for the default bar, or ring diameter preset for the circular variant. - tone (type: "default" | "brand" | "destructive" | "success", default: "default"): Fill color preset for neutral, brand, destructive, or success emphasis. - trackClassName (type: string): Merged onto the track element for custom track styling. - indicatorClassName (type: string): Merged onto the fill element for custom indicator styling. - headerClassName (type: string): Merged onto the label, helper, and value readout row above the track. - Motion and semantics: Headless progress semantics from the provider primitive with a spring-smoothed fill and restrained indeterminate motion layered on top. ## Rating - URL: https://iconiqui.com/display-and-content/rating - Package: @iconiq/rating - Install: npx shadcn@latest add @iconiq/rating - Registry JSON: https://iconiqui.com/r/rating.json - Summary: Compound star rating built from Rating and RatingButton — hover to preview, click or use arrow keys to set the value, with configurable size on the root, a springy scale pop, and color fade that ripples across the stars. - Dependencies: @radix-ui/react-use-controllable-state, motion ### Documented APIs ## Rolling Digits - URL: https://iconiqui.com/display-and-content/rolling-digits - Package: @iconiq/rolling-digits - Install: npx shadcn@latest add @iconiq/rolling-digits - Registry JSON: https://iconiqui.com/r/rolling-digits.json - Summary: Inline animated counter that swaps digits with spring-driven transform, opacity, and vertical motion while exiting the previous character. - Dependencies: motion ### Documented APIs - RollingDigits: Inline animated counter that swaps digits with spring-driven transform, opacity, and vertical motion while exiting the previous character. - value (type: number, required): Target number to display. The component rounds to the nearest integer before formatting. - pad (type: number): Minimum digit count. Applied with `padStart` for plain numbers, or through `minimumIntegerDigits` when `locale` is enabled. - animationDelay (type: number, default: 80): Milliseconds between queued value steps when `value` changes faster than the animation can finish. - stagger (type: number): Deprecated. Seconds between queued steps. Use `animationDelay` in milliseconds instead. - coalesceUpdates (type: boolean, default: false): When true, rapid `value` updates replace the pending queue with the latest value instead of stepping through every intermediate update. - onAnimationComplete (type: () => void): Called when the displayed value catches up to the latest `value` prop. - ariaLive (type: boolean | "polite" | "assertive" | "off", default: true): Controls `aria-live` on the screen-reader layer. `true` maps to `polite`; `false` and `off` disable announcements. - startOnView (type: boolean, default: true): When true, playback waits until the component enters the viewport once before animating from zero. - locale (type: true | string | Intl.NumberFormatOptions): Locale formatting. `locale` uses the runtime default locale, a string sets the locale tag, and an object is passed to `Intl.NumberFormat`. When combined with `pad`, padding is applied through `minimumIntegerDigits`. - format (type: (value: number) => string): Custom formatter that runs after rounding. Overrides `locale` when both are provided. - gap (type: number, default: 2): Pixel gap between rendered characters in the digit row. - direction (type: "dynamic" | "up" | "down", default: dynamic): Controls whether incoming digits slide up or down. `dynamic` compares the previous and next digit values. - enterStiffness (type: number, default: 170): Spring stiffness for incoming digit motion. - enterDamping (type: number, default: 10): Spring damping for incoming digit motion. - exitStiffness (type: number, default: 170): Spring stiffness for outgoing digit motion. - exitDamping (type: number, default: 15): Spring damping for outgoing digit motion. - enterY (type: number, default: 32): Vertical offset in pixels used when a digit enters. - enterBlur (type: number): Deprecated. Blur is no longer applied; digit motion uses transform and opacity for Safari-safe rendering. - enterScale (type: number, default: 0.84): Starting scale applied when a digit enters. - exitScale (type: number, default: 0.84): Ending scale applied when a digit exits. - className (type: string): Merged onto the outer inline-flex span that wraps the readable and visual layers. - digitClassName (type: string): Merged onto each animated digit cell wrapper for per-digit styling. ## Skeleton - URL: https://iconiqui.com/display-and-content/skeleton - Package: @iconiq/skeleton - Install: npx shadcn@latest add @iconiq/skeleton - Registry JSON: https://iconiqui.com/r/skeleton.json - Summary: Loading placeholder that renders a muted block with shimmer or fade animation, sensible defaults, and preset helpers for common shapes. ### Documented APIs - Skeleton: Loading placeholder that renders a muted block with shimmer or fade animation, sensible defaults, and preset helpers for common shapes. - variant (type: "shimmer" | "fade", default: shimmer): Chooses between the moving shimmer sweep and a softer opacity fade. - rounded (type: "none" | "sm" | "md" | "lg" | "full", default: md): Chooses the corner radius utility applied to the placeholder surface. - animate (type: boolean, default: true): Controls whether the selected animation variant is rendered. Set it to false for a static loading block. - duration (type: number, default: 1.6): Animation cycle duration in seconds. Defaults to 1.6s for shimmer and 2.4s for fade. - decorative (type: boolean, default: true): When true, the skeleton is hidden from assistive tech so grouped placeholders do not repeat loading announcements. - label (type: string | null): Accessible label used when `decorative={false}`. Pass `null` to force a hidden decorative skeleton. - className (type: string): Merged onto the root div so you can control width, height, spacing, colors, and any extra local styling. - HTML div props (type: HTMLAttributes): Standard div attributes such as style, data-*, aria-*, id, and event handlers are forwarded to the root element. - Preset helpers: Opinionated wrappers around the base skeleton for avatar, text-line, and button placeholders. - SkeletonAvatar (type: Component): Renders a circular `size-10` avatar placeholder. - SkeletonText (type: Component): Renders a `h-3` text-line placeholder. - SkeletonButton (type: Component): Renders a `h-9 w-24` button placeholder with `rounded="lg"`. ## Spinner - URL: https://iconiqui.com/display-and-content/spinner - Package: @iconiq/spinner - Install: npx shadcn@latest add @iconiq/spinner - Registry JSON: https://iconiqui.com/r/spinner.json - Summary: Default export for a lightweight loading indicator with ring, dots, or matrix variants, size presets, and accessibility controls. - Dependencies: motion ### Documented APIs - Spinner: Default export for a lightweight loading indicator with ring, dots, or matrix variants, size presets, and accessibility controls. - variant (type: "ring" | "dots" | "matrix", default: ring): Chooses between the rotating ring, three bouncing dots, or a square dot-matrix sweep. - size (type: "sm" | "md" | "lg", default: md): Scales the spinner footprint and ring border thickness together. - decorative (type: boolean, default: false): When true, hides the spinner from assistive tech so a parent can announce loading once. - className (type: string): Merged onto the root span so you can fine-tune color, spacing, or layout with Tailwind utilities. ## Status Dot - URL: https://iconiqui.com/display-and-content/status-dot - Package: @iconiq/status-dot - Install: npx shadcn@latest add @iconiq/status-dot - Registry JSON: https://iconiqui.com/r/status-dot.json - Summary: Inline status indicator with optional rippling halo, deployment presets, generic tones, and dot-only accessibility defaults. ### Documented APIs - StatusDot: Inline status indicator with optional rippling halo, deployment presets, generic tones, and dot-only accessibility defaults. - state (type: "QUEUED" | "BUILDING" | "ERROR" | "READY" | "CANCELED"): Deployment preset that maps to tone, default label, and default animation. Use this or `tone`. - tone (type: "neutral" | "active" | "success" | "warning" | "error"): Generic presence tone when you do not need deployment vocabulary. Use this or `state`. - showLabel (type: boolean, default: false): Shows visible label text beside the dot. Defaults to dot-only for inline copy. - label (type: string): Optional label override used for visible copy and screen reader naming. - animate (type: boolean): Overrides ripple animation. Defaults to active states only, such as `BUILDING` or `tone="active"`. - size (type: "sm" | "md" | "lg", default: "md"): Scales the dot, ripple spread, and hit area together. - inline (type: boolean, default: true): Uses an inline-flex root for embedding inside sentences and compact rows. - className (type: string): Classes applied to the root element. - labelClassName (type: string): Classes applied to the visible label when `showLabel` is enabled. ## Table - URL: https://iconiqui.com/display-and-content/table - Package: @iconiq/table - Install: npx shadcn@latest add @iconiq/table - Registry JSON: https://iconiqui.com/r/table.json - Summary: Root provider for the animated table primitives. It sets the shared column template so header and body rows stay aligned. - Dependencies: motion, lucide-react ### Documented APIs - Table: Root provider for the animated table primitives. It sets the shared column template so header and body rows stay aligned. - children (type: ReactNode, required): Compose TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, and optional helper primitives inside the root. - columns (type: string, default: "minmax(0,1.4fr) minmax(0,1fr) minmax(0,1fr) minmax(0,1fr)"): Shared grid-template-columns value applied to every header and body row so the native table semantics still keep the custom grid layout aligned. - size (type: "default" | "compact", default: default): Controls row density by tightening header and body cell padding across the table. - stickyHeader (type: boolean, default: false): When true, TableHeader stays pinned while the surrounding scroll container moves. - className (type: string): Merged onto the native table element when you need to adjust width, spacing, or placement. - TableToolbar: Optional layout helper for the control row above the table, matching the original spacing and alignment treatment. - children (type: ReactNode, required): Usually a search field, actions, filters, or bulk controls placed above the table. - tableId (type: string): Optional id of the related table, exposed through aria-controls for toolbar controls. - className (type: string): Merged onto the toolbar wrapper. - TableHeader: Native table head wrapper for the column labels and sort controls. - children (type: ReactNode, required): Usually one header TableRow. - sticky (type: boolean): Overrides the root stickyHeader setting for this header section. - className (type: string): Merged onto the header wrapper. - TableBody: Native table body wrapper that adds LayoutGroup and AnimatePresence so row insertions, removals, and reordering stay animated. - children (type: ReactNode, required): One or more TableRow elements, plus optional TableEmpty or TableLoading when no rows are visible or data is still loading. - className (type: string): Merged onto the body wrapper. - TableFooter: Native table footer wrapper for totals, pagination, and bulk actions below the body rows. - children (type: ReactNode, required): Usually one footer TableRow containing TablePagination or summary cells. - className (type: string): Merged onto the footer wrapper. - TableRow: Motion-enabled native table row used for both header and body layouts. - variant (type: "header" | "body", default: body): Header rows skip mount and exit motion, while body rows keep the original motion defaults. - index (type: number, default: 0): Optional row index used to apply a subtle stagger to body row entry motion. - hoverable (type: boolean): When true, body rows get the muted hover wash. Defaults to false so informational rows do not imply clickability. - selected (type: boolean, default: false): Applies selected styling and exposes data-state="selected" for active row selection. - className (type: string): Merged onto the row shell for spacing or color overrides. - Motion tr props (type: ComponentPropsWithoutRef): Additional motion.tr props such as layout, transition, whileHover, and exit can still be passed directly. - TableHead: Native header cell wrapper for labels, sort buttons, and aligned controls. - align (type: "left" | "center" | "right", default: left): Controls left, center, or right alignment for the header cell content. - sortDirection (type: "asc" | "desc" | "none"): Explicit aria-sort source for sortable columns. Pass "none" on inactive sortable headers. - children (type: ReactNode, required): Header label or a custom control such as TableSortButton. - className (type: string): Merged onto the header cell wrapper. - TableCell: Native body cell wrapper for row content, status pills, numeric values, and row actions. - align (type: "left" | "center" | "right", default: left): Controls left, center, or right alignment for the cell content. - children (type: ReactNode, required): Rendered cell content. - className (type: string): Merged onto the cell wrapper. - TableSelectHead: Checkbox header cell helper for select-all row selection columns. - checked (type: boolean, default: false): Controlled checked state for the select-all checkbox. - indeterminate (type: boolean, default: false): Shows the mixed selection state when only some visible rows are selected. - onCheckedChange (type: (checked: boolean) => void): Called when the select-all checkbox toggles. - aria-label (type: string, default: "Select all rows"): Accessible name for the select-all checkbox. - TableSelectCell: Checkbox body cell helper for per-row selection columns. - checked (type: boolean, default: false): Controlled checked state for the row checkbox. - onCheckedChange (type: (checked: boolean) => void): Called when the row checkbox toggles. - aria-label (type: string, required): Accessible name for the row checkbox, such as the row title. - TableCaption: Low-emphasis native table caption below the table, matching the original entry count styling. - children (type: ReactNode, required): Caption copy, summary text, or count information. - className (type: string): Merged onto the caption paragraph. - TableEmpty: Animated empty-state row for zero-result or no-data states inside TableBody. - children (type: ReactNode, required): Empty-state copy or a richer no-data message. - colSpan (type: number): Overrides the automatically derived column span when the empty row should cover a different number of columns. - Motion tr props (type: ComponentPropsWithoutRef): You can still override animate, initial, transition, or className when customizing the empty state row. - TableLoading: Placeholder body rows with pulse bars for async loading states inside TableBody. - rows (type: number, default: 3): Number of placeholder rows to render. - TableRow props (type: Omit): Optional TableRow props such as index or className passed to each loading row. - TableSortButton: Optional header helper with a larger hit area, clearer active state, and direction animation. - active (type: boolean, default: false): Strengthens the visual treatment and enables the active sort direction state for the parent column header. - direction (type: "asc" | "desc", default: asc): Rotates the chevron when the current active sort direction is descending. - align (type: "left" | "center" | "right", default: left): Keeps the sort button aligned with the header cell it lives in, including full-width right-aligned targets. - children (type: ReactNode, required): Visible sort label. - aria-label (type: string): Optional override for the generated sort label announced to screen readers. - className (type: string): Merged onto the button wrapper. - TablePagination: Pagination helper with previous/next controls and optional range copy, placed below the table. - align (type: "left" | "center" | "right", default: right): Aligns the page summary and previous/next controls as a group below the table. - page (type: number, required): Current one-based page index. - pageCount (type: number, required): Total number of available pages. - onPageChange (type: (page: number) => void, required): Called when the previous or next control changes pages. - pageSize (type: number): Used with totalItems to render a range label such as 1–5 of 12. - totalItems (type: number): Total item count shown in the optional range label. - showPageInfo (type: boolean, default: true): Toggles the range or page summary text. ## Timezone - URL: https://iconiqui.com/display-and-content/timezone - Package: @iconiq/timezone - Install: npx shadcn@latest add @iconiq/timezone - Registry JSON: https://iconiqui.com/r/timezone.json - Summary: Inline live clock that resolves friendly city names or IANA timezone strings, then animates digit changes with fluid spring rolls and pulsing separators. - Dependencies: motion ### Documented APIs - Timezone: Inline live clock that resolves friendly city names or IANA timezone strings, then animates digit changes with fluid spring rolls and pulsing separators. - zone (type: string, required): City alias such as `San Francisco`, common shorthand like `NYC`, region/city IANA paths such as `Africa/Cairo`, or any of the 400+ IANA timezones from `Intl.supportedValuesOf('timeZone')`. - format (type: "12h" | "24h", default: "12h"): Controls whether the clock renders with a 12-hour or 24-hour display. - showZoneLabel (type: boolean, default: true): When true, appends a timezone label after the clock. - showAbbreviation (type: boolean, default: true): Deprecated alias for `showZoneLabel`. Prefer `showZoneLabel` in new code. - zoneName (type: "abbreviation" | "offset", default: "abbreviation"): Controls the label style when `showZoneLabel` is true. `abbreviation` renders IST, EST, or PST. `offset` renders GMT-style labels such as GMT+5:30. - live (type: boolean, default: false): When true, updates every second and includes seconds in the formatted output. - locale (type: string, default: "en-US"): Locale passed to `Intl.DateTimeFormat` for number and time formatting. - fallback (type: ReactNode): Custom content rendered when `zone` cannot be resolved. Defaults to `Unknown timezone: {zone}`. - onError (type: (zone: string) => void): Called when `zone` cannot be resolved. Useful for logging or analytics. - animate (type: boolean, default: true): When false, disables digit and separator motion even if reduced motion is off. - ariaLive (type: boolean | "polite" | "assertive" | "off"): Adds `aria-live` to a screen-reader-only layer. Defaults to `polite` for minute clocks and off for `live` second clocks. - className (type: string): Optional class names applied to the rendered `time` element. ## Verified Badge - URL: https://iconiqui.com/display-and-content/verified-badge - Package: @iconiq/verified-badge - Install: npx shadcn@latest add @iconiq/verified-badge - Registry JSON: https://iconiqui.com/r/verified-badge.json - Summary: Inline X-style verified scallop with a check. Use shimmer or static variants, size presets, and brand/gold/neutral tones. - Dependencies: motion ### Documented APIs - VerifiedBadge: Inline X-style verified scallop with a check. Use shimmer or static variants, size presets, and brand/gold/neutral tones. - variant (type: "shimmer" | "static", default: shimmer): Use `shimmer` for a sweeping highlight across the scallop or `static` for a fixed badge. - size (type: "sm" | "md" | "lg" | number, default: md): Preset sizes map to 18px, 22px, and 28px. Pass a number for an explicit pixel width and height. - tone (type: "brand" | "gold" | "neutral", default: brand): Brand uses `--verified-badge-color` (defaults to `--ic-brand`). Gold and neutral provide alternate trust-indicator palettes. - decorative (type: boolean, default: false): When true, hides the badge from assistive tech. Use when visible copy already announces verification. - className (type: string): Merged onto the root span. Pass a `text-*` class to override the tone color. - aria-label (type: string, default: Verified): Announced to screen readers when `decorative` is false. Override when the badge conveys a different status. ## Week Calendar - URL: https://iconiqui.com/display-and-content/week-calendar - Package: @iconiq/week-calendar - Install: npx shadcn@latest add @iconiq/week-calendar - Registry JSON: https://iconiqui.com/r/week-calendar.json - Summary: Week strip that morphs into a full month grid, with a shared-layout spring pill and a draggable grabber handle. - Dependencies: motion, lucide-react, date-fns ### Documented APIs ## Alert - URL: https://iconiqui.com/feedback-and-alerts/alert - Package: @iconiq/alert - Install: npx shadcn@latest add @iconiq/alert - Registry JSON: https://iconiqui.com/r/alert.json - Summary: Root container for a single notice. Uses a compact grid layout with optional leading icon, compound title and description slots, legacy prop support, and inline or toast behavior. - Dependencies: motion, class-variance-authority ### Documented APIs - Alert: Root container for a single notice. Uses a compact grid layout with optional leading icon, compound title and description slots, legacy prop support, and inline or toast behavior. - children (type: ReactNode): Preferred compound API. Pass an optional leading icon followed by AlertTitle and AlertDescription. - icon (type: ReactNode): Legacy leading visual prop. Compound children can also provide the leading icon as the first child. - title (type: ReactNode): Legacy title prop rendered with the same AlertTitle styling. Prefer AlertTitle for new code. - message (type: ReactNode): Legacy description prop rendered with the same AlertDescription styling. Prefer AlertDescription for new code. - action (type: ReactNode): Optional action row rendered beneath the message, useful for a single follow-up button or link such as Undo or View details. - appearance (type: "default" | "success" | "info" | "destructive" | "warning", default: "default"): Visual tone for the alert surface. Success and info use semantic green and blue surfaces; destructive shifts toward error colors; warning uses a warm amber surface with muted description text. - size (type: "sm" | "md" | "lg" | "xl", default: "md"): Preset max width for inline and toast alerts. sm is 320px, md is 400px, lg is 480px, and xl is 560px. - width (type: string | number): Custom max width. Pass a CSS length such as 28rem or a pixel number. Overrides size when set. - dismissible (type: boolean, default: legacy: true; compound inline: false): Controls whether the close button is rendered. Compound inline alerts are static by default; toast and legacy prop alerts remain dismissible unless you opt out. - variant (type: "inline" | "toast", default: "inline"): Explicitly chooses layout behavior. Toasts portal to document.body and use fixed viewport positioning, while inline alerts stay in normal document flow. - position (type: "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"): Optional toast placement. Providing a position also upgrades the component to toast behavior, and omitted toast positions default to top-right. - timeout (type: number, default: legacy/toast: 5000; compound inline: 0): Auto-dismiss delay in milliseconds. Passing 0 disables the timer; compound inline alerts default to no timer so static notices stay visible. - open (type: boolean): Controlled visibility. Pair with onOpenChange when parent state should own whether the alert is shown. - defaultOpen (type: boolean, default: true): Initial visibility for uncontrolled usage. Ignored when open is provided. - onOpenChange (type: (open: boolean) => void): Called when visibility changes from dismissal, timeout, Escape, or the close button. - titleLines (type: 1 | 2 | 3 | "none", default: 1): Maximum title lines before truncation. Pass none to allow the title to wrap freely. - onDismiss (type: () => void): Called after the component finishes its exit transition, regardless of whether dismissal came from the close button or the timeout effect. - AlertTitle: Primary line for the compound alert API. Renders in the second grid column beside the optional icon. - children (type: ReactNode, required): Short title or inline formatted heading content. - className (type: string): Merged with the title typography classes for one-off styling. - AlertDescription: Secondary line for the compound alert API. Renders beneath the title in the second grid column and links to the root with aria-describedby. - children (type: ReactNode, required): Supporting message content. Keep it concise for compact inline notices and toast updates. - className (type: string): Merged with the description typography classes for one-off styling. - AlertAction: Optional action row for the compound alert API. Renders beneath the description in the content column. - children (type: ReactNode, required): Follow-up controls such as a single button or text link. Keep actions concise. - className (type: string): Merged with the action row layout classes. - Motion and lifecycle: Alert uses AnimatePresence for mount and exit, with separate variants for the container, icon, and text stack. ## Autocomplete - URL: https://iconiqui.com/inputs-and-forms/autocomplete - Package: @iconiq/b-autocomplete - Install: npx shadcn@latest add @iconiq/b-autocomplete - Registry JSON: https://iconiqui.com/r/b-autocomplete.json - Summary: Root autocomplete controller. Compose AutocompleteInput, AutocompleteContent, AutocompleteList, and AutocompleteItem inside it. - Dependencies: @base-ui/react, motion, lucide-react ### Documented APIs - Autocomplete: Root autocomplete controller. Compose AutocompleteInput, AutocompleteContent, AutocompleteList, and AutocompleteItem inside it. - items (type: readonly Item[]): Item collection used for list filtering. Pass a flat array or grouped items for sectioned results. - value (type: string): Controlled input text shown in the field. - defaultValue (type: string): Initial input text for uncontrolled usage. - onValueChange (type: (value: string, eventDetails) => void): Called when the input text changes from typing or when a suggestion is accepted. - itemToStringValue (type: (item: Item) => string): Maps each item to the string used for filtering and the committed input value. - autoHighlight (type: boolean | "always", default: true): Automatically highlights the first matching item while typing. - keepHighlight (type: boolean, default: false): When true, keeps the highlighted item when the pointer leaves the list. - open (type: boolean): Controlled popup state. Pair with onOpenChange. - onOpenChange (type: (open: boolean, eventDetails) => void): Called when the suggestion panel opens or closes. Use with open for controlled popup state. - onItemHighlighted (type: (item: Item | undefined, eventDetails) => void): Called when the highlighted suggestion changes from keyboard, pointer, or programmatic updates. - openOnInputClick (type: boolean, default: false): When true, clicking the input opens the suggestion panel even before typing. - submitOnItemClick (type: boolean, default: false): When true, selecting an item submits the owning form. Useful for search inputs. - modal (type: boolean, default: false): When true, traps focus inside the popup. Pair with AutocompleteBackdrop for a dimmed overlay. - isItemEqualToValue (type: (item: Item, value: Item) => boolean): Custom equality for object items. Use when items are recreated on each render. - AutocompleteInput: Styled input shell with border, focus ring, optional clear control, and invalid-state styling via aria-invalid. The field control uses Base UI Input. - label (type: React.ReactNode): Optional field label rendered above the input and linked with htmlFor. - labelClassName (type: string): Optional class names merged onto the field label. - placeholder (type: string): Shown when the input is empty. - showClear (type: boolean, default: true): Controls whether AutocompleteClear is rendered. - showTrigger (type: boolean, default: false): When true, renders a chevron trigger that toggles the suggestion panel. - disabled (type: boolean, default: false): Disables the input, clear button, and trigger. - aria-invalid (type: boolean | 'true' | 'false'): When true, applies destructive border and ring styling to the input shell. - AutocompleteClear: Clears the current input text. Rendered automatically when AutocompleteInput showClear is true. - disabled (type: boolean, default: false): Disables the clear button. - className (type: string): Merged onto the clear button. - AutocompleteTrigger: Chevron button that toggles the suggestion panel. Includes aria-expanded and aria-label for screen readers. - disabled (type: boolean, default: false): Disables the trigger button. - AutocompleteContent: Portaled suggestion panel with a subtle fade-slide entrance and anchored width. - side (type: "top" | "right" | "bottom" | "left", default: "bottom"): Preferred side for the popup. - align (type: "start" | "center" | "end", default: "start"): Popup alignment relative to the input anchor. - sideOffset (type: number, default: 6): Distance between the input and the popup. - className (type: string): Merged onto the animated popup panel. - AutocompleteList: Scrollable suggestion list rendered inside AutocompleteContent. - children (type: ReactNode | ((item, index) => ReactNode), required): Render explicit AutocompleteItem children or a render function when using the root items prop. - className (type: string): Merged with the default list spacing and scroll classes. - AutocompleteItem: Suggestion row with optional description and a spring-driven highlight fill. - value (type: Item, required): Item value passed to Base UI for selection handling. - description (type: ReactNode): Optional secondary line below the primary label. - AutocompleteEmpty: Empty-state message shown when filtering returns no matches. Place inside AutocompleteContent after AutocompleteList. - children (type: ReactNode, default: "No results found."): Message shown when the filtered list is empty. - AutocompleteStatus: Live status region for async loading or result counts. Keep mounted and update children instead of conditionally removing the component. - children (type: ReactNode): Status text announced politely to screen readers, such as Loading or No matches. - AutocompleteGroup: Groups related suggestions inside AutocompleteList. - items (type: readonly Item[]): Items rendered inside this group when using grouped root items. - AutocompleteLabel: Section label rendered above a group of suggestions. - children (type: ReactNode, required): Group heading text. - AutocompleteSeparator: Horizontal divider between suggestion groups or rows. - AutocompleteCollection: Renders the current filtered collection when not using AutocompleteList render props. - AutocompleteValue: Reads the current input value from context for custom display layouts. - AutocompleteIcon: Leading icon slot rendered inside AutocompleteInput. - AutocompleteBackdrop: Dimmed overlay for modal autocomplete usage. Render as a sibling of AutocompleteContent when modal is true. - AutocompleteRow: Row wrapper for multi-column or complex suggestion layouts. ## Checkbox - URL: https://iconiqui.com/inputs-and-forms/checkbox - Package: @iconiq/b-checkbox - Install: npx shadcn@latest add @iconiq/b-checkbox - Registry JSON: https://iconiqui.com/r/b-checkbox.json - Summary: Provider-switchable single checkbox layered over Base UI or Radix primitives with optional label, description, and form-field props. - Dependencies: @base-ui/react, motion ### Documented APIs - Checkbox: Provider-switchable single checkbox layered over Base UI or Radix primitives with optional label, description, and form-field props. - checked (type: boolean | "indeterminate"): Controlled checked state. Pass true, false, or "indeterminate" for partial selection rows such as select-all headers. - defaultChecked (type: boolean | "indeterminate", default: false): Initial state for uncontrolled usage. It is only read on the first render. - onCheckedChange (type: (checked: boolean) => void): Called with the next boolean value whenever the user toggles the checkbox. Indeterminate clicks resolve to true. - label (type: React.ReactNode): Optional label rendered beside the control. When provided with description, both sit inside a native label element linked by htmlFor. - description (type: React.ReactNode): Optional helper copy rendered under the label and linked through aria-describedby. - labelClassName (type: string): Merged onto the label text wrapper. - descriptionClassName (type: string): Merged onto the description text wrapper. - disabled (type: boolean, default: false): Disables interaction and applies reduced opacity to the full row. - readOnly (type: boolean, default: false): Shows the current state without allowing toggles. Useful for locked consent rows. - required (type: boolean, default: false): Forwards native required validation to the hidden checkbox input and appends a visual asterisk to the label. - invalid (type: boolean, default: false): Applies destructive border styling and aria-invalid for form validation feedback. - name (type: string): Input name submitted with native forms. - value (type: string): Value submitted when the checkbox is checked. - form (type: string): Associates the hidden input with a form element by id when the checkbox renders outside the form. - size (type: "sm" | "default" | "lg", default: "default"): Adjusts box, icon, label, and row spacing together. - id (type: string): Stable id for the control. When omitted, the component generates one and uses it for label association. - className (type: string): Merged onto the outer row wrapper so you can position the checkbox in your layout. - Motion and accessibility: Visual feedback comes from Motion while checkbox semantics travel through the underlying primitive and hidden input. ## Checkbox Group - URL: https://iconiqui.com/inputs-and-forms/checkbox-group - Package: @iconiq/b-checkbox-group - Install: npx shadcn@latest add @iconiq/b-checkbox-group - Registry JSON: https://iconiqui.com/r/b-checkbox-group.json - Summary: A single checkbox row composed as a child of CheckboxGroup or CheckboxGroupSection. - Dependencies: @base-ui/react, motion ### Documented APIs - CheckboxGroupItem: A single checkbox row composed as a child of CheckboxGroup or CheckboxGroupSection. - label (type: React.ReactNode, required): Primary copy shown for the row. - value (type: string, required): Stable identifier used when checking whether the row is selected and when producing the next selection array. - id (type: string): Optional stable id used for label and description associations. Falls back to a generated id when omitted. - description (type: React.ReactNode): Optional secondary text rendered below the label and linked through aria-describedby. - disabled (type: boolean): Disables this row only. Use CheckboxGroupSection disabled to disable an entire section. - disabledReason (type: string): Optional explainer rendered below disabled rows and linked through aria-describedby. - readOnly (type: boolean): Shows this row without allowing toggles and keeps it checked. Pair with CheckboxGroup value for mixed read-only and interactive rows. - CheckboxGroupSection: Named fieldset wrapper for a cluster of CheckboxGroupItem children. Mirrors how ButtonGroup composes child buttons. - label (type: string): Optional section heading rendered as a fieldset legend. Required for maxVisible section collapse. - disabled (type: boolean, default: false): Disables every checkbox row inside this section and applies native fieldset disabled semantics. - children (type: React.ReactNode, required): CheckboxGroupItem elements to render inside the section. - CheckboxGroupOption: Legacy options-array shape. Prefer CheckboxGroupItem children for new installs. - label (type: React.ReactNode, required): Primary copy shown for the row. - value (type: string, required): Stable identifier used when checking whether the row is selected and when producing the next selection array. - id (type: string): Optional stable id used for label and description associations. Falls back to a generated id when omitted. - description (type: React.ReactNode): Optional secondary text rendered below the label and linked through aria-describedby. - group (type: string): Optional section label used to chunk long lists into named fieldset groups when adjacent options share the same value. - disabled (type: boolean): Disables the row button and blocks hover, active, and toggle behavior for that option. Works inside grouped sections as well as flat lists. - disabledReason (type: string): Optional explainer rendered below disabled rows and linked through aria-describedby. - readOnly (type: boolean): Shows the row state without allowing toggles. Useful for locked consent or audit views. - CheckboxGroup: Animated multi-select list composed with CheckboxGroupSection and CheckboxGroupItem children, with optional legacy options prop support. - children (type: React.ReactNode): Preferred composition API. Pass CheckboxGroupItem rows directly or nest them inside CheckboxGroupSection wrappers. - options (type: CheckboxGroupOption[]): Legacy array-based configuration. Ignored when children are provided. - value (type: string[]): Controlled selected values. When provided, the parent remains the source of truth while the component renders an immediate optimistic preview after each click. - defaultValue (type: string[], default: []): Initial selected values for uncontrolled usage. Ignored when value is provided. - onChange (type: (value: string[]) => void): Receives the next selected values array after a row is toggled, normalized back into the original display order. - name (type: string): Forwarded to each hidden checkbox input for native form submission. - form (type: string): Associates the hidden checkbox inputs with a distant form element by id. - disabled (type: boolean, default: false): Disables every row in the group. Prefer CheckboxGroupSection disabled or CheckboxGroupItem disabled for partial disable. - invalid (type: boolean, default: false): Applies destructive border styling and aria-invalid for form validation feedback. - size (type: "sm" | "default" | "lg", default: "default"): Controls row padding, checkbox box size, and label typography. - maxVisible (type: number): When labeled CheckboxGroupSection children are used, limits how many sections stay visible before a show more control appears. - showMoreLabel (type: string, default: "Show more"): Button label when grouped sections are collapsed. Appends the hidden section count in parentheses. - showLessLabel (type: string, default: "Show less"): Button label when grouped sections are expanded. - aria-label (type: string): Accessible name for the checkbox group when no visible label is present. - aria-labelledby (type: string): Id of an external element that labels the checkbox group. - aria-describedby (type: string): Id of an external element that describes the checkbox group. - className (type: string): Merged onto the root flex column wrapper. - Motion and accessibility: Base UI supplies role='group', checkbox semantics, and hidden native inputs underneath the animated row shell. ## Color Picker - URL: https://iconiqui.com/inputs-and-forms/color-picker - Package: @iconiq/color-picker - Install: npx shadcn@latest add @iconiq/color-picker - Registry JSON: https://iconiqui.com/r/color-picker.json - Summary: Self-contained HSV panel with saturation field, hue/alpha sliders, multi-format readouts, presets, popover mode, and EyeDropper. - Dependencies: @base-ui/react, lucide-react, motion ### Documented APIs - ColorPicker: Self-contained HSV panel with saturation field, hue/alpha sliders, multi-format readouts, presets, popover mode, and EyeDropper. - value (type: string): Controlled hex color such as #3B82F6 or #3B82F680. When provided, the picker syncs its internal state to this value. - defaultValue (type: string, default: #3B82F6): Starting color for uncontrolled usage (3-, 6-, or 8-digit hex). Ignored when value is supplied. - onChange (type: (color: string, detail: ColorPickerChangeDetail) => void): Called when the color settles (pointer up on sliders, blur/Enter on inputs). Emits #RRGGBB, or #RRGGBBAA when alpha is below 100%, plus CSS strings in detail. - onValueCommit (type: (color: string, detail: ColorPickerChangeDetail) => void): Fires alongside onChange when the color settles. Useful for form commit handlers. - defaultAlpha (type: number, default: 100): Starting alpha percentage (0–100) for uncontrolled usage when defaultValue has no alpha channel. - defaultFormat (type: "HEX" | "RGB" | "HSL" | "OKLCH", default: HEX): Initial readout format for the footer row. - variant (type: "inline" | "popover" | "swatch", default: inline): Inline panel (default), field popover trigger, or compact swatch trigger that opens the picker on click. - open (type: boolean): Controlled open state when variant is popover. - defaultOpen (type: boolean, default: false): Initial open state for uncontrolled popover usage. - onOpenChange (type: (open: boolean) => void): Called when the popover panel opens or closes. - placeholder (type: string, default: Pick a color): Placeholder text for the popover trigger label. - presets (type: string[]): Quick-select swatch colors shown above the saturation field. - swatchShape (type: "default" | "circle", default: default): Corner style for swatch triggers and preset chips. Use circle for a fully round swatch. - showAlpha (type: boolean, default: true): Shows or hides alpha controls and keeps output opaque when false. - showCopy (type: boolean, default: false): Shows a copy-to-clipboard control for the active format string. - disabled (type: boolean, default: false): Disables picker interaction and lowers shell opacity. - showEyedropper (type: boolean, default: true): Shows or hides the pipette control in the footer row. - onEyedropperUnsupported (type: () => void): Called when EyeDropper is unavailable. No alert dialog is shown by default. - id (type: string): Root element id used for internal aria wiring. - name (type: string): Hidden input name for native form submission. - aria-label (type: string, default: Color picker): Accessible label when not using aria-labelledby. - aria-labelledby (type: string): ID of an external label element. - className (type: string): Merged onto the outer shell for width, shadow, or layout overrides. ## Combobox - URL: https://iconiqui.com/inputs-and-forms/combobox - Package: @iconiq/b-combobox - Install: npx shadcn@latest add @iconiq/b-combobox - Registry JSON: https://iconiqui.com/r/b-combobox.json - Summary: Root combobox controller. Compose ComboboxInput, ComboboxContent, ComboboxList, and ComboboxItem inside it. - Dependencies: @base-ui/react, motion, lucide-react ### Documented APIs - Combobox: Root combobox controller. Compose ComboboxInput, ComboboxContent, ComboboxList, and ComboboxItem inside it. - items (type: readonly Item[]): Optional item collection used by Base UI for filtering and render-function lists. - value (type: Item | Item[] | null): Controlled selected value. Use an array when multiple is true. - defaultValue (type: Item | Item[] | null): Initial selected value for uncontrolled usage. - onValueChange (type: (value, eventDetails) => void): Called when an item is selected, a chip is removed, or the clear action resets the selection. - multiple (type: boolean, default: false): Allows selecting multiple items. Pair with ComboboxChips, ComboboxChip, and ComboboxChipsInput. - itemToStringLabel (type: (item: Item) => string): Maps object values to the label shown in the input and used for text filtering. - itemToStringValue (type: (item: Item) => string): Maps object values to the hidden form value. - isItemEqualToValue (type: (item, value) => boolean): Custom equality check for object values. Defaults to Object.is. - inputValue (type: string): Controlled search text. Leave uncontrolled for Base UI to manage query state. - onInputValueChange (type: (inputValue, eventDetails) => void): Called when the typed query changes. - autoHighlight (type: boolean, default: false): Automatically highlights the first matching item while filtering. - open (type: boolean): Controlled popup state. Pair with onOpenChange. - onOpenChange (type: (open, eventDetails) => void): Called when the popup opens or closes. - openOnInputClick (type: boolean, default: false): When true, clicking the input shell opens the popup. Otherwise only focus is moved. - onItemHighlighted (type: (value, eventDetails) => void): Called when the highlighted item changes from keyboard or pointer navigation. - ComboboxInput: Styled input shell with border, focus ring, optional label, clear button, and rotating trigger icon. - label (type: ReactNode): Optional label rendered above the input shell with an associated htmlFor. - placeholder (type: string): Shown when no item is selected and the input is empty. - showClear (type: boolean, default: true): Controls whether ComboboxClear is rendered in the input. - showTrigger (type: boolean, default: true): Controls whether the rotating trigger icon is rendered in the input. - size (type: "sm" | "default", default: "default"): Controls the input shell height. - className (type: string): Merged onto the wrapper when label is set, otherwise onto the input shell. - disabled (type: boolean, default: false): Disables the input, clear button, and trigger while applying reduced-opacity presentation. - aria-invalid (type: boolean): When true, applies destructive border and ring styling to the input shell. - ComboboxClear: Clears the current selection. Rendered automatically inside ComboboxInput when showClear is true. - disabled (type: boolean, default: false): Prevents clearing while disabled. - className (type: string): Merged onto the clear button. - ComboboxTrigger: Opens or closes the popup. Rendered automatically inside ComboboxInput when showTrigger is true. - disabled (type: boolean, default: false): Prevents toggling while disabled. - className (type: string): Merged onto the trigger button. - ComboboxStatus: Announces async loading or empty-state copy politely to screen readers. - children (type: ReactNode): Status message content. Keep the root mounted and update children instead of conditionally rendering the component. - className (type: string): Merged onto the status container. - ComboboxContent: Portaled dropdown surface with the previous white/dark panel, border, shadow, and fade-slide motion. - side (type: "top" | "right" | "bottom" | "left" | "inline-start" | "inline-end", default: "bottom"): Preferred side for the popup. - align (type: "start" | "center" | "end", default: "start"): Popup alignment relative to the input anchor. - sideOffset (type: number, default: 4): Gap between the input shell and dropdown. - className (type: string): Merged onto the animated popup panel. - ComboboxList: Scrollable item list rendered inside ComboboxContent with the previous max-height and motion treatment. - children (type: ReactNode | ((item, index) => ReactNode), required): Render explicit children or a render function when using the root items prop. - className (type: string): Merged with the default list spacing and scroll classes. - ComboboxItem: Animated row with active highlight, optional description layout, and selected checkmark spring. - value (type: Item, required): Stable value used by Base UI for selection. - children (type: ReactNode, required): Primary item label content. - description (type: ReactNode): Optional secondary line rendered below the item label, matching the prior option description UI. - className (type: string): Merged with the default row layout and motion classes. ## File Upload - URL: https://iconiqui.com/inputs-and-forms/file-upload - Package: @iconiq/file-upload - Install: npx shadcn@latest add @iconiq/file-upload - Registry JSON: https://iconiqui.com/r/file-upload.json - Summary: Drag-and-drop uploader with paste support, validation, optional real upload hooks, controlled queue state, and accessible progress feedback. - Dependencies: motion, lucide-react ### Documented APIs - FileUpload: Drag-and-drop uploader with paste support, validation, optional real upload hooks, controlled queue state, and accessible progress feedback. - accept (type: string): Optional accept string passed to the hidden file input and enforced for dropped or pasted files, including MIME types like image/* and extensions like .pdf. - multiple (type: boolean, default: true): Allows selecting or dropping multiple files. When set to false, the next selection replaces the existing queue. - maxFiles (type: number): Caps the queue length. New files are prepended, and anything beyond the limit is rejected with inline feedback. - maxSize (type: number): Maximum file size in bytes. Files above the limit are rejected with inline feedback. - disabled (type: boolean, default: false): Disables click, drag, paste, keyboard activation, remove, clear-all, and the hidden file input. - required (type: boolean, default: false): Forwards required validation to the hidden file input when the queue is empty. - invalid (type: boolean, default: false): Marks the drop zone with invalid styling for external validation states. - preventDuplicates (type: boolean, default: false): Rejects files that match an existing queue item by name, size, and lastModified. - simulateUpload (type: boolean): Controls built-in progress simulation. Defaults to true when onUpload is not provided, and false when onUpload is set. - showClearAll (type: boolean, default: true): Shows a clear-all action when the queue has files. - name (type: string): Passes a form field name through to the hidden file input. The queue stays synced to the input for native form submission. - id (type: string): Root id used for the hidden file input and internal aria-describedby wiring. - ariaLabel (type: string, default: Upload files): Accessible label for the keyboard-focusable drop zone. - ariaDescribedBy (type: string): Additional ids merged into the drop zone aria-describedby list. - description (type: string): Optional helper text rendered above the drop zone. - dropzoneTitle (type: string): Custom primary drop zone label. - dropzoneDescription (type: string): Custom secondary drop zone hint. When omitted, a hint is generated from accept, maxFiles, and maxSize. - libraryLabel (type: string, default: Library): Heading label for the queued file list. - browseLabel (type: string, default: Browse): Label for the browse affordance in the drop zone. - clearAllLabel (type: string, default: Clear all): Label for the clear-all action. - className (type: string): Adds classes to the outer wrapper without changing the component internals. - defaultValue (type: File[]): Initial queue files for uncontrolled usage. - value (type: FileUploadItem[]): Controlled queue state including per-file progress and status. - validateFile (type: (file: File) => boolean | string): Custom per-file validator. Return true to accept, false to reject, or a string error message. - onFilesChange (type: (files: File[]) => void): Called when files are added or removed from the queue. It does not fire on every progress tick. - onValueChange (type: (items: FileUploadItem[]) => void): Called when the queue changes, including status and progress updates in controlled mode. - onFileRemove (type: (file: File, nextFiles: File[]) => void): Called after a queued file is removed. The second argument contains the remaining files in queue order. - onReject (type: (files: File[], reason: FileUploadRejectReason, message: string) => void): Called when one or more files fail accept, size, duplicate, max-files, validation, or disabled checks. - onUpload (type: (file: File, context: { setProgress: (progress: number) => void }) => Promise): Optional real upload handler. When provided, built-in progress simulation is disabled unless simulateUpload is explicitly set to true. - onUploadComplete (type: (files: File[]) => void): Called once every item in the current queue reaches done status. - Built-in behavior: The component owns preview lifecycle, progress visuals, retry, and inline rejection messaging unless you take over with onUpload or controlled value. - progress state (type: built-in): Each added file starts in uploading state. Without onUpload, a simulated progress loop runs until done. With onUpload, progress follows setProgress from your handler. - error + retry (type: built-in): Failed onUpload calls move a file to error status and expose a retry action that reruns the upload handler or restarts simulation. - image and video previews (type: built-in): Image and video files receive object URL previews. Upload progress renders as an overlay on thumbnails and as a ring for other file types. - remove + clear all (type: built-in): Each queued file can be removed individually. Clear all empties the queue and revokes preview URLs immediately. ## Input - URL: https://iconiqui.com/inputs-and-forms/input - Package: @iconiq/input - Install: npx shadcn@latest add @iconiq/input - Registry JSON: https://iconiqui.com/r/input.json - Summary: Input with a spring-animated caret. - Dependencies: @base-ui/react/input, motion ### Documented APIs - Input: Input with a spring-animated caret. - value (type: string): Controlled input value. Pair with `onValueChange` or `onChange` when the parent owns the text. - defaultValue (type: string): Initial value for uncontrolled usage. - onValueChange (type: (value: string, eventDetails: InputChangeEventDetails) => void): Base UI change handler with the next string value and event metadata. Preferred for controlled forms. - onChange (type: React.ChangeEventHandler): Native change handler fired after typing, paste, cut, or autofill. - type (type: React.HTMLInputTypeAttribute, default: text): Native input type. Smooth caret is enabled for text-like types only (`text`, `search`, `url`, `email`, `password`, `tel`). - label (type: React.ReactNode): Optional field label rendered above the control with an associated `htmlFor` id. - labelClassName (type: string): Classes merged onto the optional label element. - description (type: React.ReactNode): Optional helper text rendered below the input shell and linked with `aria-describedby`. - descriptionClassName (type: string): Classes merged onto the description element. - errorMessage (type: React.ReactNode): Validation message rendered below the field. Also sets `aria-invalid` and links through `aria-describedby`. - errorMessageClassName (type: string): Classes merged onto the error message element. - invalid (type: boolean, default: false): Applies destructive shell styling and forwards `aria-invalid` to the native input. - required (type: boolean, default: false): Forwards native required validation and appends a visual asterisk to the label. - size (type: "sm" | "default", default: default): Controls the input shell height. - shellClassName (type: string): Classes merged onto the bordered input shell. - wrapperClassName (type: string): Classes merged onto the outer field wrapper when `label`, `description`, or `errorMessage` is set. Otherwise merged onto the shell. - startAdornment (type: React.ReactNode): Optional leading slot rendered inside the input shell. - endAdornment (type: React.ReactNode): Optional trailing slot rendered inside the input shell after built-in actions. - children (type: React.ReactNode): Additional trailing content rendered inside the input shell after adornments and actions. - showClear (type: boolean, default: false): When true, renders a clear button while the field has a value and is not disabled or read-only. - showPasswordToggle (type: boolean): When `type="password"`, shows a visibility toggle by default. Pass `false` to hide it. - placeholder (type: string): Placeholder shown when the field is empty. - fontSize (type: number): Optional pixel font size override for the inner field. Defaults to the standard `text-sm` input sizing. - spring (type: { stiffness?: number; damping?: number; mass?: number }): Spring config for caret movement. Defaults to stiffness 500, damping 30, mass 0.5. - id (type: string): Optional id forwarded to the input. A generated id is used when omitted so labels stay associated. - className (type: string | ((state: InputState) => string)): Classes merged onto the native input element. Base UI also supports a state callback. - style (type: React.CSSProperties | ((state: InputState) => React.CSSProperties)): Inline styles merged onto the native input element. Base UI also supports a state callback. - render (type: React.ReactElement | ((props: React.ComponentProps<'input'>) => React.ReactElement)): Base UI render override for the native input element. Custom renders disable the smooth caret. - disabled (type: boolean, default: false): Disables interaction on the native input. - readOnly (type: boolean, default: false): Keeps the field focusable while applying muted shell styling and blocking edits. ## Input OTP - URL: https://iconiqui.com/inputs-and-forms/input-otp - Package: @iconiq/input-otp - Install: npx shadcn@latest add @iconiq/input-otp - Registry JSON: https://iconiqui.com/r/input-otp.json - Summary: Root wrapper around Base UI OTP Field with optional label, description, error message, size, and invalid styling for complete form-field semantics. - Dependencies: @base-ui/react, motion ### Documented APIs - OTP: Root wrapper around Base UI OTP Field with optional label, description, error message, size, and invalid styling for complete form-field semantics. - length (type: number, required): Number of OTP characters. Required so Base UI can clamp values, detect completion, and manage focus order. - value (type: string): Controlled OTP string. Pair with `onValueChange` when the parent owns the code. - defaultValue (type: string): Initial value for uncontrolled usage. - onValueChange (type: (value: string, eventDetails) => void): Called whenever the OTP value changes from typing, paste, backspace, or keyboard navigation. - onValueComplete (type: (value: string, eventDetails) => void): Called when all slots are filled, including when a complete code is pasted. - onValueInvalid (type: (value: string, eventDetails) => void): Called when entered text contains characters rejected by validation or normalization. - validationType (type: "numeric" | "alpha" | "alphanumeric" | "none", default: "numeric"): Built-in validation applied before values are stored. Use `alphanumeric` for backup or recovery codes. - normalizeValue (type: (value: string) => string): Normalizes accepted values before state updates, such as uppercasing recovery codes. - mask (type: boolean, default: false): Obscures entered characters in the animated slot display and native inputs. - autoSubmit (type: boolean, default: false): Submits the owning form automatically when the OTP becomes complete. - autoComplete (type: string, default: "one-time-code"): Autocomplete hint applied to the first slot and hidden validation input for SMS autofill. - inputMode (type: string): Virtual keyboard hint applied to slot inputs. Override when `validationType` defaults are not ideal. - name (type: string): Identifies the field when a form is submitted. - form (type: string): Associates the hidden validation input with a form elsewhere in the document. - id (type: string): Applied to the first input. Subsequent inputs derive ids from it. Used by `label` and `htmlFor`. - label (type: ReactNode): Visible field label rendered above the OTP group with `htmlFor` wired to the first slot. - description (type: ReactNode): Supporting text below the field, linked through `aria-describedby`. - errorMessage (type: ReactNode): Error text below the field. Also sets invalid styling when present. - invalid (type: boolean, default: false): Marks the field invalid for `aria-invalid` and destructive slot borders. - required (type: boolean, default: false): Whether the user must enter a value before submitting a form. - disabled (type: boolean, default: false): Disables interaction across every slot. - readOnly (type: boolean, default: false): Prevents editing while keeping the value visible. - size (type: "default" | "sm", default: "default"): Slot dimensions and typography scale. - className (type: string): Classes merged onto the root flex container. - wrapperClassName (type: string): Classes merged onto the outer field wrapper when label or help text is present. - containerClassName (type: string): Legacy alias merged onto the root container alongside `className`. - OTPSlots: Convenience layout that renders the correct number of slots from the parent `OTP` length, with optional separators and placeholder hints. - separatorAfter (type: number | number[]): Inserts `OTPSeparator` before each listed zero-based index, such as `3` for 3-3 or `[3, 6]` for 3-3-3 codes. - placeholder (type: string): Hint shown in empty slots until the active slot receives focus. - slotClassName (type: string): Classes forwarded to every rendered `OTPSlot`. - className (type: string): Classes merged onto the internal `OTPGroup` wrapper. - OTPSlot: Animated character cell with spring focus ring, pop-in digit motion, masked bullets, and a pulsing caret on the active empty slot. - className (type: string): Classes merged onto the animated slot surface. - placeholder (type: string): Per-slot placeholder hint when composing slots manually. - aria-label (type: string): Accessible label for slots after the first one. The first slot inherits the field label from `OTP` or a surrounding `