# SoybeanUI Docs

English LLM-friendly documentation index for the SoybeanUI docs site.

## Details

- Generated from docs/src/docs/en for the vite-ssg documentation site.
- Mirrors the current docs routing model: overview pages and component detail pages.
- Markdown component placeholders are normalized into short textual hints for LLM consumption.

## Table of Contents

- [Accordion](/components/accordion.md): A vertically (or horizontally) stacked set of interactive headings that each reveal a section of content, supporting single or multiple expansion. `SAccordion` combines an `AccordionRoot`/`AccordionItem`/`AccordionHeader`/`AccordionTrigger`/`AccordionContent`/`AccordionDescription` family of headless primitives (zero styles) with the `accordionVariants` style recipe (8 slots, 6 sizes).
- [Affix](/components/affix.md): Affix keeps content pinned to the top or bottom edge of the viewport or a custom scroll container while the target area is scrolling.
- [Alert](/components/alert.md): A callout that surfaces important, time-sensitive information — warnings, errors, or confirmations — near the content it refers to. `SAlert` combines an `AlertRoot`/`AlertTitle`/`AlertDescription`/`AlertClose` family of headless primitives (zero styles) with the `alertVariants` style recipe (6 slots, 8 colors × 5 variants × 6 sizes).
- [Anchor](/components/anchor.md): Anchor provides in-page navigation for long content sections and keeps the current section highlighted while scrolling.
- [Arrow](/components/arrow.md): `SArrow` is a primitive SVG component that renders a downward-pointing triangle, used as a visual pointer for popovers, tooltips, and other floating elements. It is primarily consumed internally by SoybeanUI overlay components (popover, tooltip, hover-card, etc.) but can be used directly when building custom floating UI.
- [AspectRatio](/components/aspect-ratio.md): `SAspectRatio` maintains a fixed aspect ratio for its content using the CSS padding-bottom technique. It wraps content in a relatively-positioned container with a dynamic `paddingBottom` percentage, and an absolutely-positioned inner element that fills the container. Use it to prevent layout shift when loading images, videos, or embeds with known dimensions.
- [Autocomplete](/components/autocomplete.md): An autocomplete that filters suggestion items from text input and quickly fills the input with a selected result. It opens as you type, fuzzy-matches options with Fuse, and supports grouping, a clearable input, and a data-driven compact API. Use it when users should type keywords to get suggestions over free text; when options come from a fixed list, prefer `SSelect`; when options come from a known set that benefits from type-to-filter, `SCombobox` is the closer sibling.
- [Avatar](/components/avatar.md): An image element with a fallback for representing the user. `SAvatar` combines a `AvatarRoot`/`AvatarImage`/`AvatarFallback` family of headless primitives (zero styles) with the `avatarVariants` style recipe (3 slots: root/image/fallback, 6 sizes xs–2xl).
- [Backtop](/components/backtop.md): `SBacktop` reveals a floating button after the scroll target passes a configurable threshold and smoothly scrolls that target back to the top when activated. It wraps `SButton` with scroll-position tracking, `requestAnimationFrame`-based smooth scrolling, and `prefers-reduced-motion` support. Use it to let users quickly return to the top of long pages or scrollable containers.
- [Badge](/components/badge.md): A small status/notification marker that overlays a trigger (button, avatar, nav item) to indicate a count, a state, or new content. `SBadge` combines a `BadgeRoot`/`BadgeContent` family of headless primitives (zero styles) with the `badgeVariants` style recipe (2 slots: root/content; 8 colors × 6 sizes × 4 positions).
- [Bottom Sheet](/components/bottom-sheet.md): A modal panel that slides in from the bottom edge of the screen. It is suited for mobile-first actions, supplemental details, and step-based confirmations. The component reuses the declarative API of `SDialog` (same headless dialog primitives), and adds bottom-sheet interactions such as drag-to-dismiss, background scaling, and `snapPoints` support.
- [Breadcrumb](/components/breadcrumb.md): Breadcrumbs allow users to navigate through the hierarchy of pages. It displays the current location within the application structure.
- [Button](/components/button.md): A button component that can be used to trigger an action.
- [Calendar](/components/calendar.md): A monthly date grid that supports single or multiple selection, disabled and unavailable dates, min/max bounds, custom cell rendering, and month/year Select controls in the compact header. Use it for booking, scheduling, or any date-picking surface that needs keyboard-navigable grids instead of a plain text input. Pair it with `SDatePicker` when you need a popup trigger, or `SRangeCalendar`-style composites for range selection.
- [CalendarRange](/components/calendar-range.md): CalendarRange displays one or more month grids and lets users pick a start and end date directly from the calendar surface. Selecting the first date starts the range, a live hover preview highlights the candidate range, and the second click commits it — with reversed selections sorted automatically. Use it for booking, scheduling, or any range-picking surface that needs a keyboard-navigable grid instead of two text inputs. Pair it with `SDateRangePicker` when you need a popup trigger, or use it standalone inside forms and custom layouts.
- [Card](/components/card.md): A container that groups related content and actions into a bordered, shadowed surface. `SCard` combines a `CardRoot`/`CardHeader`/`CardContent`/`CardFooter`/`CardTitle`/`CardDescription` family of headless primitives (zero styles) with the `cardVariants` style recipe (8 slots, 6 sizes, `scrollable`/`split` flags).
- [Carousel](/components/carousel.md): A carousel built on top of Embla Carousel that lets users browse a sequence of content (images, cards, banners, etc.) horizontally or vertically in a constrained space. `SCarousel` combines a `CarouselRoot`-family of headless primitives (zero styles) with the `carouselVariants` style recipe (8 slots: root/content/container/item/control/navigation/previous/next, 6 sizes × 2 orientations).
- [Cascader](/components/cascader.md): A cascader for selecting values from hierarchical tree data. It renders a linked multi-column panel and supports single/multiple selection, full-path value mode, parent-child check-state propagation, local filtering and remote search, lazy loading of children, and virtual scrolling for large datasets. Use it when options are organized as a tree and selection must happen level by level; for flat option lists, prefer `SSelect` or `SCombobox`.
- [Checkbox](/components/checkbox.md): A control that lets the user select or clear an option, with an indeterminate half-check state for partial selections. It ships as a standalone control, a roving-focus group, and data-driven card variants. Use it for independent toggles, multi-select lists, and "select all" scenarios with cascading half-check; for single-choice from a set, prefer `SRadioGroup`.
- [Clipboard](/components/clipboard.md): `SClipboard` is a clipboard action component built on `SButton` that copies a plain-text value to the system clipboard with accessible button semantics and copied-state feedback.
- [Collapsible](/components/collapsible.md): An interactive component that expands/collapses a panel. `SCollapsible` wraps the headless `CollapsibleRoot` with the `collapsibleVariants` style recipe (3 slots: root/trigger/content; 6 sizes), and the headless `CollapsibleTrigger`/`CollapsibleContent` primitives provide the toggle button and the animated panel.
- [Color Area](/components/color-area.md): A two-dimensional color editor for saturation/lightness, saturation/brightness, or OKLCH chroma/lightness selection. `SColorArea` combines the headless `ColorAreaRoot`/`ColorAreaArea`/`ColorAreaThumb` primitives with the `colorAreaVariants` style recipe (3 slots, 6 sizes).
- [Color Field](/components/color-field.md): An input for editing either a full color string or a single channel, with support for `hex`, `rgb`, `hsl`, and `oklch` output. `SColorField` combines the headless `ColorFieldRoot`/`ColorFieldInput` primitives with the `colorFieldVariants` style recipe (2 slots, 6 sizes).
- [Color Picker](/components/color-picker.md): A composite color picker that combines a color area, hue/alpha sliders, formatted inputs, and preset swatches, with full `oklch` editing and output support. `SColorPicker` composes the headless color primitives (`ColorArea`/`ColorSlider`/`ColorField`/`ColorSwatch`/`ColorSwatchPicker`) inside a popover, with a `SegmentCompact` for format switching. Nested part styles are unified in `colorPickerVariants` and forwarded through `provideColorPickerUi`.
- [Color Slider](/components/color-slider.md): A single-channel color slider for hue, alpha, and individual RGB/HSL/HSV/OKLCH channels. `SColorSlider` combines the headless `ColorSliderRoot`/`ColorSliderTrack`/`ColorSliderThumb` primitives with the shared `sliderVariants` style recipe (via `sliderVariants`).
- [Color Swatch](/components/color-swatch.md): A read-only color preview block with support for transparent and OKLCH values. `SColorSwatch` combines the headless `ColorSwatchRoot`/`ColorSwatchChecker`/`ColorSwatchFill` primitives with the `colorSwatchVariants` style recipe (3 slots, 6 sizes × 2 shapes).
- [Color Swatch Picker](/components/color-swatch-picker.md): Choose a color quickly from a preset palette, useful for theme panels and suggested color selections. `SColorSwatchPicker` combines the headless `ColorSwatchPickerRoot`/`Item`/`ItemSwatch`/`ItemIndicator` primitives (built on the listbox) with the `colorSwatchPickerVariants` style recipe (6 slots, 6 sizes × 2 shapes).
- [Combobox](/components/combobox.md): A combobox for searching and selecting values from an option list, with an explicit anchor composition, clearable input, and complete popup/filtering behavior. The input filters options as you type and keyboard navigation follows the WAI-ARIA combobox pattern. Use it when users must type to filter a list; for selection without typing, use `SSelect`; for fuzzy-matching suggestions over text, use `SAutocomplete`.
- [Command](/components/command.md): Fast, composable, command menu for Vue. `SCommand` is a searchable command palette built on the headless listbox primitives with Fuse fuzzy matching. It delegates filtering, grouped item aggregation, and default item composition to the headless `CommandCompact`; the UI wrapper only injects styles.
- [ConfigProvider](/components/config-provider.md): The `SConfigProvider` component is the root configuration provider for the SoybeanUI library. It manages global themes, localization, icon settings, and other context-aware features. It should wrap your entire application or specific sections that require isolated configuration.
- [ContextMenu](/components/context-menu.md): Displays a menu located at the pointer, triggered by a right-click. `SContextMenu` is a data-driven menu built on the shared headless menu primitives, opening at the pointer position via the `contextmenu` event (or a press-and-hold on touch, after `pressOpenDelay`). The family also ships checkbox (`SContextMenuCheckbox`), radio (`SContextMenuRadio`) and custom (`SContextMenuWrapper`) variants.
- [DateField](/components/date-field.md): A segmented date input that keeps day, month, year, and optional time values as separate keyboard-editable parts while still submitting a native form value. Use it for compact date entry where typing should be fast — birth dates, expiry dates, or any single date that needs validation against a range. For a date chosen from a calendar popup, prefer `SDatePicker`; for browsing a calendar grid, use `SCalendar`.
- [DatePicker](/components/date-picker.md): A date picker that pairs a keyboard-editable segmented date field with a calendar popup for visual selection. Type a date directly into the segments or click the calendar toggle to pick from a month grid. Use it whenever a user must choose a single date — booking, scheduling, filtering, or any form that needs a validated date range. For pure typing with no popup, prefer `SDateField`; for browsing a standalone calendar grid, use `SCalendar`.
- [DateRangeField](/components/date-range-field.md): A segmented date range input that renders two groups of keyboard-editable date segments — one for the start date and one for the end date — while submitting native form values for both. Use it whenever a user must enter a bounded interval fast, such as booking stay dates, reporting windows, or filter ranges where typing beats calendar clicking. For a range chosen from a calendar popup, prefer `SDateRangePicker`; for a single date, use `SDateField`.
- [DateRangePicker](/components/date-range-picker.md): A date range picker that pairs a keyboard-editable dual segmented date range field with a calendar range popup for visual selection. Type a start and end date directly into the segments or click the calendar toggle and pick both ends from a single month-range grid. Use it whenever a user must choose a bounded interval — booking stay dates, reporting windows, or filter ranges. For pure typing with no popup, prefer `SDateRangeField`; for a single date with a popup, use `SDatePicker`.
- [Dialog](/components/dialog.md): A window overlaid on either the primary window or another dialog window, rendering the content underneath inert.
- [Drawer](/components/drawer.md): A panel that slides out from the edge of the screen. It reuses the declarative API and slot contract of `SDialog` (same headless `DialogCompact` base, same modal/focus/dismissable behavior), and adds `side` to control where the panel enters — `top`/`bottom`/`left`/`right` (default `right`).
- [DropdownMenu](/components/dropdown-menu.md): Displays a menu to the user—such as a set of actions or functions—triggered by a button. `SDropdownMenu` is a data-driven menu built on the headless menu primitives (`MenuOptions`/`MenuItem`/…), rendered through the shared popover portal. The family also ships checkbox (`SDropdownMenuCheckbox`, multi-select), radio (`SDropdownMenuRadio`, single-select) and custom (`SDropdownMenuWrapper`) variants.
- [Editable](/components/editable.md): An inline text editor that switches between preview and edit states. In preview mode the value is shown as a focusable text node (or a placeholder); focusing, double-clicking, or clicking the edit button enters edit mode, then submitting (Enter/blur/submit trigger) or cancelling (Esc/cancel trigger) returns to preview. The structure follows the headless core + styled wrapper split: the 8 `EditableRoot`-family components in `@soybeanjs/headless` (zero styles) own the full state machine, and `SEditable` injects the `editableVariants` styles (8 slots: root/area/preview/input/controls/editTrigger/submitTrigger/cancelTrigger).
- [Empty](/components/empty.md): A lightweight empty-state component that highlights missing content and guides the user toward a next action. `SEmpty` combines an `EmptyRoot`/`EmptyHeader`/`EmptyMedia`/`EmptyTitle`/`EmptyDescription`/`EmptyContent` family of headless primitives (zero styles) with the `emptyVariants` style recipe (6 slots, 6 sizes).
- [Form](/components/form.md): A form composition layer for building validated forms with a headless core and styled wrappers. The `useForm` composable owns the values, touched/meta state, and validation pipeline (Standard Schema v1 — Zod, Valibot, ArkType, Yup, etc.), and returns a tuple of `[formState, SFormField, SFormFieldArray]` used to render the form. Fields register through slots, so any SoybeanUI input (`SInput`, `SSelect`, `SCheckbox`, `SSwitch`, `SRadioGroup`, …) or a plain custom control works without a per-control API.
- [Hover Card](/components/hover-card.md): Displays a richer preview card when the trigger is hovered or receives focus. `SHoverCard` combines the headless `HoverCardRoot`/`HoverCardTrigger`/`HoverCardPositioner`/`HoverCardPopup`/`HoverCardArrow` primitive family (built on the shared `Popper`) with the `hoverCardVariants` style recipe (3 slots, 6 sizes).
- [Icon](/components/icon.md): `SIcon` is a unified icon component built on top of [Iconify](https://iconify.design/). It supports rendering icons from the Iconify dataset or custom components/VNodes. It integrates with `SConfigProvider` for consistent sizing across the application.
- [Input](/components/input.md): A single-line text input that collects user input, supporting standard input attributes, prefix/suffix slots, and clearable functionality. Use it for any short free-text entry — form fields, search boxes, filters. For multi-line text use `STextarea`; for sensitive values use `SPassword`; for numeric values use `SInputNumber`.
- [InputNumber](/components/input-number.md): A numeric input field that only accepts numeric values, with increment/decrement controls, keyboard interaction, and min/max boundary handling. Use it for quantities, prices, ages, or any value that must stay numeric and within a range. For general text use `SInput`.
- [InputOtp](/components/input-otp.md): A one-time-password (OTP / verification code) input built around a real native input. It keeps the robust selection, paste, and mobile autofill behavior of vue-input-otp while exposing a default SoybeanUI presentation and a fully custom scoped slot. Use it for SMS codes, email verification codes, two-factor authentication, or any fixed-length code entry.
- [Kbd](/components/kbd.md): The `SKbd` component represents a keyboard input element, typically used to display keyboard shortcuts and key combinations. It wraps the native `<kbd>` element and optionally symbolizes key names (e.g., `shift` → `⇧`, `enter` → `↵`) with platform-aware resolution for modifier keys (`meta`, `alt`, `ctrl`).
- [Label](/components/label.md): The `SLabel` component renders a native `<label>` element that provides an accessible caption for form controls. Use the `for` prop to associate the label with an input by its `id` — clicking the label then focuses the associated control. The component prevents text selection on double-click for a cleaner UX and supports size scaling via the design system.
- [Layout](/components/layout.md): The layout component structure for admin dashboards or complex applications. It manages sidebar, header, footer, tabs, and main content areas.
- [Link](/components/link.md): `SLink` is a polymorphic link component that supports internal routing (via `RouterLink`) and external links (via `<a>` tag). It automatically detects external links and sets safe `target` and `rel` attributes, supports disabled state and polymorphic rendering (`as`/`asChild`).
- [List](/components/list.md): A semantic container for displaying a vertical list of items. `SList` wraps the headless `ListRoot` (a `<ul>`) with the `listVariants` style recipe (5 slots: root/item/content/title/description; 6 sizes). `SListItem` composes the headless `ListItem`/`ListContent`/`ListTitle`/`ListDescription` primitives into a ready-made title + description row.
- [Menu](/components/menu.md): The Menu component family lets you build complex nested menus, including dropdowns and context menus. It provides a data-driven approach using `SMenuOptions`, `SMenuCheckboxOptions`, and `SMenuRadioOptions` for easy configuration of groups, submenus, checkboxes, radio items, separators, shortcuts, and link items. The logic layer reuses `@soybeanjs/headless/menu` with full WAI-ARIA menu semantics and roving-focus keyboard navigation.
- [Menubar](/components/menubar.md): Menubar builds a persistent horizontal menu bar for application chrome: a row of triggers with roving focus that open dropdown menus on click or hover, with arbitrarily nested submenus and full keyboard navigation.
- [NavMenu](/components/nav-menu.md): NavMenu builds site-level horizontal or vertical navigation with a single shared floating surface. Unlike the Radix-derived `NavigationMenu`, it is modeled directly on the Popper primitives: the whole viewport is one `PopperPositioner`, its reference switches to the active trigger, and all hover timing runs on a single shared Popper hover machine with value routing through `pendingValue`.
- [NavigationMenu](/components/navigation-menu.md): > **⚠️ Deprecated:** `NavigationMenu` is superseded by [`NavMenu`](/components/nav-menu) as the single admitted navigation-menu family. It is frozen — no new slots, features, or prop additions, critical-bug fixes only — and will be removed in **v1.0**. New code should use `SNavMenu`; existing code can migrate now via [Migrating to NavMenu](#migrating-to-navmenu).
- [PageTabs](/components/page-tabs.md): A tabbed interface designed for navigating between different pages or views. It supports features like closable tabs, context menus, and customizable styling.
- [Pagination](/components/pagination.md): Pagination is used for splitting up content or data into several pages, with a control for navigating to the next or previous page.
- [PalettePicker](/components/palette-picker.md): `SPalettePicker` is a color picker that produces a full palette from a single base color. Its `modelValue` is a [`ColorValue`](../../../api/theme.md) — either a Tailwind palette key + level (e.g. `indigo.500`), a simple palette key (`black` / `white` / `transparent` …), or a raw custom color (`hsl(...)` / `oklch(...)`).
- [Password](/components/password.md): A password input field with a toggle button to show/hide the entered value. Use it for login forms, sign-up forms, or any sensitive credential entry. It composes the input family base with a visibility switch, and supports clearable mode. For non-sensitive text use `SInput`.
- [Popconfirm](/components/popconfirm.md): A confirmation box component based on `Popper`, used for lightweight secondary confirmation operations. `SPopconfirm` combines the headless `PopconfirmCompact` (built on the popper primitives) with the `popconfirmVariants` style recipe (13 slots, 6 sizes × 4 types).
- [Popover](/components/popover.md): Displays rich content in a portal, triggered by a button. `SPopover` combines the headless `PopoverRoot`/`PopoverTrigger`/`PopoverPositioner`/`PopoverPopup`/`PopoverArrow`/`PopoverClose` primitive family (built on the shared `Popper` + dialog-style dismissable/focus layers) with the `popoverVariants` style recipe (5 slots, 6 sizes).
- [Popper](/components/popper.md): The low-level floating primitive that anchors content to a trigger element with full trigger, open/close and dismiss behavior. `SPopper` composes the headless `PopperRoot`/`PopperTrigger`/`PopperAnchor`/`PopperPositioner`/`PopperPopup`/`PopperArrow`/`PopperSub` family (built on Floating UI) with the `popperVariants` style recipe (6 slots, 3 sizes).
- [Progress](/components/progress.md): A progress indicator for determinate or indeterminate task completion. `SProgress` combines the headless `ProgressRoot`/`ProgressIndicator` primitives with the `progressVariants` style recipe, and `SProgressCircle` offers a circular variant via `progressCircleVariants`. Both share an imperative API (`progress.start()`/`done()`) surfaced through `SProgressProvider`.
- [Radio Group](/components/radio-group.md): A set of checkable radio buttons where no more than one button can be checked at a time. It ships as a data-driven group and a card variant with icon/description content, both built on roving-focus keyboard navigation. Use it for single-choice from a small, mutually exclusive set; when multiple values are allowed, use `SCheckboxGroup`; when the option set is too large to scan at once, prefer `SSelect`.
- [Rating](/components/rating.md): A star-rating component built on a multi-slot headless core: `RatingRoot` provides the slider context, state, and keyboard handling, while each `RatingItem` renders a single star. Supports controlled and uncontrolled modes, half-star precision, clear-on-repeat-click, read-only and disabled states, horizontal/vertical orientation, RTL direction, and native form integration through a visually hidden input. Use it whenever users need to express a graded preference—product reviews, feedback surveys, or skill self-assessment.
- [ScrollArea](/components/scroll-area.md): A custom scroll container that keeps native scrolling behavior while rendering styled scrollbars for vertical and horizontal overflow.
- [Segment](/components/segment.md): A linear set of two or more mutually exclusive options presented as a unified control, with a sliding indicator that follows the active option. Use it for compact segmented pickers — time ranges, view toggles, or any small set of single-choice options — where the selection should change immediately. For a set of independent two-state buttons (single or multiple), use `SToggleGroup`; for plain tabbed content panels, use `STabs`.
- [Select](/components/select.md): Displays a list of options for the user to pick from, triggered by a button. The trigger renders the selected value (or placeholder), and the popup supports keyboard navigation, typeahead, grouping, multiple selection, and clearable mode. Use it to pick one or more values from a bounded set; for free-text search over a list, use `SCombobox`; for cascading hierarchical data, use `SCascader`.
- [Separator](/components/separator.md): The `SSeparator` component visually and semantically separates content sections. It renders a horizontal or vertical line, optionally with a label centered (or aligned) along it. Use it to divide related content blocks, group menu items, or structure form sections.
- [Skeleton](/components/skeleton.md): A placeholder used to indicate that content is still loading. `SSkeleton` combines the headless `Skeleton` primitive (zero styles) with the `skeletonVariants` style recipe (6 sizes × 2 shapes × animated toggle) and is decorative (`aria-hidden` by default).
- [Slider](/components/slider.md): A slider for picking one or more numeric values within a continuous range, supporting horizontal and vertical orientations, multi-thumb range mode, RTL and inverted directions, and complete keyboard navigation. Use it when the value belongs to a bounded numeric range and the user should adjust it with mouse or keyboard precision; when the value is free-form text or numbers, prefer `SInputNumber` instead.
- [Spinner](/components/spinner.md): `SSpinner` is a lightweight loading indicator built on top of `SIcon`. It defaults to the Iconify `svg-spinners` collection and is suitable for inline loading states such as button loading, content placeholders, and async fetch indicators. Use the `color` and `size` props to match the surrounding UI, or swap the `icon` prop for any `svg-spinners:*` animation.
- [SplitNav](/components/split-nav.md): A split navigation for admin layouts. `SSplitNav` takes one menu tree and renders it across independent first-level and nested panes, instead of nesting every level in a single sidebar. It ships four layout modes — `dual-vertical`, `vertical-horizontal`, `horizontal-vertical`, and `horizontal-dual-vertical`. The first-level rail is a dedicated RovingFocus menu (Menubar-like arrow keys; Enter/Space to activate; ArrowDown on a horizontal parent, ArrowLeft/ArrowRight on a vertical parent to open the nested pane). Nested vertical panes reuse `TreeMenuCompact`; the nested horizontal pane reuses `TreeNavCompact`.
- [Splitter](/components/splitter.md): A composable layout component that divides an area into resizable panels.
- [Stepper](/components/stepper.md): Displays progress through a multi-step workflow. `SStepper` combines a `StepperRoot`-family of headless primitives (zero styles) with the `stepperVariants` style recipe (8 slots: root/item/trigger/indicator/indicatorIcon/itemContent/separator/title/description) and 7 colors × 7 sizes. In **linear mode** (the default) steps must be completed in order — future steps are disabled and cannot be skipped; in non-linear mode any step can be activated freely. The current step is announced to screen readers through a localized `role="status"` live region, and the group exposes an `aria-label` that falls back to the `stepper.ariaLabel` locale message.
- [Switch](/components/switch.md): A control that toggles between checked and unchecked states with a sliding thumb and native form integration. Use it for a single binary setting that takes effect immediately (e.g. dark mode, notifications); when the option belongs to a form that needs explicit submission, prefer `SCheckbox`; when more than one value can be selected, use a checkbox group instead.
- [Table](/components/table.md): A data table component for displaying row and column data. `STable` combines the headless `TableCompact` aggregation component (9 zero-style base primitives in the `TableRoot` family) with the `tableVariants` style recipe (29 slots, 7 sizes × 2 visual variants). Supports a **config-driven `columns` model** (grouped headers, `index`/`selection`/`expand` type columns), sorting, filtering, multi/single selection, expandable and tree rows, fixed columns/headers, drag-and-keyboard column resizing, virtualization, and empty states; `default`/`simple` variants plus `bordered`/`rounded`/`striped` toggles. All interaction text and `aria-label`s (sorting, filtering, selection, expansion, column resize) are localized via `useLocaleMessages`.
- [Tabs](/components/tabs.md): A set of layered sections of content—known as tab panels—that are displayed one at a time.
- [Tag](/components/tag.md): A compact label used to categorize, filter, or mark content inline. `STag` combines the headless `Tag` primitive (zero styles) with the `tagVariants` style recipe (8 colors × 6 sizes × 5 variants × 2 shapes) and exposes `leading`/`trailing`/`close` slots.
- [Tags Input](/components/tags-input.md): A composable multi-value input for adding, displaying, and removing tags. Supports controlled/uncontrolled `string[]` values, tag creation via `Enter`/`Tab`/blur/delimiter typing/paste, full keyboard selection and removal (with RTL reversal), `max`/`duplicate` constraints, and hidden form-input serialization. Use it for keyword lists, email recipients, or any small-token collection that needs fast keyboard workflows instead of a plain text input.
- [Textarea](/components/textarea.md): A multi-line text input for longer free-form content, supporting auto-resizing, character counting, and clearable functionality. Use it for descriptions, comments, messages, or any content that spans multiple lines. For single-line input use `SInput`.
- [ThemeModeSelect](/components/theme-mode-select.md): `SThemeModeSelect` is a context-bound dropdown bound to the active `SConfigProvider` theme. It exposes the three `ThemeModePreference` options — `auto` (follows the OS `prefers-color-scheme`), `light`, and `dark` — each with a scheme icon, letting users pick a color scheme preference directly.
- [ThemeModeSwitch](/components/theme-mode-switch.md): `SThemeModeSwitch` is a context-bound toggle bound to the active `SConfigProvider` theme. It reflects the current _effective_ scheme (so an `auto` preference shows the OS-resolved light/dark state) and pins an explicit `light` / `dark` preference when toggled. Use it as a quick, compact light/dark switch in a header or toolbar.
- [TimeField](/components/time-field.md): A segmented time input that renders individually editable hour, minute, and optional second and day-period segments while submitting a native form value. Use it whenever a user must enter a time fast and precisely — scheduling, booking, time-window filtering, or any form that needs a validated time. For a date with a time, use `SDateField` with `granularity: 'minute'`; for a range, prefer `STimeRangeField`.
- [TimeRangeField](/components/time-range-field.md): A segmented time range input with independently editable start and end time segments (hour, minute, and optional second and day-period) while still submitting native form values for both sides. Use it whenever a user must enter a start and end time quickly and precisely — scheduling, booking, shift or time-window filtering. For a single time use `STimeField`; for a date and time range use `SDateRangeField` with a time granularity or `SDateRangePicker`.
- [Toast](/components/toast.md): Transient notifications that appear in a viewport and auto-dismiss. `SToastProvider` renders the toast viewports and the `toast` imperative API creates, updates, dismisses, and inspects notifications. It supports six types, six positions, stacking/expansion, swipe-to-dismiss, promise toasts, rich color and inverted themes, and a keyboard hotkey to focus the list.
- [Toggle](/components/toggle.md): A two-state button that toggles between pressed (`on`) and unpressed (`off`) states, reflecting its state via `aria-pressed` and `data-state`. Use it for an immediate, exclusive on/off switch such as a formatting tool or a filter chip; when the choice belongs to a form that needs explicit submission, prefer `SCheckbox` instead.
- [ToggleGroup](/components/toggle-group.md): A set of two-state buttons that can be toggled on or off as a group, supporting single and multiple selection. Use it for formatting toolbars, filter chips, or any exclusive (or multi-choice) segmented control where the selection changes immediately. For segmented _single_ options that must look like a unified control, `SSegment` may fit better; for a single independent on/off button, use `SToggle`.
- [Toolbar](/components/toolbar.md): A compact container that groups related actions, links, and toggle controls into a single roving-focus toolbar. `SToolbar` combines the headless toolbar primitives (`ToolbarRoot`/`ToolbarButton`/`ToolbarLink`/`ToolbarSeparator`/`ToolbarToggleGroup`/`ToolbarToggleItem`) with the `toolbarVariants` style recipe (7 slots, 6 sizes × 2 orientations).
- [Tooltip](/components/tooltip.md): A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. `STooltip` combines the headless `TooltipRoot`/`TooltipTrigger`/`TooltipPositioner`/`TooltipPopup`/`TooltipArrow` primitive family (built on the shared `Popper`) with the `tooltipVariants` style recipe (3 slots, 6 sizes).
- [Tree](/components/tree.md): A component for displaying hierarchical tree data with selection and expand/collapse support. `STree` combines the headless `TreeRoot` family of base primitives (`TreeRoot`/`TreeItem`/`TreeVirtualizerRoot`/`TreeVirtualizerItem`, zero-style) with the `TreeRoot` context (controlled/uncontrolled selection and expansion, single/multiple selection, cascading selection, Roving Focus keyboard navigation); `STreeVirtualizer` layers virtualization on top to smoothly handle 1000+ nodes. Node content is fully customized through the `item` slot — icons, checkboxes, indentation, and connector lines are all injected by the consumer.
- [TreeMenu](/components/tree-menu.md): A collapsible sidebar navigation tree-menu component. `STreeMenu` combines the headless `TreeMenuCompact` family of composite components (`TreeMenuRoot`/`TreeMenuOptionCompact`/`TreeMenuSlotCompact`, zero-style) with the `TreeMenuRoot` context (controlled/uncontrolled activation and expansion, collapsed sidebar mode, flyout submenus when collapsed, action menus); the UI layer only injects the 8-step size recipe and slot classes. The recursive `items` data model ships with built-in `icon`/`badge`/`tag`/`actions`/`isGroup`/link fields, and node content can be freely customized through the `item`/`item-leading`/`item-trailing` slots.
- [TreeNav](/components/tree-nav.md): TreeNav is a data-driven horizontal navigation bar with a persistent selection state: top-level entries sit in a row, branch entries open dropdown popups (hover by default), and selecting any leaf keeps the whole ancestor chain highlighted.
- [Virtualizer](/components/virtualizer.md): A virtual scrolling component that efficiently renders large lists by only rendering items currently in the viewport. `SVirtualizer` wraps the headless `VirtualizerRoot`/`VirtualizerContent` primitives (built on `@tanstack/vue-virtual`) — only the visible window of items is mounted into the DOM, keeping large lists fast.
- [Visually Hidden](/components/visually-hidden.md): `VisuallyHidden` is a utility component that hides content from the screen but keeps it accessible to screen readers. It is essential for accessibility when you want to provide context to users relying on assistive technologies without affecting the visual design.
- [Watermark](/components/watermark.md): `SWatermark` overlays a repeating text or image pattern on top of page content to indicate ownership, confidentiality, or branding. It generates a tiled canvas data URL as the overlay's `background-image`, supports text and image watermarks with rotation, gap, offset, and cross-pattern configuration, and includes an optional anti-tamper defense mechanism that automatically restores the overlay if it is removed or modified via DevTools.
- [@soybeanjs/admin](/overview/admin/index.md): > SoybeanAdmin — admin shell components built on top of SoybeanUI.
- [Installation](/overview/admin/installation.md): > TODO(admin): scaffold placeholder — fill installation steps.
- [Quick Start](/overview/admin/quick-start.md): > TODO(admin): scaffold placeholder — fill quick start guide.
- [@soybeanjs/chart](/overview/chart/index.md): > SoybeanChart — chart components built on top of SoybeanUI.
- [Installation](/overview/chart/installation.md): > TODO(chart): scaffold placeholder — fill installation steps.
- [Quick Start](/overview/chart/quick-start.md): > TODO(chart): scaffold placeholder — fill quick start guide.
- [Installation](/overview/installation.md): SoybeanUI offers two ways to add components to your project. Choose the one that fits your workflow.
- [Introduction](/overview/introduction.md): SoybeanUI is an elegant, modern, accessible, and high-quality UI component system designed for Vue 3. It supports **two distribution modes** — install as a traditional npm package, or copy source code directly into your project via the `sbean` CLI (shadcn-style). Built on a powerful Headless foundation, it provides a comprehensive set of accessible, customizable, and high-performance components to help developers build modern web applications quickly.
- [LLMs.txt](/overview/llms.md): How to use SoybeanUI's generated llms.txt routes with AI tools such as Cursor, Windsurf, GitHub Copilot, ChatGPT, and Claude.
- [Quick Start](/overview/quick-start.md): SoybeanUI offers two ways to integrate components into your project. This guide covers both paths — choose the one that fits your workflow.
- [CLI](/overview/sbean.md): sbean CLI tool reference
- [Skills](/overview/skills.md): Install SoybeanUI skills so AI coding agents can understand the styled and headless packages, component patterns, theming, and generated references.
- [Theming](/overview/theming.md): Soybean UI provides a flexible theming system that allows you to customize the appearance of components to match your application's design requirements. You can easily adjust colors, radius and global size settings.
- [Actions](/overview/ui-x/components/actions.md): `SxActions` is a compact action toolbar that renders a horizontal row of buttons, each representing a user action on an AI message (e.g., copy, like, dislike, share, regenerate).
- [ActionsCopy](/overview/ui-x/components/actions-copy.md): `SxActionsCopy` is a single-button copy action that copies a given text to the clipboard and shows a brief success state (✓/Copied) for 1.5 seconds.
- [ActionsFeedback](/overview/ui-x/components/actions-feedback.md): `SxActionsFeedback` is a like/dislike feedback control that lets users rate an AI response with two toggle buttons. Clicking the currently active polarity clears the selection back to `null`.
- [Attachments](/overview/ui-x/components/attachments.md): `SxAttachments` is the AI attachment strip — a vertical list of attachment previews with built-in select and remove actions. It renders one `SxFileCard` per attachment and delegates all visual details (icon, name, meta line) to that sibling component.
- [Bubble](/overview/ui-x/components/bubble.md): `SxBubble` renders a single chat message bubble — the atomic message unit of an AI conversation UI. It displays one message (user, AI, system or divider) with configurable placement, visual variant, a loading state and an optional typewriter animation.
- [BubbleList](/overview/ui-x/components/bubble-list.md): `SxBubbleList` renders a data-driven chat transcript from a `ChatMessage[]`. It owns the scroll container, auto-follows new messages while the user is at the bottom, and renders each item through the default `SxBubble` — user messages at the `end`, everything else at the `start`.
- [CodeBlock](/overview/ui-x/components/code-block.md): `SxCodeBlock` is a styled code block for AI output that shows a language label, a copy button, and (optionally) shiki syntax highlighting. It is a self-contained single-export component in `@soybeanjs/ui-x`.
- [Conversations](/overview/ui-x/components/conversations.md): `SxConversations` is the AI conversation sidebar list — a grouped, selectable list of conversation items with active state tracking. It groups items by their `group` field and renders group headers automatically.
- [FileCard](/overview/ui-x/components/file-card.md): `SxFileCard` is the atomic file preview card of the AI package — a single attachment rendered as a kind icon, file name and meta line (`mimeType · size`). It is the building block used by `SxAttachments` to render its list items.
- [Folder](/overview/ui-x/components/folder.md): `SxFolder` is a collapsible folder component that presents a folder-style header (name, optional icon, and optional item-count badge) above a toggleable content area.
- [Markdown](/overview/ui-x/components/markdown.md): `SxMarkdown` is a streaming markdown renderer built for AI chat output. It is a thin styled wrapper around `markstream-vue`'s `MarkdownRender` (importing `markstream-vue/index.css`) that gives you incremental rendering of AI output as it arrives.
- [Mermaid](/overview/ui-x/components/mermaid.md): `SxMermaid` is a styled Mermaid diagram renderer for AI output. It renders diagram source (`code`) into an inline SVG via `mermaid` and offers an image/code mode toggle.
- [Notification](/overview/ui-x/components/notification.md): `SxNotification` is a styled inline notification for AI output with four visual tones — `info`, `success`, `warning`, and `error`. It announces status with `role="status"` and pairs an icon, title, and optional description with a close button.
- [Prompts](/overview/ui-x/components/prompts.md): `SxPrompts` is the AI prompt pill row — a responsive row of clickable prompt buttons that give users quick, one-tap starter questions. It is the reusable building block inside `SxWelcome` and can also be used standalone under a `SxSender`.
- [Sender](/overview/ui-x/components/sender.md): `SxSender` is the AI composer input — a rich textarea with optional attachments, slash (`/`) command suggestions and mention (`@`) suggestions. It submits the typed text and delegates suggestion filtering/selection to the `useSender` composable.
- [Sources](/overview/ui-x/components/sources.md): `SxSources` is the AI citation list — a vertical list of reference sources used to answer a message. Each item is prefixed with a paperclip and either renders as an external link or a plain label.
- [Suggestion](/overview/ui-x/components/suggestion.md): `SxSuggestion` is the AI follow-up chip row — a compact row of small suggestion chips shown after an assistant message. It lets users continue, regenerate or drill into the last answer with one tap.
- [Think](/overview/ui-x/components/think.md): `SxThink` is a collapsible AI "deep thinking" panel that reveals the model's reasoning process behind an answer. It opens as a toggleable section with a header button and expandable content area, making it easy to show or hide the chain-of-thought trace.
- [ThoughtChain](/overview/ui-x/components/thought-chain.md): `SxThoughtChain` is a structured reasoning step display that renders an ordered list of AI thinking stages. Each step shows a status symbol, title, optional icon, and expandable body content for steps with details.
- [Welcome](/overview/ui-x/components/welcome.md): `SxWelcome` is the AI chat greeting screen — a centered welcome panel with an optional title, description and a list of recommended prompts. It is the first thing a user sees in a fresh chat.
- [Internationalization](/overview/ui-x/i18n.md): UI-X components are locale-aware and integrate with the same i18n system used by `@soybeanjs/ui`.
- [@soybeanjs/ui-x](/overview/ui-x/index.md): > SoybeanUI-X — AI conversation UI components built on top of SoybeanUI.
- [Installation](/overview/ui-x/installation.md): Install `@soybeanjs/ui-x` via your favorite package manager:
- [Quick Start](/overview/ui-x/quick-start.md): Once installed, UI-X components are used just like `@soybeanjs/ui` components: import the stylesheet, then render `Sx*` components.
- [Theming](/overview/ui-x/theming.md): UI-X inherits the theme system from `@soybeanjs/ui`. All theme tokens (colors, sizes, radii) are shared between UI and UI-X components.