Befehlspalette
Regeln
- Verwende die Bibliothek
cmdk – zusammensetzbar, zugänglich, schnelle integrierte Fuzzy-Suche
- Auslöser:
Cmd+K (Mac) / Ctrl+K (Windows/Linux) – registriere einen globalen Tastaturlistener
- Gruppiere Aktionen: Navigation (Seiten), Befehle (Aktionen), Zuletzt verwendet (letzte Auswahlen) – zeige Gruppenüberschriften
- Tastaturnavigation: Pfeiltasten zum Bewegen, Enter zum Auswählen, Escape zum Schließen – alles von cmdk übernommen
- Fuzzy-Suche: cmdk filtert automatisch – Trefferhervorhebung mit bewertungsbasiertem Ranking
- Zuletzt verwendete Elemente: speichere die letzten 5–10 ausgewählten Elemente in
localStorage – zeige sie oben an, wenn die Eingabe leer ist
- Dynamische Aktionen: registriere Aktionen aus verschiedenen Teilen der App – kontextabhängig (zeige verschiedene Aktionen auf verschiedenen Seiten)
- Ladezustand: asynchrone Suchergebnisse (z. B. API-Suche) – zeige Ladeindikator im Ergebnisbereich
Muster
import { Command } from "cmdk";
import { useEffect, useState } from "react";
import { useRouter } from "next/navigation";
function CommandPalette() {
const [open, setOpen] = useState(false);
const router = useRouter();
useEffect(() => {
const handleKeyDown = (e: KeyboardEvent) => {
if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
e.preventDefault();
setOpen((prev) => !prev);
}
};
document.addEventListener("keydown", handleKeyDown);
return () => document.removeEventListener("keydown", handleKeyDown);
}, []);
return (
<Command.Dialog open={open} onOpenChange={setOpen} label="Befehlspalette">
<Command.Input placeholder="Suche oder gebe einen Befehl ein..." />
<Command.List>
<Command.Empty>Keine Ergebnisse gefunden.</Command.Empty>
<Command.Group heading="Zuletzt verwendet">
{recentItems.map((item) => (
<Command.Item key={item.id} onSelect={() => { router.push(item.href); setOpen(false); }}>
{item.label}
</Command.Item>
))}
</Command.Group>
<Command.Group heading="Navigation">
<Command.Item onSelect={() => { router.push("/dashboard"); setOpen(false); }}>
Dashboard
</Command.Item>
<Command.Item onSelect={() => { router.push("/settings"); setOpen(false); }}>
Einstellungen
</Command.Item>
</Command.Group>
<Command.Group heading="Befehle">
<Command.Item onSelect={() => { toggleTheme(); setOpen(false); }}>
Dunkelmodus umschalten
</Command.Item>
<Command.Item onSelect={() => { logout(); setOpen(false); }}>
Abmelden
</Command.Item>
</Command.Group>
</Command.List>
</Command.Dialog>
);
}
Vermeide
- Eine eigene Fuzzy-Suche zu bauen – cmdk übernimmt Filterung, Bewertung und Rangfolge sofort einsatzbereit
e.preventDefault() bei Cmd+K zu vergessen – ohne sie öffnet der Browser die Standardsuche/Adressleiste
- Fehlende Behandlung der Escape-Taste – cmdk erledigt dies über
onOpenChange, stelle aber sicher, dass der Fokus zum vorherigen Element zurückkehrt
- Nur statische Aktionen – registriere Aktionen dynamisch aus dem Seitenkontext (z. B. „Diesen Beitrag bearbeiten“ nur auf Beitragsseiten)
- Keinen leeren Zustand – zeige immer „Keine Ergebnisse gefunden“ an, wenn die Suche nichts findet