Zum Inhalt springen
Dokumentation

Komponenten

Befehlspalette (Command)

Stabil

Suchen und handeln in einem Feld – Seiten, Stationen und Aktionen über die Tastatur erreichen.

Eine Befehlspalette verbindet Suche und Aktion in einem Feld: Tippen filtert die Einträge, Enter führt den markierten Eintrag aus. Mit CommandDialog liegt sie in einem Dialog und lässt sich über eine Tastenkombination öffnen.

Wann verwenden

  • Für eine Suche über viele Seiten und Aktionen, die von überall erreichbar sein soll.
  • Als Befehlsleiste für erfahrene Nutzer, etwa mit Strg+K oder ⌘+K.
  • Für eine Auswahl aus einer langen, durchsuchbaren Liste, etwa Stationen eines Hauses.

Wann nicht

  • Für eine kurze Liste mit wenigen Einträgen genügt Select.
  • Wenn die Auswahl immer sichtbar bleiben soll, passen Tabs oder eine einfache Liste.
  • Für ein Formular mit mehreren Feldern ist ein Dialog mit Formular ruhiger; die Palette ist auf ein Suchfeld ausgelegt.
  • Ohne Tastenkombination bleibt die Palette versteckt. Dann braucht es zusätzlich einen sichtbaren Einstieg.

Seiten und Aktionen

Command hält die Liste, CommandInput das Suchfeld, CommandList die Ergebnisse. CommandGroup und CommandSeparator gliedern sie, CommandEmpty zeigt den leeren Zustand und CommandShortcut die Tastenkombination eines Eintrags.

Beispiel und Quelltext
suche.tsx
import * as React from "react";

import {
  Button,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@neodin-eu/ui";

function Suche() {
  const [offen, setOffen] = React.useState(false);

  return (
    <>
      <Button variant="outline" onClick={() => setOffen(true)}>
        Befehlspalette öffnen
      </Button>
      <CommandDialog open={offen} onOpenChange={setOffen} shortcut="j">
        <CommandInput placeholder="Seite oder Aktion suchen …" />
        <CommandList>
          <CommandEmpty>Keine Treffer</CommandEmpty>
          <CommandGroup heading="Seiten">
            <CommandItem value="dienstplan">Dienstplan</CommandItem>
            <CommandItem value="stationen">Stationen</CommandItem>
            <CommandItem value="tickets">Tickets</CommandItem>
          </CommandGroup>
          <CommandSeparator />
          <CommandGroup heading="Aktionen">
            <CommandItem value="drucken">
              Dienstplan drucken
              <CommandShortcut>⌘P</CommandShortcut>
            </CommandItem>
            <CommandItem value="wechseln">Station wechseln</CommandItem>
          </CommandGroup>
        </CommandList>
      </CommandDialog>
    </>
  );
}

Eigener Titel

CommandDialog nimmt einen title entgegen; er ist der zugängliche Name des Dialogs. Ohne Angabe kommt der Text aus dem Sprachkatalog („Befehlspalette“). Das Suchfeld bekommt seinen Platzhalter ebenfalls aus dem Katalog, sofern du keinen eigenen setzt.

Beispiel und Quelltext
station.tsx
import * as React from "react";

import {
  Button,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
} from "@neodin-eu/ui";

function Station() {
  const [offen, setOffen] = React.useState(false);

  return (
    <>
      <Button variant="secondary" onClick={() => setOffen(true)}>
        Station wechseln
      </Button>
      <CommandDialog open={offen} onOpenChange={setOffen} title="Station wechseln">
        <CommandInput placeholder="Station suchen …" />
        <CommandList>
          <CommandEmpty>Keine Station gefunden</CommandEmpty>
          <CommandGroup heading="Haus A">
            <CommandItem value="station 3">Station 3 · Innere Medizin</CommandItem>
            <CommandItem value="station 4">Station 4 · Chirurgie</CommandItem>
          </CommandGroup>
          <CommandGroup heading="Haus B">
            <CommandItem value="station 7">Station 7 · Geriatrie</CommandItem>
          </CommandGroup>
        </CommandList>
      </CommandDialog>
    </>
  );
}

Die Suche dieser Dokumentation ist selbst eine Befehlspalette: Der Knopf im Kopfbereich öffnet CommandDialog mit shortcut="k", die Treffer kommen aus einem eigenen Suchindex.

Barrierefreiheit

  • Tippen filtert die Liste; im Komponententest bleibt nur der passende Eintrag übrig, der leere Zustand zeigt „Keine Treffer“ aus dem Katalog.
  • Pfeil nach unten bewegt die Markierung, Enter wählt den Eintrag – im Test über getByRole("option") geprüft.
  • CommandDialog öffnet mit Strg+K und mit ⌘+K und schließt mit Escape; das ist im Komponententest abgesichert.
  • Der Dialog trägt den Titel aus title beziehungsweise dem Katalog als zugänglichen Namen; der Test findet ihn über getByRole("dialog", { name: "Befehlspalette" }).
  • Der offene Zustand ist im Komponententest in hell und dunkel geprüft. Für die Liste gilt dabei eine Ausnahme bei der Prüfregel für Pflichtkinder, weil cmdk die Optionen in eine zusätzliche Hülle legt.
  • Eine Aktion, die nur über die Palette erreichbar ist, braucht zusätzlich einen sichtbaren Weg.

Props

Props von Command
PropTypStandardPflichtBeschreibung
asChildboolean–Nein–
classNamestring–Nein–
onValueChange((value: string) => void)–NeinEvent handler called when the selected item of the menu changes.
valuestring–NeinOptional controlled state of the selected command menu item.
Props von CommandDialog
PropTypStandardPflichtBeschreibung
onOpenChange((open: boolean) => void)–Nein–
openboolean–Nein–
shortcutstring–NeinSingle key that opens the palette while Ctrl/⌘ is held, e.g. `"k"`.
titlestring–NeinAccessible dialog title; defaults to the `commandPalette` catalog entry.
Props von CommandInput
PropTypStandardPflichtBeschreibung
asChildboolean–Nein–
classNamestring–Nein–
disabledboolean–Nein–
onValueChange((search: string) => void)–NeinEvent handler called when the search value changes.
valuestring–NeinOptional controlled state for the value of the search input.
Props von CommandItem
PropTypStandardPflichtBeschreibung
asChildboolean–Nein–
classNamestring–Nein–
disabledboolean–NeinWhether this item is currently disabled.
valuestring–NeinA unique value for this item. If no value is provided, it will be inferred from `children` or the rendered `textContent`. If your `textContent` changes between renders, you _must_ provide a stable, unique `value`.

Siehe auch