# 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. - MCP URL: https://iconiqui.com/mcp Summary: MCP setup guide for connecting Iconiq to AI coding tools through the shadcn registry workflow. ## Component Catalog ## 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 the shadcn-style variant recipe, spring press feedback, optional intrinsic width animation, and Motion ripple layer. - Dependencies: @base-ui/react, motion, class-variance-authority ### Documented APIs - Button: Base UI button with the shadcn-style variant recipe, spring press feedback, optional intrinsic width animation, 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. - 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 directly to the underlying motion.button so the component does not submit forms accidentally by default. - children (type: ReactNode): 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 1rem sizing utility. - iconPosition (type: "start" | "end", default: "start"): Chooses whether the optional icon renders before or after the button text inside the same inline content row. - 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. It also prevents ripple creation because the pointer-down handler exits early. - buttonVariants: The CVA recipe is exported alongside the component so matching button classes can be reused on links or custom wrappers. ## 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, 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, 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 while keeping the same toolbar-style border and hover treatment. - 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): Removes the outer border when set to false, which is useful for quieter toolbar-style actions. - IconButton: Icon-only toolbar action that shares the same compact border, muted idle tone, 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 without changing its general look and feel. - 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. - 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. - 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: String-based segmented selector with compact sizing, keyboard support, muted idle labels, and a spring-driven selected indicator. - options (type: string[], required): Ordered list of visible segments. The first option becomes the uncontrolled initial selection when value is not provided. - value (type: string): Controlled selected option. When provided, the internal state syncs to this prop through an effect. - onChange (type: (value: string) => void): Called with the selected option whenever a segment is pressed. - className (type: string): Merged onto the segmented wrapper for width, alignment, or spacing overrides. - layoutId (type: string, default: "segmented-indicator"): Motion layout id used by the selected indicator. Override it when you render multiple segmented controls on the same page and want isolated 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. - size (type: "default" | "sm" | "lg", default: "default"): Height, padding, and icon sizing preset for compact toolbars or larger action rows. - disabled (type: boolean): Disables interaction and dims the control while preserving its pressed appearance. - reducedMotion (type: boolean): Forces reduced-motion transitions for the fill, lift, and press scale regardless of system preference. - 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 a connected set of toggle buttons with shared variant, size, spacing, and orientation settings. - Dependencies: @base-ui/react, class-variance-authority, motion ### Documented APIs - ToggleGroup: Root container for a connected set of toggle buttons with shared variant, size, spacing, and orientation settings. - type (type: "single" | "multiple", default: "multiple"): Selection mode. Multiple allows several active items by default; single keeps one pressed item at a time. - value (type: string | string[]): Controlled selection. Pass a string for single mode or a string array for multiple mode. - defaultValue (type: string | string[]): Initial selection for uncontrolled usage in the matching single or multiple mode. - 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. - size (type: "default" | "sm" | "lg", default: "default"): Shared height, padding, and icon sizing preset for all group items. - spacing (type: number, default: 1): Gap between items in spacing units. Defaults to 1 (4px). Set to 0 to remove the gap. - orientation (type: "horizontal" | "vertical", default: "horizontal"): Layout direction for the group. Vertical stacks items and adjusts connected border handling. - disabled (type: boolean): Disables the entire group and all nested items. - 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. - size (type: "default" | "sm" | "lg"): Optional local override for the shared group size preset. - disabled (type: boolean): Disables this item without affecting the rest of the group. - 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. Pair icon-only items with aria-label. ## 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) => 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. - mode (type: "list" | "both" | "inline" | "none", default: "list"): Controls filtering and inline completion while navigating suggestions. - autoHighlight (type: boolean | "always", default: true): Automatically highlights the first matching item while typing. - 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. - openOnInputClick (type: boolean, default: false): When true, clicking the input opens the suggestion panel even before typing. - isItemEqualToValue (type: (item: Item, value: Item) => boolean): Custom equality for object items. Use when items are recreated on each render. - reducedMotion (type: boolean): Forces the Iconiq motion layer into reduced-motion mode. - AutocompleteInput: Styled input shell with border, focus ring, and optional clear control. The suggestion panel opens while typing, not on focus or click. - 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 and clear 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. - sideOffset (type: number, default: 6): Distance between the input and the popup. - 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. ## 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: Single checkbox with controlled or uncontrolled state, a visually hidden native input, and an optional inline label. - Dependencies: @base-ui/react, motion ### Documented APIs - Checkbox: Single checkbox with controlled or uncontrolled state, a visually hidden native input, and an optional inline label. - checked (type: boolean): Controlled checked state. When you pass this prop, the component always renders from it and stops mutating its own internal state. - defaultChecked (type: boolean, 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 each time the checkbox is toggled. - label (type: string): Optional text rendered to the right of the box inside the same clickable label wrapper. - className (type: string): Merged onto the root label so you can reposition the row or override spacing. - id (type: string): Passed to the hidden input and linked from the wrapping label for explicit form-field association. - Motion and accessibility: Visual feedback comes from Motion while input semantics still come from the hidden native checkbox element. ## 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: Each option row is described with a plain object and rendered as an animated button. - Dependencies: @base-ui/react, motion, lucide-react ### Documented APIs - CheckboxGroupOption: Each option row is described with a plain object and rendered as an animated button. - label (type: string, 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. - description (type: string): Optional secondary text rendered below the label. - group (type: string): Optional section label used to chunk long lists into named 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. - disabledReason (type: string): Optional explainer rendered below disabled rows so users understand why the choice is unavailable. - CheckboxGroup: Animated multi-select list with optimistic toggle feedback, stable output ordering, and optional disclosure for longer option sets. - options (type: CheckboxGroupOption[], required): Array of rows to render, in display order. - value (type: string[], default: []): Current selected values. The prop remains the source of truth, while the component renders an immediate optimistic preview after each click. - onChange (type: (value: string[]) => void): Receives the next selected values array after a row is toggled, normalized back into the original display order. - className (type: string): Merged onto the root flex column wrapper. - maxVisible (type: number): Optional progressive-disclosure cap. When provided, the list initially renders up to this many rows and reveals the rest with a built-in toggle. - showMoreLabel (type: string): Optional label prefix for the disclosure button shown when maxVisible hides rows. - showLessLabel (type: string): Optional label used when the disclosure button collapses the list back down. - Motion and accessibility: The component leans on hover surfaces and AnimatePresence rather than native checkbox UI. ## 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, and EyeDropper. - Dependencies: lucide-react, motion ### Documented APIs - ColorPicker: Self-contained HSV panel with saturation field, hue/alpha sliders, multi-format readouts, and EyeDropper. - value (type: string): Controlled hex color such as #3B82F6. When provided, the picker syncs its internal state to this value. - defaultValue (type: string, default: #3B82F6): Starting color for uncontrolled usage. Ignored when value is supplied. - onChange (type: (color: string) => void): Called when the color settles (pointer up on sliders, blur/Enter on inputs). Emits #RRGGBB, or #RRGGBBAA when alpha is below 100%. - defaultAlpha (type: number, default: 100): Starting alpha percentage (0–100) for uncontrolled usage when defaultValue has no alpha channel. - disabled (type: boolean, default: false): Disables picker interaction and lowers shell opacity. - reducedMotion (type: boolean): Forces reduced motion for format-menu animation and decorative pulses. - 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. - className (type: string): Merged onto the outer picker 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: Item | Item[] | null) => void): Called when an item is selected, a chip is removed, or the clear action resets the selection. - 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. - inputValue (type: string): Controlled search text. Leave uncontrolled for Base UI to manage query state. - open (type: boolean): Controlled popup state. Pair with onOpenChange. - reducedMotion (type: boolean): Forces the Iconiq motion layer into reduced-motion mode. - ComboboxInput: Styled input shell with the previous border, focus ring, clear button, and rotating trigger icon. - 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. - className (type: string): Merged onto the input shell so width and local layout can be adjusted. - disabled (type: boolean, default: false): Disables the input, clear button, and trigger while applying the previous reduced-opacity presentation. - 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 and ComboboxItem: Scrollable item list and animated rows with the previous active highlight, description layout, and selected checkmark spring. - ComboboxList.children (type: ReactNode | ((item, index) => ReactNode)): Render explicit children or a render function when using the root items prop. - ComboboxItem.value (type: Item): Stable value used by Base UI for selection. - ComboboxItem.description (type: ReactNode): Optional secondary line rendered below the item label, matching the prior option description UI. ## 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 an internal queue, hidden file input, keyboard-triggerable drop zone, and callback hooks for parent integrations. - Dependencies: motion, lucide-react ### Documented APIs - FileUpload: Drag-and-drop uploader with an internal queue, hidden file input, keyboard-triggerable drop zone, and callback hooks for parent integrations. - accept (type: string): Optional accept string passed to the hidden file input and also enforced for dropped 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 trimmed from the end. - disabled (type: boolean, default: false): Disables click, drag, keyboard activation, and the hidden file input without changing the component structure. - name (type: string): Passes a form field name through to the hidden file input for form integrations. - className (type: string): Adds classes to the outer wrapper without changing the component internals. - onFilesChange (type: (files: File[]) => void): Called when files are added or removed from the queue. It does not fire on every progress tick. - onFileRemove (type: (file: File, nextFiles: File[]) => void): Called after a queued file is removed. The second argument contains the remaining files in queue order. - onUploadComplete (type: (files: File[]) => void): Called once the current queue reaches 100% completion for every item. - Built-in behavior: The component still owns its progress visuals and preview lifecycle, even when you attach callbacks from parent code. - progress state (type: built-in): Each added file starts in an uploading state and advances through the built-in simulated progress loop until it reaches done. - image previews (type: built-in): Image files receive object URL previews and render as thumbnails; non-image files fall back to a file icon surface. - remove action (type: built-in): Each queued file can be removed individually from the trailing action button, with preview URLs revoked immediately. ## Radio Group - URL: https://iconiqui.com/inputs-and-forms/radio-group - Package: @iconiq/b-radio-group - Install: npx shadcn@latest add @iconiq/b-radio-group - Registry JSON: https://iconiqui.com/r/b-radio-group.json - Summary: Options are plain objects consumed by the RadioGroup component. - Dependencies: @base-ui/react, motion ### Documented APIs - Radio option shape: Options are plain objects consumed by the RadioGroup component. - value (type: string, required): Unique identifier for the option and the selected value reported through onChange. - label (type: string, required): Primary line shown for the option. - description (type: string): Optional secondary line shown below the label with reduced emphasis. - RadioGroup: Single-choice selector with animated rows, native radio inputs, and support for both controlled and uncontrolled state. - options (type: { value: string; label: string; description?: string }[], required): Available choices in display order. - defaultValue (type: string): Initial uncontrolled selection. If omitted or invalid, the component falls back to the first option. - value (type: string): Controlled selected value. When provided, parent state owns selection and the component only reports changes. - onChange (type: (value: string) => void): Called whenever a user selects a row. - name (type: string): Shared radio input name. If omitted, the component generates one per instance. - layoutId (type: string): Motion layout id used by the selected row highlight. Override it only when you want to intentionally share that highlight between groups. - "aria-label" (type: string): Accessible name for the radiogroup. Provide this or aria-labelledby so assistive tech can announce the set clearly. - "aria-labelledby" (type: string): ID of external text that labels the radiogroup. Use this instead of aria-label when visible copy already exists. - className (type: string): Merged onto the root wrapper for spacing or sizing adjustments. - Motion and accessibility: The component wraps native radio inputs in an animated label shell so keyboard, form, and screen-reader behavior stay intact. ## Select - URL: https://iconiqui.com/inputs-and-forms/select - Package: @iconiq/b-select - Install: npx shadcn@latest add @iconiq/b-select - Registry JSON: https://iconiqui.com/r/b-select.json - Summary: Root select controller. Compose SelectTrigger, SelectValue, SelectContent, and SelectItem inside it. - Dependencies: @base-ui/react, motion, lucide-react ### Documented APIs - Select: Root select controller. Compose SelectTrigger, SelectValue, SelectContent, and SelectItem inside it. - value (type: string): Controlled selected value. Leave unset with defaultValue for uncontrolled usage. - defaultValue (type: string): Initial selected value for uncontrolled usage. - onValueChange (type: (value: string) => void): Called when a SelectItem is chosen. The menu closes immediately afterward. - open (type: boolean): Controlled popup state. Pair with onOpenChange when parent state owns the menu. - defaultOpen (type: boolean, default: false): Initial popup state for uncontrolled usage. - onOpenChange (type: (open: boolean) => void): Called whenever the trigger, keyboard, item choice, or outside interaction opens or closes the menu. - SelectTrigger: Button that opens the menu and hosts SelectValue plus the animated chevron. - children (type: ReactNode): Usually a SelectValue. The chevron icon is appended automatically. - size (type: "sm" | "default", default: "default"): Data attribute hook for compact trigger variants without changing the default Iconiq styling. - className (type: string): Merged onto the trigger button. Use it for local width such as w-full max-w-48. - SelectValue: Inline label for the current selection, with placeholder support from the underlying primitive. - placeholder (type: ReactNode): Shown in the trigger when no item is selected. - className (type: string): Merged onto the value span. The default keeps text truncated inside the trigger. - SelectContent: Portaled menu surface with the previous Iconiq dropdown fade, slide, and viewport clamping. - side (type: "top" | "right" | "bottom" | "left", default: "bottom"): Preferred side for the menu before collision handling. - align (type: "start" | "center" | "end", default: "start"): Horizontal alignment against the trigger or anchor. - sideOffset (type: number, default: 8): Gap between trigger and menu. The default matches the prior select spacing. - className (type: string): Merged onto the animated menu panel for local max height, width, or surface overrides. - SelectItem: Selectable row with primitive keyboard behavior plus the previous active-row highlight and checkmark motion. - value (type: string, required): Stable value reported through onValueChange and used to determine the selected checkmark. - children (type: ReactNode, required): Item label content. Primitive ItemText also feeds the selected trigger value. - icon (type: ReactNode): Optional leading icon rendered inline with the item label and selected trigger value. - disabled (type: boolean, default: false): Prevents the item from receiving selection. - className (type: string): Merged onto the row while preserving the animated active highlight and selected checkmark. - Groups, labels, separators, and scroll buttons: Supporting parts for structured menus: SelectGroup, SelectLabel, SelectSeparator, SelectScrollUpButton, and SelectScrollDownButton. ## Slider - URL: https://iconiqui.com/inputs-and-forms/slider - Package: @iconiq/b-slider - Install: npx shadcn@latest add @iconiq/b-slider - Registry JSON: https://iconiqui.com/r/b-slider.json - Summary: Pointer-driven range control with optional controlled or uncontrolled value management. - Dependencies: @base-ui/react, motion ### Documented APIs - Slider: Pointer-driven range control with optional controlled or uncontrolled value management. - value (type: number): Controlled value. When provided, the parent owns the current position. - defaultValue (type: number, default: 50): Initial internal value used when value is not supplied. - min (type: number, default: 0): Lower bound used for clamping and display mapping. - max (type: number, default: 100): Upper bound used for clamping and display mapping. - step (type: number, default: 1): Step size applied after translating pointer position into a raw numeric value. - onChange (type: (value: number) => void): Called for live value updates from pointer or keyboard input when the snapped value actually changes. - onValueCommit (type: (value: number) => void): Called when an interaction is committed, such as releasing a drag or finishing a keyboard step. - showValue (type: boolean, default: true): Controls whether the live numeric readout is shown on the right side of the label row. - valueDecimals (type: number, default: 0): Controls how many decimal places are shown in the readout when you want precision without custom formatting. - formatValue (type: (value: number) => string): Optional formatter for the visible readout and aria-valuetext, useful for units such as dB, percent, or milliseconds. - label (type: string): Optional label shown on the left side of the header row above the track. - ariaLabel (type: string): Accessible name used when no visible label is rendered for the slider. - ariaLabelledBy (type: string): ID of an external label element that should be announced instead of the built-in label. - marks (type: { value: number; label?: string }[]): Optional tick marks rendered below the track so large ranges can include landmarks like Low, Medium, and High. - Interaction model: Slider supports pointer, keyboard, and screen-reader friendly range semantics. ## Switch - URL: https://iconiqui.com/inputs-and-forms/switch - Package: @iconiq/b-switch - Install: npx shadcn@latest add @iconiq/b-switch - Registry JSON: https://iconiqui.com/r/b-switch.json - Summary: Binary on or off control built on Radix Switch, with a motion-driven thumb travel, foreground fill sweep, and optional inline label. - Dependencies: @base-ui/react, motion ### Documented APIs - Switch: Binary on or off control built on Radix Switch, with a motion-driven thumb travel, foreground fill sweep, and optional inline label. - checked (type: boolean): Controlled checked state. Pass this when the parent owns the current on or off value. - defaultChecked (type: boolean): Initial checked state for uncontrolled usage. The component keeps its local animation state in sync with this mode too. - onCheckedChange (type: (checked: boolean) => void): Called whenever the switch changes state, after the thumb and fill animation sequence starts. - disabled (type: boolean): Disables pointer and keyboard interaction, and dims the switch and optional label together. - label (type: string): Optional inline text rendered beside the switch. When omitted, the component returns only the switch control itself. - labelSide (type: "left" | "right", default: right): Controls which side of the switch the optional label text appears on. - className (type: string): Merged onto the Radix root element for local spacing or surface overrides. - Motion and interaction behavior: The switch uses separate motion values for thumb travel, thumb squash, and track fill opacity so the state change feels tactile without becoming noisy. ## Theme Toggle - URL: https://iconiqui.com/inputs-and-forms/theme-toggle - Package: @iconiq/theme-toggle - Install: npx shadcn@latest add @iconiq/theme-toggle - Registry JSON: https://iconiqui.com/r/theme-toggle.json - Summary: Client-only pill switch that toggles light and dark mode by adding or removing the `dark` class on `document.documentElement`, with sun and moon icons inside a sliding knob. - Dependencies: @base-ui/react/toggle, lucide-react ### Documented APIs - ThemeToggle: Client-only pill switch that toggles light and dark mode by adding or removing the `dark` class on `document.documentElement`, with sun and moon icons inside a sliding knob. - size (type: "sm" | "md" | "lg", default: md): Controls track, knob, and icon dimensions. Use `sm` in compact toolbars and `lg` for hero or settings layouts. - className (type: string): Optional class names merged onto the root button for spacing or layout in your header or settings panel. ## Alert Dialog - URL: https://iconiqui.com/overlay-and-popups/alert-dialog - Package: @iconiq/b-alert-dialog - Install: npx shadcn@latest add @iconiq/b-alert-dialog - Registry JSON: https://iconiqui.com/r/b-alert-dialog.json - Summary: Alert dialog with a shared Iconiq trigger, content, cancel, and action API layered over Base UI primitives, plus Motion-backed confirm-state transitions. - Dependencies: @base-ui/react, motion ### Documented APIs ## Context Menu - URL: https://iconiqui.com/overlay-and-popups/context-menu - Package: @iconiq/b-context-menu - Install: npx shadcn@latest add @iconiq/b-context-menu - Registry JSON: https://iconiqui.com/r/b-context-menu.json - Summary: Root provider that coordinates open state and the shared motion shell used by the trigger, content, and item primitives. - Dependencies: @base-ui/react, motion, lucide-react ### Documented APIs - ContextMenu: Root provider that coordinates open state and the shared motion shell used by the trigger, content, and item primitives. - children (type: ReactNode, required): Compose ContextMenuTrigger, ContextMenuContent, and item primitives such as ContextMenuItem or ContextMenuSub inside the root. - open (type: boolean): Controlled open state for the menu surface. Supported on the Base UI install. - defaultOpen (type: boolean, default: false): Initial open state for uncontrolled usage on the Base UI install. - onOpenChange (type: (open: boolean) => void): Called whenever the trigger, outside interaction, or Escape key changes the open state. - reducedMotion (type: boolean): Forces reduced motion for this menu instance, overriding the user system preference. - ContextMenuTrigger: Interactive surface that opens the menu on right click, long press, or keyboard context-menu shortcuts. - children (type: ReactNode, required): Trigger content rendered inside the context-click target. - asChild (type: boolean): Merges trigger behavior onto the single child element instead of rendering a wrapper element. - className (type: string): Merged onto the trigger surface, including the focus ring and theme token scope. - ContextMenuContent: Portaled menu panel that renders the composed item tree with the Iconiq border, shadow, and motion treatment. - children (type: ReactNode, required): Menu body content such as groups, items, separators, checkbox rows, and nested submenus. - className (type: string): Merged onto the animated panel shell. Use width utilities such as w-48 when you want a fixed menu width. - collisionPadding (type: number, default: 8): Viewport padding used while the underlying primitive resolves collision-aware placement. - ContextMenuItem: Interactive menu row with the Iconiq active highlight, row entrance motion, and optional destructive styling. - children (type: ReactNode, required): Row content. Pair with ContextMenuShortcut when you want trailing keyboard hints. - variant (type: "default" | "destructive", default: default): Switches the row into the destructive color treatment used for irreversible actions. - disabled (type: boolean): Dims the row and blocks pointer and keyboard selection. - inset (type: boolean): Adds extra start padding so the row aligns with checkbox and radio items. - onSelect (type: (event: Event) => void): Called when the row is activated. - ContextMenuShortcut: Trailing helper text for keyboard hints. It stays muted until the parent row is focused. - children (type: ReactNode, required): Shortcut copy such as ⌘R or Del. - className (type: string): Merged onto the trailing shortcut span. - ContextMenuSub: Nested submenu root. Pair ContextMenuSubTrigger with ContextMenuSubContent to build secondary menus such as More Tools. - children (type: ReactNode, required): Submenu trigger and content parts rendered inside the parent menu. - ContextMenuCheckboxItem: Toggle row with a trailing check indicator and the same Iconiq row motion treatment as ContextMenuItem. - checked (type: boolean): Controls whether the row renders in the checked state. - onCheckedChange (type: (checked: boolean) => void): Called when the row toggles between checked and unchecked. - disabled (type: boolean): Dims the row and blocks pointer and keyboard selection. - inset (type: boolean): Adds extra start padding to align with sibling rows. - ContextMenuRadioGroup: Single-select group for ContextMenuRadioItem rows. Use ContextMenuLabel above the options when you need a section heading. - value (type: string): Controlled selected value for the radio group. - onValueChange (type: (value: string) => void): Called when a radio row is selected. ## Dialog - URL: https://iconiqui.com/overlay-and-popups/dialog - Package: @iconiq/b-dialog - Install: npx shadcn@latest add @iconiq/b-dialog - Registry JSON: https://iconiqui.com/r/b-dialog.json - Summary: Dialog, DialogTrigger, DialogClose, and DialogPortal are direct re-exports of the matching Radix dialog primitives. - Dependencies: @base-ui/react, @radix-ui/react-slot, motion, lucide-react ### Documented APIs - Dialog: Dialog, DialogTrigger, DialogClose, and DialogPortal are direct re-exports of the matching Radix dialog primitives. - open (type: boolean): Controlled open state on the Dialog root when you want the parent component to own visibility. - defaultOpen (type: boolean): Uncontrolled initial state forwarded to Radix Dialog.Root. - onOpenChange (type: (open: boolean) => void): Called whenever Radix requests a state change through triggers, overlay clicks, or escape key handling. - children (type: ReactNode, required): Composition surface for the trigger, content, and any related dialog helpers. - DialogContent: Motion-enhanced content wrapper built around DialogPrimitive.Content and AnimatePresence. - open (type: boolean): Controls whether the animated portal branch renders at all. In practice this must mirror the root open state for the content to appear and exit correctly. - className (type: string): Merged onto the inner motion panel rather than the full-screen DialogPrimitive.Content wrapper. - children (type: ReactNode, required): Content rendered inside the animated panel. Each direct child is wrapped in its own motion.div for staggered entry. - DialogTrigger and DialogClose: These exports are direct Radix aliases used to open or close the dialog from any custom element. - asChild (type: boolean): Lets you turn a custom button or link into the trigger or close control without adding an extra wrapper element. - children (type: ReactNode, required): Interactive content rendered by the trigger or close primitive. - DialogHeader and DialogFooter: Layout helpers used to structure dialog content without changing dialog behavior. - children (type: ReactNode, required): Content rendered inside the helper container. - className (type: string): Merged onto the helper wrapper so spacing and alignment can be adjusted per dialog. - DialogTitle and DialogDescription: Semantic text helpers that forward to the matching Radix title and description primitives. - children (type: ReactNode, required): Text or inline markup rendered inside the title or description primitive. - className (type: string): Merged with the default title or description styles. ## Drawer - URL: https://iconiqui.com/overlay-and-popups/drawer - Package: @iconiq/drawer - Install: npx shadcn@latest add @iconiq/drawer - Registry JSON: https://iconiqui.com/r/drawer.json - Summary: Vaul-backed drawer root that coordinates open state, drag gestures, overlay dismissal, focus management, and side-based placement for the compound parts. - Dependencies: vaul ### Documented APIs - Drawer: Vaul-backed drawer root that coordinates open state, drag gestures, overlay dismissal, focus management, and side-based placement for the compound parts. - open (type: boolean): Optional controlled open state. Pair it with onOpenChange when parent state should own the drawer lifecycle. - defaultOpen (type: boolean): Initial open state for uncontrolled usage. Vaul skips the first enter animation when the drawer is mounted open. - onOpenChange (type: (open: boolean) => void): Called whenever the drawer opens or closes from the trigger, overlay, Escape key, close part, or drag release. - direction (type: "left" | "right" | "top" | "bottom", default: "bottom"): Chooses the drawer edge and matching Vaul slide direction. The content classes style each direction with the appropriate inset and rounded leading edge. - modal (type: boolean, default: true): Keeps focus and outside interaction modal while the drawer is open. Set false for non-modal command surfaces. - dismissible (type: boolean, default: true): Allows overlay click, Escape, and drag gestures to close the drawer. Controlled drawers can disable this when a flow must be completed explicitly. - snapPoints (type: (number | string)[]): Optional Vaul snap points for stepped drawer heights or widths. Values may be percentages or px strings. - Compound parts: The registry entry exports the familiar shadcn-style DrawerTrigger, DrawerPortal, DrawerOverlay, DrawerContent, DrawerClose, DrawerHeader, DrawerFooter, DrawerTitle, and DrawerDescription parts. - DrawerTrigger (type: Vaul Trigger props): Opens the drawer. Use asChild when a local button or link should remain the visible trigger element. - DrawerContent (type: Vaul Content props): Portals the overlay and animated panel, applies direction-aware layout classes, and renders the optional bottom drag handle. - DrawerClose (type: Vaul Close props): Closes the drawer. Use asChild to turn an existing footer action into the close control. - DrawerHeader / DrawerFooter (type: div props): Layout helpers for the title area and bottom action area. Both merge className with the default spacing. - DrawerTitle / DrawerDescription (type: Vaul Title and Description props): Accessible heading and helper text parts forwarded to Vaul's dialog title and description primitives. - Motion and layout: The component leans on Vaul's drag-aware transform animation, then adds softer overlay timing, tuned animation duration, and direction-specific panel geometry. - overlay (type: built-in): A fixed full-screen overlay fades in behind the drawer and uses a subtle black tint with backdrop blur support. - content (type: built-in): The panel gets a fluid cubic-bezier open curve, a shorter close duration, GPU-friendly transform hints, and a slightly extended initial transform for a softer arrival. ## Dropdown - URL: https://iconiqui.com/overlay-and-popups/dropdown - Package: @iconiq/r-dropdown - Install: npx shadcn@latest add @iconiq/r-dropdown - Registry JSON: https://iconiqui.com/r/r-dropdown.json - Summary: Root provider that coordinates open state, selected value state, and the shared behavior used by the trigger, content, and item primitives. - Dependencies: @radix-ui/react-dropdown-menu, @radix-ui/react-scroll-area, motion, lucide-react ### Documented APIs - Dropdown: Root provider that coordinates open state, selected value state, and the shared behavior used by the trigger, content, and item primitives. - children (type: ReactNode, required): Compose DropdownTrigger, DropdownContent, DropdownItem, and optional helpers like DropdownValue or DropdownSeparator inside the root. - value (type: string): Controlled selected value for the select variant. Action mode usually leaves this unset. - defaultValue (type: string): Initial selected value for uncontrolled select usage. - onValueChange (type: (value: string | undefined) => void): Called when a select item updates the current value. - open (type: boolean): Controlled open state for the menu surface. - defaultOpen (type: boolean, default: false): Initial open state for uncontrolled usage. - onOpenChange (type: (open: boolean) => void): Called whenever the trigger, outside click handling, or Escape key changes the open state. - variant (type: "select" | "action", default: select): Use select when items should commit a persistent value with a checkmark, or action when items should behave like immediate commands. - className (type: string): Merged onto the outer relative wrapper around the trigger and content. - DropdownTrigger: Interactive trigger button that opens and closes the menu. It works with plain children, DropdownValue, or custom trigger content like an avatar. - children (type: ReactNode): Trigger content. In select mode this usually includes DropdownValue, while action menus can pass custom content such as an avatar or label row. - showChevron (type: boolean, default: true): Hides the default chevron when you want a cleaner custom trigger, such as an avatar-only action menu. - className (type: string): Merged onto the trigger button shell. - disabled (type: boolean): Prevents opening and dims the trigger styling. - DropdownValue: Small helper for select mode that reads the current value from context and prints the matching item label or a placeholder. - placeholder (type: string, default: "Select an option"): Text shown when no matching selected value is currently registered. - className (type: string): Merged onto the rendered span inside the trigger. - DropdownContent: Animated menu surface that positions itself under the trigger and renders the item list for either variant. - children (type: ReactNode, required): Usually DropdownItem children, with optional DropdownSeparator nodes between groups. - align (type: "start" | "center" | "end", default: start): Horizontal alignment relative to the trigger wrapper. - sideOffset (type: number, default: 8): Vertical gap between the trigger and the dropdown surface. - className (type: string): Merged onto the dropdown surface, which is useful for setting a custom width or changing shadows in docs/examples. - DropdownItem: Single interactive row used by both variants. In select mode it can register a value, and in action mode it acts like a plain command item. - children (type: ReactNode, required): Row content. You can place icons inline before the label for action menus or richer item layouts. - value (type: string): Selection key for select mode. When it matches the root value, the item renders the checkmark state. - textValue (type: string): Optional explicit label used by DropdownValue and typeahead when your item children are not plain text. - onClick (type: (event: MouseEvent) => void): Runs before the item closes the menu. Action menus typically use this for immediate commands like profile or logout. - disabled (type: boolean): Prevents interaction and dims the row. - DropdownGroup: Optional wrapper for chunking larger menus into sections, with or without a visible label. - children (type: ReactNode, required): Usually one or more DropdownItem nodes. Add label when you want a visible heading, or omit it when you just want grouped spacing. - label (type: ReactNode): Optional convenience heading rendered with DropdownLabel styling and linked to the group for assistive technologies. - labelClassName (type: string): Merged onto the generated section heading when you want to tweak its spacing or tone. - className (type: string): Merged onto the group wrapper. The base version adds light vertical spacing between grouped rows. - DropdownLabel: Standalone non-interactive heading helper for advanced content layouts or custom grouping patterns. - children (type: ReactNode, required): Short section text such as Product, Billing, or Workspace settings. - className (type: string): Merged onto the rendered div when you want to adjust spacing, weight, or casing locally. - DropdownSeparator: Simple divider for grouping related items inside the content surface. - className (type: string): Merged onto the divider element when you want to adjust spacing or tone locally. ## Hover Card - URL: https://iconiqui.com/overlay-and-popups/hover-card - Package: @iconiq/b-hover-card - Install: npx shadcn@latest add @iconiq/b-hover-card - Registry JSON: https://iconiqui.com/r/b-hover-card.json - Summary: Stateful wrapper that opens a callout on delayed hover or immediate focus, then closes it once pointer and focus both leave the hover-card region. - Dependencies: @base-ui/react, motion ### Documented APIs - HoverCard: Stateful wrapper that opens a callout on delayed hover or immediate focus, then closes it once pointer and focus both leave the hover-card region. - children (type: ReactNode, required): Composition surface for the trigger and content primitives rendered inside the hover card root. - className (type: string): Merged onto the inline-flex wrapper that groups the trigger and content primitives. - openDelay (type: number, default: 80): Delay in milliseconds before the card opens after pointer entry. Keyboard focus opens immediately. - closeDelay (type: number, default: 120): Delay in milliseconds before the card closes after pointer exit. Blur closes immediately unless focus is still moving within the card. - HoverCardTrigger: Trigger surface that renders a button by default or forwards behavior into a custom child through Radix Slot. - children (type: ReactNode, required): Interactive content rendered by the trigger or by the child passed through asChild. - asChild (type: boolean): Lets you supply your own trigger element while keeping the hover-card trigger behavior and class merging. - className (type: string): Merged onto the rendered trigger element for local layout or visual styling. - HoverCardContent: Animated content panel with collision-aware positioning, side and align controls, and a spring-driven scale and directional offset fade. - children (type: ReactNode, required): Content rendered inside the hover card panel. - className (type: string): Merged onto the motion.div panel so width, spacing, or surface styles can be adjusted. - side (type: "top" | "right" | "bottom" | "left", default: "bottom"): Preferred side for the panel before collision handling adjusts the placement. - align (type: "start" | "center" | "end", default: "center"): Horizontal or vertical alignment relative to the trigger, depending on side. - sideOffset (type: number, default: 12): Gap between trigger and panel. The component also extends an invisible hover bridge through that gap to reduce accidental closes. - alignOffset (type: number, default: 0): Additional offset applied along the alignment axis. - avoidCollisions (type: boolean, default: true): Enables Radix collision handling so the card can shift or flip when space is tight. - collisionPadding (type: number | Partial>, default: 12): Padding from viewport edges used during collision detection. ## Popover - URL: https://iconiqui.com/overlay-and-popups/popover - Package: @iconiq/b-popover - Install: npx shadcn@latest add @iconiq/b-popover - Registry JSON: https://iconiqui.com/r/b-popover.json - Summary: Thin wrapper around `PopoverPrimitive.Root` that mirrors the resolved open state into local context so `PopoverContent` can infer presence automatically. - Dependencies: @base-ui/react, motion ### Documented APIs - Popover: Thin wrapper around `PopoverPrimitive.Root` that mirrors the resolved open state into local context so `PopoverContent` can infer presence automatically. - open (type: boolean): Controlled open state on the Radix root when you want React state to own visibility. - defaultOpen (type: boolean): Uncontrolled initial state forwarded to the underlying Radix popover root. - onOpenChange (type: (open: boolean) => void): Called whenever Radix requests a state change through the trigger, outside interaction, or escape handling. - children (type: ReactNode, required): Composition surface for the trigger, optional anchor, and content primitives. - PopoverTrigger and PopoverAnchor: `PopoverTrigger` is a light wrapper around the Radix trigger with a larger default hit area when not using `asChild`, while `PopoverAnchor` remains the Radix positioning anchor. - asChild (type: boolean): Lets you render your own button, link, or wrapper element without adding an extra DOM node. - children (type: ReactNode, required): Interactive or layout content rendered by the trigger or anchor primitive. - PopoverContent: Animated content wrapper built on Radix Popover.Content and AnimatePresence. - open (type: boolean): Accepted for backwards compatibility, but no longer required. The nearest `Popover` root state now drives content presence automatically. - children (type: ReactNode, required): Content rendered inside the animated panel. - className (type: string): Merged onto the motion.div panel for local width, spacing, or surface overrides. - align (type: "start" | "center" | "end", default: center): Forwarded to Radix Popover.Content to control horizontal alignment relative to the trigger or anchor. - sideOffset (type: number, default: 8): Forwarded to Radix Popover.Content to control the gap between the anchor and the floating panel. - collisionPadding (type: number | Partial>, default: 12): Adds a little default breathing room from the viewport edge before collision handling nudges the popover inward. ## Tooltip - URL: https://iconiqui.com/overlay-and-popups/tooltip - Package: @iconiq/b-tooltip - Install: npx shadcn@latest add @iconiq/b-tooltip - Registry JSON: https://iconiqui.com/r/b-tooltip.json - Summary: Animated tooltip with a canonical Tooltip export. It owns its own open state, expects a single trigger element, and toggles in response to hover and focus events. - Dependencies: @base-ui/react, motion ### Documented APIs - Tooltip: Animated tooltip with a canonical Tooltip export. It owns its own open state, expects a single trigger element, and toggles in response to hover and focus events. - children (type: ReactElement, required): A single trigger element that receives hover, focus, and aria-describedby props through a slotted wrapper. - content (type: string, required): Short, non-interactive tooltip copy rendered inside the animated bubble. Use Popover for longer or richer content. - side (type: "top" | "bottom" | "left" | "right", default: top): Preferred popup side passed into the collision-aware Radix popover positioner. - delay (type: number, default: 0.15): Open delay in seconds. The implementation multiplies it by 1000 before scheduling the timer. - className (type: string): Merged onto the tooltip bubble for local surface styling overrides. - Positioning and accessibility: This tooltip is portaled through Radix Popover so it can avoid viewport collisions and escape clipping parents. ## Accordion - URL: https://iconiqui.com/navigation/accordion - Package: @iconiq/b-accordion - Install: npx shadcn@latest add @iconiq/b-accordion - Registry JSON: https://iconiqui.com/r/b-accordion.json - Summary: Each row is described by a simple object and rendered as a single-expand accordion item. - Dependencies: @base-ui/react, motion ### Documented APIs - AccordionItem: Each row is described by a simple object and rendered as a single-expand accordion item. - id (type: string, required): Stable key used for React rendering, internal open-state comparison, and the generated aria-controls id. - title (type: string, required): Text shown in the trigger row. - content (type: string, required): Body copy shown inside the open panel with a horizontal masked wipe and a soft lift into place. - Accordion: Stateful accordion component with internal open state and no controlled API. - items (type: AccordionItem[], required): Rows to render in order. - className (type: string): Merged onto the max-w-2xl root wrapper so you can stretch or reposition the accordion in your layout. - multiple (type: boolean, default: false): Allows several rows to stay open at once. When omitted, opening one row closes the previously open row. - variant (type: "default" | "quiet", default: "default"): Switches between the plain divided list and the quieter inline plus/minus treatment. - Motion and accessibility: The accordion uses native buttons and animated height transitions rather than a headless primitive. ## Breadcrumbs - URL: https://iconiqui.com/navigation/breadcrumbs - Package: @iconiq/breadcrumbs - Install: npx shadcn@latest add @iconiq/breadcrumbs - Registry JSON: https://iconiqui.com/r/breadcrumbs.json - Summary: Root semantic navigation wrapper for a breadcrumb trail. - Dependencies: @base-ui/react, motion, lucide-react ### Documented APIs - Breadcrumb: Root semantic navigation wrapper for a breadcrumb trail. - className (type: string): Merged onto the nav element for placement inside headers, toolbars, and page shells. - BreadcrumbList: Animated ordered list that lays out breadcrumb segments and separators. - className (type: string): Merged with the default flex wrapping, spacing, and muted text styles. - BreadcrumbItem: Animated list item wrapper for each breadcrumb segment. - className (type: string): Merged with the inline-flex item layout. Dynamic items should receive stable React keys when rendered from arrays. - BreadcrumbLink: Base UI render-compatible link for navigable breadcrumb segments. - href (type: string): Destination for the linked segment. You can also compose a router link with the render prop. - render (type: ReactElement | render function): Optional Base UI render override for composing with framework-specific links while preserving merged props. - className (type: string): Merged with the default color transition and hover foreground treatment. - BreadcrumbPage: Current page segment rendered as disabled link-like text with aria-current. - className (type: string): Merged with the default foreground current-page text style. - BreadcrumbSeparator: Animated visual separator between breadcrumb items, defaulting to a chevron icon. - children (type: ReactNode): Optional custom separator content. When omitted, ChevronRightIcon is rendered. - className (type: string): Merged with the default icon sizing class for separator icons. - BreadcrumbEllipsis: Compact overflow marker for collapsed breadcrumb paths. - className (type: string): Merged with the default 20px square centered icon layout. - Accessibility and motion: The compound API keeps semantic breadcrumb structure while layering Motion on top. ## FAQ Pro - URL: https://iconiqui.com/navigation/faq-pro - Package: @iconiq/faq-pro - Install: npx shadcn@latest add @iconiq/faq-pro - Registry JSON: https://iconiqui.com/r/faq-pro.json - Summary: Searchable FAQ accordion with rounded cards, animated panels, query highlighting, and automatic expansion for filtered results. - Dependencies: @base-ui/react/accordion, motion, lucide-react ### Documented APIs - FaqPro: Searchable FAQ accordion with rounded cards, animated panels, query highlighting, and automatic expansion for filtered results. - items (type: FaqProItem[], required): Array of `{ id, question, answer }` entries. Each id must be unique within the list. - searchPlaceholder (type: string, default: Search FAQs...): Placeholder copy for the search field. - defaultOpenFirst (type: boolean, default: false): Opens the first item when there is no active search query. - className (type: string): Optional class names applied to the root container. ## Tabs - URL: https://iconiqui.com/navigation/tabs - Package: @iconiq/b-tabs - Install: npx shadcn@latest add @iconiq/b-tabs - Registry JSON: https://iconiqui.com/r/b-tabs.json - Summary: Root wrapper for measured tabs with controlled or uncontrolled state, spring-smoothed panel sizing, and a forgiving fallback when values do not match content. - Dependencies: @base-ui/react, motion ### Documented APIs - Tabs: Root wrapper for measured tabs with controlled or uncontrolled state, spring-smoothed panel sizing, and a forgiving fallback when values do not match content. - children (type: ReactNode, required): Compose TabsList, TabsTrigger, and TabsContent inside the root. - defaultValue (type: string): Initial active tab value for uncontrolled usage. Invalid values fall back to the first declared TabsContent. - value (type: string): Controlled active tab value. Invalid values fall back to the first declared TabsContent. - onValueChange (type: (value: string) => void): Called when a trigger activates a different tab through click or keyboard interaction. - activationMode (type: "manual" | "automatic", default: "manual"): Controls keyboard behavior. In manual mode arrow keys move focus and Enter or Space activates the focused tab. In automatic mode focus movement also changes the active tab. - className (type: string): Merged onto the root wrapper around the list and content panels. - TabsList: Inline trigger rail with a spring-driven underline indicator and horizontal overflow support for longer tab sets. - children (type: ReactNode): Usually a row of TabsTrigger elements. - className (type: string): Merged onto the inline-flex rail around the triggers. - TabsTrigger: Interactive tab button with touch-friendly sizing, quicker hover feedback, a visible keyboard focus ring, and coordination with the shared underline. - value (type: string, required): Unique tab identifier used for active state and content matching. - children (type: ReactNode, required): Label content rendered inside the trigger button. - className (type: string): Merged onto the trigger button for local spacing, typography, or active-state overrides. - disabled (type: boolean): Prevents the trigger from receiving focus or changing the active tab. - TabsContent: Declarative panel definition tied to a matching trigger value and rendered through the root's animated panel shell. - value (type: string, required): Matches the corresponding TabsTrigger value. - children (type: ReactNode, required): Panel body shown when the content value is active. - className (type: string): Merged onto the rendered active panel element when this content value is selected. ## 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, 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. - reducedMotion (type: boolean): Forces the avatar tooltip onto its calmer motion path while still respecting system reduced-motion preferences when unset. - 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 green status badge that scales with the root Avatar size. Add tooltip to Avatar when the whole avatar should expose the status hint. - children (type: ReactNode): Optional icon or status mark. Small avatars hide nested SVGs automatically. - 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. - reducedMotion (type: boolean): Forces the badge tooltip onto its calmer motion path while still respecting system reduced-motion preferences when unset. - 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 a shimmer-enabled default variant, a quieter dot variant, and preset color tokens. - Dependencies: motion, class-variance-authority ### Documented APIs - Badge: Compact label pill with a shimmer-enabled default variant, a quieter dot variant, and preset color tokens. - 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: BadgeColor, default: "gray"): Picks a preset palette token. The default variant turns it into a tinted fill, while the dot variant uses it for the status dot and border tint. - waveColor (type: string): Optional shimmer midpoint override for the default variant. When omitted, the sweep derives a subtle tone from the current text color. - Visual behavior: The default variant keeps the original spring-in shimmer treatment, while the dot variant adds a subtle status pulse. ## 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: shadcn-style animated monthly calendar with controlled/uncontrolled month state, day selection, and direct month/year picking. - Dependencies: motion, lucide-react, date-fns ### Documented APIs - Calendar: shadcn-style animated monthly calendar with controlled/uncontrolled month state, day selection, and direct month/year picking. - selected (type: Date): Controlled selected day. When provided, the highlighted day is always derived from this prop. - defaultSelected (type: Date): Initial selected day for uncontrolled usage when selected is not provided. - onSelect (type: (date: Date) => void): Called when the user picks any interactive day, including visible outside-month days. - 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. Disabled days keep the same visuals but cannot be selected. - locale (type: Locale): Optional date-fns locale used for month labels, weekday headers, selected-date copy, and spoken date 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. - Date math and layout behavior: The grid is rebuilt with date-fns whenever the visible month changes. - Motion and interaction model: Month transitions, selected-day changes, and the live selection summary each animate independently. ## 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 optional interactive lift, Motion-smoothed layout transitions, and shared header, action, content, and footer slots. - Dependencies: motion ### Documented APIs ## 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: Embla-powered carousel with aspect-ratio presets and horizontal or vertical slides. Built with embla-carousel-react and Lucide. - Dependencies: embla-carousel-react, lucide-react ### Documented APIs ## 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 eases the surface in with fluid motion. - Dependencies: recharts, motion ### Documented APIs - ChartContainer: Theme-aware Recharts shell that maps ChartConfig tokens to CSS variables, applies registry chart colors, and eases the surface in with fluid motion. - config (type: ChartConfig, required): Series labels and colors. Use var(--chart-1) style tokens or per-key theme overrides; ChartStyle writes --color-{key} variables scoped to this chart instance. - children (type: ReactNode, required): Recharts chart markup, usually a BarChart, LineChart, or AreaChart wrapped by ResponsiveContainer through this container. - id (type: string): Optional stable id for the generated data-chart attribute and scoped CSS variables. - initialDimension (type: { width: number; height: number }): Optional fallback size for ResponsiveContainer before the first measure. By default the chart fills its parent (100% width/height) with a debounced resize handler. - reducedMotion (type: boolean): Forces the calmer motion path for the surface reveal, tooltip, legend, and ChartBar timing while still honoring system reduced-motion preferences when unset. - 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. - ChartTooltip & ChartTooltipContent: Recharts tooltip primitive plus a styled content shell with a soft spring 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. - 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 & ChartLegendContent: Legend primitive 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. - verticalAlign (type: "top" | "bottom", default: "bottom"): Adjusts legend spacing relative to the chart. ## 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: Progress component documentation. ### Documented APIs ## 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: Lightweight loading placeholder that renders a muted block with an optional shimmer pass layered above it. ### Documented APIs - ShimmerSkeleton: Lightweight loading placeholder that renders a muted block with an optional shimmer pass layered above it. - 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 shimmer overlay is rendered. Set it to false when you want a static loading block. - 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. - Registry bundle: Install the exact registry entry shown on the right when you want the component file with no additional runtime dependencies. ## 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 built around an output element. - Dependencies: motion ### Documented APIs - Spinner: Default export for a lightweight loading indicator built around an output element. - variant (type: "ring" | "dots", default: ring): Chooses between the rotating circular border and the three bouncing dots treatment. - className (type: string): Merged onto the root output element so you can resize or recolor the spinner with Tailwind utilities. ## 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, 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. - 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. - 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. - 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 when no rows are visible. - className (type: string): Merged onto the body 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. - 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 right-aligned controls. - align (type: "left" | "right", default: left): Controls left or right alignment for the header cell content. - children (type: ReactNode, required): Header label or a custom control such as TableSortButton. When used with TableSortButton, the column header also receives the correct aria-sort state. - 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" | "right", default: left): Controls left or right alignment for the cell content. - children (type: ReactNode, required): Rendered cell content. - className (type: string): Merged onto the cell wrapper. - 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. - 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" | "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. - className (type: string): Merged onto the button wrapper. ## 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. - Dependencies: motion ### Documented APIs - VerifiedBadge: Inline X-style verified scallop with a check. Use shimmer or static variants. - variant (type: "shimmer" | "static", default: shimmer): Use `shimmer` for a sweeping highlight across the scallop or `static` for a fixed badge. - size (type: number, default: 64): Width and height in pixels for the outer badge; the check scales to half this value. - className (type: string): Merged onto the root span. Pass a `text-*` class to override the default Twitter-blue scallop color. - aria-label (type: string, default: Verified): Announced to screen readers. Override when the badge conveys a different status. ## 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" | "destructive" | "warning", default: "default"): Visual tone for the alert surface. 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. - 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. - Motion and lifecycle: Alert uses AnimatePresence for mount and exit, with separate variants for the container, icon, and text stack. ## Collapsible - URL: https://iconiqui.com/layout-and-toolbars/collapsible - Package: @iconiq/b-collapsible - Install: npx shadcn@latest add @iconiq/b-collapsible - Registry JSON: https://iconiqui.com/r/b-collapsible.json - Summary: Collapsible with the same Iconiq API layered over Base UI primitives, preserving the same height, icon, and content transitions as the Radix version. - Dependencies: @base-ui/react, motion, lucide-react ### Documented APIs ## Selection Toolbar - URL: https://iconiqui.com/layout-and-toolbars/selection-toolbar - Package: @iconiq/b-selection-toolbar - Install: npx shadcn@latest add @iconiq/b-selection-toolbar - Registry JSON: https://iconiqui.com/r/b-selection-toolbar.json - Summary: Floating formatting toolbar for editable text. It watches document selection, shows itself only when the selection lives inside the provided container, and exposes bold, italic, and underline actions. - Dependencies: @base-ui/react, lucide-react ### Documented APIs - SelectionToolbar: Floating formatting toolbar for editable text. It watches document selection, shows itself only when the selection lives inside the provided container, and exposes bold, italic, and underline actions. - containerRef (type: React.RefObject, required): Ref pointing at the editable container whose text selection should drive the toolbar. Selections outside this element immediately hide the toolbar. - Positioning and editing behavior: The toolbar positions itself from the live range rectangle returned by the browser selection API and applies formatting through the native rich-text command pipeline. ## Separator - URL: https://iconiqui.com/layout-and-toolbars/separator - Package: @iconiq/separator - Install: npx shadcn@latest add @iconiq/separator - Registry JSON: https://iconiqui.com/r/separator.json - Summary: Separator component documentation. ### Documented APIs ## Infinite Ribbon - URL: https://iconiqui.com/layout-and-toolbars/infiniteribbon - Package: @iconiq/infiniteribbon - Install: npx shadcn@latest add @iconiq/infiniteribbon - Registry JSON: https://iconiqui.com/r/infiniteribbon.json - Summary: Full-width looping announcement ribbon with repeated content, optional reverse direction, and diagonal rotation controls. ### Documented APIs ## Radial Button - URL: https://iconiqui.com/special-one/radial-button - Package: @iconiq/radial-button - Install: npx shadcn@latest add @iconiq/radial-button - Registry JSON: https://iconiqui.com/r/radial-button.json - Summary: Ref-forwarding motion button with a radial fill, press feedback, and native form support. Hover, focus-visible, pointer-down, and keyboard activation spread the fill from the entry point. - Dependencies: motion ### Documented APIs - RadialButton: Ref-forwarding motion button with a radial fill, press feedback, and native form support. Hover, focus-visible, pointer-down, and keyboard activation spread the fill from the entry point. - children (type: React.ReactNode): Button label or custom content rendered above the animated fill layer. - type (type: "button" | "submit" | "reset", default: button): Native button type. Defaults to button so the control does not submit a form unless you opt in. - loading (type: boolean, default: false): Sets aria-busy and disables interaction while a form or async action is in progress. - disabled (type: boolean, default: false): Native disabled state. Also suppresses fill, press, and ripple-like feedback. - className (type: string): Optional class names merged onto the root button element. - onClick (type: React.MouseEventHandler): Native click handler forwarded to the underlying button. - name (type: string): Form field name submitted with the parent form. - value (type: string): Optional submitted value when type is submit. - form (type: string): Associates the button with a form element by id. ## Typography - URL: https://iconiqui.com/foundation/typography - Package: @iconiq/typography - Install: npx shadcn@latest add @iconiq/typography - Registry JSON: https://iconiqui.com/r/typography.json - Summary: Single text primitive that keeps the full type scale in one place, with semantic element defaults derived from the selected variant. - Dependencies: class-variance-authority ### Documented APIs - Typography: Single text primitive that keeps the full type scale in one place, with semantic element defaults derived from the selected variant. - variant (type: "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "label-xl" | "label-lg" | "label-md" | "label-sm" | "label-xs" | "paragraph-xl" | "paragraph-lg" | "paragraph-md" | "paragraph-sm" | "paragraph-xs" | "subheading-md" | "subheading-sm" | "subheading-xs" | "subheading-2xs" | "doc-label" | "doc-paragraph", default: "paragraph-md"): Chooses one of the exported typography recipes. Each variant locks in the exact font size, line height, weight, and letter spacing from the scale. - as (type: React.ElementType): Overrides the rendered HTML tag when the default semantic element for the chosen variant is not the one you want in a specific layout. - children (type: ReactNode, required): Text or inline content rendered with the selected recipe. - className (type: string): Merged after the variant classes so local color, spacing, or layout adjustments can be layered on top without forking the scale. - Scale structure: The component ships with grouped metadata for titles, labels, paragraphs, subheadings, and documentation copy. ## Dia Text - URL: https://iconiqui.com/texts/dia-text - Package: @iconiq/dia-text - Install: npx shadcn@latest add @iconiq/dia-text - Registry JSON: https://iconiqui.com/r/dia-text.json - Summary: Animated inline text reveal with a sweeping gradient band, repeat controls, and optional fixed-width rotation for motion-driven typography. - Dependencies: motion ### Documented APIs ## Shimmer Text - URL: https://iconiqui.com/texts/shimmer-text - Package: @iconiq/shimmer-text - Install: npx shadcn@latest add @iconiq/shimmer-text - Registry JSON: https://iconiqui.com/r/shimmer-text.json - Summary: Animated shimmer text with a sweeping highlight band, adjustable spread, and configurable loop speed for emphasis-heavy copy. - Dependencies: motion ### Documented APIs ## Text Inertia - URL: https://iconiqui.com/texts/text-inertia - Package: @iconiq/text-inertia - Install: npx shadcn@latest add @iconiq/text-inertia - Registry JSON: https://iconiqui.com/r/text-inertia.json - Summary: Pointer-reactive word treatment that tracks local cursor velocity, applies that momentum to the hovered word, and springs the word back into place. - Dependencies: motion ### Documented APIs - TextInertia: Pointer-reactive word treatment that tracks local cursor velocity, applies that momentum to the hovered word, and springs the word back into place. - text (type: string, default: "Interfaces remember momentum"): The phrase to render. The component splits it into words and keeps those word wrappers stable for hover-driven motion. - intensity (type: number, default: 1): Scales how strongly cursor velocity affects each hovered word. Values just above 1 feel more kinetic; lower values stay calmer. - className (type: string): Merged onto the root word group for typography, color, alignment, and layout overrides. - wordClassName (type: string): Merged onto each animated word span when you need per-word styling without changing the root layout. - Pointer velocity behavior: Text Inertia uses Motion values and spring animations instead of a runtime DOM-splitting animation plugin. ## Typewriter - URL: https://iconiqui.com/texts/typewriter - Package: @iconiq/typewriter - Install: npx shadcn@latest add @iconiq/typewriter - Registry JSON: https://iconiqui.com/r/typewriter.json - Summary: Looping typewriter text effect that types a string character by character, briefly swaps in glitch characters, and finishes each pass with a blinking cursor. - Dependencies: motion ### Documented APIs - TextTypewriter: Looping typewriter text effect that types a string character by character, briefly swaps in glitch characters, and finishes each pass with a blinking cursor. - children (type: string, required): The text content to type. The component expects a single string because the animation advances through each character in order. - className (type: string): Merged onto the root wrapper for local typography, color, spacing, or alignment classes. - duration (type: number, default: 3): Scales the scheduled typing and glitch delays. Lower values make each pass faster; higher values slow the sequence down. - Typing and glitch behavior: The animation schedules a small sequence of per-character timeouts, occasionally inserts a wrong character, removes it, then types the intended character before continuing.