# 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. - MCP URL: https://iconiqui.com/mcp Summary: MCP setup guide for connecting Iconiq to AI coding tools through the shadcn registry workflow. - 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. ## 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) => 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 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. ## Pagination - URL: https://iconiqui.com/components/pagination - Package: @iconiq/pagination - Install: npx shadcn@latest add @iconiq/pagination - Registry JSON: https://iconiqui.com/r/pagination.json - Summary: Pagination root that can either render the full paginator from total, page, and onChange props or act as the parent wrapper for the composed shadcn-style pieces. - Dependencies: motion ### Documented APIs - Pagination: Pagination root that can either render the full paginator from total, page, and onChange props or act as the parent wrapper for the composed shadcn-style pieces. - total (type: number): Total number of pages available. When you use the built-in wrapper mode, the component renders the first page, last page, current page, and one sibling on either side, collapsing the rest into ellipsis markers. - page (type: number): Controlled current page. When omitted, the root manages its own page state internally starting from page 1. - onChange (type: (page: number) => void): Called whenever a valid next page is chosen from the numbered buttons or the previous and next controls. The composed primitives also use this through context when you do not provide custom button handlers. - children (type: ReactNode): Optional composed pagination structure. When omitted, the root renders the full paginator automatically using total, page, and onChange. - PaginationContent and PaginationItem: The composed content wrapper keeps previous and next controls on the edges while the page links stay centered inside the same fixed-width rail. - children (type: ReactNode, required): Render PaginationPrevious, PaginationNext, PaginationLink, and PaginationEllipsis inside PaginationContent. Numeric and ellipsis entries can be wrapped with PaginationItem. - PaginationLink, PaginationPrevious, PaginationNext, and PaginationEllipsis: These primitives expose the numbered buttons and edge controls individually while keeping the existing visual behavior intact. - isActive (type: boolean): Marks the current page on PaginationLink and keeps the underline anchored under the active number. - text (type: string): Optional label override for PaginationPrevious and PaginationNext. They default to Prev and Next. ## 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. ## Skeleton - URL: https://iconiqui.com/components/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. ## 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: Binary on or off control built on Radix Switch, with a motion-driven thumb travel, foreground fill sweep, and optional inline label. - Dependencies: @radix-ui/react-switch, 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. ## 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): 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): 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 wrapper for a clean tab interface with controlled or uncontrolled value handling from Base UI. - Dependencies: @base-ui/react ### Documented APIs - Tabs: Root wrapper for a clean tab interface with controlled or uncontrolled value handling from Base UI. - children (type: ReactNode, required): Compose TabsList, TabsTrigger, and TabsContent inside the root, following the familiar shadcn-style structure. - defaultValue (type: string): Initial active tab value for uncontrolled usage. - value (type: string): Controlled active tab value. - onValueChange (type: (value: string, details: object) => void): Called when a trigger changes the active tab through click or keyboard navigation. - className (type: string): Merged onto the root wrapper around the list and content panels. - TabsList: Inline trigger rail that provides the muted segmented background behind a set of tab triggers. - 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 a clean active surface, quieter inactive state, and built-in accessibility wiring from Base UI. - 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: Single panel tied to a matching trigger value. - 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 panel element. ## 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. ## 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: Dia Text component documentation. ### 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: Shimmer Text component documentation. ### Documented APIs