EmptyState | Tuff Docs

Usage

variant picks the preset title, description, and illustration; primaryAction and secondaryAction generate the buttons.

Loading demo...

Loading demo...

variant="custom" has no preset copy or illustration; the slots supply everything.

Loading demo...

Loading demo...

Pick the closest preset before overriding copy: search-empty for filters, no-selection for split panes, permission for access, offline for network failures.
Make the title situational and actionable: "No automation rules yet", not "Empty".
Switch loading, empty, and error states inside one data container to avoid layout jumps.
Use primaryAction / secondaryAction for standard flows; use the actions slot only for a custom layout.
Use surface="card" in dashboards and panels; keep plain inside tables, drawers, and cards that already frame it.

Prop	Type	Default	Description
`variant`	`EmptyStateVariant`	`'empty'`	Preset title, description, and illustration.
`title`	`string`	-	Overrides the preset title; an empty string hides it.
`description`	`string`	-	Overrides the preset description; an empty string hides it.
`icon`	`TxIconSource \| string \| null`	-	Icon source or class that replaces the illustration; `null` hides the icon area.
`iconSize`	`number`	size preset	Icon or spinner size in px; defaults to `28`, `36`, or `44` by `size`.
`layout`	`'vertical' \| 'horizontal'`	`'vertical'`	Stacks the icon and content, or places them side by side.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Aligns the icon, copy, and actions.
`size`	`'small' \| 'medium' \| 'large'`	`'medium'`	Spacing, text scale, and illustration size.
`surface`	`'plain' \| 'card'`	`'plain'`	`card` adds a bordered card surface.
`primaryAction`	`EmptyStateAction`	-	Renders the primary button, which emits `primary`.
`secondaryAction`	`EmptyStateAction`	-	Renders the secondary button before the primary one; it emits `secondary`.
`actionSize`	`TxButtonProps['size']`	`'sm'`	Default size of the generated buttons.
`loading`	`boolean`	`false`	Shows `TxSpinner` when no custom icon is given.

Event	Payload	Description
`primary`	-	Fires when the generated primary button is clicked.
`secondary`	-	Fires when the generated secondary button is clicked.

Slot	Props	Description
`icon`	-	Replaces the illustration, the spinner, or `icon`.
`title`	-	Replaces the title.
`description`	-	Replaces the description.
`actions`	-	Replaces the generated primary and secondary buttons.

Prop	Type	Default	Description
`label`	`string`	-	Button text.
`type`	`TxButtonProps['type']`	-	Tone forwarded to `TxButton`.
`variant`	`TxButtonProps['variant']`	-	Visual variant forwarded to `TxButton`.
`size`	`TxButtonProps['size']`	-	Per-button size; falls back to `actionSize`.
`disabled`	`boolean`	`false`	Disables the button, which then emits nothing.
`icon`	`string`	-	Icon class forwarded to `TxButton`.

Variant	Default title	Default description	Illustration source
`empty`	`Nothing here`	`There is nothing to show yet.`	Built-in SVG illustration.
`blank-slate`	`Start from scratch`	`Create your first item to get started.`	Built-in SVG illustration.
`no-data`	`No data`	`No data available yet.`	Built-in SVG illustration.
`no-selection`	`Nothing selected`	`Select an item to see details.`	Built-in SVG illustration.
`search-empty`	`No results`	`Try a different keyword or filter.`	Built-in SVG illustration.
`loading`	`Loading`	`Please wait a moment.`	Built-in skeleton illustration; a spinner when `loading=true`.
`offline`	`You are offline`	`Check your connection and retry.`	Built-in SVG illustration.
`permission`	`Access denied`	`You do not have permission to view this content.`	Built-in SVG illustration.
`error`	`Something went wrong`	`Please try again later.`	Built-in SVG illustration.
`guide`	`Start here`	`Follow the steps to get started.`	Built-in SVG illustration.
`custom`	empty	empty	None unless `icon` or the `icon` slot is provided.

Each preset fixes variant and forwards every other prop, event, and slot to TxEmptyState unchanged.

Component	Forced variant	Notes
`TxBlankSlate`	`blank-slate`	Defaults to `size="large"`, `layout="vertical"`, and `surface="plain"`.
`TxLoadingState`	`loading`	Loading placeholder.
`TxNoSelection`	`no-selection`	Detail pane before a list item is selected.
`TxNoData`	`no-data`	Successful load with no data.
`TxSearchEmpty`	`search-empty`	Search or filter with no matches.
`TxOfflineState`	`offline`	Network unavailable.
`TxPermissionState`	`permission`	Access denied.
`TxErrorState`	`error`	Error.
`TxGuideState`	`guide`	Guided onboarding.

The variant preset resolves first, then explicit props apply; a slot wins over generated content in its region.
The actions slot replaces both generated buttons; generated buttons render secondary first, then primary.
icon=null hides the illustration; loading swaps in TxSpinner only when there is no icon slot and icon is empty.
surface="card" adds visual containment only; semantics and button behavior are unchanged.
Under reduced motion, every illustration rests on a complete still frame.

Source: packages/tuffex/packages/components/src/empty-state/; each preset lives in its own directory.

packages/tuffex/packages/components/src/empty-state/index.ts