v0.0.14
@xds/core
The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.1. Install the package
bash
2. Import a component
typescript
Components (168)
AppShellThe outermost layout for an application. Provides slots for top navigation, side navigation, banners, and main content. Use it as the root wrapper for every page — it handles responsive collapse, skip-to-content, and mobile navigation automatically.
AspectRatioMaintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.
BadgeBadge shows a short label like a status, count, or category. Use it in table rows, list items, navigation, and anywhere you need to call out a state or group at a glance.
BannerBanner shows a persistent message at the top of a page or section. Use it for form errors, system updates, maintenance notices, or success confirmations that the user needs to see until they act on it.
BlockquoteA styled quotation block with an accent-colored left border and secondary text color. Use to highlight quoted content, testimonials, or excerpts.
Button +4Button triggers an action when clicked. Use it for form submissions, confirmations, navigation, or any interaction that needs a clear call to action.
CalendarCalendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.
CardCard groups related content into a visually distinct container with a border and background. Use it for profile cards, settings panels, data summaries, or any content that needs to stand out from the page.
CarouselCarousel scrolls a row of items horizontally when they overflow the available width. Use it for card grids, image galleries, product lists, or any set of items that should be browsable without taking up the full page.
Chat +14Layout shell for a chat composer. Arranges named slots (drawer, header, input, footer, send) with page-radius container, hover/focus shadows, and concentric inner radius for child elements.
Checkbox +2CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.
CircularProgressA circular progress indicator that shows completion as a ring or arc. Use it for upload progress, score displays, dashboard gauges, or compact progress where horizontal space is limited. Complements XDSProgressBar for radial layouts.
ClickableCardAn interactive card for navigation or action targets. Nested interactive elements work independently.
CodeInline code element. Renders a styled <code> with monospace font and muted background. For fenced blocks, use XDSCodeBlock.
Collapsible +2A primitive that makes any content collapsible — a trigger button toggles visibility of the content area, managing its own state or deferring to a parent XDSCollapsibleGroup.
CommandPalette +6Root component. Manages open state, search, keyboard navigation, and composition slots.
ContextMenu +1A context menu that appears on right-click at the cursor position. Wraps trigger content as children.
DateInputDateInput lets the user type or pick a date from a calendar popover. Use it for scheduling, deadlines, booking dates, or any form field that needs a specific calendar date.
DateRangeInputDateRangeInput lets users select a start and end date from a dual-month calendar popover. Use it for filtering data by time period, report generation, analytics dashboards, and booking flows.
DateTimeInputDateTimeInput combines a calendar popover with a time input for selecting both a date and time in a single interaction flow. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.
DividerA visual separator that divides content into distinct sections. Use to create clear boundaries between groups of related content, or to demarcate interactive regions within a layout.
EmptyStateEmptyState shows a placeholder when a content area has no data. Use it for empty lists, zero search results, first-time setups, or cleared inboxes. Always include a title and a next step so the user is not stuck.
FileInputFileInput provides file upload with optional drag-and-drop support. Use it for single or multiple file selection with built-in validation for file type, size, and count. Pair with validation status for upload feedback.
HeadingSemantic heading component that renders h1–h6 elements with themed styling, themed sizing via type scale tokens, and line-clamp truncation.
HoverCard +1Component wrapper for hover card display — a richer, larger overlay triggered on hover or focus.
IconIcons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.
ItemA universal item primitive that unifies the "media + label + description + trailing content" layout pattern. Use as a building block for list items, menu items, contact rows, notifications, and more.
KbdRenders a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and help text to show key combinations.
Layout +13Page shell with header, sidebar(s), content, and footer slots for building full app layouts.
LightboxA fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.
MarkdownRenders a markdown string as XDS-styled components. Use Markdown for user-generated content, AI responses, and documentation — it handles headings, lists, tables, code blocks, and citations with consistent styling.
MobileNavA slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical.
MoreMenuMoreMenu is a three-dot button that opens a list of actions. Use it for secondary actions that don't need to be always visible, like in table rows, card headers, or toolbars.
NavHeadingMenuAccessible menu container and items for nav heading popovers. XDSNavHeadingMenu provides role="menu" with keyboard navigation; XDSNavHeadingMenuItem renders individual selectable items. Pass as the menu prop of XDSSideNavHeading or XDSTopNavHeading.
NavIconNavIcon is a circular icon container with an accent-colored background. Use it in navigation headers such as TopNavHeading and PageNavHeader to visually identify a section or application.
NumberInputA form input for numeric values with built-in validation, min/max constraints, and step controls. Use NumberInput for quantities, measurements, percentages, and similar inputs.
OverflowListA horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.
PaginationPagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context — numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.
Popover +1A click-triggered popover for displaying interactive content anchored to a trigger element.
PowerSearchPowerSearch is a structured filter bar where each token represents a field, operator, and value. Use it for complex multi-dimensional filtering when users need to combine multiple search criteria. For simple single-field search, use a text input instead.
ProgressBarA horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.
Resizable +1Draggable separator between panels. Pill-grip design: invisible at rest, visible on hover (0.6 opacity), fully opaque during drag (1.0). Keyboard-accessible.
SegmentedControl +1Container wrapper providing context (value, onChange, size, isDisabled) to XDSSegmentedControlItem children.
SelectableCardA card that toggles between selected and unselected states with an accent border. For navigation use ClickableCard.
SideNav +4Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible mode.
SkeletonAn animated shimmer placeholder that previews the shape of content while it loads. Use it to build loading screens that match the layout of the real content. For content with unknown dimensions, use Spinner instead.
SliderA draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.
SpinnerAn animated loading indicator for processes with unknown duration, such as data fetching or form submission. Supports visible labels, multiple sizes, and a dark background variant. For content with known dimensions, use Skeleton instead.
StatusDotA small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.
Stepper +1Container component that manages step state and renders steps in horizontal or vertical orientation.
SwitchA toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.
Table +9Styled, data-driven table with density, dividers, hover highlight, striped rows, and named plugin support.
Tabs +2Individual tab item that renders as a button or an anchor link, with selected-state styling and optional icons.
TextSemantic body text component that renders text with type-based styling from the theme, with optional truncation, decoration, and layout props.
TextAreaTextArea is a multi-line text input for collecting longer-form content like comments, descriptions, or messages. Use it when the expected input spans multiple lines. For shorter, single-line values, use TextInput.
TextInputTextInput collects short-form text like names, emails, or search queries. Use it for single-line values where the expected input is brief. Pair it with validation status to guide users through required or formatted fields.
ThumbnailThumbnail displays a compact, square preview of an image attachment. It shows a shimmer effect while uploading, the image on success, and a placeholder icon when no source is set. Use it in chat composers, file upload lists, or anywhere you need a small image preview with optional remove and click actions.
TimeInputTimeInput lets users enter a time of day and converts it to a standard format. It also allows users to adjust times using the arrow keys. Use it in forms, scheduling flows, or any interface where users need to select a specific time.
TimestampTimestamp formats a date or time value into human-readable text. Use it to show when something was created, updated, or is scheduled — picking relative for recency, absolute for precision, or auto to let the component decide.
Toast +1Toast shows a brief, non-blocking notification to confirm an action or present temporary information. Use it for scenarios where the user needs feedback but not a decision, such as saving, deleting, or changing a status.
For production use, prefer the `useXDSToast()` hook — it handles positioning, stacking, auto-dismiss, and deduplication via `XDSToastViewport`. The `XDSToast` component renders the visual toast element inline and is useful for previews, documentation, and static showcases where the viewport lifecycle is not needed.
TokenToken is a small, inline element for representing discrete pieces of associated data — like tags, categories, or selections. Use it to label content, show active filters, or represent removable items like selected recipients in a compose field.
TokenizerTokenizer is a multi-select input that lets users search, select, and manage multiple items displayed as removable chips. Use it when users need to build a set of selections from a searchable data source, like adding team members, applying tags, or choosing filters.
TopNav +6Main navigation bar container with slot-based layout. Children are accepted as an alias for startContent.