Design System

Component reference and live examples.

Api Reference Colors Typography Buttons Badges Form Controls Form Patterns Cards Data Display Feedback Overlays Floating Navigation Layout Primitives Utility

API Reference

Props and variants for key components.

Button

Prop	Type	Default	Description
`variant`	"default" \| "destructive" \| "outline" \| "secondary" \| "amber" \| "ghost" \| "link"	`"default"`	Visual style of the button
`size`	"default" \| "sm" \| "lg" \| "icon"	`"default"`	Button size
`asChild`	boolean	`false`	Merge props onto child element instead of rendering a <button>

Badge

Prop	Type	Default	Description
`variant`	"default" \| "secondary" \| "destructive" \| "outline" \| "success" \| "warning" \| "error"	`"default"`	Visual style and color of the badge

Card

Prop	Type	Default	Description
`interactive`	boolean	`false`	Adds hover border, shadow lift, and press-down effect

Input

Prop	Type	Default	Description
`type`	string	—	HTML input type (text, email, password, etc.)
`className`	string	—	Additional classes. Uses border-2 and focus:ring by default.

Field

Prop	Type	Default	Description
`error`	boolean	`false`	Applies error styling to label and child inputs
`id`	string	—	Custom id — auto-generated if not provided

Combobox

Prop	Type	Default	Description
`options`	{ value: string; label: string }[]	—	List of selectable options
`value`	string \| string[]	—	Currently selected value(s)
`onValueChange`	(value) => void	—	Callback when selection changes
`multiple`	boolean	`false`	Enable multi-select mode
`placeholder`	string	`"Select..."`	Text shown when nothing is selected
`searchPlaceholder`	string	`"Search..."`	Placeholder inside the search input
`emptyMessage`	string	`"No results found."`	Message when no options match the search

DataTable

Prop	Type	Default	Description
`columns`	ColumnDef<TData>[]	—	TanStack Table column definitions
`data`	TData[]	—	Array of row data
`toolbar`	ReactNode	—	Optional toolbar rendered above the table

DatePicker

Prop	Type	Default	Description
`date`	Date	—	Currently selected date
`onDateChange`	(date: Date \| undefined) => void	—	Callback when a date is selected
`placeholder`	string	`"Pick a date"`	Text shown when no date is selected

SearchField

Prop	Type	Default	Description
`value`	string	—	Current search string
`onChange`	(value: string) => void	—	Callback when the search value changes
`placeholder`	string	`"Search..."`	Input placeholder text
`shortcut`	string	—	Optional keyboard shortcut hint (e.g. "/")
`onClear`	() => void	—	Optional callback when the clear button is clicked

Stack

Prop	Type	Default	Description
`gap`	"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"	`"md"`	Vertical spacing between children
`align`	"start" \| "center" \| "end" \| "stretch"	`"stretch"`	Cross-axis alignment
`asChild`	boolean	`false`	Merge props onto child element

Cluster

Prop	Type	Default	Description
`gap`	"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"	`"sm"`	Spacing between items
`align`	"start" \| "center" \| "end" \| "baseline"	`"center"`	Cross-axis alignment
`justify`	"start" \| "center" \| "end" \| "between"	`"start"`	Main-axis justification
`wrap`	boolean	`true`	Allow items to wrap to the next line

Grid

Prop	Type	Default	Description
`columns`	1 \| 2 \| 3 \| 4 \| 5 \| 6 \| "auto-fill" \| "auto-fit"	`1`	Number of columns or auto layout mode
`gap`	"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"	`"md"`	Gap between grid cells
`minChildWidth`	string	—	Minimum child width for auto modes (e.g. "280px")

Center

Prop	Type	Default	Description
`max`	"sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "full"	`"2xl"`	Maximum width constraint
`padding`	boolean	`true`	Apply responsive horizontal padding

Alert

Prop	Type	Default	Description
`variant`	"default" \| "destructive" \| "success" \| "warning"	`"default"`	Visual style and color of the alert

Spinner

Prop	Type	Default	Description
`size`	"sm" \| "default" \| "lg"	`"default"`	Spinner diameter

Empty

Prop	Type	Default	Description
`children`	ReactNode	—	Compose with EmptyIcon, EmptyTitle, EmptyDescription, EmptyAction

FormSection

Prop	Type	Default	Description
`children`	ReactNode	—	Compose with FormSectionHeader, FormSectionTitle, FormSectionDescription, FormSectionContent

FormSectionContent

Prop	Type	Default	Description
`layout`	"stack" \| "grid"	`"stack"`	Layout mode — "grid" renders a responsive two-column grid

StatCard

Prop	Type	Default	Description
`title`	string	—	Metric label displayed above the value
`value`	string	—	Primary metric value
`change`	string	—	Optional delta text (e.g. "+12.5%")
`changeType`	"positive" \| "negative" \| "neutral"	`"neutral"`	Color of the change text
`icon`	ComponentType	—	Optional icon component rendered top-right

AppShellNavItem

Prop	Type	Default	Description
`href`	string	—	Navigation link URL
`icon`	ComponentType	—	Icon component rendered before the label
`active`	boolean	`false`	Highlights the item as the current page

Colors

Raw palette, semantic tokens, and status colors.

Plum

100

200

300

400

500

600

700

800

900

950

Amber

100

200

300

400

500

600

700

800

Warm Neutrals

100

200

300

400

500

600

700

800

900

950

Semantic Tokens

background

card

sunken

raised

interactive

primary

destructive

accent

Status Colors

success

warning

error

Typography

Every typographic component with sample text.

H1

Heading One

H2

Heading Two

H3

Heading Three

H4

Heading Four

P

This is a paragraph of body text used across the interface.

Lead

Lead text for introductions and summaries.

Large

Large emphasis text.

Small

Small caption text.

Muted

Muted secondary text for descriptions.

Code

const x = 42;

Mono

Monospaced text for data display.

Buttons

All variants, sizes, and states.

Variants

Sizes

Disabled

Button Group

Click any button to see the press-down effect.

Badges

Status indicators and labels.

Default

Secondary

Destructive

Outline

Success

Warning

Error

Form Controls

Individual form elements and input types.

Input

Please enter a valid email address.

Textarea

Select

Checkbox

Unchecked

Checked

Disabled

Radio Group

Option One

Option Two

Option Three

Switch

Off

Disabled

Slider

Value: 50

Combobox

Date Picker

Native Select

Input OTP

[data-input-otp] { --nojs-bg: white !important; --nojs-fg: black !important; background-color: var(--nojs-bg) !important; color: var(--nojs-fg) !important; caret-color: var(--nojs-fg) !important; letter-spacing: .25em !important; text-align: center !important; border: 1px solid var(--nojs-fg) !important; border-radius: 4px !important; width: 100% !important; } @media (prefers-color-scheme: dark) { [data-input-otp] { --nojs-bg: black !important; --nojs-fg: white !important; } }

Search Field

Form Patterns

Structured form layout with sections and validation.

Cards

Content containers with optional interactivity.

Default Card

A standard card with header, content, and footer.

Card content goes here. This is a simple example of a card layout.

Interactive Card

Hover over this card to see the interactive effect.

This card responds to hover with a subtle visual change.

Card 1

Grid card example.

Content for card 1.

Card 2

Grid card example.

Content for card 2.

Card 3

Grid card example.

Content for card 3.

Data Display

Tables, accordions, and tabbed content.

Table

Name	Email	Role	Status
Alex Chen	alex@example.com	Engineering	Active
Sarah Kim	sarah@example.com	Design	Active
James Wilson	james@example.com	Product	Pending
Maria Garcia	maria@example.com	Engineering	Active
David Park	david@example.com	Marketing	Inactive

Data Table


Alex Chen	alex@example.com	Engineering	Active
Sarah Kim	sarah@example.com	Design	Active
James Wilson	james@example.com	Product	Pending
Maria Garcia	maria@example.com	Engineering	Active
David Park	david@example.com	Marketing	Inactive

0 of 5 row(s) selected.

Page 1 of 1

Accordion

Tabs

Overview content with project summary and key metrics.

Feedback

Alerts, progress indicators, and loading states.

Alerts

Information

This is a default informational alert.

Success

Your changes have been saved successfully.

Warning

Please review your input before continuing.

Error

Something went wrong. Please try again.

Progress

Spinner

default

Skeleton

Empty State

No results found

Try adjusting your search or filters to find what you're looking for.

Overlays & Floating

Dialogs, sheets, popovers, tooltips, and menus.

Context Menu

Right-click here to open the context menu

Layout Primitives

Composable layout components for spacing and alignment.

Stack

Stack item 1

Stack item 2

Stack item 3

Stack item 4

Cluster

Tag 1

Tag 2

Tag 3

Tag 4

Tag 5

Tag 6

Grid

Grid 1

Grid 2

Grid 3

Grid 4

Grid 5

Grid 6

Center

This page uses Center max="xl" for its main content area.

Divider

With Label

Spacer

Left

Right

Utility

Keyboard hints, avatars, separators, and more.

Kbd

K⌘+K

Avatar

SCAC

Separator

Item A

Item B

Item C

Scroll Area

Scrollable item 1

Scrollable item 2

Scrollable item 3

Scrollable item 4

Scrollable item 5

Scrollable item 6

Scrollable item 7

Scrollable item 8

Scrollable item 9

Scrollable item 10

Scrollable item 11

Scrollable item 12

Scrollable item 13

Scrollable item 14

Scrollable item 15

Scrollable item 16

Scrollable item 17

Scrollable item 18

Scrollable item 19

Scrollable item 20

Aspect Ratio

16:9

Design System

API Reference

Button

Badge

Card

Input

Field

Combobox

DataTable

DatePicker

SearchField

Stack

Cluster

Grid

Center

Alert

Spinner

Empty

FormSection

FormSectionContent

StatCard

AppShellNavItem

Colors

Plum

Amber

Warm Neutrals

Semantic Tokens

Status Colors

Typography

Heading One

Heading Two

Heading Three

Heading Four

Buttons

Variants

Sizes

Disabled

Button Group

Badges

Form Controls

Input

Textarea

Select

Checkbox

Radio Group

Switch

Slider

Combobox

Date Picker

Native Select

Input OTP

Search Field

Form Patterns

Cards

Data Display

Table

Data Table

Accordion

What is SubstrateUI?

How do I install it?

Is it accessible?

Tabs

Feedback

Alerts

Information

Success

Warning

Error

Progress

Spinner

Skeleton

Empty State

No results found

Overlays & Floating

Context Menu

Navigation

Breadcrumb

Pagination

Navigation Menu

Layout Primitives