# @elabs-ai/components-ui > Foundation + app UI (Button, Card, Dialog, Tabs, AppShell, …). Import from `@elabs-ai/components-ui`. Part of brand-ui — see the root `llms.txt` for routing. ## Components - Accordion — Vertically stacked sections that expand one at a time (or several) to reveal their content. - AccordionContent - AccordionItem - AccordionTrigger - AdvancedGroup - AffordanceHint - Alert (variant=default*|info|success|warning|destructive) — An inline message with a tone — info, success, warning, destructive — a title and a description. - AlertDescription - AlertDialog — Confirmation overlay for destructive / irreversible actions — friction proportional to consequence. - avoid: Firing the destructive action immediately on click — require the AlertDialog confirm (or an undo window). - avoid: Making the destructive action the default-focused button — focus the Cancel/safe action first. - AlertDialogAction - AlertDialogCancel - AlertDialogContent - AlertDialogDescription - AlertDialogFooter - AlertDialogHeader - AlertDialogPortal - AlertDialogTitle - AlertDialogTrigger - AlertTitle - AMBIENT_DEFAULT_STOPS - AMBIENT_MAX_ALPHA - AmbientField - APPROVAL_SCOPE_DESCRIPTION_KEYS - AppShell — Top-level application frame — sidebar + header + content region. - avoid: Deep wrapper nesting inside the shell — keep the DOM shallow; one element, one job. - avoid: Painting the shell's chrome recess in the component — the chrome→canvas hierarchy is a THEME property; fix --sidebar's lightness, not AppShell. - AppSidebar — The opinionated application sidebar: the Sidebar skeleton behind typed header and footer slots, with the navigation as children. - avoid: Reaching for it when the shell is genuinely bespoke — then compose the Sidebar primitive set directly instead of fighting the typed slots. - avoid: Passing a whole nav tree through the header slot — header is the identity row; the navigation is children. - avoid: Forgetting SidebarInset for the content pane — the canvas must read brighter than the chrome, which is what stops an app shell going flat. - AspectRatio — A box that keeps a fixed width-to-height ratio for whatever it wraps — an image, a video, a map. - AttributionPanel - ATTRIBUTIONS - Audio — An audio player with its own controls (seek, play, time, scrubber, mute, volume) — voice replies, recordings, clips. - avoid: Reaching for a third-party media engine — compose the MediaPlayer parts. - avoid: `autoPlay` with sound — browsers block it; start from a control. - Avatar — A person or agent mark: an image with initials as the fallback, in the standard sizes. - AvatarFallback - AvatarGroup - AvatarImage - Badge (variant=default*|secondary|outline|success|warning|destructive|info) — Compact status/label chip (status, count, category). - avoid: Using it to carry an execution status — that is StatusBadge, whose closed seven-state vocabulary pairs a distinct glyph with every tone so the state survives greyscale. - avoid: Using a Badge as a clickable control — use a Button (Badge is not interactive). - avoid: Encoding status by color alone — pair the color with text/icon for non-color users. - BentoGrid - BentoGridItem (hero=true|false* · interactive=true|false*) - BoundedNumber - Breadcrumb — The path to the current page as a list of links, with the current item last. - BreadcrumbEllipsis - BreadcrumbItem - BreadcrumbLink - BreadcrumbList - BreadcrumbPage - BreadcrumbSeparator - Button (variant=default*|secondary|destructive|outline|outline-subtle|ghost|link · size=sm|default*|lg|icon|icon-sm|icon-lg) — Primary action trigger — the canonical way to invoke an action. - avoid: Two primary Buttons in the same action group — demote one to secondary/outline. - avoid: Button used for navigation — use a link instead (asChild + , or the variant="link"). - avoid: destructive variant for an irreversible action with no confirm step — wrap in AlertDialog. - avoid: Icon-only Button without an aria-label — the control has no accessible name. - ButtonGroup (orientation=horizontal*|vertical) — Buttons joined into one connected control — a segmented choice or a set of related actions. - ButtonGroupSeparator - ButtonGroupText - Calendar - Card (interactive=true|false*) — Surface grouping related content into a bordered, padded block. - avoid: Card inside a Card (nested cards) — flatten; cards are not a generic wrapper. - avoid: Card-for-everything — use a Card only when a bordered surface is the right affordance. - avoid: Identical icon-tile-above-heading Card grids repeated endlessly — vary structure. - CardAction - CardContent - CardDescription - CardFooter - CardHeader - CardMedia - CardTitle - Carousel - CarouselContent - CarouselDots - CarouselItem - CarouselNext - CarouselPrevious - CATEGORY_LABEL - ChangeReview - ChangeReviewHeader - ChangeReviewHunk - ChangeReviewList - ChangeReviewProvenance - ChangeReviewProvider - Checkbox — Binary on/off toggle within a form (multi-select within a group). - avoid: Checkbox and its Label not sharing one hit target — clicking the label must toggle the box (no dead zone). - avoid: Using a Checkbox for mutually-exclusive choices — use RadioGroup. - Collapsible — A single section that toggles between hidden and shown, with a trigger that reports its state. - CollapsibleContent - CollapsibleTrigger - COLOR_TOKENS - ColorPicker - Combobox — Searchable single/multi select — Select with typeahead over a large or async option set. - avoid: Using Combobox for a tiny fixed option set — a plain Select is simpler and lighter. - avoid: Restyling the trigger/panel by hand — Combobox is a Popover + Command assembly; style through those parts. - Command - CommandChip - CommandDialog - CommandEmpty - CommandGroup - CommandInput - CommandItem - CommandList - CommandSeparator - CommandShortcut - CommandTrigger - ConfirmDialog - ContextMenu — A right-click menu attached to an element, with items, groups, checks and submenus. - ContextMenuCheckboxItem - ContextMenuContent - ContextMenuGroup - ContextMenuItem - ContextMenuLabel - ContextMenuRadioGroup - ContextMenuRadioItem - ContextMenuSeparator - ContextMenuShortcut - ContextMenuSub - ContextMenuSubContent - ContextMenuSubTrigger - ContextMenuTrigger - ContextRail - COPY_FEEDBACK_MS - CopyableValue - DatePicker - DateRangePicker - DEFAULT_COMMAND_CHIP_LABELS - DEFAULT_INSTALL_TABS_LABELS - DEFAULT_INTEGRATION_MATRIX_LABELS - DEFAULT_MESSAGES - DEFAULT_SPEC_PLAYGROUND_LABELS - DEFAULT_SURFACE_TOUR_ACTIONS_LABELS - DEFAULT_THEME_FAMILY_SWITCH_LABELS - DEFAULT_TOKEN_SPOTLIGHT_LABELS - Descriptions - DescriptionsItem - Dialog — Modal overlay for focused tasks/flows that block the page until dismissed. - avoid: Dialog without a DialogTitle — screen readers announce no name (use sr-only if visually hidden). - avoid: Nesting a Dialog inside a Dialog — use a single flow or a Sheet/Drawer for the secondary surface. - avoid: Confirming a destructive action in a plain Dialog — use AlertDialog (it traps focus on the safe action). - DialogBody - DialogClose - DialogContent (size=sm|lg*|xl|full) - DialogDescription - DialogFooter - DialogHeader - DialogOverlay - DialogPortal - DialogSection - DialogTitle - DialogTrigger - DOCUMENT_ADDRESS_KINDS - DRAFTING_MARKS_HEIGHT - DRAFTING_MARKS_WIDTH - DraftingMarks - Drawer — A panel that slides in from an edge of the screen for a secondary task, and can be dragged closed on touch. - DrawerClose - DrawerContent - DrawerDescription - DrawerFooter - DrawerHeader - DrawerPortal - DrawerTitle - DrawerTrigger - DropdownMenu — A menu opened from a trigger, with items, groups, checks, radios and submenus. - DropdownMenuCheckboxItem - DropdownMenuContent - DropdownMenuGroup - DropdownMenuItem - DropdownMenuLabel - DropdownMenuPortal - DropdownMenuRadioGroup - DropdownMenuRadioItem - DropdownMenuSeparator - DropdownMenuShortcut - DropdownMenuSub - DropdownMenuSubContent - DropdownMenuSubTrigger - DropdownMenuTrigger - EmptyListIllustration - EmptyState — The placeholder for a region with nothing to show yet: an illustration, a message and the action that fills it. - ErrorIllustration - ErrorState — The panel for a failed load or action: what went wrong and how to retry. - ExpandDialog - ExpandDialogContent - ExpandDialogHeader - ExpandDialogPanes (detailPlacement=side*|bottom · stackBelow=never*|sm|md|lg) - FieldControl - FieldDescription - FieldError - FieldLabel - FieldRoot - FieldRow - FILE_CATEGORY_ICONS - FileUpload - FileUploadDropzone - FileUploadItem - FileUploadList - FilterChip - FirstRunIllustration - Heading (size=display-lg|display|title*|subtitle) - HoverCard — A rich preview card that opens when a link or name is hovered or focused. - HoverCardContent - HoverCardTrigger - IconButton - ILLUSTRATION_ACCENT_VAR - Image (fit=contain*|cover|fill|none|scale-down) — A token-styled : `fit` (object-fit), a Skeleton in a reserved box while it decodes, an accessible ImageOff fallback on error. - avoid: Zoom/rotation on Image — that is the viewer shell's job (ADR 0026). - avoid: A `loading` boolean — use native `loading="lazy"`; an has no external not-ready signal. - avoid: No `width`+`height` or `aspectRatio` on a late image — the skeleton cannot reserve the box. - avoid: A person/agent mark with initials — that is Avatar. - Input — Single-line text field — the base form input. - avoid: Hand-building a search field on it — a leading icon plus a clear button is SearchInput in @elabs-ai/components-data. - avoid: Input without an associated Label (visible or sr-only) — it has no accessible name. - avoid: Blocking paste (onPaste + preventDefault) — never block paste. - avoid: Wrong type/inputmode — use type=email/tel/url/number + inputmode so mobile keyboards + validation match. - avoid: Missing autocomplete + a meaningful name on a real form field. - InputGroup (variant=outline*|surface|card) — An input with attached prefix and suffix slots — a unit, an icon, a button — as one field. - InputGroupAddon (align=inline-start*|inline-end|block-start|block-end) - InputGroupButton - InputGroupInput - InputGroupText - InputGroupTextarea - InputOTP — A one-time-code entry with one slot per digit and paste support. - InputOTPGroup - InputOTPSeparator - InputOTPSlot - InstallTabs - IntegrationMatrix - Kbd - KeyboardShortcuts — Grouped, searchable presentation of an application's shortcut set — the sheet the Kbd atom belongs in. - avoid: Rendering a raw key string instead of Kbd — the atom carries the platform glyphs and the translate opt-out. - avoid: Showing a group's count without its items — a count with nothing behind it is a claim the sheet cannot keep. - avoid: Leaving an empty filter result blank — an empty search renders a real empty state, not a blank region. - KeyValueEditor - Label — The caption for a form control, wired to it for clicks and assistive technology. - LinkPreview - LinkPreviewCard - ListEditor - LoadingState — The placeholder shown while a region loads: a layout-shaped skeleton or a spinner with a message. - LocaleProvider - MatchHighlight - Media - MediaPlayer — The compound media player — root, element, viewport and every control part — for a custom layout the Audio/Video presets do not cover. - avoid: Reaching for a third-party media engine — compose these parts. - avoid: The native `controls` attribute — it doubles the UI. - MediaPlayerCaptionsButton - MediaPlayerControls (placement=docked*|overlay) - MediaPlayerElement (fit=contain*|cover) - MediaPlayerError - MediaPlayerFullscreenButton - MediaPlayerLoading - MediaPlayerMuteButton - MediaPlayerPipButton - MediaPlayerPlaybackRateMenu - MediaPlayerPlayButton - MediaPlayerSeekButton - MediaPlayerTime - MediaPlayerTimeSlider - MediaPlayerViewport - MediaPlayerVolumeSlider - MediaPlayerWaveform (placement=inline*|stage|strip) - MentionInput - MentionInputContent - MentionInputEmpty - MentionInputItem - MentionInputList - MentionInputTextarea - Menubar — A horizontal application menu bar with drop-down menus, as in a desktop app. - MenubarCheckboxItem - MenubarContent - MenubarGroup - MenubarItem - MenubarMenu - MenubarPortal - MenubarRadioGroup - MenubarRadioItem - MenubarSeparator - MenubarShortcut - MenubarSub - MenubarSubContent - MenubarSubTrigger - MenubarTrigger - Meter (size=xs|sm*|md) - MetricCard — Single KPI tile — label, value, delta/trend. - avoid: Numbers without tabular-nums — figures jitter across a row; use tabular-nums for any number column. - avoid: Encoding up/down by color alone — pair with an arrow/sign. - avoid: Re-declaring a KPI tile in another package — MetricCard is owned by @elabs-ai/components-ui; charts and editor re-export it (ADR 0012). - ModelPicker - MOTION_FACTOR_FLOOR - NavigationMenu — Top-level site navigation with rich drop-down panels for each section. - NavigationMenuContent - NavigationMenuItem - NavigationMenuLink - NavigationMenuList - NavigationMenuTrigger - NavigationMenuViewport - NavMain - NavNotifications - NavUser - NoAccessIllustration - NoResultsIllustration - NumberInput - OfflineIllustration - PageShell - Pagination — Page links with previous and next for stepping through a long list. - PaginationContent - PaginationEllipsis - PaginationItem - PaginationLink - PaginationNext - PaginationPrevious - PARALLAX_MAX_TRAVEL - PARALLAX_PLANE_RATES - ParallaxPlane - Popover — Anchored, dismissible floating panel for lightweight contextual content. - avoid: Reimplementing dismissal/positioning by hand — let the Radix Popover own focus + outside-click. - avoid: Expecting PopoverContent to render its own focus ring — it is outline-none by design; the trigger carries the ring. - PopoverAnchor - PopoverContent - PopoverTrigger - Progress - PROSE_HEADING_REM - PROSE_HEADING_TRACKING - PROSE_HEADING_WEIGHT - ProseBlockquote - ProseHeading - ProseInlineCode - ProseLink - ProseList - ProseListItem - ProseText - RadioGroup — Mutually-exclusive single choice from a small visible set. - avoid: Using a RadioGroup for many options — use Select/Combobox past ~7 options. - avoid: RadioGroup items without labels sharing a hit target. - RadioGroupItem - Rating - ResizableHandle - ResizablePanel - ResizablePanelGroup - ResultCount - Reveal (appear=fade|up*|down|left|right|zoom · speed=fast|base|slow*) - RevealGroup - RevealOnEnter - RevisionTimeline (density=comfortable*|compact) - SchemaForm - SchemaFormDescription - SchemaFormError - SchemaFormFallback - SchemaFormField - SchemaFormFields - SchemaFormProvider - SchemaFormRoot - SchemaFormSubmit - SchemaFormTestAction - SchemaFormTitle - ScrollArea — A scroll container with themed, overlay scrollbars that stay consistent across platforms. - ScrollBar - SectionHeader - SegmentedField - Select — Single-choice dropdown from a known set of options. - avoid: Using Select for free-form or searchable values — use Combobox when the user may type/search. - avoid: Select without a Label — no accessible name. - SelectContent - SelectGroup - SelectItem - SelectLabel - SelectSeparator - SelectTrigger - SelectValue - Separator — A horizontal or vertical divider between regions of the same surface. - Sheet — Edge-anchored panel (left/right/top/bottom) for secondary flows beside the page. - avoid: Sheet without a SheetTitle — no accessible name. - avoid: Scroll chaining to the page behind it — set overscroll-behavior: contain. - SheetClose - SheetContent - SheetDescription - SheetFooter - SheetHeader - SheetPortal - SheetTitle - SheetTrigger - Sidebar — The sidebar PRIMITIVE set you assemble yourself — provider, rail, header/content/footer regions and the menu parts. - avoid: Rebuilding the Sidebar -> SidebarHeader -> SidebarContent -> SidebarFooter skeleton by hand — that skeleton IS AppSidebar, which takes typed header/footer slots. - avoid: Rendering it outside SidebarProvider — the open state, the keyboard shortcut and the cookie persistence all live on the provider. - avoid: Conditionally mounting it to collapse it — the collapse is a width tween on an always-mounted rail; a conditional mount cannot animate. - SidebarContent - SidebarFooter - SidebarGroup - SidebarGroupAction - SidebarGroupContent - SidebarGroupLabel - SidebarHeader - SidebarInput - SidebarInset - SidebarMenu - SidebarMenuAction - SidebarMenuBadge - SidebarMenuButton (variant=default*|outline · size=default*|sm|lg) - SidebarMenuItem - SidebarMenuSkeleton - SidebarMenuSub - SidebarMenuSubButton - SidebarMenuSubItem - SidebarProvider - SidebarRail - SidebarSeparator - SidebarTrigger - SideDock - SiteShell - SiteShellFooter - SiteShellHeader - SiteShellMain - Skeleton - SkipLink - Slider - SliderNumber - SpecPlayground - Spinner - SplitPanel - StatePanel (kind=empty*|error|loading) - STATUS_LABELS - STATUS_ROLE - STATUS_TONE_ICONS - STATUS_TONES - StatusBadge (status=pending|running|complete|awaiting-approval|denied|failed|skipped · tone=neutral|info|success|warning|destructive · size=sm|md*) — The closed seven-state execution-status vocabulary, each state carrying its own icon as well as its own tone. - avoid: Using it for a neutral label or a count — that is Badge; this one asserts an execution state. - avoid: Inventing an eighth status by passing a custom label into the canonical enum — map an out-of-vocabulary state ONCE, near your domain, through the {label, tone, icon} form. - avoid: Relying on the tone alone to distinguish two states — the glyph is the second channel that keeps them apart in greyscale. - STATUSES - StatusIcon - STREAMDOWN_TRANSLATION_KEYS - SuccessIllustration - SurfaceTour - SurfaceTourActions - Switch — Immediate on/off setting toggle (applies on change, not on submit). - avoid: Switch that needs a separate Save to apply — use a Checkbox in a form instead; a Switch should apply immediately. - Table - TableBody - TableCaption - TableCell - TableFooter - TableHead - TableHeader - TableOfContents - TableRow - Tabs — Switch between peer views in the same context without navigating away. - avoid: Tabs for sequential steps — use a stepper/wizard; tabs are for peer, non-sequential views. - avoid: More than ~7 tabs — consider a Select or a sidebar nav. - TabsContent - TabsList (variant=segmented*|underline|rail) - TabsTrigger (variant=segmented*|underline|rail) - TagInput - TeamSwitcher - Text (variant=lead|body*|caption|meta|kpi|kpi-sm|eyebrow|code · tone=default*|muted|primary) - TEXT_ROLE_REM - Textarea — Multi-line text input, sized by rows and auto-growing when asked. - ThemeFamilySwitch - ThemeSwitcher - Timeline - TimelineItem - TimelineRoot - Toaster - Toggle (variant=default*|outline|segmented · size=default*|sm|lg) — A two-state button that stays pressed, for an on/off setting shown as a button. - ToggleGroup — Several toggles as one control, choosing one or several of the options. - ToggleGroupItem - TOKEN_SPOTLIGHT_SCAN_LIMIT - TokenSpotlight - Toolbar (orientation=horizontal*|vertical) — A dense row of controls that acts on nearby content, collapsed into ONE tab stop with arrow-key navigation between the controls. - avoid: Using it for the ordinary control row above a list or table — that is ViewToolbar, where every control is its own tab stop. - avoid: Omitting aria-label — a toolbar is one tab stop, so an unnamed one announces nothing about what it acts on. - avoid: Putting a text input or a link inside it — the roving tabindex swallows the arrow keys those controls need. - avoid: Reaching for it to attach actions to a canvas node — that is NodeToolbar in @elabs-ai/components-ai. - ToolbarButton - ToolbarSeparator - ToolbarSlot - ToolbarToggleGroup - ToolbarToggleItem - Tooltip — Transient hover/focus hint with supplementary (non-essential) text. - avoid: Putting essential information ONLY in a Tooltip — it is unreachable on touch and transient; keep critical content visible. - avoid: Tooltip on a non-focusable element — it won't show on keyboard focus. - TooltipContent - TooltipProvider - TooltipTrigger - TopNav - Transfer — Two lists with move buttons between them, for choosing a subset of items from a larger set. - Tree — A hierarchical list with expand and collapse, single or multiple selection and full keyboard navigation. - TreeSelect - UnsupportedJsonSchemaError - Video — A video player: bordered frame, bg-muted letterbox, opaque control bar docked beneath (or overlaid, auto-hiding); also the muted thumbnail. - avoid: `autoPlay` with sound — autoplay only `muted` (hero loops). - avoid: A black letterbox literal — the ground is `bg-muted`. - avoid: Captionless video — pass a `tracks` captions entry; thumbnails are `aria-hidden`. - ViewToolbar — The row above a list, table or board — status and filters on the left, actions on the right, every control its own tab stop. - avoid: Giving it role=toolbar — it deliberately does not claim that role; a dense row that should cost ONE tab stop with arrow-key roving is Toolbar. - avoid: Putting the primary page action in it — this row acts on the VIEW; a page-level action belongs in the page header. - avoid: Hiding the result count while filters are applied — the count is how a person tells an empty filter from an empty dataset. - ViewToolbarFilters - VirtualSelect - Wizard - WizardNav - WizardStep - WizardSteps - WorkspacePicker — Choose the workspace or project directory a session runs against, from recents or a typed path. - avoid: Re-implementing the picker list — WorkspacePicker composes ModelPicker; a second searchable-popover list is the duplication this component exists to avoid. - avoid: Marking the current workspace with a glyph alone — the marker is a word in the accessible name (1.4.1). - avoid: Reading the filesystem — the component takes a workspace list as a prop and never enumerates directories itself. - avoid: Natively disabling the path submit — an empty field uses aria-disabled plus a handler guard, so focus is never stranded. ## Hooks - useCarouselPosition - useCollapsiblePanel - useCommandActiveItemId - useControllableState - useCopyToClipboard - useDialogDismissGuard - useDiffRows - useFileUpload - useIsMobile - useLocale - useMediaPlayer - useMediaState - useMentionInput - useScrollProgress - useScrollSpy - useSidebar - useStreamdownTranslations - useThemeTransition - useTreeKeyboard - useVirtualListbox ## Subpath exports - ALIAS_TRANSFORMS (`@elabs-ai/components-ui/definition` · component) - Form (`@elabs-ai/components-ui/form` · component) - FormControl (`@elabs-ai/components-ui/form` · component) - FormDescription (`@elabs-ai/components-ui/form` · component) - FormField (`@elabs-ai/components-ui/form` · component) - FormItem (`@elabs-ai/components-ui/form` · component) - FormLabel (`@elabs-ai/components-ui/form` · component) - FormMessage (`@elabs-ai/components-ui/form` · component) - useFormField (`@elabs-ai/components-ui/form` · hook)