Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
empty-state · base base · style base-lyraOpen under the product theme

A 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.

Theme
Density
Text
Status
Accent theme
Accent
empty-state-a-filter-matched-nothing · base base · style base-lyraOpen under the product theme
empty-state-a-filter-matched-nothing.tsx
"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.

Theme
Density
Text
Status
Accent theme
Accent
empty-state-no-copy-supplied · base base · style base-lyraOpen under the product theme
empty-state-no-copy-supplied.tsx
import { 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.

Theme
Density
Text
Status
Accent theme
Accent
empty-state-with-an-illustration · base base · style base-lyraOpen under the product theme
empty-state-with-an-illustration.tsx
import { 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 skeleton instead.
  • The whole view failed, rather than one surface that could not load.Use alert-banner instead.
  • There is content, but it needs a caveat.Use callout instead.
  • Permission is needed before anything can be shown.Use consent-sheet instead.
  • One value is missing inside a full surface.Use value instead.

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.
KeyActionNotes
TabMoves focus to the action, then to the quieter alternativeNothing else is focusable. No action means no tab stop.
Shift+TabMoves focus back through the same controlsReverse order matches visual order.
EnterActivates whichever control has focushref follows the destination, onSelect calls the handler.
SpaceActivates the onSelect form onlyThe platform's button and link distinction. No page scroll.
After activationThe caller's, not this component'sAn onSelect that unmounts the state drops focus to body. Move it.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below 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.