Skip to content

OrigamEmptyState ​

A placeholder shown when a list, table, or any collection has nothing to render. Five presets cover the most common cases (no data yet, no search results, an error, offline, locked content); five slots let you swap a single piece or replace the whole layout.

vue
<template>
    <origam-empty-state
            preset="no-data"
            title="No items yet"
            description="Create your first item to get started."
            size="md"
    >
        <template #actions>
            <origam-btn @click="create">Create item</origam-btn>
        </template>
    </origam-empty-state>
</template>

Presets ​

PresetDefault iconIntentWhen to reach for it
no-datamdi:mdi-database-off-outlineneutralThe collection has never had data — first-run / empty inbox / new project.
no-resultsmdi:mdi-magnify-closeneutralA search or filter returned nothing — surface "broaden filters" CTA.
errormdi:mdi-alert-circle-outlinedangerAn operation failed — surface a Retry CTA.
offlinemdi:mdi-wifi-offwarningNetwork is down — surface "Switch to offline mode" / "Retry".
lockedmdi:mdi-lock-outlinesecondaryGated by plan / auth / permissions — surface Sign-in / Upgrade.

Each preset bundles a default icon + iconColor; override either via the matching props for the 5% case (e.g. brand-specific illustration on top of the error preset).

Props ​

PropTypeDefaultNotes
preset'no-data' | 'no-results' | 'error' | 'offline' | 'locked''no-data'Bundles a default icon + intent — see Presets.
titlestringundefinedPrimary heading. Override via #title slot for richer markup.
descriptionstringundefinedOptional sub-heading.
iconTIconper-presetOverrides the preset icon. Same shape as <OrigamIcon>.
iconColorTIntentper-presetOverrides the preset's icon color (semantic intent).
size'sm' | 'md' | 'lg''md'Drives icon size, font sizes, padding, gap.
align'center' | 'left''center'Horizontal alignment of the stack.
tagstring'div'Root element tag.
fontFamilyTFontFamilyundefinedFont family token applied to both the title and description (sans · mono · serif).
fontSizeTFontSizeundefinedFont size token applied to both surfaces. Overrides the size-driven font-size when set; size drives when unset.
fontWeightTFontWeightundefinedFont weight token applied to both surfaces.
lineHeightTLineHeightundefinedLine-height token applied to both surfaces.

Typography props come from the shared ITypographyProps surface and act on both text surfaces (title + description) at once. letterSpacing was removed from IEmptyStateProps (issue #501) — neither surface declares a letter-spacing rule.

Slots ​

SlotPurpose
defaultReplaces the entire built-in layout. Use for bespoke hero placeholders.
iconReplaces the default <OrigamIcon>. Use for SVG / <img> illustrations.
titleReplaces the rendered title element. Slot wins over the title prop.
descriptionReplaces the rendered description element. Slot wins over the description prop.
actionsActions row rendered below the description. Typically 1–2 buttons (Create / Retry / …).

Examples ​

vue
<origam-empty-state
        preset="no-data"
        title="No items yet"
        description="Create your first item to get started."
>
    <template #actions>
        <origam-btn intent="primary" @click="create">Create item</origam-btn>
    </template>
</origam-empty-state>

<origam-empty-state
        preset="error"
        title="Something went wrong"
        description="We could not load this list. Retry in a few seconds."
>
    <template #actions>
        <origam-btn @click="retry">Retry</origam-btn>
    </template>
</origam-empty-state>

<origam-empty-state
        preset="no-results"
        title="No matches found"
        description="Try a different keyword or broaden the filters."
>
    <template #icon>
        <svg viewBox="0 0 64 64" aria-hidden="true">
            <circle cx="28" cy="28" r="18" fill="none" stroke="currentColor" stroke-width="3"/>
            <line x1="42" y1="42" x2="56" y2="56" stroke="currentColor" stroke-width="3"/>
        </svg>
    </template>
</origam-empty-state>

Accessibility ​

  • The root carries role="status" and aria-live="polite" so an empty state appearing dynamically (e.g. after a search filter clears the list) is announced passively by screen readers.
  • The icon is decorative (the title and description carry the semantic) — the icon container is marked aria-hidden="true" so assistive tools do not announce it.
  • The actions slot is just a flex row; place your actionable controls (buttons, links) inside it directly — they keep their own semantics and keyboard handling.
  • When passing a custom SVG illustration through the #icon slot, ensure it carries aria-hidden="true" if it is decorative, or the appropriate <title> / aria-label if it carries meaning not duplicated by the text.
  • OrigamAlert — surface a warning / feedback message inline alongside existing data. Use Alert for "something is happening", EmptyState for "there is nothing to show".