# Iconiq

> Detailed AI-readable product index for Iconiq

## Product Summary

Iconiq is an open-source React component library built around the shadcn registry workflow. Browse polished 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

## Latest Release

- Version: v1.0.4
- Date: 7 May 2026
- Title: GEO and AI discovery rollout
- Summary: Adds a full Generative Engine Optimization layer across the product, with AI-readable discovery routes, richer metadata, and structured component indexing.

## 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.

- Changelog
  URL: https://iconiqui.com/changelog
  Summary: Release notes rendered from the local changelog source file, covering added, updated, and fixed work.

## Component Catalog

## Accordion

- URL: https://iconiqui.com/components/accordion
- Package: @iconiq/accordion
- Install: npx shadcn@latest add @iconiq/accordion
- Registry JSON: https://iconiqui.com/r/accordion.json
- Summary: Each row is described by a simple object and rendered as a single-expand accordion item.
- Dependencies: motion, lucide-react

### 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 one internal openId value 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.
- Motion and accessibility: The accordion uses native buttons and animated height transitions rather than a headless primitive.

## Alert

- URL: https://iconiqui.com/components/alert
- Package: @iconiq/alert
- Install: npx shadcn@latest add @iconiq/alert
- Registry JSON: https://iconiqui.com/r/alert.json
- Summary: Default export for a single dismissible notice. It can render inline with surrounding content or portal to the viewport when you provide a position.
- Dependencies: motion

### Documented APIs
- Alert: Default export for a single dismissible notice. It can render inline with surrounding content or portal to the viewport when you provide a position.
  - icon (type: ReactNode, required): Leading visual passed straight into the icon slot. The wrapper applies fallback sizing to nested SVGs so Lucide icons land around 18px without extra setup.
  - title (type: string, required): Primary line rendered in the stronger label style.
  - message (type: string, required): Secondary copy rendered below the title with a lighter foreground tone.
  - dismissible (type: boolean, default: true): Controls whether the close button is rendered. Disabling it removes manual dismissal only; timeout still applies unless it is set to 0.
  - position (type: "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"): When present, the component portals to document.body and uses fixed positioning classes. When omitted, the alert stays in normal flow and maxes out at max-w-sm.
  - timeout (type: number, default: 10000): Auto-dismiss delay in milliseconds. Passing 0 disables the timer and removes the progress-bar countdown.
  - onDismiss (type: () => void): Called after the component marks itself hidden, regardless of whether dismissal came from the close button or the timeout effect.
- Motion and lifecycle: Alert uses AnimatePresence for mount and exit, with separate variants for the container, icon, and text stack.

## Avatar

- URL: https://iconiqui.com/components/avatar
- Package: @iconiq/avatar
- Install: npx shadcn@latest add @iconiq/avatar
- Registry JSON: https://iconiqui.com/r/avatar.json
- Summary: Compact motion avatar with a canonical Avatar export, optional image source, and fallback text for empty states.
- Dependencies: motion

### Documented APIs
- Avatar: Compact motion avatar with a canonical Avatar export, optional image source, and fallback text for empty states.
  - src (type: string): Image URL rendered into a framework-agnostic img element. When present, the image fills the 42x42 circular mask with a blur-and-clip reveal animation.
  - fallback (type: string, default: ?): Text rendered in the center when no src is provided, typically initials or a short placeholder character.
  - className (type: string): Merged onto the root motion.div. The base component already fixes the size to 42x42 and applies the circular overflow mask.
- Image and motion behavior: Motion behavior changes slightly when reduced motion is enabled, but the same two rendering paths stay intact.

## Badge

- URL: https://iconiqui.com/components/badge
- Package: @iconiq/badge
- Install: npx shadcn@latest add @iconiq/badge
- Registry JSON: https://iconiqui.com/r/badge.json
- Summary: Default export for a compact label pill with a permanent shimmer pass layered behind the content.
- Dependencies: motion

### Documented APIs
- Badge: Default export for a compact label pill with a permanent shimmer pass layered behind the content.
  - children (type: ReactNode, required): Badge content rendered in the foreground layer so it always stays above the animated shimmer.
  - className (type: string, default: ""): Appended directly to the root span. Useful for size, radius, spacing, or border overrides.
  - bgColor (type: string): Inline backgroundColor override. If omitted, the component uses a dark neutral surface in light mode and a white surface in dark mode.
  - textColor (type: string): Inline text color override. If omitted, the badge picks the inverse of its default background palette.
  - waveColor (type: string): Color used for the middle stop of the animated gradient sweep. Defaults to the local CSS variable declared on the shimmer layer.
- Visual behavior: Badge uses a quick mount animation and a continuously repeating shimmer sweep.

## Breadcrumbs

- URL: https://iconiqui.com/components/breadcrumbs
- Package: @iconiq/breadcrumbs
- Install: npx shadcn@latest add @iconiq/breadcrumbs
- Registry JSON: https://iconiqui.com/r/breadcrumbs.json
- Summary: Each breadcrumb segment is described by a small object consumed by the Breadcrumbs component.
- Dependencies: motion, lucide-react

### Documented APIs
- BreadcrumbItem: Each breadcrumb segment is described by a small object consumed by the Breadcrumbs component.
  - label (type: string, required): Visible label and React key for the item. Labels should therefore be unique inside a single breadcrumb trail.
  - href (type: string): Link destination used by the rendered anchor. If it is omitted, the component falls back to '#'.
  - icon (type: ReactNode): Optional icon shown before the label, typically a Lucide icon or any other inline React node.
- Breadcrumbs: Animated breadcrumb trail that maps over the items array and styles the last entry as the current location.
  - items (type: BreadcrumbItem[], required): Ordered list of segments. Earlier items receive hover and tap motion, while the last item gets the shimmer and pulsing dot treatment.
  - className (type: string): Merged onto the root nav wrapper so you can place the trail inside your own header layout.
- Accessibility and motion: The component keeps semantic breadcrumb structure while layering Motion on top.

## Button

- URL: https://iconiqui.com/components/button
- Package: @iconiq/button
- Install: npx shadcn@latest add @iconiq/button
- Registry JSON: https://iconiqui.com/r/button.json
- Summary: Ref-forwarding button built on motion.button plus a CVA recipe for size and variant styling.
- Dependencies: motion, class-variance-authority

### Documented APIs
- Button: Ref-forwarding button built on motion.button plus a CVA recipe for size and variant styling.
  - variant (type: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link", default: default): Chooses the visual recipe from the exported buttonVariants map.
  - size (type: "sm" | "md" | "lg" | "custom", default: md): Controls height and padding. The custom size leaves sizing classes empty so the caller can drive layout entirely through className.
  - 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.
  - 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/components/button-group
- Package: @iconiq/button-group
- Install: npx shadcn@latest add @iconiq/button-group
- Registry JSON: https://iconiqui.com/r/button-group.json
- Summary: Standalone motion button with a light upward entrance, hover scale, and a small label nudge inside the content span.
- Dependencies: motion

### Documented APIs
- Button: Standalone motion button with a light upward entrance, hover scale, and a small label nudge inside the content span.
  - children (type: ReactNode, required): Button content rendered inside an animated inline span so the label can shift slightly on hover.
  - className (type: string): Merged onto the root button. Use it for local width, spacing, or surface overrides.
- IconButton: Compact icon-only version of the same button surface, with a stronger hover scale and a rotating inner icon span.
  - children (type: ReactNode, required): Icon content rendered inside the motion span. SVG children inherit the built-in 1rem sizing utility.
  - className (type: string): Merged onto the icon button root for size or surface overrides.
- ButtonGroup: Simple flex wrapper for arranging several button surfaces in one row with shared staggered entrance motion.
  - children (type: ReactNode, required): Buttons, icon buttons, or any other inline controls you want to keep in the same row.
  - className (type: string): Merged onto the outer motion div. The base layout already applies a horizontal flex row with a small gap.
- ButtonGroupItems: Segmented button shell that turns each valid child element into an internal motion button with shared borders and equal visual rhythm.
  - 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.
- SegmentedControl: String-based segmented selector with internal state support, hover wash, 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.
- Motion and interaction: Each export shares the same spring-heavy motion language, but the interaction style changes slightly by surface.

## Calendar

- URL: https://iconiqui.com/components/calendar
- Package: @iconiq/calendar
- Install: npx shadcn@latest add @iconiq/calendar
- Registry JSON: https://iconiqui.com/r/calendar.json
- Summary: Animated monthly calendar card that now supports both controlled and uncontrolled month and selection state.
- Dependencies: motion, lucide-react, date-fns

### Documented APIs
- Calendar: Animated monthly calendar card that now supports both controlled and uncontrolled month and selection state.
  - 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 an interactive day in the current month.
  - month (type: Date): Controlled visible month. Prev/next 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 to a previous or next month.
  - disabled (type: (date: Date) => boolean): Marks dates as non-interactive. Disabled days keep the same visuals but cannot be selected.
- 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 footer summary each animate independently.

## Carousel

- URL: https://iconiqui.com/components/carousels
- Package: @iconiq/carousels
- Install: npx shadcn@latest add @iconiq/carousels
- Registry JSON: https://iconiqui.com/r/carousels.json
- Summary: Single exported testimonial carousel with internal pagination state, swipe gestures, animated slide transitions, and built-in arrow and dot controls.
- Dependencies: motion, lucide-react

### Documented APIs
- Carousel: Single exported testimonial carousel with internal pagination state, swipe gestures, animated slide transitions, and built-in arrow and dot controls.
  - testimonials (type: Testimonial[]): Optional testimonial list shown by the carousel. When omitted, the component falls back to the sample items declared in the source file.
- Testimonial item: Each item passed into the testimonials array follows a small typed shape used for the quote, author, and avatar row.
  - quote (type: string, required): Main testimonial copy rendered in the large italic text block inside the active slide.
  - name (type: string, required): Author name shown in the lower identity row beside the avatar or initials fallback.
  - handle (type: string, required): Secondary identity label rendered below the name, usually a short username or role marker.
  - avatar (type: string): Optional avatar image source. When omitted, the component shows the initials fallback chip instead.
  - initials (type: string): Optional fallback text rendered when no avatar string is provided. Leave it empty when you want the author row to render without any leading media.
- Interaction and layout behavior: The component couples motion and navigation into one fixed layout, so consumers get a ready-made interaction shell rather than a headless slider primitive.
  - swipe threshold (type: built-in): Dragging left or right past 80px changes slides. Smaller drags snap back to the current item.
  - pagination dots (type: built-in): Each testimonial maps to a dot button. The active dot stretches wider and clicking any dot jumps to that index.
  - arrow controls (type: built-in): Previous and next buttons wrap around the array length instead of stopping at the edges.

## Collapsible

- URL: https://iconiqui.com/components/collapsible
- Package: @iconiq/collapsible
- Install: npx shadcn@latest add @iconiq/collapsible
- Registry JSON: https://iconiqui.com/r/collapsible.json
- Summary: Root wrapper around Radix Collapsible.Root with a small internal context used by the custom content animation.
- Dependencies: @radix-ui/react-collapsible, motion

### Documented APIs
- Collapsible: Root wrapper around Radix Collapsible.Root with a small internal context used by the custom content animation.
  - open (type: boolean): Controlled open state. When provided, the component follows this prop instead of its own internal state.
  - defaultOpen (type: boolean): Initial open value for uncontrolled usage.
  - onOpenChange (type: (open: boolean) => void): Called whenever the trigger toggles the root. It runs for both controlled and uncontrolled usage.
  - children (type: ReactNode, required): Composition surface for the trigger and content primitives rendered inside the root.
- CollapsibleTrigger: Thin wrapper around Radix CollapsibleTrigger.
  - children (type: ReactNode, required): Interactive content rendered inside the trigger surface.
  - asChild (type: boolean): Lets you supply your own trigger element while preserving the Radix trigger behavior.
  - disabled (type: boolean): Disables trigger interaction through the underlying Radix primitive.
- CollapsibleContent: Custom motion-driven content area that intentionally exposes a smaller API than the Radix primitive.
  - children (type: ReactNode, required): Rendered inside the animated content wrapper.
  - className (type: string): Applied to the inner motion.div that reveals the content.

## Combobox

- URL: https://iconiqui.com/components/combobox
- Package: @iconiq/combobox
- Install: npx shadcn@latest add @iconiq/combobox
- Registry JSON: https://iconiqui.com/r/combobox.json
- Summary: Each selectable row is described by a plain object and can optionally include a secondary description line.
- Dependencies: motion, lucide-react

### Documented APIs
- ComboboxOption: Each selectable row is described by a plain object and can optionally include a secondary description line.
  - value (type: string, required): Stable identifier used for the selected state and returned through onChange.
  - label (type: string, required): Primary text shown in the closed field and inside the dropdown row.
  - description (type: string): Optional helper copy rendered under the label inside the dropdown list.
- Combobox: Searchable single-select field that owns open state, search query, and active row internally, while the selected value stays parent-driven.
  - options (type: ComboboxOption[], required): Available rows rendered in display order and used as the filtering source.
  - value (type: string): Currently selected option value. The component derives the visible label entirely from this prop when the field is closed.
  - onChange (type: (value: string) => void): Called when a row is selected and also when the clear action resets the field to an empty string.
  - placeholder (type: string, default: "Select an option..."): Shown when no value is selected, and again while the field is open with an empty query.
  - emptyMessage (type: string, default: "No results found."): Fallback copy rendered when filtering produces no matching options.
  - className (type: string): Merged onto the outer relative wrapper so width or placement can be adjusted externally.
  - disabled (type: boolean, default: false): Disables the input, blocks opening, and applies a reduced-opacity presentation.
  - clearable (type: boolean, default: true): Controls whether the clear button appears once a value has been selected.
- Filtering, keyboard, and layout behavior: The dropdown is portaled to document.body, positioned from the field bounds, and supports a stronger keyboard model than the simpler select component.

## Context menu

- URL: https://iconiqui.com/components/context-menu
- Package: @iconiq/context-menu
- Install: npx shadcn@latest add @iconiq/context-menu
- Registry JSON: https://iconiqui.com/r/context-menu.json
- Summary: Stateful wrapper that listens for the native contextmenu event on a local surface and renders a fixed-position floating menu.
- Dependencies: motion

### Documented APIs
- ContextMenu: Stateful wrapper that listens for the native contextmenu event on a local surface and renders a fixed-position floating menu.
  - items (type: ContextMenuItem[], required): Ordered list of menu rows. Each item defines its own label, optional icon and shortcut, click handler, and row state.
  - children (type: ReactNode, required): Content wrapped by the local context-click target. The component always renders a div around this content and attaches the right-click handler there.
  - className (type: string): Merged onto the wrapper div that receives the native context menu event.
  - menuClassName (type: string): Merged onto the floating motion.div for local surface styling overrides. The component still applies an inline width of 232px.
- ContextMenuItem: Data shape used by the items prop to define each row in the menu.
  - label (type: string, required): Primary row copy rendered as the main action label.
  - icon (type: ReactNode): Optional leading visual rendered inside the fixed 16px icon slot.
  - shortcut (type: string): Optional trailing helper text, typically a keyboard hint such as R or Cmd+D.
  - onSelect (type: () => void): Called when the row is activated with a click or Enter on the currently highlighted item.
  - destructive (type: boolean): Switches the row into the destructive color treatment and changes the active highlight tint.
  - disabled (type: boolean): Dims the row and blocks pointer and Enter selection.
  - separatorAfter (type: boolean): Inserts a thin divider after the row unless it is already the last rendered item.

## Drawer

- URL: https://iconiqui.com/components/drawer
- Package: @iconiq/drawer
- Install: npx shadcn@latest add @iconiq/drawer
- Registry JSON: https://iconiqui.com/r/drawer.json
- Summary: Single exported overlay drawer controlled entirely from parent state, with side-based panel motion and built-in body scroll locking.
- Dependencies: motion, lucide-react

### Documented APIs
- Drawer: Single exported overlay drawer controlled entirely from parent state, with side-based panel motion and built-in body scroll locking.
  - open (type: boolean, required): Controls whether the drawer and overlay render at all. The component is fully controlled and does not keep its own open state.
  - onClose (type: () => void, required): Called when the overlay is clicked or when Escape is pressed while the drawer is open.
  - side (type: "left" | "right" | "top" | "bottom", default: "right"): Chooses the panel edge, slide direction, and the matching border placement from the internal panelVariants map.
  - title (type: string): Primary heading rendered in the header row. When omitted, the heading node still renders but stays empty.
  - description (type: string): Secondary helper line rendered under the title when present.
  - children (type: ReactNode): Content rendered inside the scrolling body area below the header.
- Motion, layout, and close behavior: The drawer uses a spring-driven panel plus staggered header and body children, with a softer duration fallback when reduced motion is enabled.
  - overlay (type: built-in): A fixed full-screen overlay is always rendered behind the panel and closes the drawer on click.
  - close button (type: built-in): The header always includes a close button with the Lucide X icon wired to onClose.

## Dialog

- URL: https://iconiqui.com/components/dialog
- Package: @iconiq/dialog
- Install: npx shadcn@latest add @iconiq/dialog
- Registry JSON: https://iconiqui.com/r/dialog.json
- Summary: Dialog, DialogTrigger, DialogClose, and DialogPortal are direct re-exports of the matching Radix dialog primitives.
- Dependencies: @radix-ui/react-dialog, 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.

## Dropdown

- URL: https://iconiqui.com/components/dropdown
- Package: @iconiq/dropdown
- Install: npx shadcn@latest add @iconiq/dropdown
- Registry JSON: https://iconiqui.com/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: 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 when your item children are not plain text.
  - onClick (type: (event: MouseEvent<HTMLButtonElement>) => 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.
- 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.

## File upload

- URL: https://iconiqui.com/components/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.

## Hover card

- URL: https://iconiqui.com/components/hover-card
- Package: @iconiq/hover-card
- Install: npx shadcn@latest add @iconiq/hover-card
- Registry JSON: https://iconiqui.com/r/hover-card.json
- Summary: Stateful wrapper that opens and closes a local callout from pointer and focus events with configurable delays.
- Dependencies: @radix-ui/react-slot, motion

### Documented APIs
- HoverCard: Stateful wrapper that opens and closes a local callout from pointer and focus events with configurable delays.
  - children (type: ReactNode, required): Composition surface for the trigger and content primitives rendered inside the hover card root.
  - className (type: string): Merged onto the root span that anchors the trigger and positioned content.
  - openDelay (type: number, default: 80): Delay in milliseconds before the card opens after pointer or focus entry.
  - closeDelay (type: number, default: 120): Delay in milliseconds before the card closes after pointer or focus leaves the root.
- 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 that appears below the trigger with a spring entrance and blur 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.

## Input

- URL: https://iconiqui.com/components/input
- Package: @iconiq/input
- Install: npx shadcn@latest add @iconiq/input
- Registry JSON: https://iconiqui.com/r/input.json
- Summary: Animated text input with a canonical Input export, always-visible label, and built-in helper behaviors for password, search, and email states.
- Dependencies: motion

### Documented APIs
- Input: Animated text input with a canonical Input export, always-visible label, and built-in helper behaviors for password, search, and email states.
  - label (type: string, default: Type here): Always-visible label rendered above the field and linked to the input via htmlFor.
  - value (type: string): Controlled string value. When omitted, the component uses local state starting from an empty string.
  - onChange (type: (value: string) => void): Receives the next string value rather than the original change event.
  - type (type: HTMLInputTypeAttribute, default: text): Native input type used by the underlying input element. Password, email, search, and number each trigger additional local behavior.
  - placeholder (type: string): Forwarded to the native input so empty fields can show guidance copy before any text is entered.
  - disabled (type: boolean): Disables the native input and also turns off interactive affordances such as the password toggle and search clear button.
  - readOnly (type: boolean): Leaves the field focusable but disables local editing affordances and prevents value changes through the built-in helper actions.
  - id (type: string): Optional input id. If you leave it out, the component creates one with useId.
  - className (type: string): Applied to the outer wrapper that contains both the label and the animated input shell.
- Type-specific behavior: Several input types ship with extra runtime behavior beyond what the browser gives you for free.

## Input group

- URL: https://iconiqui.com/components/input-group
- Package: @iconiq/input-group
- Install: npx shadcn@latest add @iconiq/input-group
- Registry JSON: https://iconiqui.com/r/input-group.json
- Summary: Floating-label input field with optional prefix and suffix slots, a center-out focus rule, and inline error messaging driven entirely by props.
- Dependencies: motion

### Documented APIs
- Inputgroups: Floating-label input field with optional prefix and suffix slots, a center-out focus rule, and inline error messaging driven entirely by props.
  - label (type: string, required): Field label rendered inside the shell until the input becomes focused or contains a value, then animated upward into its floating position.
  - error (type: string): Optional validation message rendered below the field. Passing a value also switches the label and underline to the destructive palette.
  - prefixIcon (type: ReactNode): Leading visual placed before the input area. The slot is best suited to compact icons and inherits the same focus-aware color shift as the suffix.
  - suffixIcon (type: ReactNode): Optional trailing visual rendered inside a button, which makes it useful for actions such as show-password toggles or clear controls.
  - onSuffixClick (type: () => void): Called when the suffix button is pressed. It only matters when suffixIcon is also present.
  - id (type: string): Optional input id. When omitted, the component creates one with useId and links the animated label automatically.
  - className (type: string): Applied to the native input element itself, not the outer shell. Use it for text sizing, placeholder, or input-level spacing overrides.
- InputGroup: Lightweight vertical wrapper for stacking multiple Inputgroups fields with consistent spacing.
  - children (type: ReactNode, required): One or more Inputgroups fields, or any other custom content you want to keep in the same vertical flow.
  - className (type: string): Merged onto the wrapper div. The base layout already uses a full-width flex column with a 1.5rem gap.
- Motion and behavior: The component keeps its motion treatment quiet and focused on form affordances rather than full-panel animation.

## Popover

- URL: https://iconiqui.com/components/popover
- Package: @iconiq/popover
- Install: npx shadcn@latest add @iconiq/popover
- Registry JSON: https://iconiqui.com/r/popover.json
- Summary: Standard shadcn-style export: `Popover` is `PopoverPrimitive.Root`, matching what the CLI installs into `components/ui/popover`.
- Dependencies: @radix-ui/react-popover, motion

### Documented APIs
- Popover: Standard shadcn-style export: `Popover` is `PopoverPrimitive.Root`, matching what the CLI installs into `components/ui/popover`.
  - 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: These exports are direct aliases of the matching Radix primitives and are used to open the popover or redefine its 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, required): Controls whether the animated portal branch renders at all. In practice this must mirror the root open state for entry and exit motion to run correctly.
  - 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.

## Checkbox group

- URL: https://iconiqui.com/components/checkbox-group
- Package: @iconiq/checkbox-group
- Install: npx shadcn@latest add @iconiq/checkbox-group
- Registry JSON: https://iconiqui.com/r/checkbox-group.json
- Summary: Each option row is described with a plain object and rendered as an animated button.
- Dependencies: 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.
  - disabled (type: boolean): Disables the row button and blocks hover, active, and toggle behavior for that option.
- CheckboxGroup: Animated multi-select list whose checked state is derived entirely from the value prop.
  - options (type: CheckboxGroupOption[], required): Array of rows to render, in display order.
  - value (type: string[], default: []): Current selected values. The component does not keep internal selection state beyond this prop.
  - onChange (type: (value: string[]) => void): Receives the next selected values array after a row is toggled.
  - className (type: string): Merged onto the root flex column wrapper.
- Motion and accessibility: The component leans on hover surfaces and AnimatePresence rather than native checkbox UI.

## Radio group

- URL: https://iconiqui.com/components/radiogroup
- Package: @iconiq/radiogroup
- Install: npx shadcn@latest add @iconiq/radiogroup
- Registry JSON: https://iconiqui.com/r/radiogroup.json
- Summary: Options are plain objects consumed by the RadioGroup component.
- Dependencies: 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 that can run uncontrolled from local state or sync to a controlled value prop.
  - options (type: { value: string; label: string; description?: string }[], required): Available choices in display order.
  - value (type: string): Controlled selected value. If omitted, the component starts from the first option's value and manages selection locally.
  - onChange (type: (value: string) => void): Called whenever a user selects a row.
  - className (type: string): Merged onto the root wrapper for spacing or sizing adjustments.
- Motion and accessibility: The component layers Motion over custom radio semantics rather than using native input[type=radio].

## Select

- URL: https://iconiqui.com/components/select
- Package: @iconiq/select
- Install: npx shadcn@latest add @iconiq/select
- Registry JSON: https://iconiqui.com/r/select.json
- Summary: Each selectable row is described by a plain object and rendered inside a portaled menu.
- Dependencies: motion, lucide-react

### Documented APIs
- Option shape: Each selectable row is described by a plain object and rendered inside a portaled menu.
  - value (type: string, required): Stable identifier used to determine the selected option and what onChange returns.
  - label (type: string, required): Text shown in both the trigger and the dropdown row.
  - icon (type: ReactNode): Optional leading visual shown only inside the dropdown row.
- Select: Animated single-select dropdown that manages open state internally but expects the selected value to come from the parent.
  - options (type: { value: string; label: string; icon?: ReactNode }[], required): Rows available in the dropdown menu.
  - value (type: string): Currently selected option value. The component derives its selected label entirely from this prop.
  - onChange (type: (value: string) => void): Called when a row is chosen. The menu closes immediately afterward.
  - placeholder (type: string, default: Select an option…): Fallback trigger text shown when no option matches the current value.
  - className (type: string): Merged onto the outer wrapper so width and placement can be adjusted without editing the component source.
- Overlay and interaction behavior: The dropdown menu is portaled to document.body and continuously repositioned while open.

## Slider

- URL: https://iconiqui.com/components/slider
- Package: @iconiq/slider
- Install: npx shadcn@latest add @iconiq/slider
- Registry JSON: https://iconiqui.com/r/slider.json
- Summary: Pointer-driven range control with optional controlled or uncontrolled value management.
- Dependencies: 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 whenever pointer interaction computes a new clamped value.
  - showValue (type: boolean, default: true): Controls whether the live numeric readout is shown on the right side of the label row.
  - label (type: string): Optional label shown on the left side of the header row above the track.
- Interaction model: Slider is currently optimized for pointer interaction only.

## Spinner

- URL: https://iconiqui.com/components/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.

## Switch

- URL: https://iconiqui.com/components/switch
- Package: @iconiq/switch
- Install: npx shadcn@latest add @iconiq/switch
- Registry JSON: https://iconiqui.com/r/switch.json
- Summary: Animated switch with a canonical Switch export. Checked state is expected to come from the parent.
- Dependencies: motion

### Documented APIs
- Switch: Animated switch with a canonical Switch export. Checked state is expected to come from the parent.
  - checked (type: boolean, default: false): Current switch state shown by the thumb position and track color.
  - onCheckedChange (type: (checked: boolean) => void): Called with the next boolean when the button is clicked.
  - disabled (type: boolean, default: false): Disables the native button and dims the control.
  - className (type: string): Merged onto the root button for placement and sizing overrides.
  - size (type: "sm" | "md" | "lg", default: md): Selects the track dimensions, thumb size, and travel distance from the internal SWITCH_LAYOUT map.
- Size and motion behavior: The switch uses separate transitions for the track and the thumb so the two parts settle at slightly different tempos.

## Table

- URL: https://iconiqui.com/components/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 custom layouts stay aligned.
  - className (type: string): Merged onto the root wrapper 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: Top shell for the header area. It preserves the original top border before the first row.
  - children (type: ReactNode, required): Usually one header TableRow.
  - className (type: string): Merged onto the header wrapper.
- TableBody: 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 row primitive used for both header and body layouts.
  - variant (type: "header" | "body", default: body): Header rows skip mount and exit motion, while body rows use the original spring-based row transitions.
  - 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 keep the original muted hover wash. Defaults to false for header rows and true for body rows.
  - className (type: string): Merged onto the row shell for spacing or color overrides.
  - Motion div props (type: ComponentPropsWithoutRef<typeof motion.div>): Additional motion.div props such as layout, transition, whileHover, and exit can still be passed directly.
- TableHead: 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.
  - className (type: string): Merged onto the header cell wrapper.
- TableCell: 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 caption line 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 block for zero-result or no-data states inside TableBody.
  - children (type: ReactNode, required): Empty-state copy or a richer no-data message.
  - Motion div props (type: ComponentPropsWithoutRef<typeof motion.div>): You can still override animate, initial, transition, or className when customizing the empty state.
- TableSortButton: Optional header helper that preserves the original label-plus-chevron treatment and direction animation.
  - active (type: boolean, default: false): Strengthens the icon opacity and enables the active sort direction treatment.
  - 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.
  - children (type: ReactNode, required): Visible sort label.
  - className (type: string): Merged onto the button wrapper.

## Tabs

- URL: https://iconiqui.com/components/tabs
- Package: @iconiq/tabs
- Install: npx shadcn@latest add @iconiq/tabs
- Registry JSON: https://iconiqui.com/r/tabs.json
- Summary: Root provider that manages the active value, hover state, trigger measurements, and the shared animated panel transition.
- Dependencies: motion

### Documented APIs
- Tabs: Root provider that manages the active value, hover state, trigger measurements, and the shared animated panel transition.
  - children (type: ReactNode, required): Compose TabsList, TabsTrigger, and TabsContent inside the root, following the same structure people expect from shadcn tabs.
  - defaultValue (type: string): Initial active tab value for uncontrolled usage. When omitted, the first TabsContent value becomes active.
  - value (type: string): Controlled active tab value.
  - onValueChange (type: (value: string) => void): Called when a trigger changes the active tab through click or keyboard navigation.
  - className (type: string): Merged onto the root wrapper around the tab rail and the animated content area.
- TabsList: Measured trigger rail that renders the active underline and hover ghost underline without changing the visual design of the original component.
  - children (type: ReactNode): Usually a row of TabsTrigger elements.
  - className (type: string): Merged onto the inline-flex rail around the triggers.
- TabsTrigger: Native button trigger that drives the active tab, hover state, keyboard navigation, and underline measurements.
  - value (type: string, required): Unique tab identifier used for active state, focus movement, and content matching.
  - children (type: ReactNode, required): Label content rendered inside the trigger button.
  - className (type: string): Merged onto the trigger button if you need local spacing or typography overrides.
  - disabled (type: boolean): Prevents the trigger from receiving focus or changing the active tab.
- TabsContent: Declarative content marker for a single tab panel. The root reads these nodes and renders the active one through the shared animated content 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 animated panel wrapper for the active content only.

## Toggle

- URL: https://iconiqui.com/components/toggle
- Package: @iconiq/toggle
- Install: npx shadcn@latest add @iconiq/toggle
- Registry JSON: https://iconiqui.com/r/toggle.json
- Summary: Single pressed-state toggle built on Radix Toggle, with Motion-driven button, icon, and ripple feedback layered over shadcn-style size and variant classes.
- Dependencies: @radix-ui/react-toggle, class-variance-authority, motion

### Documented APIs
- Toggle: Single pressed-state toggle built on Radix Toggle, with Motion-driven button, icon, and ripple feedback layered over shadcn-style size and variant classes.
  - children (type: ReactNode, required): Visible button content rendered inside the animated inner span. This can be plain text, icons, or both.
  - variant (type: "default" | "outline", default: default): Visual treatment from the internal CVA config. Outline adds the input border and shadow-sm treatment.
  - size (type: "default" | "sm" | "lg", default: default): Height and horizontal padding preset applied through the shared toggleVariants helper.
  - pressed (type: boolean): Controlled pressed state from Radix Toggle.Root. Use this when the parent should own the on/off state.
  - defaultPressed (type: boolean): Initial pressed state for uncontrolled usage.
  - onPressedChange (type: (pressed: boolean) => void): Called after the component kicks off its local motion sequence, with the next pressed value from Radix.
  - disabled (type: boolean): Disables the toggle and prevents the hover, tap, and pressed-state interaction flow.
  - className (type: string): Merged onto the rendered motion button for local spacing or surface overrides.
- Motion and state behavior: Every pressed change triggers a button squash, a center ripple, and a separate icon animation sequence.

## Tooltip

- URL: https://iconiqui.com/components/tooltip
- Package: @iconiq/tooltip
- Install: npx shadcn@latest add @iconiq/tooltip
- Registry JSON: https://iconiqui.com/r/tooltip.json
- Summary: Animated tooltip with a canonical Tooltip export. It owns its own open state and toggles in response to hover and focus events.
- Dependencies: motion

### Documented APIs
- Tooltip: Animated tooltip with a canonical Tooltip export. It owns its own open state and toggles in response to hover and focus events.
  - children (type: ReactNode, required): Trigger content wrapped in a relative inline-flex container.
  - content (type: ReactNode, required): Tooltip body rendered inside the animated bubble.
  - side (type: "top" | "bottom" | "left" | "right", default: top): Controls which positioning class and directional motion offset are used.
  - 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 absolutely positioned inside its local wrapper rather than portaled to the document body.