Empty State Section
Explain empty, search, success, and error states with accessible actions and application content.
EmptyStateSection builds on Puzzle UI's existing EmptyState primitives. EmptyStatePanel remains available as a compact panel composition; both components share the same content and action slots.
Variants
Choose a layout based on the state and the next step rather than the illustration alone.
centered - Give an empty collection a clear focal point.
illustration - Pair the message with decorative media.
minimal - Use a quiet message inside a larger layout.
card - Contain the message and action on a surface.
split - Place supporting content beside the message.
search - Explain a search with no matching results.
error - Describe a failed operation and next step.
success - Confirm an empty-state transition.
onboarding - Invite a first-time user to begin.
full-page - Fill a route with no primary content.
compact - Show a smaller empty result inline.
action - Emphasize a primary next step.
Error state
Error details are optional and use a native disclosure, so technical context stays available without overwhelming the default message. Error variants announce the section as an alert; provide only details that are safe to show to the current user.
Supported variants: centered, illustration, minimal, card, split, search, error, success, onboarding, full-page, compact, and action.
Accessibility
- The title labels a semantic section and uses a level-two heading; an illustration can be given an accessible name with
illustrationLabel. status="status"orstatus="alert"enables a live announcement; error variants announce as alerts by default, while static states are not announced automatically.- Actions are caller-provided buttons or links. Keep their labels specific and preserve normal keyboard focus.
API
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
title | ReactNode | Yes | — | State heading. |
description | ReactNode | No | — | Supporting explanation. |
illustration, icon | ReactNode | No | — | Decorative media or icon slot. |
illustrationLabel | string | No | — | Accessible name for informative media. |
primaryAction, secondaryAction, action | ReactNode | No | — | Caller-provided actions; action is the legacy primary slot. |
children | ReactNode | No | — | Additional state-specific content. |
errorDetails | ReactNode | No | — | Optional native details disclosure. |
variant | EmptyStateSectionVariant | No | card | Visual layout. |
status | "status" | "alert" | "off" | No | alert for errors, otherwise off | Live announcement behavior. |
className | string | No | — | Additional root class. |
Customization
Use the component's className and documented slots to adapt the composition. Prefer a caller-provided ReactNode for media, actions, or controls rather than adding domain behavior to the section.
import type { ComponentProps } from "react";
import { EmptyStateSection } from "@puzzle-ui/pieces";
type EmptyStateSectionProps = ComponentProps<typeof EmptyStateSection>;
export function CustomizedSection(props: EmptyStateSectionProps) {
return (
<EmptyStateSection
{...props}
className={[props.className, "brand-section"].filter(Boolean).join(" ")}
/>
);
}Responsive behavior
Use the preview device selector to review mobile, tablet, and desktop widths. The built-in variant controls section structure; ensure application-provided media, form controls, and children can shrink or wrap without horizontal overflow. Use the existing responsive breakpoints in scoped CSS when the consuming layout needs a product-specific adjustment.
Theme support
The section consumes semantic variables from @puzzle-ui/theme and inherits active or scoped themes. Wrap the application with Theme, and use semantic roles such as text, surface, border, and primary for local overrides. Avoid hard-coded colors, spacing, radii, and shadows.
.brand-section {
color: var(--puzzle-color-text);
background: var(--puzzle-color-surface);
border-color: var(--puzzle-color-border);
}Composition
Compose this section with the UI primitives named in its API and use the documented slots for consumer-owned controls or media. Keep data fetching, routing, validation, permissions, and persistence in the application. The children slot is intended for additional content that belongs with this section, not as a substitute for its typed data model.
TypeScript example
The package exports this component from its root. Derive a wrapper's exact prop type from the public component rather than widening it:
import type { ComponentProps } from "react";
import { EmptyStateSection } from "@puzzle-ui/pieces";
type EmptyStateSectionProps = ComponentProps<typeof EmptyStateSection>;
export function SectionWrapper(props: EmptyStateSectionProps) {
return <EmptyStateSection {...props} />;
}Framework compatibility
The section is router-independent. Static compositions can be server-rendered; place callback-driven interactions in the framework's client boundary. See Next.js and TanStack Start integration for runnable framework examples and SSR guidance.