Empty
A placeholder for empty data, supporting titles, rich descriptions, icon media, two built-in illustrations, size tiers, horizontal alignment and container variants.
Basic usage
Basic usage
Title + description
Combine the title attribute (rendered into the visible title region; absorbed from the host on read so no native hover tooltip remains; pass an empty string to clear) with the description attribute.
Title + description
The title layer supports rich content: content in the title slot overrides the attribute text (badges, links or any markup).
Rich title (slot=title)
Description
Description text is set via the description attribute, or via rich content placed in the default slot (which overrides the attribute when present) — handy for wrapped text or usage hints.
Description attribute
Rich description (default slot)
Size tiers
size provides small / medium / large (default medium), scaling both the media and typography. image-size stays available for pixel-level tuning and takes precedence over the tier.
Size tiers
Custom illustration (image URL / SVG markup / slot)
The illustration attribute accepts an image URL or inline SVG/HTML markup; the illustration slot takes any content and has the highest priority.
Image URL
SVG markup
Slot custom illustration
Second built-in illustration
illustration="simple" switches to the built-in simple illustration (original lightweight artwork).
Simple illustration
Icon media
The icon attribute accepts an icon name (from the @oas-ui/icons registry) and renders an icon badge with a circular tinted background — mutually exclusive with the illustration form. Its color is driven by the CSS variable --oas-empty-icon-color (defaults to the secondary text color; hosts may override it).
Icon media
Icon media (custom color)
Horizontal alignment
align="start" or align="end" switches to a horizontal layout (media on the inline-start / inline-end side) — a good fit for wide containers or in-form empty states; the default center stays vertical. Mirrors automatically under RTL.
Horizontal alignment
Container variants
variant provides outlined (bordered container) and filled (tinted container); without it the empty state keeps its default bare layout.
Container variants
Hide illustration
hide-image hides the media area and keeps only the text and actions.
Hide illustration
Action area
Place action buttons in the action slot below the content.
Action area
Content composition (avatar / avatar group / search input)
The empty state has no built-in variant props for business content — compose it via slots: put oas-avatar / oas-avatar-group in the illustration slot (media area, replacing the built-in illustration), and interactive elements such as oas-input in the default slot (rich description, overriding the description attribute when non-empty) or the action slot.
Avatar (slot=illustration)
Avatar group (slot=illustration)
No search results (default slot + oas-input)
API
oas-empty
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
align | Layout alignment: center (default, vertical) / start / end (horizontal, media leading or trailing) | string | center |
description | Description text | — | — |
hide-image | Hide the illustration | — | — |
icon | Icon-set name (oas-icon icon name): icon media with a tinted circular backdrop, mutually exclusive with illustration | — | — |
illustration | Custom illustration: SVG/HTML markup or image URL | — | — |
image-size | Illustration size (px) | — | — |
size | Size preset small / medium (default) / large: scales media and font sizes; orthogonal to image-size | string | medium |
title | Title shown above the description (absorbed from the host once rendered — native title absorption; use the title slot for rich content) | string | — |
variant | Container variant: outlined (border) / filled (tinted background); none by default | string | — |
Slots
| Name | Description |
|---|---|
| default | Rich description slot; overrides the description attribute and built-in text when present |
action | Action area, placed below the description |
illustration | Custom illustration content, takes precedence over the illustration attribute |
title | Rich title slot; overrides the title attribute when present |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-empty-desc-size | var(--oas-font-size-md) |
--oas-empty-icon-color | var(--oas-color-text-secondary) |
--oas-empty-title-size | var(--oas-font-size-lg) |