EmptyState

Usage

• Use EmptyState when a page, panel, or table has no content to display, and guide users to a solution through actions and supplementary resources.
• Use it for first-use experiences, no-result states after filters or searches, error recovery, and feature promotion.
• Use EmptyState when the content area is empty and needs an explanation. Use Banner instead when the page already has content and you need to surface a message within its workflow.
• Include at least a title or a description — one of the two is required.
• Include both a title and a description for most cases, and add actions that lead to the EmptyState's removal.
• Use the full composition (EmptyStateTitle, EmptyStateDescription, EmptyStateActions, EmptyStateFooter, EmptyStateGraphic) for experiences brand new to the user.
• Limit actions to two buttons, provide at least one primary action, and place the primary action first.
• Choose an icon that reflects the content type that is missing or the feature being introduced, never a generic warning icon for a non-error state.

Types

• Default (variant="default") — informs users of actions they can take when data isn't available.
• Promotion (variant="promotion") — introduces a feature with a larger title, an optional eyebrow badge, and a graphic for visual emphasis.

Appearance

• Icon (icon on EmptyStateTitle) — adds visual context supporting the title and description.
• Custom graphic (EmptyStateGraphic) — use illustrations or images in place of the default icon for more meaningful visual storytelling.
• Graphics render above the title in the default variant and below the actions in the promotion variant.

Behaviors

• Eyebrow badge (eyebrow on EmptyStateTitle) — renders a subtle green label above the title. Use it with the promotion variant to categorize or label the feature being promoted.
• Footer (EmptyStateFooter) — always renders below the actions. Use it for supplementary text and supporting documentation links.

Content

• Write titles in sentence case, describing what's missing in a few words. Omit ending punctuation except where a question mark is required.
• Name the missing content specifically — never use vague titles such as "Nothing to see here".
• Focus first-use titles on the missing item; describe what wasn't found for no-result states.
• Frame promotion titles around the benefit the feature provides, never as an absence or a failure of the user.
• Write descriptions that offer a next step or explain why the state occurred. Keep them to one or two sentences and never restate the title.
• Write action labels that describe the specific action the user can take — never vague labels such as "Click here".
• Match tone to the situation: factual and direct for errors, friendly for first-use experiences. Never cast blame on the user.

Implementation Notes

• EmptyState is a compound component. Compose it from the EmptyStateTitle, EmptyStateDescription, EmptyStateActions, EmptyStateFooter, and EmptyStateGraphic children. Every subcomponent is optional.
• Each subcomponent occupies a named CSS grid area, so the order in which children are passed doesn't change their placement — the layout adapts to whichever subcomponents are present.
• variant is the only prop EmptyState defines and defaults to "default". It extends Box, so it also takes Box props.
• EmptyStateTitle extends Heading and renders as h3 by default. Its icon prop wraps the icon in an EmptyStateGraphic internally — never wrap a title icon in a second EmptyStateGraphic.
• eyebrow takes a plain string and renders a Label with color="green".
• EmptyStateDescription and EmptyStateFooter extend Paragraph with variant="secondary". EmptyStateGraphic extends Box and takes arbitrary visual content.
• EmptyStateActions renders a ButtonGroup with groupVariant="spaced" — pass Button children directly rather than nesting another group.
• Override the content max-width with the emptyStateWidth CSS variable, exported as vars.emptyStateWidth (defaults to 400px, and 544px for the promotion description).
• React passes content as children to each subcomponent; Ember yields it in the default block.
• Ember invocation uses <PlumaEmptyState>, <PlumaEmptyStateTitle @icon="campaigns" @eyebrow="Campaigns">, <PlumaEmptyStateDescription>, <PlumaEmptyStateActions>, <PlumaEmptyStateFooter>, and <PlumaEmptyStateGraphic>.