{ "site": { "name": "Iconiq UI", "url": "https://iconiqui.com", "description": "Iconiq UI is an open-source React component library built around the shadcn registry workflow. Browse motion-powered UI primitives, install them as local files, and adapt them directly inside modern interfaces.", "llms": { "overview": "https://iconiqui.com/llms.txt", "full": "https://iconiqui.com/llms-full.txt" }, "catalogs": { "aiIndex": "https://iconiqui.com/ai-index.json" } }, "guides": [ { "title": "Overview", "href": "/", "url": "https://iconiqui.com", "summary": "Homepage with the full live component playground and the primary installation path for the registry." }, { "title": "Introduction", "href": "/introduction", "url": "https://iconiqui.com/introduction", "summary": "Product overview, design principles, and the delivery model behind the Iconiq component library." }, { "title": "Installation", "href": "/installation", "url": "https://iconiqui.com/installation", "summary": "Installation guide for the shadcn registry flow, direct registry JSON URLs, and sample component entries." }, { "title": "Marketplace", "href": "/marketplace", "url": "https://iconiqui.com/marketplace", "summary": "VS Code Marketplace install page for the Iconiq UI extension, with links to the extension README and registry guides." }, { "title": "MCP", "href": "/mcp", "url": "https://iconiqui.com/mcp", "summary": "MCP setup guide for connecting Iconiq to AI coding tools through the shadcn registry workflow." } ], "components": [ { "slug": "bento-builder", "name": "Bento Builder", "href": "/builder/bento-builder", "url": "https://iconiqui.com/builder/bento-builder", "installPackage": "@iconiq/bento-builder", "installCommand": "npx shadcn@latest add @iconiq/bento-builder", "registryPath": "bento-builder.json", "registryUrl": "https://iconiqui.com/r/bento-builder.json", "summary": "Interactive bento-grid layout tool — drag tiles to reposition, tap to rename, drag a corner to resize, add tiles, then export the generated grid layout code to drop straight into your own project.", "apiSections": [], "dependencies": [ "motion", "lucide-react" ] }, { "slug": "ai-input", "name": "AI Input", "href": "/blocks/ai-input", "url": "https://iconiqui.com/blocks/ai-input", "installPackage": "@iconiq/ai-input", "installCommand": "npx shadcn@latest add @iconiq/ai-input", "registryPath": "ai-input.json", "registryUrl": "https://iconiqui.com/r/ai-input.json", "summary": "Chat-style composer that stacks sent messages above the input as bubbles, exposes agent and model selector chips, and plays an Apple Intelligence-style gradient wave inside the surface when a message is sent.", "apiSections": [ { "id": "ai-input", "title": "AIInput", "summary": "Chat-style composer that stacks sent messages above the input as bubbles, exposes agent and model selector chips, and plays an Apple Intelligence-style gradient wave inside the surface when a message is sent.", "notes": [ "Press Enter to send; Shift+Enter inserts a newline. Empty drafts are ignored.", "The textarea auto-grows with the draft up to 132px, then scrolls.", "Clicking send (or pressing Enter) plays the gradient wave once: a tall, softly blurred multicolor band rises from the bottom to the top of the composer in a single pass, then fades out.", "The wave only appears after a message is sent — never while typing.", "The wave sweep collapses to a static gradient fade when the user prefers reduced motion.", "Agent and model chips open lightweight spring-animated menus that dismiss on outside click or Escape.", "The plus menu is fully data-driven via `menuItems`: actions, switch toggles, separators, and one-level submenus that slide in with a back button.", "The plus menu flips to open downward automatically when there is not enough room above the composer.", "The send button lifts to full contrast once the draft has content." ], "fields": [ { "name": "agents", "type": "AIInputOption[]", "defaultValue": "", "required": false, "description": "Options for the agent chip on the left of the footer. Each option has `value` and `label`. Omit to hide the chip." }, { "name": "defaultAgent", "type": "string", "defaultValue": "", "required": false, "description": "Initially selected agent value. Falls back to the first agent option." }, { "name": "models", "type": "AIInputOption[]", "defaultValue": "", "required": false, "description": "Options for the model chip on the right of the footer. Omit to hide the chip." }, { "name": "defaultModel", "type": "string", "defaultValue": "", "required": false, "description": "Initially selected model value. Falls back to the first model option." }, { "name": "menuItems", "type": "AIInputMenuItem[]", "defaultValue": "", "required": false, "description": "Items for the plus menu. Each item has `value`, `label`, and optional `icon`. Set `type` to `\"toggle\"` for a switch row (with optional `defaultChecked`) or `\"separator\"` for a divider. Action items accept a per-item `onClick` and toggles a per-item `onCheckedChange`, firing alongside the component-level callbacks. Pass nested `items` to turn an action into a one-level submenu with a slide transition and back button. Omit to make the plus button a plain attachment button." }, { "name": "placeholder", "type": "string", "defaultValue": "\"Ask for follow-up changes\"", "required": false, "description": "Placeholder copy for the textarea." }, { "name": "showMessages", "type": "boolean", "defaultValue": "true", "required": false, "description": "Render sent messages as right-aligned chat bubbles above the composer. Disable when you render your own thread." }, { "name": "onSend", "type": "(message: string, meta: { agent: string; model: string }) => void", "defaultValue": "", "required": false, "description": "Called with the trimmed message and the current agent and model picks when the user presses Enter or clicks send." }, { "name": "onMicClick", "type": "() => void", "defaultValue": "", "required": false, "description": "Called when the microphone button is clicked." }, { "name": "onPlusClick", "type": "() => void", "defaultValue": "", "required": false, "description": "Called when the plus button is clicked and no `menuItems` are provided." }, { "name": "onMenuSelect", "type": "(value: string) => void", "defaultValue": "", "required": false, "description": "Called with the item's `value` when an action item — top-level or inside a submenu — is selected in the plus menu." }, { "name": "onMenuToggle", "type": "(value: string, checked: boolean) => void", "defaultValue": "", "required": false, "description": "Called when a toggle item in the plus menu is switched on or off." }, { "name": "onAgentChange", "type": "(value: string) => void", "defaultValue": "", "required": false, "description": "Called with the new agent value when the agent chip selection changes." }, { "name": "onModelChange", "type": "(value: string) => void", "defaultValue": "", "required": false, "description": "Called with the new model value when the model chip selection changes." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Extra classes for the outer wrapper." } ] } ], "dependencies": [ "@base-ui/react", "motion", "lucide-react" ] }, { "slug": "banner", "name": "Banner", "href": "/blocks/banner", "url": "https://iconiqui.com/blocks/banner", "installPackage": "@iconiq/banner", "installCommand": "npx shadcn@latest add @iconiq/banner", "registryPath": "banner.json", "registryUrl": "https://iconiqui.com/r/banner.json", "summary": "Top-of-screen announcement banner with four gradient tones, a left-aligned ringed icon and message, a right-aligned outlined action, a dismiss collapse, and a fluid spring morph that melts the bar into a confirmation pill when its action is clicked.", "apiSections": [], "dependencies": [ "motion", "lucide-react" ] }, { "slug": "code-block", "name": "Code Block", "href": "/blocks/code-block", "url": "https://iconiqui.com/blocks/code-block", "installPackage": "@iconiq/code-block", "installCommand": "npx shadcn@latest add @iconiq/code-block", "registryPath": "code-block.json", "registryUrl": "https://iconiqui.com/r/code-block.json", "summary": "Editor-style code block with a filename tab, a top-right spring-crossfade copy button, a bottom status bar with language and line count, line numbers, built-in theme-aware syntax highlighting, and line emphasis.", "apiSections": [], "dependencies": [ "motion", "lucide-react" ] }, { "slug": "contribution-graph", "name": "Contribution Graph", "href": "/blocks/contribution-graph", "url": "https://iconiqui.com/blocks/contribution-graph", "installPackage": "@iconiq/contribution-graph", "installCommand": "npx shadcn@latest add @iconiq/contribution-graph", "registryPath": "contribution-graph.json", "registryUrl": "https://iconiqui.com/r/contribution-graph.json", "summary": "GitHub-style contribution calendar with compound calendar, block, total-count, and legend parts — pass raw Activity data or just a GitHub username and it fetches and caches the last year of contributions itself, shimmers a skeleton grid while loading, then fades the muted grid in and lights the greens up level by level — lightest to darkest — with springy pops, plus custom per-day tooltips and reduced-motion aware behavior.", "apiSections": [], "dependencies": [ "date-fns" ] }, { "slug": "feedback-form", "name": "Feedback Form", "href": "/blocks/feedback-form", "url": "https://iconiqui.com/blocks/feedback-form", "installPackage": "@iconiq/feedback-form", "installCommand": "npx shadcn@latest add @iconiq/feedback-form", "registryPath": "feedback-form.json", "registryUrl": "https://iconiqui.com/r/feedback-form.json", "summary": "Feedback Form component documentation.", "apiSections": [], "dependencies": [] }, { "slug": "logo-carousel", "name": "Logo Carousel", "href": "/blocks/logo-carousel", "url": "https://iconiqui.com/blocks/logo-carousel", "installPackage": "@iconiq/logo-carousel", "installCommand": "npx shadcn@latest add @iconiq/logo-carousel", "registryPath": "logo-carousel.json", "registryUrl": "https://iconiqui.com/r/logo-carousel.json", "summary": "Logo Carousel component documentation.", "apiSections": [], "dependencies": [] }, { "slug": "message", "name": "Message", "href": "/blocks/message", "url": "https://iconiqui.com/blocks/message", "installPackage": "@iconiq/message", "installCommand": "npx shadcn@latest add @iconiq/message", "registryPath": "message.json", "registryUrl": "https://iconiqui.com/r/message.json", "summary": "Composable chat message primitives — group, row, avatar, bubble, header, and footer — where each message slides in beside its composer with a bouncy spring: sent messages arrive from the right, received from the left, morphing up from the bubble's tail corner and bouncing back once as they land, plus reduced-motion aware behavior.", "apiSections": [], "dependencies": [ "motion" ] }, { "slug": "reasoning-steps", "name": "Reasoning Steps", "href": "/blocks/reasoning-steps", "url": "https://iconiqui.com/blocks/reasoning-steps", "installPackage": "@iconiq/reasoning-steps", "installCommand": "npx shadcn@latest add @iconiq/reasoning-steps", "registryPath": "reasoning-steps.json", "registryUrl": "https://iconiqui.com/r/reasoning-steps.json", "summary": "Base UI collapsible reasoning trace for AI replies with a shimmering trigger label and no status icon, per-step dots that pop into checkmarks once done, a self-timing elapsed-seconds readout, a crossfading collapsed preview of the current step, and a staggered vertical timeline once expanded.", "apiSections": [], "dependencies": [ "@base-ui/react", "motion", "lucide-react" ] }, { "slug": "scroll-progress", "name": "Scroll Progress", "href": "/blocks/scroll-progress", "url": "https://iconiqui.com/blocks/scroll-progress", "installPackage": "@iconiq/scroll-progress", "installCommand": "npx shadcn@latest add @iconiq/scroll-progress", "registryPath": "scroll-progress.json", "registryUrl": "https://iconiqui.com/r/scroll-progress.json", "summary": "Ruler-style scroll indicator with tick marks that fill in as the page scrolls and a live percentage readout, dockable to either side or bottom corner of the viewport or a scrollable container.", "apiSections": [], "dependencies": [] }, { "slug": "setup-checklist", "name": "Setup Checklist", "href": "/blocks/setup-checklist", "url": "https://iconiqui.com/blocks/setup-checklist", "installPackage": "@iconiq/setup-checklist", "installCommand": "npx shadcn@latest add @iconiq/setup-checklist", "registryPath": "setup-checklist.json", "registryUrl": "https://iconiqui.com/r/setup-checklist.json", "summary": "Animated onboarding checklist card with staggered task rows, a drawn checkmark badge, and a floating progress pill with a spring-smoothed pie.", "apiSections": [], "dependencies": [ "motion", "lucide-react" ] }, { "slug": "streaming-text", "name": "Streaming Text", "href": "/blocks/streaming-text", "url": "https://iconiqui.com/blocks/streaming-text", "installPackage": "@iconiq/streaming-text", "installCommand": "npx shadcn@latest add @iconiq/streaming-text", "registryPath": "streaming-text.json", "registryUrl": "https://iconiqui.com/r/streaming-text.json", "summary": "Word-by-word AI text streaming where each word fades in crisply wearing a blue gradient, then crossfades into the theme foreground once settled — black in light mode, white in dark — with a pulsing gradient dot at the stream head, natural prose wrapping, sr-only full-text announcement, and reduced-motion aware behavior.", "apiSections": [], "dependencies": [ "motion" ] }, { "slug": "team-invitation", "name": "Team Invitation", "href": "/blocks/team-invitation", "url": "https://iconiqui.com/blocks/team-invitation", "installPackage": "@iconiq/team-invitation", "installCommand": "npx shadcn@latest add @iconiq/team-invitation", "registryPath": "team-invitation.json", "registryUrl": "https://iconiqui.com/r/team-invitation.json", "summary": "Team invitation block with fluid morphing variants for inviting members, managing the team, assigning roles, and tracking pending invites.", "apiSections": [], "dependencies": [ "motion", "lucide-react" ] }, { "slug": "testimonials", "name": "Testimonials", "href": "/blocks/testimonials", "url": "https://iconiqui.com/blocks/testimonials", "installPackage": "@iconiq/testimonials", "installCommand": "npx shadcn@latest add @iconiq/testimonials", "registryPath": "testimonials.json", "registryUrl": "https://iconiqui.com/r/testimonials.json", "summary": "Inline testimonial wall where hovering one quote blurs and dims the rest while the author attribution reveals beside the highlighted quote. Pure CSS :has()-driven hover state — no per-frame JS animation.", "apiSections": [], "dependencies": [] }, { "slug": "thinking-indicator", "name": "Thinking Indicator", "href": "/blocks/thinking-indicator", "url": "https://iconiqui.com/blocks/thinking-indicator", "installPackage": "@iconiq/thinking-indicator", "installCommand": "npx shadcn@latest add @iconiq/thinking-indicator", "registryPath": "thinking-indicator.json", "registryUrl": "https://iconiqui.com/r/thinking-indicator.json", "summary": "AI loading state with a sparkle glyph that wobbles through liquid blob keyframes into a circle while a companion twinkle blooms on the same timeline, cycling status words that slide through a soft blur, a per-word shimmer sweep, layout-stable width, and reduced-motion aware behavior.", "apiSections": [], "dependencies": [ "motion" ] }, { "slug": "b-button", "name": "Button", "href": "/buttons-and-actions/button", "url": "https://iconiqui.com/buttons-and-actions/button", "installPackage": "@iconiq/b-button", "installCommand": "npx shadcn@latest add @iconiq/b-button", "registryPath": "b-button.json", "registryUrl": "https://iconiqui.com/r/b-button.json", "summary": "Base UI button with embedded Iconiq theme tokens, shadcn-style variants, spring press feedback, optional loading state, link rendering, and Motion ripple layer.", "apiSections": [ { "id": "button", "title": "Button", "summary": "Base UI button with embedded Iconiq theme tokens, shadcn-style variants, spring press feedback, optional loading state, link rendering, and Motion ripple layer.", "notes": [ "The component ships embedded Iconiq theme tokens so primary, border, accent, and destructive colors resolve correctly without a separate theme install.", "Standard button attributes such as onClick, aria-*, name, form, and data-* are forwarded to the rendered button or anchor.", "href mode renders a motion-enhanced anchor; button mode renders Base UI Button with a motion.button surface via the render prop.", "The local pointer-down handler calls your onPointerDown first, then respects e.defaultPrevented before deciding whether to enter the pressed state or spawn a ripple.", "Pointer, keyboard, and blur handlers keep the pressed state in sync so Space and Enter get the same immediate feedback as pointer input.", "animateSize works best on intrinsically sized buttons rather than width-constrained layouts such as w-full.", "Icon-only sizes log a development warning when neither iconLabel nor aria-label is provided." ], "fields": [ { "name": "variant", "type": "\"default\" | \"destructive\" | \"outline\" | \"secondary\" | \"ghost\" | \"link\"", "defaultValue": "default", "required": false, "description": "Chooses the visual recipe from the exported buttonVariants map." }, { "name": "linkUnderline", "type": "\"motion\" | \"static\"", "defaultValue": "\"motion\" (when variant is link)", "required": false, "description": "Link variant only. motion keeps foreground text with a grey baseline underline that fills darker on hover. static uses the same text size as other variants with hover:underline." }, { "name": "size", "type": "\"default\" | \"xs\" | \"sm\" | \"lg\" | \"icon\" | \"icon-xs\" | \"icon-sm\" | \"icon-lg\"", "defaultValue": "default", "required": false, "description": "Controls the shadcn-style height, padding, gap, radius, and icon sizing for text and icon-only buttons." }, { "name": "animateSize", "type": "boolean", "defaultValue": "false", "required": false, "description": "Animates the button width with a spring as its intrinsic content changes, which is useful for labels like Continue, Saving..., and Saved on the same control." }, { "name": "loading", "type": "boolean", "defaultValue": "false", "required": false, "description": "Locks the control, sets aria-busy, crossfades the label and icon into a spring-animated spinner, and suppresses ripples until loading finishes." }, { "name": "loadingIcon", "type": "ReactNode", "defaultValue": "", "required": false, "description": "Optional spinner or status icon shown while loading is true. Defaults to a Lucide Loader2 icon with animate-spin." }, { "name": "href", "type": "string", "defaultValue": "", "required": false, "description": "When set, renders an animated anchor instead of a button. Disabled and loading states use aria-disabled, tabIndex -1, and click prevention." }, { "name": "target", "type": "string", "defaultValue": "", "required": false, "description": "Anchor target such as \"_blank\". When the target opens a new tab, rel automatically gains noopener and noreferrer unless you already supplied them." }, { "name": "rel", "type": "string", "defaultValue": "", "required": false, "description": "Optional anchor rel attribute. Merged with noopener noreferrer when target includes _blank." }, { "name": "disableRipple", "type": "boolean", "defaultValue": "false", "required": false, "description": "Skips the pointer ripple when you want only the press-state feedback. Link buttons also skip the ripple by default to avoid a contained splash on text-only actions." }, { "name": "type", "type": "\"button\" | \"submit\" | \"reset\"", "defaultValue": "button", "required": false, "description": "Passed to the underlying button element so the component does not submit forms accidentally by default. Ignored for href links." }, { "name": "children", "type": "ReactNode", "defaultValue": "", "required": false, "description": "Label content rendered above the ripple layer inside a z-10 span." }, { "name": "icon", "type": "ReactNode", "defaultValue": "", "required": false, "description": "Optional icon rendered inline with the label. Nested SVGs inherit the built-in size utility and variant-aware icon color." }, { "name": "iconLabel", "type": "string", "defaultValue": "", "required": false, "description": "Convenience prop that sets aria-label, which is required for icon-only sizes when no visible text children are present." }, { "name": "iconPosition", "type": "\"start\" | \"end\"", "defaultValue": "\"start\"", "required": false, "description": "Chooses whether the optional icon renders before or after the button text inside the same inline content row. Loading always renders at the start." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged after the generated CVA classes, making it the main escape hatch for one-off layout changes." }, { "name": "disabled", "type": "boolean", "defaultValue": "", "required": false, "description": "Native disabled state. Combines with loading to lock interaction and prevent ripple creation." } ] }, { "id": "button-variants", "title": "buttonVariants", "summary": "The CVA recipe exported alongside the component so matching button classes can be reused on links or custom wrappers.", "notes": [ "Variants ship with six visual states and eight size tokens, including icon-only sizes.", "Because buttonVariants is a plain CVA export, you can compose it independently from the Button component when you do not want a motion.button element.", "The recipe includes the same embedded Iconiq theme tokens as the Button root." ], "fields": [ { "name": "variant", "type": "\"default\" | \"destructive\" | \"outline\" | \"secondary\" | \"ghost\" | \"link\"", "defaultValue": "\"default\"", "required": false, "description": "Visual recipe passed to the CVA helper when composing classes outside the Button component." }, { "name": "linkUnderline", "type": "\"motion\" | \"static\"", "defaultValue": "\"motion\" (when variant is link)", "required": false, "description": "Link variant only. Pass through the same underline mode used by the Button component." }, { "name": "size", "type": "\"default\" | \"xs\" | \"sm\" | \"lg\" | \"icon\" | \"icon-xs\" | \"icon-sm\" | \"icon-lg\"", "defaultValue": "\"default\"", "required": false, "description": "Size token passed to the CVA helper for text and icon-only button recipes." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Optional classes merged after the generated variant and size classes." } ] } ], "dependencies": [ "@base-ui/react", "class-variance-authority", "lucide-react", "motion" ] }, { "slug": "button-group", "name": "Button Group", "href": "/buttons-and-actions/button-group", "url": "https://iconiqui.com/buttons-and-actions/button-group", "installPackage": "@iconiq/button-group", "installCommand": "npx shadcn@latest add @iconiq/button-group", "registryPath": "button-group.json", "registryUrl": "https://iconiqui.com/r/button-group.json", "summary": "Compact bordered action button with muted idle text, darker hover text, optional ripple feedback, variants, and shadcn-style size controls.", "apiSections": [ { "id": "button-group-button", "title": "Button", "summary": "Compact bordered action button with muted idle text, darker hover text, optional ripple feedback, variants, and shadcn-style size controls.", "notes": [ "Most standard button props such as type, disabled, onClick, name, value, aria-*, and data-* are forwarded to the underlying motion button.", "Inside ButtonGroup, individual borders are omitted so default and ghost variants sit flush in one connected surface.", "The public prop surface intentionally leaves out the native drag and CSS animation callback props because they conflict with Motion's own handler names." ], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Button content rendered inside an inline span so icon-and-label pairs keep consistent spacing across sizes." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the root button. Use it for local width, spacing, or surface overrides." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "defaultValue": "\"md\"", "required": false, "description": "Compacts or expands the control. Inherits the ButtonGroup size when the button is rendered inside a group." }, { "name": "variant", "type": "\"default\" | \"destructive\" | \"ghost\" | \"outline\"", "defaultValue": "\"default\"", "required": false, "description": "Visual treatment for the action. Destructive is useful for delete or irreversible actions inside a toolbar." }, { "name": "disableRipple", "type": "boolean", "defaultValue": "false", "required": false, "description": "Turns off the click ripple while preserving the rest of the hover and focus styling." }, { "name": "showBorder", "type": "boolean", "defaultValue": "true", "required": false, "description": "Adds a standalone border when the button is used outside ButtonGroup. Inside ButtonGroup, the wrapper supplies the outer border and dividers instead." } ] }, { "id": "button-group-icon-button", "title": "IconButton", "summary": "Icon-only toolbar action that shares the same compact border, muted idle tone, variants, and optional ripple behavior as Button.", "notes": [], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Icon content rendered inside the inline content span. SVG children inherit the built-in size utilities for the active size variant." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the icon button root for size or surface overrides." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "defaultValue": "\"md\"", "required": false, "description": "Controls the square footprint of the icon button. Inherits the ButtonGroup size when rendered inside a group." }, { "name": "variant", "type": "\"default\" | \"destructive\" | \"ghost\" | \"outline\"", "defaultValue": "\"default\"", "required": false, "description": "Matches the Button variant surface for icon-only actions." }, { "name": "disableRipple", "type": "boolean", "defaultValue": "false", "required": false, "description": "Disables the click ripple for quieter toolbar actions." }, { "name": "showBorder", "type": "boolean", "defaultValue": "true", "required": false, "description": "Removes the outer border when set to false so the icon action can sit more quietly beside a borderless group." } ] }, { "id": "button-group-layout", "title": "ButtonGroup", "summary": "Slot-aware flex wrapper for arranging adjacent controls with horizontal or vertical rounding rules and shared size context.", "notes": [], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Buttons, icon buttons, ButtonGroupText, ButtonGroupSeparator, ButtonGroupItems, or any other data-slot controls you want to keep together." }, { "name": "orientation", "type": "\"horizontal\" | \"vertical\"", "defaultValue": "\"horizontal\"", "required": false, "description": "Chooses the grouped rounding and shared-border direction used by buttonGroupVariants." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "defaultValue": "\"md\"", "required": false, "description": "Shared density for Button, IconButton, and ButtonGroupText children unless a child overrides size locally." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the outer group. Use it for wrapping, alignment, or local spacing overrides." } ] }, { "id": "button-group-text", "title": "ButtonGroupText", "summary": "Non-interactive text segment for labeling a group without leaving the shared button-group surface.", "notes": [], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Short label or inline content rendered inside the grouped text segment." }, { "name": "render", "type": "useRender render prop", "defaultValue": "", "required": false, "description": "Optional Base UI render override when you need a different element while keeping the same merged props." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged with the default muted bordered text segment classes." } ] }, { "id": "button-group-separator", "title": "ButtonGroupSeparator", "summary": "Separator segment for splitting labels, buttons, inputs, and grouped actions inside ButtonGroup.", "notes": [], "fields": [ { "name": "orientation", "type": "\"horizontal\" | \"vertical\"", "defaultValue": "\"vertical\"", "required": false, "description": "Controls the separator axis. Vertical separators are the default for horizontal button groups." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged with the self-stretching separator classes for custom color or spacing." } ] }, { "id": "button-group-items", "title": "ButtonGroupItems", "summary": "Segmented button shell that converts valid child elements into compact internal buttons with muted idle text and darker hover states.", "notes": [ "Only valid React elements are rendered. Non-element children are ignored and warned about in development.", "The child node itself is not preserved; ButtonGroupItems reads each child's props and children, then renders a fresh motion button for that slot.", "When showDividers is false, hover feedback moves as a shared spring layer between items and re-measures on resize.", "Uses data-slot=\"button-group-items\" so it can sit inside ButtonGroup without breaking connected layout rules." ], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Pass plain button-like elements as children. Their props and children are hoisted into the internal motion buttons rendered by the group." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the outer segmented wrapper for width or surface overrides." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "defaultValue": "\"md\"", "required": false, "description": "Sets the shared height, padding, and typography of the grouped buttons." }, { "name": "showDividers", "type": "boolean", "defaultValue": "true", "required": false, "description": "Removes the internal separator lines and the outer wrapper border when set to false, then switches the group to a smoother shared hover surface." }, { "name": "disableRipple", "type": "boolean", "defaultValue": "false", "required": false, "description": "Turns off the ripple for every internal button rendered by the group." } ] }, { "id": "segmented-control", "title": "SegmentedControl", "summary": "Segmented selector with string or rich option objects, compact sizing, keyboard support, RTL-aware navigation, form name support, and a spring-driven selected indicator.", "notes": [ "The control uses radiogroup semantics with arrow-key, Home, and End navigation.", "Arrow-left and arrow-right reverse automatically in RTL layouts.", "Disabled options are skipped while moving selection with the keyboard." ], "fields": [ { "name": "options", "type": "Array", "defaultValue": "", "required": true, "description": "Ordered list of segments. Each entry can be a plain string or an object with a stable value, optional label, icon, and disabled flag." }, { "name": "value", "type": "string", "defaultValue": "", "required": false, "description": "Controlled selected value. When provided, the internal state syncs to this prop through an effect." }, { "name": "onChange", "type": "(value: string) => void", "defaultValue": "", "required": false, "description": "Called with the selected value whenever a segment is pressed or moved to with the keyboard." }, { "name": "ariaLabel", "type": "string", "defaultValue": "", "required": false, "description": "Accessible name for the radiogroup. Provide this or ariaLabelledBy so screen readers can identify the control." }, { "name": "ariaLabelledBy", "type": "string", "defaultValue": "", "required": false, "description": "ID of an external label element that names the radiogroup. Use when a visible label already exists in the page." }, { "name": "name", "type": "string", "defaultValue": "", "required": false, "description": "When provided, renders a hidden input so the selected value can participate in native form submission." }, { "name": "disabled", "type": "boolean", "defaultValue": "false", "required": false, "description": "Disables the entire control and every segment inside it." }, { "name": "orientation", "type": "\"horizontal\" | \"vertical\"", "defaultValue": "\"horizontal\"", "required": false, "description": "Layout direction for the segmented shell and the primary arrow-key axis." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the segmented wrapper for width, alignment, or spacing overrides." }, { "name": "layoutId", "type": "string", "defaultValue": "", "required": false, "description": "Optional Motion layout id for the selected indicator. When omitted, a unique id is generated per instance so multiple controls on one page do not share indicator motion." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "defaultValue": "\"md\"", "required": false, "description": "Controls the overall density of the segmented control shell and each segment inside it." } ] }, { "id": "button-group-motion", "title": "Motion and interaction", "summary": "Each export keeps the same tactile feel, but the default presentation is now much more compact and toolbar-like.", "notes": [ "Button, IconButton, and ButtonGroupItems all default to muted text that darkens on hover, which better matches compact shadcn-style controls.", "ButtonGroup applies embedded theme tokens once at the group root so nested buttons do not repeat the full token block.", "The ButtonGroup wrapper uses the exported buttonGroupVariants CVA recipe, while existing motion-powered controls keep their ripple and shared-hover behavior.", "Ripple feedback can now be turned off per surface, which is useful when you want a quieter desktop toolbar feel.", "SegmentedControl keeps motion focused on selection changes rather than entrance effects, so the control feels faster and less oversized." ], "fields": [] } ], "dependencies": [ "@base-ui/react", "motion", "class-variance-authority" ] }, { "slug": "flux-button", "name": "Flux Button", "href": "/buttons-and-actions/flux-button", "url": "https://iconiqui.com/buttons-and-actions/flux-button", "installPackage": "@iconiq/flux-button", "installCommand": "npx shadcn@latest add @iconiq/flux-button", "registryPath": "flux-button.json", "registryUrl": "https://iconiqui.com/r/flux-button.json", "summary": "Async button with idle, loading, and success states, plus b-button visual variants.", "apiSections": [ { "id": "flux-button", "title": "FluxButton", "summary": "Async button with idle, loading, and success states, plus b-button visual variants.", "notes": [ "Built on `@base-ui/react/button` with a Motion render surface, matching the b-button integration pattern.", "Locks interaction while loading or showing success without applying disabled opacity, using aria-disabled and pointer-events-none instead.", "Motion transitions start only after the first click, so the button renders statically on page load.", "Install path is `components/ui/flux-button.tsx` with the `FluxButton` export." ], "fields": [ { "name": "idleLabel", "type": "string", "defaultValue": "", "required": true, "description": "Label shown before the action starts." }, { "name": "loadingLabel", "type": "string", "defaultValue": "", "required": true, "description": "Label shown with the built-in loader while onAction is in progress." }, { "name": "successLabel", "type": "string", "defaultValue": "", "required": true, "description": "Label shown after onAction resolves." }, { "name": "successIcon", "type": "React.ReactNode", "defaultValue": "", "required": false, "description": "Optional icon shown on success. Pass any node, such as a Lucide checkmark. Omit for text-only success." }, { "name": "onAction", "type": "() => void | Promise", "defaultValue": "", "required": true, "description": "Runs when the button is pressed, drives loading and success states, then returns to idle after successHold." }, { "name": "variant", "type": "\"default\" | \"outline\" | \"secondary\" | \"ghost\" | \"destructive\" | \"link\"", "defaultValue": "default", "required": false, "description": "Visual style variant. Matches the b-button variant set." }, { "name": "successHold", "type": "number", "defaultValue": "1000", "required": false, "description": "Milliseconds to hold the success state before returning to the idle label." }, { "name": "size", "type": "\"xs\" | \"sm\" | \"default\" | \"lg\"", "defaultValue": "default", "required": false, "description": "Height and horizontal padding preset. Matches b-button sizes." }, { "name": "type", "type": "\"button\" | \"submit\"", "defaultValue": "button", "required": false, "description": "Native button type. Use submit inside forms; defaults to button so the control does not submit unless you opt in." }, { "name": "disabled", "type": "boolean", "defaultValue": "false", "required": false, "description": "Native disabled state. Also blocks the action flow while true." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Optional class names merged onto the root button element." }, { "name": "onClick", "type": "React.MouseEventHandler", "defaultValue": "", "required": false, "description": "Native click handler forwarded to the underlying button." } ] } ], "dependencies": [ "@base-ui/react/button", "class-variance-authority", "lucide-react", "motion" ] }, { "slug": "icon-bar", "name": "Icon Bar", "href": "/buttons-and-actions/icon-bar", "url": "https://iconiqui.com/buttons-and-actions/icon-bar", "installPackage": "@iconiq/icon-bar", "installCommand": "npx shadcn@latest add @iconiq/icon-bar", "registryPath": "icon-bar.json", "registryUrl": "https://iconiqui.com/r/icon-bar.json", "summary": "Horizontal toolbar of compact icon chips. Hover or focus previews labels; clicking selects one item and keeps it expanded.", "apiSections": [ { "id": "icon-bar", "title": "IconBar", "summary": "Horizontal toolbar of compact icon chips. Hover or focus previews labels; clicking selects one item and keeps it expanded.", "notes": [], "fields": [ { "name": "value", "type": "string | null", "defaultValue": "", "required": false, "description": "Controlled selected item value. Pair with onValueChange for fully controlled selection." }, { "name": "defaultValue", "type": "string | null", "defaultValue": "", "required": false, "description": "Optional initial selected item when uncontrolled. Omit to start with every chip collapsed until the user clicks one." }, { "name": "onValueChange", "type": "(value: string | null) => void", "defaultValue": "", "required": false, "description": "Called when selection changes. Receives null when the active chip is clicked again to deselect." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Optional class names applied to the outer flex container." }, { "name": "children", "type": "React.ReactNode", "defaultValue": "", "required": false, "description": "One or more IconBarItem elements rendered in a single row with consistent spacing." } ] }, { "id": "icon-bar-item", "title": "IconBarItem", "summary": "Individual pill chip with a Lucide icon and animated label reveal on hover, focus, or selection.", "notes": [ "Only one item stays expanded at a time. Clicking a chip selects it; clicking another moves selection; clicking the active chip again collapses it.", "Hover and keyboard focus preview labels on non-selected chips. Give each item a unique value when labels repeat.", "In controlled mode, update value from onValueChange (including null on deselect) for the UI to stay in sync." ], "fields": [ { "name": "icon", "type": "LucideIcon", "defaultValue": "", "required": true, "description": "Lucide icon component rendered inside the fixed 36px icon well." }, { "name": "label", "type": "string", "defaultValue": "", "required": true, "description": "Short text revealed when the chip expands. Keep labels concise so the width animation stays smooth." }, { "name": "value", "type": "string", "defaultValue": "", "required": false, "description": "Selection identity for this chip. Defaults to label when omitted." }, { "name": "onClick", "type": "(event: React.MouseEvent) => void", "defaultValue": "", "required": false, "description": "Optional click handler fired after selection updates." }, { "name": "disabled", "type": "boolean", "defaultValue": "false", "required": false, "description": "Disables interaction, hover preview, and selection." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Optional class names merged onto the chip button." } ] } ], "dependencies": [ "@base-ui/react/toggle", "@base-ui/react/toggle-group", "motion", "lucide-react" ] }, { "slug": "toggle", "name": "Toggle", "href": "/buttons-and-actions/toggle", "url": "https://iconiqui.com/buttons-and-actions/toggle", "installPackage": "@iconiq/toggle", "installCommand": "npx shadcn@latest add @iconiq/toggle", "registryPath": "toggle.json", "registryUrl": "https://iconiqui.com/r/toggle.json", "summary": "Two-state button with spring press feedback and a muted fill that bounces in when pressed.", "apiSections": [ { "id": "toggle", "title": "Toggle", "summary": "Two-state button with spring press feedback and a muted fill that bounces in when pressed.", "notes": [ "Use aria-label when the toggle contains only an icon. Visible text or icon-plus-label children do not need a separate aria-label.", "Off-state copy uses muted foreground; pressed state shifts to foreground for clearer toolbar contrast.", "Use className to adjust footprint for icon-only controls, such as fixed square dimensions in toolbars.", "Additional primitive props such as value, name, and form attributes are forwarded to the root button." ], "fields": [ { "name": "pressed", "type": "boolean", "defaultValue": "", "required": false, "description": "Controlled pressed state. Pass this when the parent owns whether the toggle is on." }, { "name": "defaultPressed", "type": "boolean", "defaultValue": "false", "required": false, "description": "Initial pressed state for uncontrolled usage. The component manages future toggles internally." }, { "name": "onPressedChange", "type": "(pressed: boolean) => void", "defaultValue": "", "required": false, "description": "Called with the next pressed state whenever the toggle is activated or deactivated." }, { "name": "variant", "type": "\"default\" | \"outline\"", "defaultValue": "\"default\"", "required": false, "description": "Visual treatment. Outline adds a border for toolbar or segmented layouts." }, { "name": "disabled", "type": "boolean", "defaultValue": "", "required": false, "description": "Disables interaction and dims the control while preserving its pressed appearance." }, { "name": "children", "type": "React.ReactNode", "defaultValue": "", "required": false, "description": "Icon, text label, or icon-plus-label content. Children sit in normal document flow so labels expand the control width naturally." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the root button for local spacing, width, or color overrides." } ] }, { "id": "toggle-motion", "title": "Motion and interaction behavior", "summary": "Pressed state drives a horizontal liquid wipe, a one-shot light sheen, and tactile icon motion.", "notes": [ "The muted fill wipes in from the left when pressed and retracts to the right on release with a heavy spring.", "Each state change sends a diagonal sheen across the surface once. Outline keeps the same outer border in both states.", "Icons scale and squash on press with a spring settle." ], "fields": [] } ], "dependencies": [ "@base-ui/react", "class-variance-authority", "motion" ] }, { "slug": "toggle-group", "name": "Toggle Group", "href": "/buttons-and-actions/toggle-group", "url": "https://iconiqui.com/buttons-and-actions/toggle-group", "installPackage": "@iconiq/toggle-group", "installCommand": "npx shadcn@latest add @iconiq/toggle-group", "registryPath": "toggle-group.json", "registryUrl": "https://iconiqui.com/r/toggle-group.json", "summary": "Root container for toggle buttons with shared variant, spacing, and orientation. Use spacing={0} for a connected segmented layout.", "apiSections": [ { "id": "toggle-group", "title": "ToggleGroup", "summary": "Root container for toggle buttons with shared variant, spacing, and orientation. Use spacing={0} for a connected segmented layout.", "notes": [ "Default spacing is 4px between items. Pass spacing={0} for a connected outline shell with one outer border and internal dividers between items.", "Each item uses the same fluid wipe fill, sheen sweep, and icon press feedback as the standalone Toggle component.", "Group items inherit variant from context but can override it locally. Use className on items to adjust footprint for icon-only controls.", "Radix installs use type; Base UI installs use multiple. Both default to multi-select." ], "fields": [ { "name": "type", "type": "\"single\" | \"multiple\"", "defaultValue": "\"multiple\"", "required": false, "description": "Radix selection mode. Multiple allows several active items by default; single keeps one pressed item at a time." }, { "name": "multiple", "type": "boolean", "defaultValue": "true", "required": false, "description": "Base UI selection mode. Pass multiple={false} for single selection; true keeps several active items." }, { "name": "value", "type": "string | string[]", "defaultValue": "", "required": false, "description": "Controlled selection. Radix uses a string in single mode and a string array in multiple mode. Base UI always uses a string array." }, { "name": "defaultValue", "type": "string | string[]", "defaultValue": "", "required": false, "description": "Initial selection for uncontrolled usage. Match the selection mode and value shape for your installed primitive." }, { "name": "onValueChange", "type": "(value: string | string[]) => void", "defaultValue": "", "required": false, "description": "Called with the next selection whenever an item is pressed or released." }, { "name": "variant", "type": "\"default\" | \"outline\"", "defaultValue": "\"default\"", "required": false, "description": "Shared visual treatment applied to every item unless an item overrides it locally." }, { "name": "spacing", "type": "number", "defaultValue": "1", "required": false, "description": "Gap between items in spacing units. Defaults to 1 (4px). Set to 0 for a connected outline shell with one outer border and internal dividers." }, { "name": "orientation", "type": "\"horizontal\" | \"vertical\"", "defaultValue": "\"horizontal\"", "required": false, "description": "Layout direction for the group. Also sets aria-orientation and connected divider direction when spacing={0}." }, { "name": "disabled", "type": "boolean", "defaultValue": "", "required": false, "description": "Disables the entire group and all nested items." }, { "name": "aria-label", "type": "string", "defaultValue": "", "required": false, "description": "Accessible name for the group. Required when items are icon-only and no visible group label is present." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the root group wrapper for local layout or width overrides." } ] }, { "id": "toggle-group-item", "title": "ToggleGroupItem", "summary": "Individual toggle button inside the group with the same fluid motion as the standalone toggle.", "notes": [ "Items share the standalone toggle fluid motion system: liquid wipe fill, sheen sweep, and icon press squeeze.", "Supports aria-invalid styling for form validation parity with the standalone Toggle component." ], "fields": [ { "name": "value", "type": "string", "defaultValue": "", "required": true, "description": "Stable identifier used when reading or updating the group selection." }, { "name": "variant", "type": "\"default\" | \"outline\"", "defaultValue": "", "required": false, "description": "Optional local override for the shared group variant treatment." }, { "name": "disabled", "type": "boolean", "defaultValue": "", "required": false, "description": "Disables this item without affecting the rest of the group." }, { "name": "aria-label", "type": "string", "defaultValue": "", "required": false, "description": "Accessible name for icon-only items. Omit when the item already contains visible text." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the item button for local width, color, or spacing overrides." }, { "name": "children", "type": "ReactNode", "defaultValue": "", "required": false, "description": "Icon or label content rendered inside the item." } ] } ], "dependencies": [ "@base-ui/react", "class-variance-authority", "motion" ] }, { "slug": "avatar", "name": "Avatar", "href": "/display-and-content/avatar", "url": "https://iconiqui.com/display-and-content/avatar", "installPackage": "@iconiq/avatar", "installCommand": "npx shadcn@latest add @iconiq/avatar", "registryPath": "avatar.json", "registryUrl": "https://iconiqui.com/r/avatar.json", "summary": "Base UI avatar root with shared sizing and an optional tooltip for hover or focus status hints.", "apiSections": [ { "id": "avatar", "title": "Avatar", "summary": "Base UI avatar root with shared sizing and an optional tooltip for hover or focus status hints.", "notes": [ "The root renders data-slot=\"avatar\" and data-size so grouped stacks and badges can respond to the selected size.", "The root keeps a circular border overlay with dark/light blend handling and accepts the full Base UI Root props surface.", "Put tooltip on Avatar when the whole avatar should expose the status hint. Put tooltip on AvatarBadge when only the badge should be interactive." ], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": false, "description": "Compose AvatarImage, AvatarFallback, and an optional AvatarBadge inside the root." }, { "name": "size", "type": "\"default\" | \"sm\" | \"lg\"", "defaultValue": "\"default\"", "required": false, "description": "Controls the root size and drives badge/fallback sizing through data-size selectors." }, { "name": "tooltip", "type": "string", "defaultValue": "", "required": false, "description": "Optional short label shown in the Iconiq tooltip surface when the entire avatar is hovered or focused." }, { "name": "tooltipSide", "type": "\"top\" | \"bottom\" | \"left\" | \"right\"", "defaultValue": "\"right\"", "required": false, "description": "Preferred side for the avatar tooltip bubble. The default collision order is right, left, top, then bottom." }, { "name": "tooltipDelay", "type": "number", "defaultValue": "0.15", "required": false, "description": "Delay in seconds before the avatar tooltip opens." }, { "name": "tooltipClassName", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the tooltip bubble when the avatar tooltip is enabled." }, { "name": "name", "type": "string", "defaultValue": "", "required": false, "description": "Optional display name used by AvatarFallback to auto-generate initials when children are omitted." }, { "name": "asChild", "type": "boolean", "defaultValue": "false", "required": false, "description": "Merge avatar props onto the child element via Radix Slot, useful for link or button triggers." }, { "name": "aria-label", "type": "string", "defaultValue": "", "required": false, "description": "Accessible name for the avatar. Defaults to the tooltip string when tooltip is set." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the Base UI avatar root. Use it for local radius, ring, or size overrides." } ] }, { "id": "avatar-image", "title": "AvatarImage", "summary": "Image slot for the compound avatar, backed by Base UI's image loading behavior.", "notes": [], "fields": [ { "name": "src", "type": "string", "defaultValue": "", "required": true, "description": "Image URL passed to the underlying Base UI image primitive." }, { "name": "alt", "type": "string", "defaultValue": "", "required": true, "description": "Accessible text for the image. Pass an empty string only when the avatar is decorative." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged with the full-size rounded image classes." } ] }, { "id": "avatar-fallback", "title": "AvatarFallback", "summary": "Fallback slot shown by Base UI while the image is loading, missing, or failed.", "notes": [], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Initials, icon, or other compact fallback content centered inside the avatar." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged with the muted circular fallback classes." } ] }, { "id": "avatar-badge", "title": "AvatarBadge", "summary": "Absolute status badge that scales with the root Avatar size. Use variant for preset presence colors or tooltip for badge-only status hints.", "notes": [], "fields": [ { "name": "variant", "type": "\"online\" | \"offline\" | \"busy\" | \"away\"", "defaultValue": "\"online\"", "required": false, "description": "Preset status color mapped to theme-friendly green, muted, destructive, and amber tokens." }, { "name": "aria-label", "type": "string", "defaultValue": "", "required": false, "description": "Accessible status label. Defaults to the tooltip string or the variant label such as Online or Busy." }, { "name": "children", "type": "ReactNode", "defaultValue": "", "required": false, "description": "Optional icon or status mark. Icons scale down on small avatars instead of disappearing." }, { "name": "tooltip", "type": "string", "defaultValue": "", "required": false, "description": "Optional short label shown in the Iconiq tooltip surface when only the badge should be the trigger." }, { "name": "tooltipSide", "type": "\"top\" | \"bottom\" | \"left\" | \"right\"", "defaultValue": "\"right\"", "required": false, "description": "Preferred side for the tooltip bubble. The default collision order is right, left, top, then bottom." }, { "name": "tooltipDelay", "type": "number", "defaultValue": "0.15", "required": false, "description": "Delay in seconds before the tooltip opens." }, { "name": "tooltipClassName", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the tooltip bubble when the badge tooltip is enabled." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged with the green status badge background, foreground, and ring classes." } ] }, { "id": "avatar-group", "title": "AvatarGroup", "summary": "Stack wrapper for overlapping avatars and matching overflow count chips.", "notes": [], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Avatar and AvatarGroupCount children rendered in an overlapping row." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged with the negative-space group classes and child avatar rings." } ] }, { "id": "avatar-group-count", "title": "AvatarGroupCount", "summary": "Overflow count part that follows the largest avatar size used in the group.", "notes": [], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Count label or icon shown after the visible avatars." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged with the muted circular count chip classes." } ] } ], "dependencies": [ "@base-ui/react", "@radix-ui/react-slot", "motion" ] }, { "slug": "badge", "name": "Badge", "href": "/display-and-content/badge", "url": "https://iconiqui.com/display-and-content/badge", "installPackage": "@iconiq/badge", "installCommand": "npx shadcn@latest add @iconiq/badge", "registryPath": "badge.json", "registryUrl": "https://iconiqui.com/r/badge.json", "summary": "Compact label pill with tinted fills, a shimmer-enabled default variant, a quieter dot variant, semantic color aliases, and optional icon or dismiss controls.", "apiSections": [ { "id": "badge", "title": "Badge", "summary": "Compact label pill with tinted fills, a shimmer-enabled default variant, a quieter dot variant, semantic color aliases, and optional icon or dismiss controls.", "notes": [ "The root renders `data-slot=\"badge\"` and spreads remaining span props, so ids, data attributes, and click handlers can be attached directly.", "Interactive badges with `onClick` receive `role=\"button\"`, `tabIndex={0}`, and Enter/Space keyboard activation. The dismiss button is a separate focusable control.", "When `asChild` is true, badge styles merge onto the single child element without shimmer, dot, icon, or dismiss layers.", "`icon` and `onDismiss` are mutually exclusive on the default variant.", "Use Badge for inline labels and chips. Use Status Dot for deployment-style ripple states. Use AvatarBadge for avatar presence dots.", "Install path is `components/ui/badge.tsx` with named and default `Badge` exports. Requires `@/lib/utils` (`cn`)." ], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Badge content rendered above the optional shimmer layer so labels stay readable while the default variant animates." }, { "name": "className", "type": "string", "defaultValue": "\"\"", "required": false, "description": "Appended directly to the root badge element. Useful for radius, spacing, or local border overrides." }, { "name": "variant", "type": "\"default\" | \"dot\"", "defaultValue": "\"default\"", "required": false, "description": "Chooses between the animated filled badge and the quieter outlined badge with a leading status dot." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "defaultValue": "\"md\"", "required": false, "description": "Controls height, horizontal padding, gap, and label size for denser or roomier badge treatments." }, { "name": "color", "type": "BadgeColorProp", "defaultValue": "\"gray\"", "required": false, "description": "Picks a preset palette token or semantic alias (`success`, `warning`, `error`, `info`). Each token sets matched background and foreground tones for light and dark mode." }, { "name": "icon", "type": "ReactNode", "defaultValue": "", "required": false, "description": "Optional leading icon rendered before the label on the default variant only. Ignored when `variant=\"dot\"` or when `onDismiss` is provided." }, { "name": "onDismiss", "type": "() => void", "defaultValue": "", "required": false, "description": "When provided on the default variant, renders a dismiss button after the label for removable filter chips. Ignored when `variant=\"dot\"` or when `icon` is provided." }, { "name": "dismissLabel", "type": "string", "defaultValue": "\"Remove\"", "required": false, "description": "Accessible label for the dismiss button when `onDismiss` is enabled." }, { "name": "animate", "type": "boolean", "defaultValue": "true", "required": false, "description": "Controls the default variant mount fade/scale entrance and the dot variant status pulse. Use with `shimmer={false}` on the default variant when you want a one-time entrance without the looping sweep. Automatically disabled when `prefers-reduced-motion` is set." }, { "name": "shimmer", "type": "boolean", "defaultValue": "true", "required": false, "description": "Controls the default variant shimmer sweep independently of the mount entrance. Automatically disabled when `prefers-reduced-motion` is set." }, { "name": "asChild", "type": "boolean", "defaultValue": "false", "required": false, "description": "Merges badge styles onto the child element, such as an anchor, via Radix Slot." }, { "name": "waveColor", "type": "string", "defaultValue": "", "required": false, "description": "Optional shimmer midpoint override for the default variant. When omitted, the sweep derives a subtle tone from the current text color." } ] }, { "id": "badge-variants", "title": "badgeVariants", "summary": "CVA recipe exported alongside Badge for reusing badge layout, color tokens, and interactive focus styles on custom elements.", "notes": [], "fields": [ { "name": "variant", "type": "\"default\" | \"dot\"", "defaultValue": "\"default\"", "required": false, "description": "Chooses between the filled badge and dot badge recipes." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "defaultValue": "\"md\"", "required": false, "description": "Controls height, padding, gap, and label size." }, { "name": "color", "type": "BadgeColor", "defaultValue": "", "required": false, "description": "Resolved palette token passed to `getBadgeColorVariables()` when reusing badge color tokens outside the component." }, { "name": "interactive", "type": "boolean", "defaultValue": "false", "required": false, "description": "Adds pointer cursor and focus ring styles for clickable badge roots." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Optional classes merged after the generated recipe classes." } ] }, { "id": "badge-colors", "title": "badgeColors", "summary": "Preset color hex map used by Badge tone generation for palette-consistent fills and dot treatments.", "notes": [ "Use the exported `BadgeColor`, `BadgeSemanticColor`, and `BadgeColorProp` types for compile-time checks.", "`badgeSemanticColors` maps `success`, `warning`, `error`, and `info` to palette tokens. Prefer the semantic names in UI pickers instead of their duplicate palette entries (`green`, `amber`, `red`, `blue`).", "`getBadgePlaygroundColorOptions()` filters palette colors that already have a semantic alias.", "`resolveBadgeColor()` normalizes semantic aliases before styling.", "`getBadgeColorVariables()` sets `--badge-bg`, `--badge-fg`, `--badge-dot`, and `--badge-border` inline so palette tones apply reliably in light and dark mode." ], "fields": [ { "name": "keys", "type": "BadgeColor", "defaultValue": "", "required": false, "description": "Named palette tokens such as gray, blue, green, amber, red, and purple." } ] }, { "id": "badge-visuals", "title": "Visual behavior", "summary": "The default variant keeps the spring-in shimmer treatment, while the dot variant adds a subtle status pulse. Motion respects reduced-motion preferences.", "notes": [ "The default badge fades and scales from 0.95 to 1 on mount over 0.3 seconds when `animate` is true.", "Its shimmer travels from left to right over 2 seconds, waits 1.5 seconds, then repeats indefinitely when `shimmer` is true.", "The dot variant omits the shimmer layer, sizes its leading status dot to match the chosen badge size, and gives it a gentle repeating blink.", "All entrance, shimmer, and dot pulse animations are skipped when `prefers-reduced-motion` is enabled." ], "fields": [] } ], "dependencies": [ "motion", "class-variance-authority", "@radix-ui/react-slot" ] }, { "slug": "calendar", "name": "Calendar", "href": "/display-and-content/calendar", "url": "https://iconiqui.com/display-and-content/calendar", "installPackage": "@iconiq/calendar", "installCommand": "npx shadcn@latest add @iconiq/calendar", "registryPath": "calendar.json", "registryUrl": "https://iconiqui.com/r/calendar.json", "summary": "Animated monthly calendar with single-day or range selection, bounds, modifiers, locale-aware labels, and direct month/year picking.", "apiSections": [ { "id": "calendar", "title": "Calendar", "summary": "Animated monthly calendar with single-day or range selection, bounds, modifiers, locale-aware labels, and direct month/year picking.", "notes": [ "Controlled mode: pass selected/month or range/month and respond to the matching change handlers.", "Uncontrolled mode: omit the controlled value props and optionally seed with defaultSelected, defaultRange, or defaultMonth.", "Pair with the date-picker registry entry when you need a collapsible trigger instead of an always-visible grid.", "Pass stable disabled and modifiers callbacks in production to avoid unnecessary focus resets." ], "fields": [ { "name": "mode", "type": "\"single\" | \"range\"", "defaultValue": "\"single\"", "required": false, "description": "Selection model. Use single for one date or range for start/end selection." }, { "name": "selected", "type": "Date | null", "defaultValue": "", "required": false, "description": "Controlled selected day for single mode. Pass null to clear the highlight." }, { "name": "defaultSelected", "type": "Date | null", "defaultValue": "", "required": false, "description": "Initial selected day for uncontrolled single mode when selected is not provided." }, { "name": "onSelect", "type": "(date: Date | null) => void", "defaultValue": "", "required": false, "description": "Called when the user picks a day in single mode, including visible outside-month days." }, { "name": "range", "type": "CalendarRange", "defaultValue": "", "required": false, "description": "Controlled range for range mode. Shape is `{ from?: Date; to?: Date }`." }, { "name": "defaultRange", "type": "CalendarRange", "defaultValue": "", "required": false, "description": "Initial range for uncontrolled range mode." }, { "name": "onRangeSelect", "type": "(range: CalendarRange) => void", "defaultValue": "", "required": false, "description": "Called when the user updates the range in range mode." }, { "name": "month", "type": "Date", "defaultValue": "", "required": false, "description": "Controlled visible month. Prev/next, outside-day, and month/year picker navigation requests flow through onMonthChange." }, { "name": "defaultMonth", "type": "Date", "defaultValue": "", "required": false, "description": "Initial visible month for uncontrolled usage when month is not provided." }, { "name": "onMonthChange", "type": "(month: Date) => void", "defaultValue": "", "required": false, "description": "Called whenever the user navigates with prev/next, an outside day, or the month/year picker." }, { "name": "disabled", "type": "(date: Date) => boolean", "defaultValue": "", "required": false, "description": "Marks dates as non-interactive in addition to minDate/maxDate bounds." }, { "name": "minDate", "type": "Date", "defaultValue": "", "required": false, "description": "Earliest selectable day. Also disables month navigation into fully out-of-range months." }, { "name": "maxDate", "type": "Date", "defaultValue": "", "required": false, "description": "Latest selectable day. Also disables month navigation into fully out-of-range months." }, { "name": "locale", "type": "Locale", "defaultValue": "", "required": false, "description": "Optional date-fns locale used for month labels, weekday headers, and spoken date labels." }, { "name": "labels", "type": "Partial", "defaultValue": "", "required": false, "description": "Override built-in English UI and accessibility strings such as Today, Clear, and picker labels." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "defaultValue": "", "required": false, "description": "Controls the overall calendar scale, including the card width, spacing, nav controls, weekday row, and day cell sizing. Defaults to sm." }, { "name": "weekStartsOn", "type": "0 | 1 | 2 | 3 | 4 | 5 | 6", "defaultValue": "", "required": false, "description": "Overrides the first day of the week for both the weekday header and rendered month grid." }, { "name": "minYear", "type": "number", "defaultValue": "", "required": false, "description": "Optional lower bound for selectable years in the year picker." }, { "name": "maxYear", "type": "number", "defaultValue": "", "required": false, "description": "Optional upper bound for selectable years in the year picker." }, { "name": "showOutsideDays", "type": "boolean", "defaultValue": "true", "required": false, "description": "Whether leading and trailing days from adjacent months are rendered in the grid." }, { "name": "fixedWeeks", "type": "boolean", "defaultValue": "false", "required": false, "description": "Pads the month grid to six weeks for consistent height. Only applies when showOutsideDays is true." }, { "name": "modifiers", "type": "Record boolean>", "defaultValue": "", "required": false, "description": "Named matchers that render marker dots under matching days." }, { "name": "modifierLabels", "type": "Record", "defaultValue": "", "required": false, "description": "Human-readable names for modifier keys, appended to spoken day labels." }, { "name": "id", "type": "string", "defaultValue": "", "required": false, "description": "Optional root id used for heading and live-region relationships." }, { "name": "name", "type": "string", "defaultValue": "", "required": false, "description": "Optional native form field name. Renders a hidden input in single mode." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Optional class names applied to the root surface." } ] }, { "id": "calendar-grid", "title": "Date math and layout behavior", "summary": "The grid is rebuilt with date-fns whenever the visible month changes.", "notes": [ "The rendered range runs from startOfWeek(startOfMonth(currentMonth)) through endOfWeek(endOfMonth(currentMonth)). fixedWeeks pads the grid to six rows only when showOutsideDays is enabled.", "Days outside the active month remain visible by default and can still be selected. Choosing one switches the visible month and selects that day, unless the date is unavailable.", "Weekday headers and the grid start day follow the provided locale and weekStartsOn settings.", "Selected days are highlighted even when they appear as outside-month cells in the current grid." ], "fields": [] }, { "id": "calendar-motion-a11y", "title": "Motion and accessibility", "summary": "Motion, keyboard support, and screen-reader semantics are built into the grid and picker overlays.", "notes": [ "The root uses role=application with a role=grid date table, aria-selected day buttons, and a polite live selection summary.", "Keyboard users can move through days with arrow keys, Home/End, PageUp/PageDown, and select with Enter or Space.", "Month and year overlays trap focus, support arrow-key grid navigation, and return focus to the trigger on Escape.", "Theme colors come from CSS variables, so the surface follows light/dark mode without client-side palette hydration.", "Animations respect prefers-reduced-motion through useReducedMotion()." ], "fields": [] } ], "dependencies": [ "motion", "lucide-react", "date-fns" ] }, { "slug": "card", "name": "Card", "href": "/display-and-content/card", "url": "https://iconiqui.com/display-and-content/card", "installPackage": "@iconiq/card", "installCommand": "npx shadcn@latest add @iconiq/card", "registryPath": "card.json", "registryUrl": "https://iconiqui.com/r/card.json", "summary": "Compound card surface with slot-based sections, optional interactive lift, and layout-aware motion between content states.", "apiSections": [ { "id": "card", "title": "Card", "summary": "Compound card surface with slot-based sections, optional interactive lift, and layout-aware motion between content states.", "notes": [ "The root forwards standard div props, so you can attach ids, aria attributes, data attributes, and event handlers directly.", "Cards with a direct leading image automatically remove top padding and inherit the root radius on the first and last image edges.", "Footer-aware padding is handled by the card itself, so adding CardFooter trims the bottom padding without extra wrapper logic.", "For whole-card navigation, prefer asChild with a single anchor or button child instead of nesting interactive controls inside a second clickable wrapper.", "Keep nested buttons or links inside a non-wrapped card shell to avoid invalid interactive nesting." ], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Compose CardHeader, CardContent, CardFooter, media, or custom blocks inside the shared card shell." }, { "name": "interactive", "type": "boolean", "defaultValue": "false", "required": false, "description": "Enables the restrained hover lift and stronger surface response intended for clickable or focusable cards." }, { "name": "asChild", "type": "boolean", "defaultValue": "false", "required": false, "description": "Merges the card surface classes and interaction handlers onto the single child element, which is useful for link or button cards." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the root card surface for local spacing, border, or layout adjustments without replacing the slot API." }, { "name": "onHoverStart", "type": "() => void", "defaultValue": "", "required": false, "description": "Called when interactive hover feedback begins from pointer, focus, or keyboard focus within the card." }, { "name": "onHoverEnd", "type": "() => void", "defaultValue": "", "required": false, "description": "Called when interactive hover feedback ends after pointer leave and focus exits the card." } ] }, { "id": "card-header", "title": "CardHeader", "summary": "Top header grid for title, description, and an optional trailing CardAction.", "notes": [ "The header uses a compact grid so status pills and actions align naturally without extra wrappers." ], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Compose CardTitle, CardDescription, and optional CardAction inside the header grid." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the header grid wrapper." } ] }, { "id": "card-title", "title": "CardTitle", "summary": "Primary heading slot with default title typography.", "notes": [], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Heading content for the card. Works with links, badges, metrics, or richer inline content." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged with the default title typography classes." }, { "name": "as", "type": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | \"div\" | \"span\"", "defaultValue": "\"h3\"", "required": false, "description": "Semantic heading element used for the title. Defaults to h3 for accessible card headings." } ] }, { "id": "card-description", "title": "CardDescription", "summary": "Secondary supporting copy beneath the title.", "notes": [], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Supporting description or excerpt text rendered with muted body styling." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged with the muted description typography classes." }, { "name": "as", "type": "\"p\" | \"div\" | \"span\"", "defaultValue": "\"p\"", "required": false, "description": "Semantic text element used for the description. Defaults to p for accessible supporting copy." } ] }, { "id": "card-action", "title": "CardAction", "summary": "Optional trailing action slot aligned to the top-right of CardHeader.", "notes": [], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Action content such as a menu trigger, status pill, or compact control." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged with the default action placement classes." } ] }, { "id": "card-content", "title": "CardContent", "summary": "Flexible middle section for body copy, media, stats, and custom layouts.", "notes": [], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Main card body content rendered inside the padded content slot." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged with the default horizontal padding classes." } ] }, { "id": "card-footer", "title": "CardFooter", "summary": "Bottom section for supporting actions, metadata, or contextual labels.", "notes": [ "Adding CardFooter trims the root card bottom padding automatically." ], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Footer content rendered on a quieter separated surface beneath the body." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged with the default footer surface and spacing classes." } ] }, { "id": "card-image", "title": "CardImage", "summary": "Next.js Image slot with the shared inset media frame, default fill sizing, and card-aware radius handling. Always renders next/image.", "notes": [ "CardImage always renders next/image and requires a Next.js app.", "Use CardMedia instead for video, charts, embeds, or other non-image leading media.", "Fill images default to a 16:10 aspect ratio unless you override it with className." ], "fields": [ { "name": "alt", "type": "string", "defaultValue": "", "required": true, "description": "Accessible alternative text for the image." }, { "name": "src", "type": "string", "defaultValue": "", "required": true, "description": "Image source passed through to next/image." }, { "name": "inset", "type": "boolean", "defaultValue": "true", "required": false, "description": "When true, wraps the image in the padded card media frame. Set false for edge-to-edge media." }, { "name": "fill", "type": "boolean", "defaultValue": "", "required": false, "description": "Uses fill layout when true. Defaults to fill when width and height are both omitted." }, { "name": "sizes", "type": "string", "defaultValue": "\"(max-width: 768px) 100vw, 400px\"", "required": false, "description": "Responsive sizes hint forwarded to next/image for better loading performance." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the rendered image element." } ] }, { "id": "card-media", "title": "CardMedia", "summary": "Media slot for video, charts, embeds, or other custom leading media blocks.", "notes": [ "Use CardImage for static card artwork and photos.", "Both CardImage and CardMedia use the card-image slot so the root card can trim top padding automatically." ], "fields": [ { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Non-image media content such as video, a chart container, or an embed." }, { "name": "inset", "type": "boolean", "defaultValue": "true", "required": false, "description": "When true, wraps children in the padded card media frame. Set false for edge-to-edge media." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the outer media wrapper." } ] }, { "id": "card-clickable", "title": "Clickable card recipes", "summary": "Patterns for whole-card navigation and cards that contain separate interactive controls.", "notes": [ "Whole-card link: ....", "Whole-card button: .", "Card with its own CTA: keep Card unwrapped and place buttons or links inside CardContent or CardFooter.", "Do not wrap a card that already contains buttons or links in another anchor or button via asChild." ], "fields": [] }, { "id": "card-motion", "title": "Motion and interaction model", "summary": "Layout changes are animated through Motion so expanding or swapping card content feels fluid rather than abrupt.", "notes": [ "When interactive is enabled, hover drives a spring-smoothed motion value so lift, scale, and shadow ease in and out as one fluid surface; compound slots only animate layout when content changes.", "interactive only changes the visible surface response: border, shadow, and a very small hover lift. The component does not add button semantics on its own.", "prefers-reduced-motion disables spring hover and layout transitions. Interactive cards still get border and surface feedback through CSS.", "asChild cards use CSS-based hover lift instead of spring transforms so the merged anchor or button remains the interactive root. Lift is also skipped when prefers-reduced-motion is enabled." ], "fields": [] } ], "dependencies": [ "motion", "@radix-ui/react-slot" ] }, { "slug": "carousel", "name": "Carousel", "href": "/display-and-content/carousel", "url": "https://iconiqui.com/display-and-content/carousel", "installPackage": "@iconiq/carousel", "installCommand": "npx shadcn@latest add @iconiq/carousel", "registryPath": "carousel.json", "registryUrl": "https://iconiqui.com/r/carousel.json", "summary": "Root carousel region wired to Embla. Exposes scroll state through `useCarousel`, supports responsive nav placement, optional autoplay, and keyboard navigation for horizontal and vertical layouts.", "apiSections": [ { "id": "carousel", "title": "Carousel", "summary": "Root carousel region wired to Embla. Exposes scroll state through `useCarousel`, supports responsive nav placement, optional autoplay, and keyboard navigation for horizontal and vertical layouts.", "notes": [ "Install path is `components/ui/carousel.tsx`. Exports include `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext`, `useCarousel`, `CarouselApi`, `CarouselOptions`, and `CarouselPlugin`.", "Navigation controls are self-contained icon buttons — no separate button registry item is required.", "The root region is focusable (`tabIndex={0}`) and announces the active slide through an `aria-live` region.", "Custom aspect ratios are applied with inline `aspect-ratio` styles so Tailwind does not need safelisted arbitrary classes.", "With `navPlacement=\"outside\"` or `\"responsive\"` at `sm+`, add horizontal padding to the carousel wrapper so controls stay visible." ], "fields": [ { "name": "orientation", "type": "\"horizontal\" | \"vertical\"", "defaultValue": "horizontal", "required": false, "description": "Sets the Embla scroll axis and the spacing applied between slides." }, { "name": "aspectRatio", "type": "\"square\" | \"video\" | \"4/3\" | \"3/2\" | \"portrait\" | string", "defaultValue": "video", "required": false, "description": "Sets the slide viewport shape on `CarouselContent`. Use presets like `video` (16:9) and `square`, or pass a custom ratio string such as `21/9`." }, { "name": "navPlacement", "type": "\"outside\" | \"responsive\"", "defaultValue": "responsive", "required": false, "description": "Positions previous and next controls. `responsive` places controls below the carousel on the right on mobile and outside the track from `sm` upward." }, { "name": "autoplay", "type": "boolean | number", "defaultValue": "", "required": false, "description": "When enabled, advances slides on a timer. Pass a number for the delay in milliseconds. Pair with `opts={{ loop: true }}` for continuous playback." }, { "name": "opts", "type": "CarouselOptions", "defaultValue": "", "required": false, "description": "Forwarded Embla options such as `align`, `loop`, or `slidesToScroll`. The root merges `axis` from `orientation`." }, { "name": "plugins", "type": "CarouselPlugin", "defaultValue": "", "required": false, "description": "Optional Embla plugins passed to `useEmblaCarousel`, such as `embla-carousel-autoplay`." }, { "name": "setApi", "type": "(api: CarouselApi) => void", "defaultValue": "", "required": false, "description": "Optional callback that receives the Embla API instance after mount for external index or dot indicators." }, { "name": "aria-label", "type": "string", "defaultValue": "Carousel", "required": false, "description": "Accessible label for the root `role=\"region\"` carousel wrapper." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Optional class names merged onto the root `role=\"region\"` wrapper." } ] }, { "id": "carousel-content", "title": "CarouselContent", "summary": "Overflow-hidden viewport that hosts the Embla ref and the flex track of slides.", "notes": [], "fields": [ { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Optional class names merged onto the inner flex container that holds slides." } ] }, { "id": "carousel-item", "title": "CarouselItem", "summary": "Single slide wrapper sized to `basis-full` with directional padding between siblings. Inactive slides are marked `aria-hidden`.", "notes": [], "fields": [ { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Optional class names merged onto each slide group." } ] }, { "id": "carousel-navigation", "title": "CarouselPrevious / CarouselNext", "summary": "Self-contained icon buttons that call `scrollPrev` and `scrollNext` and disable when Embla cannot scroll further.", "notes": [], "fields": [ { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Optional class names merged onto the control for local offsets or sizing." } ] }, { "id": "use-carousel", "title": "useCarousel", "summary": "Hook for custom indicators or synced UI. Must be used inside `Carousel`.", "notes": [], "fields": [ { "name": "selectedIndex", "type": "number", "defaultValue": "", "required": false, "description": "Zero-based index of the active scroll snap." }, { "name": "scrollSnapCount", "type": "number", "defaultValue": "", "required": false, "description": "Total number of scroll snaps reported by Embla." }, { "name": "scrollTo", "type": "(index: number) => void", "defaultValue": "", "required": false, "description": "Scrolls directly to the requested snap index." }, { "name": "scrollPrev / scrollNext", "type": "() => void", "defaultValue": "", "required": false, "description": "Moves to the previous or next snap." }, { "name": "api", "type": "CarouselApi", "defaultValue": "", "required": false, "description": "Underlying Embla API instance when you need lower-level control." } ] } ], "dependencies": [ "embla-carousel-react", "lucide-react" ] }, { "slug": "charts", "name": "Charts", "href": "/display-and-content/charts", "url": "https://iconiqui.com/display-and-content/charts", "installPackage": "@iconiq/charts", "installCommand": "npx shadcn@latest add @iconiq/charts", "registryPath": "charts.json", "registryUrl": "https://iconiqui.com/r/charts.json", "summary": "Theme-aware Recharts shell that maps ChartConfig tokens to CSS variables, applies registry chart colors, and fades the surface in on mount.", "apiSections": [ { "id": "chart-container", "title": "ChartContainer", "summary": "Theme-aware Recharts shell that maps ChartConfig tokens to CSS variables, applies registry chart colors, and fades the surface in on mount.", "notes": [ "ChartContainer ships its own local --chart-1 through --chart-5 defaults, so chart installs do not need a shared theme helper.", "Pair ChartContainer with Recharts primitives and ChartTooltip / ChartLegend helpers rather than Radix UI or Base UI wrappers.", "Set accessibilityLayer on Recharts cartesian charts to improve keyboard and screen-reader support." ], "fields": [ { "name": "config", "type": "ChartConfig", "defaultValue": "", "required": true, "description": "Series labels, optional icons, and colors. Use var(--chart-1) style tokens or per-key theme overrides; scoped --color-{key} variables are generated for this chart instance." }, { "name": "children", "type": "ReactNode", "defaultValue": "", "required": true, "description": "Recharts chart markup, usually a BarChart, LineChart, AreaChart, PieChart, RadarChart, or RadialBarChart rendered inside ResponsiveContainer." }, { "name": "id", "type": "string", "defaultValue": "", "required": false, "description": "Optional stable id for the generated data-chart attribute and scoped CSS variables." }, { "name": "seriesCount", "type": "number", "defaultValue": "", "required": false, "description": "Overrides inferred series count for animation timing when ChartConfig keys do not match plotted series." }, { "name": "initialDimension", "type": "{ width: number; height: number }", "defaultValue": "", "required": false, "description": "Optional fallback size for ResponsiveContainer before the first measure. By default the chart fills its parent with a debounced resize handler." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the chart shell alongside the chart component's local theme tokens." } ] }, { "id": "chart-bar", "title": "ChartBar", "summary": "Thin Recharts Bar wrapper with restrained ease-out growth timing tuned for the Iconiq motion profile.", "notes": [ "Use fill=\"var(--color-desktop)\" (or your config key) so bars pick up ChartConfig colors.", "Series growth runs once on first paint; resize uses a debounced container and skips repeat animations so narrowing the viewport stays stable." ], "fields": [ { "name": "seriesIndex", "type": "number", "defaultValue": "0", "required": false, "description": "Offsets bar growth start time for multi-series charts so each series eases in with a short stagger." }, { "name": "...props", "type": "Recharts Bar props", "defaultValue": "", "required": false, "description": "Forwards the full Bar API. animationDuration (~480ms), ease-out easing, and isAnimationActive inherit calm defaults unless you override them." } ] }, { "id": "chart-line", "title": "ChartLine", "summary": "Recharts Line wrapper that shares the same ease-out timing and stagger defaults as ChartBar.", "notes": [], "fields": [ { "name": "seriesIndex", "type": "number", "defaultValue": "0", "required": false, "description": "Offsets line draw start time for multi-series charts so each stroke eases in with a short stagger." }, { "name": "...props", "type": "Recharts Line props", "defaultValue": "", "required": false, "description": "Forwards the full Line API. animationDuration, easing, and isAnimationActive inherit calm defaults unless you override them." } ] }, { "id": "chart-area", "title": "ChartArea", "summary": "Recharts Area wrapper that shares the same ease-out timing and stagger defaults as ChartBar.", "notes": [], "fields": [ { "name": "seriesIndex", "type": "number", "defaultValue": "0", "required": false, "description": "Offsets area reveal start time for multi-series charts so each fill eases in with a short stagger." }, { "name": "...props", "type": "Recharts Area props", "defaultValue": "", "required": false, "description": "Forwards the full Area API. animationDuration, easing, and isAnimationActive inherit calm defaults unless you override them." } ] }, { "id": "chart-tooltip", "title": "ChartTooltip", "summary": "Recharts tooltip primitive that defaults to ChartTooltipContent when content is omitted.", "notes": [], "fields": [ { "name": "content", "type": "ReactNode | ComponentType", "defaultValue": "", "required": false, "description": "Tooltip renderer. Defaults to ChartTooltipContent when omitted." }, { "name": "cursor", "type": "boolean | object", "defaultValue": "", "required": false, "description": "Recharts cursor configuration for hover feedback." } ] }, { "id": "chart-tooltip-content", "title": "ChartTooltipContent", "summary": "Styled tooltip content shell with a calm fade entrance and dashed, dot, or line indicators.", "notes": [], "fields": [ { "name": "indicator", "type": "\"dot\" | \"line\" | \"dashed\"", "defaultValue": "\"dot\"", "required": false, "description": "Marker style rendered beside each tooltip row." }, { "name": "hideLabel", "type": "boolean", "defaultValue": "false", "required": false, "description": "Suppresses the formatted label block above the value rows." }, { "name": "hideIndicator", "type": "boolean", "defaultValue": "false", "required": false, "description": "Hides the color marker when you only want text values." }, { "name": "nameKey", "type": "string", "defaultValue": "", "required": false, "description": "Payload key used to resolve ChartConfig labels and colors for each tooltip row." }, { "name": "labelKey", "type": "string", "defaultValue": "", "required": false, "description": "Payload key used to resolve the tooltip label row from ChartConfig." }, { "name": "label", "type": "string", "defaultValue": "", "required": false, "description": "Optional label key override when you want the tooltip header to read from ChartConfig directly." }, { "name": "labelClassName", "type": "string", "defaultValue": "", "required": false, "description": "Classes merged onto the tooltip label row." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Classes merged onto the tooltip shell." }, { "name": "color", "type": "string", "defaultValue": "", "required": false, "description": "Optional shared indicator color override for every tooltip row." }, { "name": "labelFormatter", "type": "(value, payload) => ReactNode", "defaultValue": "", "required": false, "description": "Custom formatter for the tooltip label row." }, { "name": "formatter", "type": "Recharts formatter", "defaultValue": "", "required": false, "description": "Optional per-row formatter; when omitted, the default label and value layout is used." } ] }, { "id": "chart-legend", "title": "ChartLegend", "summary": "Recharts legend primitive that defaults to ChartLegendContent when content is omitted.", "notes": [], "fields": [ { "name": "content", "type": "ReactNode | ComponentType", "defaultValue": "", "required": false, "description": "Legend renderer. Defaults to ChartLegendContent when omitted." }, { "name": "verticalAlign", "type": "\"top\" | \"bottom\"", "defaultValue": "\"bottom\"", "required": false, "description": "Adjusts legend spacing relative to the chart." } ] }, { "id": "chart-legend-content", "title": "ChartLegendContent", "summary": "Legend content shell with a quiet fade-and-rise entrance that matches the chart surface motion.", "notes": [], "fields": [ { "name": "hideIcon", "type": "boolean", "defaultValue": "false", "required": false, "description": "Hides config icons and falls back to the color swatch derived from the series color." }, { "name": "nameKey", "type": "string", "defaultValue": "", "required": false, "description": "Payload key used to resolve ChartConfig labels and swatch colors for each legend row." }, { "name": "verticalAlign", "type": "\"top\" | \"bottom\"", "defaultValue": "\"bottom\"", "required": false, "description": "Adjusts legend spacing relative to the chart." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Classes merged onto the legend shell." } ] }, { "id": "chart-empty-state", "title": "ChartEmptyState", "summary": "Centered empty placeholder for charts with no data yet or while a dataset is loading.", "notes": [ "Render ChartEmptyState inside ChartContainer when your query returns zero rows or while async data is still loading." ], "fields": [ { "name": "label", "type": "ReactNode", "defaultValue": "\"No data available\"", "required": false, "description": "Primary empty-state message." }, { "name": "description", "type": "ReactNode", "defaultValue": "", "required": false, "description": "Optional supporting copy beneath the label." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Classes merged onto the empty-state shell." } ] }, { "id": "use-chart", "title": "useChart", "summary": "Reads ChartContainer context, including ChartConfig and whether the initial series animation is still active.", "notes": [ "Use this hook inside custom tooltip, legend, or annotation content rendered within ChartContainer." ], "fields": [ { "name": "config", "type": "ChartConfig", "defaultValue": "", "required": false, "description": "The ChartConfig passed to ChartContainer." }, { "name": "chartAnimationActive", "type": "boolean", "defaultValue": "", "required": false, "description": "True during the first ease-out series animation window, then false after resize-safe timing completes." } ] } ], "dependencies": [ "recharts", "motion" ] }, { "slug": "date-picker", "name": "Date Picker", "href": "/display-and-content/date-picker", "url": "https://iconiqui.com/display-and-content/date-picker", "installPackage": "@iconiq/date-picker", "installCommand": "npx shadcn@latest add @iconiq/date-picker", "registryPath": "date-picker.json", "registryUrl": "https://iconiqui.com/r/date-picker.json", "summary": "Collapsible date field with a read-only Base UI input trigger and a portaled Iconiq Calendar panel.", "apiSections": [ { "id": "date-picker", "title": "DatePicker", "summary": "Collapsible date field with a read-only Base UI input trigger and a portaled Iconiq Calendar panel.", "notes": [ "Also exported as `AnimatedDatePicker` for backwards compatibility.", "The trigger formats the selected date with `dateFormat` and toggles the portaled panel open and closed.", "Choosing a date closes the panel by default while keeping the visible month aligned with the selected value.", "Click outside or press Escape to close the panel. Focus returns to the trigger and the embedded Calendar stays mounted after the first open to avoid repeat entrance motion.", "Install the `calendar` registry entry alongside `date-picker` so `@/components/ui/calendar` resolves in consumer apps." ], "fields": [ { "name": "value", "type": "Date | null", "defaultValue": "", "required": false, "description": "Controlled selected date. When provided, the trigger and embedded Calendar both reflect this value." }, { "name": "defaultValue", "type": "Date | null", "defaultValue": "null", "required": false, "description": "Initial selected date for uncontrolled usage when `value` is omitted." }, { "name": "placeholder", "type": "string", "defaultValue": "Select a date", "required": false, "description": "Copy shown in the trigger when no date is selected." }, { "name": "onChange", "type": "(date: Date | null) => void", "defaultValue": "", "required": false, "description": "Called when the user picks or clears a date from the embedded Calendar or clear control." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Optional class names applied to the outer wrapper." }, { "name": "defaultOpen", "type": "boolean", "defaultValue": "false", "required": false, "description": "Whether the Calendar panel starts expanded on first render." }, { "name": "open", "type": "boolean", "defaultValue": "", "required": false, "description": "Controlled open state for the Calendar panel. Pair with `onOpenChange`." }, { "name": "onOpenChange", "type": "(open: boolean) => void", "defaultValue": "", "required": false, "description": "Called when the panel opens or closes from the trigger, selection, Escape, or outside click." }, { "name": "disabled", "type": "boolean", "defaultValue": "false", "required": false, "description": "Disables the trigger and prevents the panel from opening." }, { "name": "clearable", "type": "boolean", "defaultValue": "false", "required": false, "description": "Shows a clear button when a date is selected so users can reset to `null`." }, { "name": "closeOnSelect", "type": "boolean", "defaultValue": "true", "required": false, "description": "Whether picking a date closes the panel automatically." }, { "name": "dateFormat", "type": "string", "defaultValue": "EEE, MMM d, yyyy", "required": false, "description": "date-fns format string for the trigger label. Uses `calendarProps.locale` when provided." }, { "name": "name", "type": "string", "defaultValue": "", "required": false, "description": "Optional form field name. Renders a hidden input with the selected ISO date." }, { "name": "id", "type": "string", "defaultValue": "", "required": false, "description": "Optional id applied to the trigger button." }, { "name": "aria-invalid", "type": "boolean", "defaultValue": "", "required": false, "description": "Marks the trigger as invalid for assistive tech and applies error styling." }, { "name": "side", "type": "\"top\" | \"bottom\"", "defaultValue": "bottom", "required": false, "description": "Preferred panel side relative to the trigger. Flips when there is not enough space." }, { "name": "align", "type": "\"start\" | \"end\"", "defaultValue": "start", "required": false, "description": "Horizontal alignment of the portaled panel to the trigger." }, { "name": "calendarProps", "type": "Omit", "defaultValue": "", "required": false, "description": "Props forwarded to the embedded Calendar, such as size, locale, disabled, bounds, modifiers, weekStartsOn, minYear, and maxYear. Range mode is not supported on DatePicker." } ] } ], "dependencies": [ "@base-ui/react/input", "motion", "lucide-react", "date-fns" ] }, { "slug": "favicon-badge", "name": "Favicon Badge", "href": "/display-and-content/favicon-badge", "url": "https://iconiqui.com/display-and-content/favicon-badge", "installPackage": "@iconiq/favicon-badge", "installCommand": "npx shadcn@latest add @iconiq/favicon-badge", "registryPath": "favicon-badge.json", "registryUrl": "https://iconiqui.com/r/favicon-badge.json", "summary": "Inline circular badge that resolves a website favicon from a domain or URL, with an optional text label and spring entrance animation.", "apiSections": [ { "id": "favicon-badge", "title": "FaviconBadge", "summary": "Inline circular badge that resolves a website favicon from a domain or URL, with an optional text label and spring entrance animation.", "notes": [ "Extends native `span` props (`id`, `onClick`, `data-*`, and other `aria-*` attributes) via prop spreading on the root.", "Favicons are resolved from Google and DuckDuckGo icon services after `extractDomain` normalizes the `website` value.", "While resolving, the badge shows a pulsing skeleton and sets `aria-busy` on the root. Failed resolution uses a muted globe with a destructive-tinted border.", "Google placeholder icons (16×16 defaults) are skipped automatically before falling back to the next provider.", "Favicon images use `referrerPolicy=\"no-referrer\"` and a single in-DOM `` load path to avoid duplicate network requests.", "When `label` is omitted, the root uses `role=\"img\"` with an `aria-label` derived from the label, domain, or raw `website` value.", "Exports `extractDomain`, `getFaviconCandidates`, `getFaviconUrl`, `isLikelyDefaultFavicon`, and `FaviconBadgeSize` for reuse in search fields or attribution rows.", "Install path is `components/ui/favicon-badge.tsx` with named and default `FaviconBadge` exports. Requires `@/lib/utils` (`cn`).", "External favicon requests require `img-src` allowances for `https://www.google.com` and `https://icons.duckduckgo.com` unless `faviconUrl` is used." ], "fields": [ { "name": "website", "type": "string", "defaultValue": "", "required": true, "description": "Domain or full URL used to resolve the favicon. Values such as `iconiqui.com` or `https://www.iconiqui.com` are normalized to a hostname." }, { "name": "label", "type": "string", "defaultValue": "", "required": false, "description": "Optional label rendered beside the circular favicon badge. When omitted, only the badge is shown and the domain is exposed to screen readers." }, { "name": "faviconUrl", "type": "string", "defaultValue": "", "required": false, "description": "Optional favicon URL that bypasses Google and DuckDuckGo resolution. Use for self-hosted icons or strict CSP environments." }, { "name": "faviconSize", "type": "16 | 32 | 64 | 128", "defaultValue": "64", "required": false, "description": "Pixel size requested from Google's favicon service. Higher values can improve clarity on retina displays." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "defaultValue": "\"md\"", "required": false, "description": "Visual scale for the circular favicon badge container. Label text scales with size: `text-sm` on small, `text-base` on medium, and `text-lg` on large." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the root inline-flex wrapper." }, { "name": "badgeClassName", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the circular favicon container for local border, background, or sizing overrides." }, { "name": "labelClassName", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the optional label when `label` is provided." }, { "name": "onFaviconLoad", "type": "(url: string) => void", "defaultValue": "", "required": false, "description": "Called after a favicon URL resolves successfully, including when `faviconUrl` is provided." }, { "name": "onFaviconError", "type": "() => void", "defaultValue": "", "required": false, "description": "Called when every provider fails or an override URL fails to load." } ] } ], "dependencies": [ "motion", "lucide-react" ] }, { "slug": "marker", "name": "Marker", "href": "/display-and-content/marker", "url": "https://iconiqui.com/display-and-content/marker", "installPackage": "@iconiq/marker", "installCommand": "npx shadcn@latest add @iconiq/marker", "registryPath": "marker.json", "registryUrl": "https://iconiqui.com/r/marker.json", "summary": "Hand-drawn text annotations — wavy, circle, highlight, underline, and more — that draw themselves in like ink as they scroll into view, with an optional animate prop for a fully static render.", "apiSections": [], "dependencies": [ "motion" ] }, { "slug": "progress", "name": "Progress", "href": "/display-and-content/progress", "url": "https://iconiqui.com/display-and-content/progress", "installPackage": "@iconiq/progress", "installCommand": "npx shadcn@latest add @iconiq/progress", "registryPath": "progress.json", "registryUrl": "https://iconiqui.com/r/progress.json", "summary": "Determinate and indeterminate progress—with subtle motion.", "apiSections": [ { "id": "progress", "title": "Progress", "summary": "Determinate and indeterminate progress—with subtle motion.", "notes": [ "The component clamps numeric values into the min/max range before calculating the fill width.", "The visible value readout animates from the same motion value as the fill width, so the text and the bar stay visually locked together while values change.", "There is no controlled versus uncontrolled split here; value is simply rendered as the current state of the task.", "Helper copy is linked to the progressbar through aria-describedby on both Radix and Base UI installs." ], "fields": [ { "name": "value", "type": "number | null", "defaultValue": "0", "required": false, "description": "Current progress value. Pass null to switch into the indeterminate motion state instead of rendering a measured fill width." }, { "name": "min", "type": "number", "defaultValue": "0", "required": false, "description": "Lower bound used to normalize the fill width and the visible value text." }, { "name": "max", "type": "number", "defaultValue": "100", "required": false, "description": "Upper bound used to normalize the fill width and the visible value text." }, { "name": "label", "type": "string", "defaultValue": "", "required": false, "description": "Optional title rendered above the bar and linked to the progress semantics when present." }, { "name": "helper", "type": "string", "defaultValue": "", "required": false, "description": "Optional supporting copy rendered near the label for extra task context. When omitted, the header collapses down to just the label and trailing value readout." }, { "name": "showValue", "type": "boolean", "defaultValue": "true", "required": false, "description": "Controls whether the trailing inline readout with the live formatted value or indeterminate label is shown." }, { "name": "formatValue", "type": "(value: number, percent: number) => string", "defaultValue": "", "required": false, "description": "Optional formatter for the visible value readout. Receives the current normalized value and percent so you can render units, fractions, or custom labels." }, { "name": "getValueLabel", "type": "(value: number, percent: number) => string", "defaultValue": "", "required": false, "description": "Optional formatter for screen-reader announcements when the accessible text should be more explicit than the visible readout." }, { "name": "indeterminateLabel", "type": "string", "defaultValue": "\"In progress\"", "required": false, "description": "Text used for the visible value readout and accessible status when value is null." }, { "name": "ariaLabel", "type": "string", "defaultValue": "", "required": false, "description": "Accessible name used when no visible label is rendered. When omitted, unlabeled installs fall back to a generic Progress label." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the root wrapper so you can control width, spacing, or placement in your layout." }, { "name": "variant", "type": "\"default\" | \"circular\"", "defaultValue": "\"default\"", "required": false, "description": "Linear bar (default) or circular gauge layout with a dual-stroke ring, 5% gap, and CSS-smoothed arc transitions. Circular mode renders the value readout centered inside the ring." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "defaultValue": "\"md\"", "required": false, "description": "Track height preset for the default bar, or ring diameter preset for the circular variant." }, { "name": "tone", "type": "\"default\" | \"brand\" | \"destructive\" | \"success\"", "defaultValue": "\"default\"", "required": false, "description": "Fill color preset for neutral, brand, destructive, or success emphasis." }, { "name": "trackClassName", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the track element for custom track styling." }, { "name": "indicatorClassName", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the fill element for custom indicator styling." }, { "name": "headerClassName", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the label, helper, and value readout row above the track." } ] }, { "id": "progress-motion", "title": "Motion and semantics", "summary": "Headless progress semantics from the provider primitive with a spring-smoothed fill and restrained indeterminate motion layered on top.", "notes": [ "Determinate mode uses a spring-smoothed width animation instead of a hard width jump, which keeps status updates feeling more fluid when values change rapidly.", "Indeterminate mode uses one minimal left-to-right flow band with a soft fade at the start and end of each pass, so the restart stays visually quiet." ], "fields": [] } ], "dependencies": [ "@radix-ui/react-progress", "motion" ] }, { "slug": "rating", "name": "Rating", "href": "/display-and-content/rating", "url": "https://iconiqui.com/display-and-content/rating", "installPackage": "@iconiq/rating", "installCommand": "npx shadcn@latest add @iconiq/rating", "registryPath": "rating.json", "registryUrl": "https://iconiqui.com/r/rating.json", "summary": "Compound star rating built from Rating and RatingButton — hover to preview, click or use arrow keys to set the value, with configurable size on the root, a springy scale pop, and color fade that ripples across the stars.", "apiSections": [], "dependencies": [ "@radix-ui/react-use-controllable-state", "motion" ] }, { "slug": "rolling-digits", "name": "Rolling Digits", "href": "/display-and-content/rolling-digits", "url": "https://iconiqui.com/display-and-content/rolling-digits", "installPackage": "@iconiq/rolling-digits", "installCommand": "npx shadcn@latest add @iconiq/rolling-digits", "registryPath": "rolling-digits.json", "registryUrl": "https://iconiqui.com/r/rolling-digits.json", "summary": "Inline animated counter that swaps digits with spring-driven transform, opacity, and vertical motion while exiting the previous character.", "apiSections": [ { "id": "rolling-digits", "title": "RollingDigits", "summary": "Inline animated counter that swaps digits with spring-driven transform, opacity, and vertical motion while exiting the previous character.", "notes": [ "Export `RollingDigitsText` when you already have a formatted string such as `12:34:56`.", "Non-digit characters from locale separators or custom formatters render as static spans and do not animate.", "The visual layer is `aria-hidden`; screen readers receive the formatted number through an `sr-only` span with `aria-live`.", "When `startOnView` is enabled, the ticker displays zero until the container crosses the viewport threshold (`once: true`, `amount: 0.6`).", "Digit positions use right-aligned stable keys so rolls stay tied to place value when separators appear.", "Digit rolls use transform and opacity only so Safari and other WebKit browsers avoid filter-blur compositing glitches.", "Layer symbols such as `%` or `$` beside the component in your layout, or include them through `format`." ], "fields": [ { "name": "value", "type": "number", "defaultValue": "", "required": true, "description": "Target number to display. The component rounds to the nearest integer before formatting." }, { "name": "pad", "type": "number", "defaultValue": "", "required": false, "description": "Minimum digit count. Applied with `padStart` for plain numbers, or through `minimumIntegerDigits` when `locale` is enabled." }, { "name": "animationDelay", "type": "number", "defaultValue": "80", "required": false, "description": "Milliseconds between queued value steps when `value` changes faster than the animation can finish." }, { "name": "stagger", "type": "number", "defaultValue": "", "required": false, "description": "Deprecated. Seconds between queued steps. Use `animationDelay` in milliseconds instead." }, { "name": "coalesceUpdates", "type": "boolean", "defaultValue": "false", "required": false, "description": "When true, rapid `value` updates replace the pending queue with the latest value instead of stepping through every intermediate update." }, { "name": "onAnimationComplete", "type": "() => void", "defaultValue": "", "required": false, "description": "Called when the displayed value catches up to the latest `value` prop." }, { "name": "ariaLive", "type": "boolean | \"polite\" | \"assertive\" | \"off\"", "defaultValue": "true", "required": false, "description": "Controls `aria-live` on the screen-reader layer. `true` maps to `polite`; `false` and `off` disable announcements." }, { "name": "startOnView", "type": "boolean", "defaultValue": "true", "required": false, "description": "When true, playback waits until the component enters the viewport once before animating from zero." }, { "name": "locale", "type": "true | string | Intl.NumberFormatOptions", "defaultValue": "", "required": false, "description": "Locale formatting. `locale` uses the runtime default locale, a string sets the locale tag, and an object is passed to `Intl.NumberFormat`. When combined with `pad`, padding is applied through `minimumIntegerDigits`." }, { "name": "format", "type": "(value: number) => string", "defaultValue": "", "required": false, "description": "Custom formatter that runs after rounding. Overrides `locale` when both are provided." }, { "name": "gap", "type": "number", "defaultValue": "2", "required": false, "description": "Pixel gap between rendered characters in the digit row." }, { "name": "direction", "type": "\"dynamic\" | \"up\" | \"down\"", "defaultValue": "dynamic", "required": false, "description": "Controls whether incoming digits slide up or down. `dynamic` compares the previous and next digit values." }, { "name": "enterStiffness", "type": "number", "defaultValue": "170", "required": false, "description": "Spring stiffness for incoming digit motion." }, { "name": "enterDamping", "type": "number", "defaultValue": "10", "required": false, "description": "Spring damping for incoming digit motion." }, { "name": "exitStiffness", "type": "number", "defaultValue": "170", "required": false, "description": "Spring stiffness for outgoing digit motion." }, { "name": "exitDamping", "type": "number", "defaultValue": "15", "required": false, "description": "Spring damping for outgoing digit motion." }, { "name": "enterY", "type": "number", "defaultValue": "32", "required": false, "description": "Vertical offset in pixels used when a digit enters." }, { "name": "enterBlur", "type": "number", "defaultValue": "", "required": false, "description": "Deprecated. Blur is no longer applied; digit motion uses transform and opacity for Safari-safe rendering." }, { "name": "enterScale", "type": "number", "defaultValue": "0.84", "required": false, "description": "Starting scale applied when a digit enters." }, { "name": "exitScale", "type": "number", "defaultValue": "0.84", "required": false, "description": "Ending scale applied when a digit exits." }, { "name": "className", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto the outer inline-flex span that wraps the readable and visual layers." }, { "name": "digitClassName", "type": "string", "defaultValue": "", "required": false, "description": "Merged onto each animated digit cell wrapper for per-digit styling." } ] } ], "dependencies": [ "motion" ] }, { "slug": "skeleton", "name": "Skeleton", "href": "/display-and-content/skeleton", "url": "https://iconiqui.com/display-and-content/skeleton", "installPackage": "@iconiq/skeleton", "installCommand": "npx shadcn@latest add @iconiq/skeleton", "registryPath": "skeleton.json", "registryUrl": "https://iconiqui.com/r/skeleton.json", "summary": "Loading placeholder that renders a muted block with shimmer or fade animation, sensible defaults, and preset helpers for common shapes.", "apiSections": [ { "id": "skeleton", "title": "Skeleton", "summary": "Loading placeholder that renders a muted block with shimmer or fade animation, sensible defaults, and preset helpers for common shapes.", "notes": [ "The root defaults to `h-4 w-full`, so skeletons work without extra sizing for simple text lines.", "Decorative skeletons render `aria-hidden`. Standalone loading blocks can set `decorative={false}` to expose `role=\"status\"`, `aria-live=\"polite\"`, and a label.", "Theme tokens are embedded on the root node, so colors resolve out of the box without installing iconiq-theme separately.", "Shimmer and fade styles are injected once on the client through a scoped keyframe helper, so lists of skeletons do not duplicate `