Skip to Content

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.

390 × 844

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.

390 × 844

illustration - Pair the message with decorative media.

390 × 844

minimal - Use a quiet message inside a larger layout.

390 × 844

card - Contain the message and action on a surface.

390 × 844

split - Place supporting content beside the message.

390 × 844

search - Explain a search with no matching results.

390 × 844

error - Describe a failed operation and next step.

390 × 844

success - Confirm an empty-state transition.

390 × 844

onboarding - Invite a first-time user to begin.

390 × 844

full-page - Fill a route with no primary content.

390 × 844

compact - Show a smaller empty result inline.

390 × 844

action - Emphasize a primary next step.

390 × 844

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.

390 × 844

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" or status="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

PropTypeRequiredDefaultDescription
titleReactNodeYes—State heading.
descriptionReactNodeNo—Supporting explanation.
illustration, iconReactNodeNo—Decorative media or icon slot.
illustrationLabelstringNo—Accessible name for informative media.
primaryAction, secondaryAction, actionReactNodeNo—Caller-provided actions; action is the legacy primary slot.
childrenReactNodeNo—Additional state-specific content.
errorDetailsReactNodeNo—Optional native details disclosure.
variantEmptyStateSectionVariantNocardVisual layout.
status"status" | "alert" | "off"Noalert for errors, otherwise offLive announcement behavior.
classNamestringNo—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.