Empty State
Placeholder for empty lists or search results.
<arc-empty-state>Overview
EmptyState is a structured placeholder for screens, sections, or lists that have no content to display. It centralises an icon, heading, description, and action buttons into a clean, centered layout that guides users toward a next step rather than leaving them staring at a blank area. Common use cases include empty search results, first-run experiences, empty data tables, and zero-state dashboards.
The component uses a dashed border and --bg-card background to visually distinguish itself from regular content cards. The icon slot (named icon) accepts any custom icon markup (SVG, emoji, or icon-font), displayed at 40px in --text-ghost color. The heading and description are set via string properties, keeping the API simple for the most common use cases.
The action slot (named action) provides a flex container for one or more buttons, enabling patterns like "Create your first item" or "Try a different search". The description text is capped at 360px max-width for comfortable reading. The outer container uses role="status" so assistive technology announces the empty state to screen reader users.
Guidelines
When to use
- Always provide at least one action button so the user knows what to do next
- Use a relevant icon that hints at the type of missing content (search, folder, etc.)
- Write a clear, specific heading like "No results found" rather than a generic "Empty"
- Include a helpful description that explains why the area is empty or how to populate it
- Use empty state inside data tables, lists, and dashboards that can have zero items
When not to use
- Do not use empty state as a general-purpose card. It is specifically for zero-content scenarios
- Do not leave out the action slot. An empty state without a next step is a dead end
- Do not write vague descriptions like "Nothing here". Be specific about the cause and solution
- Do not use more than two action buttons. Keep the path forward simple and clear
- Do not show an empty state while data is loading. Use skeletons for loading, empty state for zero results
Features
- Quiet by default; `announce` makes it a polite live region, for an empty result the user just asked for
- Centered layout with icon, heading, description, and action button area
- Dashed border container with `--bg-card` background for visual distinction
- Named icon slot for custom SVG or emoji icons displayed at 40px
- Named action slot with flex layout for one or more CTA buttons
- Description text capped at 360px max-width for readability
- `role="status"` on the container for screen reader announcements
- CSS parts (container, icon, heading, description, actions) for styling
- Heading and description conditionally rendered only when provided
Preview
No projects yet
Create your first project to get started with ARC UI.
Usage
<arc-empty-state heading="No results found" description="Try adjusting your search.">
</arc-empty-state>import { EmptyState } from '@arclux/arc-ui-react';
export default function Example() {
return (
<EmptyState heading="No results found" description="Try adjusting your search.">
</EmptyState>
);
}<script setup>
import { EmptyState } from '@arclux/arc-ui-vue';
</script>
<template>
<EmptyState heading="No results found" description="Try adjusting your search.">
</EmptyState>
</template><script>
import { EmptyState } from '@arclux/arc-ui-svelte';
</script>
<EmptyState heading="No results found" description="Try adjusting your search.">
</EmptyState>import { Component } from '@angular/core';
import { EmptyState } from '@arclux/arc-ui-angular';
@Component({
imports: [EmptyState],
template: `
<arc-empty-state heading="No results found" description="Try adjusting your search.">
</arc-empty-state>
`,
})
export class MyComponent {}import { EmptyState } from '@arclux/arc-ui-solid';
export default function Example() {
return (
<EmptyState heading="No results found" description="Try adjusting your search.">
</EmptyState>
);
}import { EmptyState } from '@arclux/arc-ui-preact';
export default function Example() {
return (
<EmptyState heading="No results found" description="Try adjusting your search.">
</EmptyState>
);
}<!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-empty-state — requires empty-state.css + base.css (or arc-ui.css) -->
<div class="arc-empty-state">
<div class="empty" role="status">
<div class="empty__icon" aria-hidden="true">
</div>
Heading
Description text goes here
<div class="empty__actions">
</div>
</div>
</div><!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-empty-state — self-contained, no external CSS needed -->
<div class="arc-empty-state" style="display: block">
<div style="display: flex; flex-direction: column; align-items: center; text-align: center; padding: 64px 40px; border: 1px dashed rgb(34, 34, 41); border-radius: 14px; background: rgb(13, 13, 18)" role="status">
<div style="margin-bottom: 24px; color: rgb(107, 107, 128); font-size: 40px" aria-hidden="true">
</div>
Heading
Description text goes here
<div style="display: flex; gap: 8px">
</div>
</div>
</div>API
headingstring''- Main heading text displayed below the icon
descriptionstring''- Supporting text displayed below the heading, max-width 360px
announcebooleanfalse- Makes the empty state a polite live region (
role="status"), so a screen reader reads it when it appears, as for "No results" after a search the user just ran. Off by default: an empty list on page load is not news, and a live region reads out everything that changes inside it.
See Also
- ButtonPrimary call-to-action element with three visual variants that map to action hierarchy. Supports prefix and suffix slots for icons. Renders as an anchor when given an href, for navigation actions on landing pages, toolbars, and forms.
- IconRenders icons by name from any registered library. Phosphor (1,500+) and Lucide (1,900+) ship in `@arclux/arc-ui-icons`, with one-line library switching and custom icon registration.
- CTA BannerFull-width call-to-action banner with gradient background, eyebrow text, headline, body copy, and action buttons. For landing page CTAs, marketing sections, and page closers.