React Empty State: Erste Nutzung, keine Treffer, Fehler

Eine Liste, die nichts zu zeigen hat, ist trotzdem eine Ansicht, und jemand sieht sie sich an. Ein neuer Nutzer sieht eine leere Kundenliste und fragt sich, wo er anfangen soll. Eine Suche nach „Tulsa“ liefert nichts, und man fragt sich, ob die Suche kaputt ist. Eine API läuft in einen Timeout, und die Seite sieht genauso aus wie die leere Kundenliste. Ein React Empty State ist der kleine UI-Baustein, der diese Fälle auseinanderhält und für jeden einen nächsten Schritt anbietet. Dieser Guide behandelt die Arten von Empty States, die passenden Texte und Aktionen für jede Art, die Einbindung in eine Liste und eine Tabelle sowie die Details zu Barrierefreiheit und Smartphone.

Was sollte eine React Empty State Komponente zeigen?

Ein Icon oder eine Illustration, einen Titel, eine kurze Beschreibung und eine oder zwei Aktionen. Der Artikel der Nielsen Norman Group über Empty States (opens in a new tab) (Kate Kaplan, September 2021) gibt ihnen drei Aufgaben: den Systemstatus vermitteln, Hinweise zum Lernen geben und direkte Wege zur wichtigsten Aufgabe anbieten. Jeder Teil des Aufbaus übernimmt eine davon:

• Die Kachel oder Illustration markiert den Bereich als absichtlich leer. Sie ist dekorativ, deshalb überspringen Screenreader sie.
• Der Titel benennt, was fehlt. „Noch keine Kunden“ sagt mehr als „Hier ist nichts“.
• Die Beschreibung sagt in ein oder zwei Sätzen, warum, oder was hier erscheinen wird.
• Die Aktionen lösen das Problem: den ersten Eintrag anlegen, die Filter entfernen, es noch mal versuchen, Zugriff anfragen.

Schwieriger ist es, den richtigen Text zu finden, denn „leer“ hat mehrere Ursachen, und jede braucht eine eigene Botschaft.

Welche Arten von Empty States braucht eine App?

Sechs Arten decken fast jede Ansicht ab: erste Nutzung, leer, keine Treffer, Fehler, kein Zugriff und offline. Die Empty-State-Richtlinien von PatternFly (opens in a new tab) (geprüft im Oktober 2026) führen sich überschneidende Typen auf, etwa Getting Started, No Results, No Access und Back-End Failure. Der Empty State von Wingo UI liefert sie als Presets, die Icon, Farbton und Standardtext auf einmal setzen:

Die Reihenfolge der Prüfungen zählt mehr als die Optik. Ist ein Filter aktiv, ist die Liste gefiltert, und der Text muss das sagen. Wer jemandem mit 200 Kunden „Leg deinen ersten Kunden an“ zeigt, weil seine Suche nichts gefunden hat, lässt ihn glauben, seine Daten seien weg.

Wechsle im Playground das Preset, um alle durchzugehen, wähl dann error und drück den Retry-Button.

Wie schreibe ich Empty-State-Texte, die weiterhelfen?

Sag, was fehlt, und gib dann einen klaren nächsten Schritt vor. An diese Regeln halten wir uns, die meisten decken sich mit den oben verlinkten PatternFly-Richtlinien:

• Benenn das Objekt. „Noch keine Rechnungen“ ist besser als „Keine Daten“. Wo etwas angelegt werden soll, liest sich „Noch keine X“ wie ein Anfang, „Keine X gefunden“ wie ein Fehlschlag.
• Nenn bei leeren Suchergebnissen die Suchanfrage. Ein Titel wie Keine Kunden passen zu "Tulsa" zeigt, dass die Suche gelaufen ist, und macht einen Tippfehler sofort sichtbar.
• Sag, was man als Nächstes tun kann. Ein Satz. Das Tutorial gehört ins Onboarding.
• Eine Hauptaktion. Eine zweite, dezentere Aktion ist in Ordnung (CSV importieren neben Kunde anlegen). Drei Buttons sind ein Menü.
• Keine Schuldzuweisung und keine Ausrufezeichen. „Prüf deine Verbindung und versuch es noch mal“ statt „Du hast eine ungültige Suche eingegeben!“.
• Pass die Aktion an die Ursache an. Noch mal versuchen bei einem Timeout, Zugriff anfragen bei einem 403, Filter entfernen bei keinen Treffern. Ein Retry-Button bei einem Berechtigungsfehler schlägt nur erneut fehl.

Ein paar Empty State Design Beispiele, vorher und nachher:

Wie baue ich eine Empty State Komponente in React?

Installier die Komponente und verzweig dann in fester Reihenfolge nach dem Zustand deiner Daten: Laden, Fehler, gefiltert ohne Treffer, gar keine Daten und zuletzt die Liste. Lässt du eine Prüfung aus, behauptet die Empty State Komponente, die Daten seien weg, obwohl sie nur laden oder gefiltert sind.

npx wingo-ui@latest add empty-state skeleton

"use client";

import { FileUp, UserPlus } from "lucide-react";
import { Button } from "@/components/ui/button";
import { EmptyState } from "@/components/ui/empty-state";
import { SkeletonList } from "@/components/ui/skeleton";

type Client = { id: string; name: string; city: string };

type ClientsViewProps = {
  status: "loading" | "error" | "ready";
  clients: Client[];
  query: string;
  onClearSearch: () => void;
  onRetry: () => Promise<void>;
  onAdd: () => void;
};

export function ClientsView({ status, clients, query, onClearSearch, onRetry, onAdd }: ClientsViewProps) {
  if (status === "loading") return <SkeletonList rows={5} label="Kunden werden geladen" />;

  if (status === "error") {
    return (
      <EmptyState
        preset="error"
        title="Wir konnten deine Kunden nicht laden"
        description="Prüf deine Verbindung und versuch es noch mal."
        onRetry={onRetry}
        live
      />
    );
  }

  // eine gefilterte liste ist kein leeres konto: zuerst die suche prüfen
  if (clients.length === 0 && query) {
    return (
      <EmptyState
        preset="no-results"
        title={`Keine Kunden passen zu "${query}"`}
        description="Prüf die Schreibweise oder such stattdessen nach einer Stadt."
        live
        actions={
          <Button variant="outline" onClick={onClearSearch}>
            Suche zurücksetzen
          </Button>
        }
      />
    );
  }

  if (clients.length === 0) {
    return (
      <EmptyState
        preset="first-run"
        variant="dashed"
        title="Noch keine Kunden"
        description="Leg deinen ersten Kunden an oder importier die Liste aus einer CSV-Datei."
        actions={
          <>
            <Button variant="outline" leftIcon={<FileUp />}>
              CSV importieren
            </Button>
            <Button leftIcon={<UserPlus />} onClick={onAdd}>
              Kunde anlegen
            </Button>
          </>
        }
      />
    );
  }

  return (
    <ul className="flex flex-col">
      {clients.map((client) => (
        <li key={client.id} className="flex min-h-12 items-center border-b border-foreground/10">
          {client.name}, {client.city}
        </li>
      ))}
    </ul>
  );
}

Die Props, auf die es ankommt:

• preset wählt Icon, Farbton und Standardtext. title, description, icon und badge überschreiben einzelne Teile; mit null blendest du einen davon aus.
• actions nimmt deine Buttons. Setz die Hauptaktion im DOM ans Ende: Auf breiten Bildschirmen steht sie dann am Ende der Reihe, gestapelt ganz oben.
• onRetry ergänzt einen Outline-Button „Try again“. Gibt die Funktion ein Promise zurück, zeigt der Button einen Ladezustand, bis das Promise abgeschlossen ist. Wird es abgelehnt, stoppt nur der Spinner; welcher Zustand danach kommt, entscheidest du.
• size nimmst du als sm in einer Tabellenzelle, einer Liste oder einem Popover, als md in einem Panel (der Standard) und als lg für eine ganze Seite. variant ist plain, dashed (Bereiche für den ersten Start, Drop Zones) oder surface (ein erhöhtes Panel).
• illustration ersetzt die Icon-Kachel durch ein Bild oder SVG, und align="start" richtet für Karten und Sidebars alles linksbündig aus.

Soll ich beim Laden ein Skeleton oder einen Empty State zeigen?

Ein Skeleton, und zwar immer, solange der Request noch läuft. Der Empty State gehört zu dem Moment, in dem die Antwort mit null Einträgen ankommt. Renderst du „Noch keine Kunden“, bevor der Fetch fertig ist, blitzt bei jedem Seitenaufruf kurz eine Meldung auf, nach der die Daten weg sind, und wird dann ersetzt. Das Skeleton bringt Formen für Listen, Tabellen, Karten und Profile mit (SkeletonList, SkeletonTable, SkeletonCard, SkeletonProfile) und ein verstecktes Label „Loading“ für Screenreader, sodass der Ladezustand denselben Platz einnimmt wie der Inhalt, den er vertritt. Der Guide zum React Skeleton Loader behandelt Formen, Layout Shift und die Frage, wann ein Spinner die bessere Wahl ist.

Wie gehe ich mit einem React Table Empty State um?

Render den Zustand anstelle der Zeilen, mit eigenem Text für eine Tabelle ohne Zeilen und für eine, in der Suche oder Filter jede Zeile ausblenden. Eine einfache HTML-Tabelle braucht eine Zelle über die ganze Breite, damit sich der Zustand nicht in die erste Spalte quetscht:

<tbody>
  {invoices.length === 0 ? (
    <tr>
      <td colSpan={4} className="p-0">
        <EmptyState size="sm" preset="empty" title="Keine überfälligen Rechnungen" description="Alle Kunden haben pünktlich bezahlt." />
      </td>
    </tr>
  ) : (
    invoices.map((invoice) => <InvoiceRow key={invoice.id} invoice={invoice} />)
  )}
</tbody>

Die Data Table erledigt den ganzen Ablauf für den React Table Empty State selbst. Sie zeigt Skeleton-Zeilen, solange loading true ist, einen Fehlerzustand mit Try again, wenn du error und onRetry übergibst, einen empty-Zustand, wenn es keine Daten gibt, und einen Zustand ohne Treffer mit einem Button „Clear filters“, wenn Suche oder Filter jede Zeile ausblenden. Die Standardzustände ersetzt du mit emptyState und noResultsState:

<DataTable
  data={clients}
  columns={columns}
  caption="Kunden"
  loading={isLoading}
  error={loadError ? "Der Server hat nicht geantwortet. Versuch es gleich noch mal." : undefined}
  onRetry={refetch}
  emptyState={
    <EmptyState
      preset="first-run"
      size="sm"
      title="Noch keine Kunden"
      description="Leg deinen ersten Kunden an, um Rechnungen zu verschicken und Salden im Blick zu behalten."
      actions={
        <Button size="sm" leftIcon={<UserPlus />}>
          Kunde anlegen
        </Button>
      }
    />
  }
/>

Standardmäßig rendert sie den Zustand allein, ohne Spaltenköpfe über einer leeren Fläche; mit showHeaderWhenEmpty bleiben die Köpfe stehen. Die Data Table ist eine Pro-Komponente (Preise); der Empty State darin ist kostenlos. Am Smartphone wird die Tabelle zu Karten, ein Muster, das der Guide zu responsiven Tabellen erklärt.

Wie mache ich einen Empty State barrierefrei?

Lass Zustände ansagen, die nach einer Suche oder einem fehlgeschlagenen Laden erscheinen, halt die Gliederung der Überschriften intakt, versteck das Icon vor Screenreadern und setz den Fokus um, wenn der Zustand verschwindet:

1. Lass Zustände ansagen, die nach einer Aktion erscheinen. Das WCAG-2.2-Erfolgskriterium 4.1.3 Status Messages (opens in a new tab) (Stufe AA) nennt die Meldung, dass eine Suche keine Ergebnisse geliefert hat, als Beispiel für eine Statusmeldung, die Hilfstechnologien ohne Fokuswechsel ausgeben sollen. Die Prop live ergänzt role="status" mit einer Live-Region auf polite, sodass ein Screenreader Titel und Beschreibung einmal vorliest, wenn der Zustand erscheint. Nutz sie bei leeren Suchergebnissen und Fehlern, nicht für eine statische Seite zum ersten Start.
2. Halt die Gliederung der Überschriften intakt. Der Titel ist standardmäßig ein h3; setz titleAs auf h2, h4 oder p, damit er zur Seite passt.
3. Lass das Icon dekorativ. Kachel und Illustration rendern mit aria-hidden, die Bedeutung trägt der Titel.
4. Setz den Fokus um, wenn der Zustand verschwindet. Wenn „Filter entfernen“ den Empty State unmountet, landet der Fokus auf dem Body. Schick ihn zurück ins Suchfeld, wie es das No-Results-Beispiel der Komponente mit einem Ref macht.

Wie verhält sich ein Empty State am Smartphone?

Seine Aktionen stapeln sich in voller Breite, die Hauptaktion oben, damit sie gut mit dem Daumen erreichbar sind und in eine schmale Spalte passen. Der Empty State reagiert über eine Container Query: Ist er etwa 400px breit oder schmaler und hat zwei oder mehr Aktionen, stapelt sich die Reihe. Maßgeblich ist die Breite der Komponente, also stapelt sich auch eine schmale Karte am Desktop. Die Größe lg fällt unter 640px auf die Abstände von md zurück, und Buttons bekommen bei einem groben Zeiger (Touch) ein Touch Target von 44px. Die Einblendung (die Kachel skaliert herein, dann gleiten Text und Aktionen nacheinander nach oben) wird zu einem Fade, wenn jemand reduzierte Bewegung eingestellt hat, und das serverseitig gerenderte Markup zeigt schon den Endzustand.

Wie übersetze ich den Standardtext einmal für die ganze App?

Übergib presets über die defaults von UIProvider. icon, tone, title, description und badge jedes Presets werden mit DEFAULT_EMPTY_STATE_PRESETS gemergt und überschreiben dessen Werte. So legst du deinen Stil einmal fest statt in jeder Ansicht:

import { UIProvider } from "@/lib/ui-config";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <UIProvider
      defaults={{
        "empty-state": {
          presets: {
            error: { title: "Das hat nicht geladen", description: "Prüf deine Verbindung und versuch es noch mal." },
            "no-permission": { description: "Bitte einen Workspace-Admin, dir Zugriff zu geben." },
          },
        },
      }}
    >
      {children}
    </UIProvider>
  );
}

Explizite Props haben weiterhin Vorrang, eine einzelne Ansicht kann also ihren eigenen Text behalten.

Wie füge ich ihn meinem Projekt hinzu?

Führ npx wingo-ui@latest add empty-state aus. Die CLI kopiert den Quellcode nach components/ui, ergänzt den Button und die Helfer für Motion, Farbtöne und Konfiguration, die er importiert, und installiert motion, lucide-react und @radix-ui/react-slot. Für ganzseitige Varianten (404, Wartung, offline) lies das Tutorial zur React-404-Seite. Weitere Deep Dives zu einzelnen Komponenten findest du in der Kategorie Komponenten-Guides, und der Guide zu React-Formularkomponenten wendet dieselben Regeln für Text, Fokus und Smartphone auf jedes Formularelement an.

Häufige Fragen

Was ist ein Empty State im UI-Design?

Ein Empty State ist das, was eine Liste, Tabelle, Suche oder Seite zeigt, wenn es keinen Inhalt gibt. Ein guter Empty State sagt, warum der Bereich leer ist, und bietet den nächsten Schritt an, etwa den ersten Eintrag anzulegen, einen Filter zu entfernen oder einen fehlgeschlagenen Ladevorgang zu wiederholen.

Wie zeige ich einen Empty State in einer React-Tabelle?

Render ihn anstelle der Zeilen, sobald das Laden fertig und das Daten-Array leer ist, mit unterschiedlichem Text für „keine Daten“ und für Filter ohne Treffer. In einer einfachen HTML-Tabelle kommt er in eine einzelne Zelle, deren colSpan der Spaltenanzahl entspricht; die Data Table von Wingo UI erledigt das für dich über ihre Props emptyState und noResultsState.

Soll ich beim Laden einen Spinner, ein Skeleton oder einen Empty State zeigen?

Zeig ein Skeleton oder einen Spinner, solange der Request läuft, und den Empty State erst, wenn die Antwort mit null Einträgen ankommt. Wer den Empty State zuerst zeigt, lässt Nutzer für einen Moment glauben, ihre Daten seien weg.

Wie mache ich einen Empty State barrierefrei?

Lass das Icon dekorativ, gib dem Titel eine Überschriftenebene, die zur Gliederung der Seite passt, und nutz role="status" für Zustände, die nach einer Suche oder Filteränderung erscheinen, damit Screenreader sie ansagen. Wenn ein Button den Empty State beim Zurücksetzen unmountet, setz den Fokus zurück ins Suchfeld.

Ist der Empty State von Wingo UI kostenlos?

Ja. Empty State und Skeleton sind kostenlose Komponenten. Die Data Table, die den Empty State für ihre Zustände ohne Daten, ohne Treffer und bei Fehlern nutzt, ist eine Pro-Komponente.