ui/components/empty-state

Empty State

Composable placeholder content for empty views with centered and inline layout variants. Size propagates to all parts through the root's data-size attribute; variant controls root layout only.

Preview

tsx

1 import { EmptyState, EmptyStateDescription, EmptyStateMessage } from "@/components/ui/empty-state";2 3 export default function EmptyStateDefault() {4   return (5     <EmptyState>6       <EmptyStateMessage>No reviews found</EmptyStateMessage>7       <EmptyStateDescription>Start a new review to see results here.</EmptyStateDescription>8     </EmptyState>9   );10 }11

Installation

$pnpm exec dgadd add ui/empty-state

[Installs to]src/components/ui/empty-state[Item]ui/empty-state

dgadd ships in @diffgazer/add on npm: pnpm add -D @diffgazer/add puts it on pnpm exec, and npx @diffgazer/add runs it without the install.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS from the installed package.

Usage

tsx

1 import { EmptyState, EmptyStateDescription, EmptyStateMessage } from "@/components/ui/empty-state";2 3 export default function EmptyStateDefault() {4   return (5     <EmptyState>6       <EmptyStateMessage>No reviews found</EmptyStateMessage>7       <EmptyStateDescription>Start a new review to see results here.</EmptyStateDescription>8     </EmptyState>9   );10 }11

Examples

Variants

Preview

tsx

1 import { Button } from "@/components/ui/button";2 import {3   EmptyState,4   EmptyStateActions,5   EmptyStateDescription,6   EmptyStateIcon,7   EmptyStateMessage,8 } from "@/components/ui/empty-state";9 10 export default function EmptyStateVariants() {11   return (12     <div className="flex flex-col gap-8">13       <EmptyState variant="centered" size="lg">14         <EmptyStateIcon className="font-mono leading-none">∅</EmptyStateIcon>15         <EmptyStateMessage>No results match your search</EmptyStateMessage>16         <EmptyStateDescription>Try adjusting your filters or search terms.</EmptyStateDescription>17         <EmptyStateActions>18           <Button variant="secondary" size="sm" bracket>19             CLEAR FILTERS20           </Button>21         </EmptyStateActions>22       </EmptyState>23       <EmptyState variant="centered" size="sm">24         <EmptyStateMessage>Nothing here yet</EmptyStateMessage>25         <EmptyStateDescription>Items will appear once added.</EmptyStateDescription>26       </EmptyState>27       <div className="border border-border font-mono text-xs">28         <div className="flex items-center justify-between border-b border-border px-3 py-2">29           <span className="text-foreground">src/review/pipeline.ts</span>30           <span className="text-muted-foreground">+42 -7</span>31         </div>32         <EmptyState variant="inline" size="sm">33           <EmptyStateMessage>No comments yet on this file.</EmptyStateMessage>34         </EmptyState>35       </div>36     </div>37   );38 }39

Keyboard hint

Preview

tsx

1 import { EmptyState, EmptyStateHint, EmptyStateMessage } from "@/components/ui/empty-state";2 import { Kbd } from "@/components/ui/kbd";3 4 export default function EmptyStateHintExample() {5   return (6     <div className="flex flex-col gap-8">7       <EmptyState variant="centered" size="md">8         <EmptyStateMessage>No runs match this search</EmptyStateMessage>9         <EmptyStateHint>10           <Kbd size="sm">Esc</Kbd> clear search11         </EmptyStateHint>12       </EmptyState>13       {/* The inline variant is a ROW, so a Message + Hint pair needs flex-col14           on the root instance to stack. */}15       <EmptyState variant="inline" size="sm" className="flex-col border border-border">16         <EmptyStateMessage>No comments on this file</EmptyStateMessage>17         <EmptyStateHint>18           <Kbd size="sm">c</Kbd> start a thread19         </EmptyStateHint>20       </EmptyState>21     </div>22   );23 }24

Dynamic (live)

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { EmptyState, EmptyStateDescription, EmptyStateMessage } from "@/components/ui/empty-state";5 import { Input } from "@/components/ui/input";6 7 const items = ["useNavigation", "useFocusTrap", "useScrollLock"];8 9 export default function EmptyStateLive() {10   const [query, setQuery] = useState("");11   const filtered = items.filter((item) => item.toLowerCase().includes(query.toLowerCase()));12   const isEmpty = filtered.length === 0;13 14   return (15     <div className="flex flex-col gap-4">16       <Input17         type="search"18         aria-label="Filter hooks"19         placeholder="Filter hooks…"20         value={query}21         onChange={(e) => setQuery(e.target.value)}22       />23       {filtered.length > 0 && (24         <ul className="text-sm text-foreground">25           {filtered.map((item) => (26             <li key={item}>{item}</li>27           ))}28         </ul>29       )}30       {/* The live region stays mounted across the results→empty transition (and31           starts empty) so screen readers announce the message when it appears. */}32       <EmptyState live size="sm">33         {isEmpty ? (34           <>35             <EmptyStateMessage>No hooks match "{query}"</EmptyStateMessage>36             <EmptyStateDescription>Try a different search term.</EmptyStateDescription>37           </>38         ) : null}39       </EmptyState>40     </div>41   );42 }43

API Reference

EmptyState

Name	Type	Default	Description
variant	"centered" \| "inline"	"centered"	Root layout. Centered stacks children vertically; inline aligns them horizontally.
size	"sm" \| "md" \| "lg"	"md"	Spacing and font-size scale propagated to all subparts via data-size attribute.
live	boolean	false	When true, adds role="status" and aria-live="polite" so screen readers announce the empty state. Keep a live EmptyState mounted across the results→empty transition (render it unconditionally, empty while results exist, and swap its children) rather than conditionally mounting it with its message already inside.
children	ReactNode	—	EmptyState subparts (Icon, Message, Description, Actions).

EmptyStateIcon

Name	Type	Default	Description
children	ReactNode	—	Visual marker. Always rendered with aria-hidden.

EmptyStateMessage

Name	Type	Default	Description
children	ReactNode	—	Primary empty-state copy.

EmptyStateDescription

Name	Type	Default	Description
children	ReactNode	—	Supporting copy.

EmptyStateActions

Name	Type	Default	Description
children	ReactNode	—	Action buttons or links.

EmptyStateHint

Name	Type	Default	Description
children	ReactNode	—	Keyboard affordance copy, typically Kbd chips plus two or three words.

Accessibility

Notes

Layout Variants

centered variant for full-page empty states, inline variant for embedded contexts.

Size

sm for compact embedded contexts, md (default) for standard use, lg for full-page empty states. Size propagates to all parts through the root's data-size attribute.

Icon

EmptyStateIcon scales its font size with the root size, so a text glyph or a currentColor icon inherits the theme in both palettes. Avoid color emoji: they render identically in light and dark and break the monochrome identity.

Compound Composition

Compose semantic parts for icon, message, description, and actions. There is no React context here: the root stamps data-size and every part reads it through group-data variants, so a copy-mode consumer must keep the root's group/es class. Variant controls root layout only.

Keyboard Hint

EmptyStateHint is the keyboard affordance: compose it with Kbd so an empty screen ends with the key that fills it instead of a full stop. It is deliberately non-interactive — on a touch surface there is no key to press, so render EmptyStateActions (a real button) there and let the Hint be the desktop affordance; the two compose, Actions above and Hint below. Kbd is a peer composition, so copy-mode consumers who never use the hint are not forced to pull it. The inline variant lays its root out as a row, so a Message + Hint pair needs flex-col on that instance to stack.

Writing Empty States

Name what is missing, name the action, name the key. Active voice, present tense, no apology and no 'oops'. Keep the hint to about three words — under live it is announced right after the message, so a sentence there becomes a paragraph in the ear.

Accessibility

For empty states that appear dynamically (e.g., after filtering returns no results), set live on the root. This adds role="status" and aria-live="polite" so screen readers announce the change. A live EmptyState must stay mounted across the results→empty transition: render it unconditionally (empty while results exist) and swap its children, instead of conditionally mounting it already containing its message — many screen-reader/browser pairs do not announce a live region inserted with content already inside it.

Source

Install via CLI: pnpm exec dgadd add ui/empty-state.

Highlighted source loads after this disclosure opens. Browse the source repository.

Empty State

Installation

Usage

Examples

Variants

Keyboard hint

Dynamic (live)

API Reference

EmptyState

EmptyStateIcon

EmptyStateMessage

EmptyStateDescription

EmptyStateActions

EmptyStateHint

Accessibility

Notes

Layout Variants

Size

Icon

Compound Composition

Keyboard Hint

Writing Empty States

Accessibility

Source

View component source (11 files)