Components
EmptyState
What a screen shows before there is anything on it. It says plainly why it is empty and gives you one clear thing to do about it.
Usage
pnpm dlx shadcn@latest add @opsinjs/empty-state
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { EmptyState } from "@/components/ui/empty-state"<EmptyState
reason="nothing-yet"
title="No readings yet"
action={{ label: "Add a reading", href: "/readings/new" }}
>
Once you add your first reading it will be here, with the range your product
compares it against.
</EmptyState>Examples
empty-state · base base · style base-lyraOpen under the product themeA filter matched nothing
reason="no-matches" with an onSelect that clears the filter. The list owns the
live region and moves focus when the control unmounts.
empty-state-a-filter-matched-nothing · base base · style base-lyraOpen under the product theme"use client"
import { useEffect, useRef, useState } from "react"
import { Check } from "lucide-react"
import { EmptyState } from "@/components/ui/empty-state"
/* Deliberately fictional and deliberately numberless. A screenshot of an
opsinjs example must not be mistakable for somebody's own list of results. */
const ROWS = [
{ id: "first", label: "First example measurement", tag: "sample" },
{ id: "second", label: "Second example measurement", tag: "sample" },
{ id: "third", label: "Third example measurement", tag: "other" },
]
const TAGS = ["sample", "other", "missing"]
export default function EmptyStateAFilterMatchedNothing() {
const [tag, setTag] = useState("missing")
const [announcement, setAnnouncement] = useState("")
/* Not a boolean: the reader can clear the filter twice, and a flag that is
already `true` would not re-run the effect. A counter changes every time. */
const [returns, setReturns] = useState(0)
const listRef = useRef<HTMLUListElement>(null)
const rows = ROWS.filter((row) => row.tag === tag)
useEffect(() => {
if (returns === 0) return
listRef.current?.focus()
}, [returns])
/* One handler for both controls, so the announcement cannot describe one
state while the list shows another. It says what the list holds now, in
words, and it never characterises the absence.
`fromEmptyState` is what keeps the focus move honest. Focus is moved only
when the control that was holding it is about to be unmounted, which is
true of the empty state's action and false of the filter chips. A chip
that yanked focus into the list would take it away from a reader who was
about to try a different filter. */
function applyTag(next: string, fromEmptyState = false) {
const matched = ROWS.filter((row) => row.tag === next)
setTag(next)
setAnnouncement(
matched.length === 0
? `No readings match the filter ${next}. Your readings are still here.`
: `Showing the readings that match the filter ${next}.`,
)
if (fromEmptyState && matched.length > 0) setReturns((count) => count + 1)
}
return (
<div className="flex w-full max-w-md flex-col gap-opsin-4">
{/* The active chip needs a cue that survives greyscale and low vision.
`aria-pressed` is correct for assistive technology and says nothing to
a sighted reader; the tint between `--card` and `--muted` is under 4%
in the light theme and fainter still in the dark. A filter example
whose active filter cannot be told apart is teaching the confusion it
exists to prevent, so the pressed chip earns a leading tick and a
`--foreground` boundary as well as the tint. The tick sits in a slot
that is always the same width, so the row does not reflow under the
thumb as the reader moves between chips. */}
<div className="flex flex-wrap gap-opsin-2">
{TAGS.map((option) => (
<button
key={option}
type="button"
onClick={() => applyTag(option)}
aria-pressed={tag === option}
className="inline-flex min-h-(--opsin-target-minimum,2.75rem) items-center justify-center gap-opsin-1 rounded-opsin-md border border-border bg-card px-opsin-3 text-opsin-subheadline aria-pressed:border-foreground aria-pressed:bg-muted"
>
<Check
aria-hidden="true"
className={
tag === option ? "size-[1em]" : "size-[1em] invisible"
}
/>
{option}
</button>
))}
</div>
{/* Polite, atomic and permanently mounted. A region created at the moment
it has something to say is often missed, because the assistive
technology has to notice the node before it notices the text in it. */}
<p role="status" aria-live="polite" aria-atomic="true" className="sr-only">
{announcement}
</p>
{rows.length > 0 ? (
<ul
ref={listRef}
tabIndex={-1}
className="m-0 flex list-none flex-col gap-opsin-2 p-0 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
aria-label="Example measurements"
>
{rows.map((row) => (
<li
key={row.id}
className="border-b border-border py-opsin-2 text-opsin-body"
>
{row.label}
</li>
))}
</ul>
) : (
<EmptyState
reason="no-matches"
title="No readings match this filter"
titleLevel={3}
action={{
label: "Clear the filter",
onSelect: () => applyTag("sample", true),
}}
>
Your readings are still here. The filter you have applied does not
match any of them, so the list has nothing to show while it is on.
</EmptyState>
)}
</div>
)
}What happens when nobody wrote the body
The first card has no children, so it admits the app does not say why and
warns. The second has two sentences.
empty-state-no-copy-supplied · base base · style base-lyraOpen under the product themeimport { EmptyState } from "@/components/ui/empty-state"
export default function EmptyStateNoCopySupplied() {
return (
<div className="@container w-full">
<div className="grid w-full max-w-3xl gap-opsin-6 @2xl:grid-cols-2">
<div className="rounded-opsin-md border border-border">
<EmptyState reason="nothing-left" title="Nothing left to review" titleLevel={3} />
</div>
<div className="rounded-opsin-md border border-border">
<EmptyState
reason="nothing-left"
title="Nothing left to review"
titleLevel={3}
action={{ label: "See everything you have added", href: "#example-destination" }}
>
There is nothing in the review queue at the moment. Items arrive here
when this product has something for you to look at, and they stay
until you have opened them.
</EmptyState>
</div>
</div>
</div>
)
}An illustration, and what it is not allowed to do
illustration is aria-hidden and inert, hidden in print and below 17rem.
Cover it and the state still reads whole.
empty-state-with-an-illustration · base base · style base-lyraOpen under the product themeimport { EmptyState } from "@/components/ui/empty-state"
/* Deliberately abstract. A picture of a heart, a chart or a pill bottle beside
an absence of somebody's own data starts to look like a statement about that
data, and this one has nothing to say. */
function ExampleMark() {
return (
<svg
viewBox="0 0 64 48"
className="size-opsin-16 text-muted-foreground"
fill="none"
stroke="currentColor"
strokeWidth="2"
strokeLinecap="round"
>
<rect x="3" y="3" width="58" height="42" rx="6" />
<path d="M14 33h36" strokeDasharray="4 6" />
<path d="M14 23h20" strokeDasharray="4 6" />
</svg>
)
}
export default function EmptyStateWithAnIllustration() {
return (
<div className="w-full max-w-md rounded-opsin-md border border-border">
<EmptyState
reason="nothing-yet"
title="Nothing in your log yet"
titleLevel={3}
illustration={<ExampleMark />}
action={{ label: "Add your first entry", href: "#example-destination" }}
secondary={{ label: "Read what a log is for", href: "#example-destination" }}
>
Entries you add appear here in the order you record them. Nothing has
been recorded so far, so there is nothing to show.
</EmptyState>
</div>
)
}When to use it
Use it when
- Nothing added yet, where the fastest help is the first step.
- A filter or search that matched nothing, where the reader must know it was the filter, not the data.
- A view that cannot yet draw honestly, such as a trend with too few readings.
Do not use it when
- The content is loading and will arrive shortly.Use
skeletoninstead. - The whole view failed, rather than one surface that could not load.Use
alert-bannerinstead. - There is content, but it needs a caveat.Use
calloutinstead. - Permission is needed before anything can be shown.Use
consent-sheetinstead. - One value is missing inside a full surface.Use
valueinstead.
Accessibility
Neither colour axis is used, so nothing can mix. titleLevel renders a real h2 to
h6, default 2, so check it against the outline. The could-not-load flag carries
its meaning in a word beside an aria-hidden icon, not colour, and the href action is
an anchor floored at var(--opsin-target-minimum, 2.75rem) on both axes. The default
preview renders clean on /view, and the audit changed nothing.
Residual items.
- No live region mounts, by design. On a stateless, read-only render one could only mis-fire, since it announces only changes made after first paint. The announcement belongs to whatever region changed, which the caller owns, as the filter example shows.
- The three example files were audited from source alone.
- Contrast against the card surface is unmeasured, and the report below carries it.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus to the action, then to the quieter alternative | Nothing else is focusable. No action means no tab stop. |
| Shift+Tab | Moves focus back through the same controls | Reverse order matches visual order. |
| Enter | Activates whichever control has focus | href follows the destination, onSelect calls the handler. |
| Space | Activates the onSelect form only | The platform's button and link distinction. No page scroll. |
| After activation | The caller's, not this component's | An onSelect that unmounts the state drops focus to body. Move it. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from EmptyStateProps in registry/bases/base/empty-state.tsx.
reason and title are required. There is no exported EmptyReason type, so
name the union EmptyStateProps["reason"]. A blank title, a body with no
text or only a number, and an action with nothing to do each render a fallback and
warn once. A secondary with no action also warns.