CommandProvider

Code

import { type Command, useRegisterCommands } from "@fadymondy/nasaq/web";import { FilePlus2 } from "lucide-react";import { useMemo } from "react";export function IssuesPage({ createIssue }: { createIssue: () => void }) {  const commands = useMemo<Command[]>(    () => [      {        id: "mahaam.issue.new",        section: "create",        label: "New issue",        icon: FilePlus2,        shortcut: "C",        keywords: ["add", "مهمة"],        perform: createIssue,      },    ],    [createIssue],  );  useRegisterCommands(commands);  return <h1>Issues</h1>;}

Keyboard & Commands · stable

Live examples and controls: CommandProvider in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/commands.json

The registry that lets a product add commands to the CommandPalette without Nasaq holding any business logic. Any mounted component calls useRegisterCommands([...]) with plain data and a perform callback; the commands exist while it is mounted and disappear when it unmounts, so a page can contribute "This page" actions and the palette stays accurate. Async sources (useRegisterCommandSource) add records as the user types. The registry also binds keyboard shortcuts (C, G I) globally.

AppShell already renders a CommandProvider. Use it directly only for apps without the shell. It has no story of its own; it is demonstrated by the Command Palette story.

When to useCopy Anchor Link

• Adding navigation, create, contextual, AI or system actions to the palette.
• Binding single-key or sequence shortcuts (C, G I) to actions.
• Searching your own data (issues, people, docs) from the palette.
• Building your own command UI on useRegisteredCommands.

When not to useCopy Anchor Link

• Modifier shortcuts (⌘S): the binder ignores Meta/Ctrl/Alt chords; own them with your own key handler and set bindShortcut: false.
• A menu of item actions in the UI (context or dropdown menus): use DropdownMenu.
• Rendering the palette: use CommandPalette.

ImportCopy Anchor Link

import {
  CommandProvider, useRegisterCommands, useRegisterCommandSource, useRegisteredCommands,
  COMMAND_SECTIONS, DEFAULT_SECTION_LABELS, normalizeForSearch, scoreCommand,
  type Command, type CommandSource, type CommandSection,
} from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { type Command, useRegisterCommands } from "@fadymondy/nasaq/web";
import { FilePlus2 } from "lucide-react";
import { useMemo } from "react";

export function IssuesPage({ createIssue }: { createIssue: () => void }) {
  const commands = useMemo<Command[]>(
    () => [
      {
        id: "mahaam.issue.new",
        section: "create",
        label: "New issue",
        icon: FilePlus2,
        shortcut: "C",
        keywords: ["add", "مهمة"],
        perform: createIssue,
      },
    ],
    [createIssue],
  );
  useRegisterCommands(commands);
  return <h1>Issues</h1>;
}

Inside an AppShell with a <CommandPalette />, "New issue" now appears under "Create", and pressing C (outside text fields) runs it.

Always pass a stable (memoised) array: the effect depends on array identity.

AnatomyCopy Anchor Link

CommandProvider (or AppShell)
├─ CommandRegistry              one instance; a nested provider reuses the outer one
├─ ShortcutBinder               window keydown listener for registered shortcuts
└─ your tree
   ├─ useRegisterCommands(...)          → registry.setCommands(ownerId, commands)
   ├─ useRegisterCommandSource(...)     → registry.setSource(ownerId, source)
   └─ CommandPalette                    → useRegisteredCommands()

APICopy Anchor Link

CommandCopy Anchor Link

CommandSourceCopy Anchor Link

Results without a section land in "search". Sources run only on the root page.

CommandProviderCopy Anchor Link

CommandRegistry (class)Copy Anchor Link

HooksCopy Anchor Link

Constants and helpersCopy Anchor Link

RankingCopy Anchor Link

Sections in sectionOrder, then match score, then priority, then registration order. With no query, searchOnly commands are hidden.

Shortcut bindingCopy Anchor Link

• Single keys ("C"), sequences ("G I", each key within 900ms of the last), "Shift A" (Shift held), and modified chords: "Mod K", "⌘ Shift P", "Alt N" (Mod/⌘ is ⌘ on Apple, Ctrl elsewhere; <html data-platform> decides when set, otherwise the browser's platform). Shift only counts for letters and digits; "?" already implies it.
• The longest registered sequence wins: with "G C" and "C" both bound, G then C runs only "G C". A pending prefix that is also bound on its own runs when the sequence is not continued in time.
• Matched on physical keys (KeyC → c, Digit1 → 1), so shortcuts work on Arabic layouts. Other keys match on event.key lower-cased (e.g. arrowdown, escape).
• Plain keys are ignored while typing in an input, textarea, select or contenteditable, inside a dialog combobox, when the event is already defaultPrevented, and while a dialog or menu is open. Chords with Mod/Ctrl/Alt fire anywhere.
• A hit (or a pending prefix) calls preventDefault(); a hit calls perform().

ExamplesCopy Anchor Link

Page-scoped commands that come and goCopy Anchor Link

import { type Command, useRegisterCommands } from "@fadymondy/nasaq/web";
import { Archive } from "lucide-react";
import { useMemo } from "react";

export function ProjectPage({ archive, name }: { archive: () => void; name: string }) {
  const commands = useMemo<Command[]>(
    () => [
      {
        id: "mahaam.project.archive",
        section: "context",
        label: `Archive ${name}`,
        icon: Archive,
        hint: "Project",
        searchOnly: true,
        perform: archive,
      },
    ],
    [archive, name],
  );
  useRegisterCommands(commands);
  return null;
}

Custom section and a shortcut owned elsewhereCopy Anchor Link

import { type Command, useRegisterCommands } from "@fadymondy/nasaq/web";
import { PanelLeft, Rocket } from "lucide-react";
import { useMemo } from "react";

export function Extra({ toggleSidebar }: { toggleSidebar: () => void }) {
  const commands = useMemo<Command[]>(
    () => [
      { id: "app.deploy", section: "deploy", sectionLabel: "Deploy", sectionOrder: 5, label: "Deploy to staging", icon: Rocket, perform: () => {} },
      { id: "app.sidebar", section: "system", label: "Toggle sidebar", icon: PanelLeft, shortcut: "⌘ B", bindShortcut: false, perform: toggleSidebar },
    ],
    [toggleSidebar],
  );
  useRegisterCommands(commands);
  return null;
}

Provider for an app without AppShell, Arabic labelsCopy Anchor Link

import { type Command, CommandPalette, CommandProvider, useRegisterCommands } from "@fadymondy/nasaq/web";
import { Home } from "lucide-react";
import { useMemo, useState } from "react";

function Registrar() {
  const commands = useMemo<Command[]>(
    () => [{ id: "app.home", section: "navigation", label: "الرئيسية", keywords: ["home"], icon: Home, shortcut: "G H", perform: () => location.assign("/") }],
    [],
  );
  useRegisterCommands(commands);
  return null;
}

export function App() {
  const [open, setOpen] = useState(false);
  return (
    <CommandProvider>
      <Registrar />
      <CommandPalette open={open} onOpenChange={setOpen} />
    </CommandProvider>
  );
}

Use the matcher in your own listCopy Anchor Link

import { type Command, normalizeForSearch, scoreCommand } from "@fadymondy/nasaq/web";

export function filterCommands(all: Command[], raw: string) {
  const query = normalizeForSearch(raw);
  return all.filter((c) => scoreCommand(c, query) > 0).sort((a, b) => scoreCommand(b, query) - scoreCommand(a, query));
}

AccessibilityCopy Anchor Link

Shortcuts are the keyboard route to commands; the palette is the discoverable route.

• Shortcuts never fire while the user types, so they cannot corrupt input.
• Always give commands a visible label; icons are decorative.
• Every command with a shortcut should also be reachable from the palette (it is, automatically).
• Localise: every label, hint, sectionLabel and keywords.

RTL & i18nCopy Anchor Link

• Shortcuts use physical keys, so they are layout-independent (Arabic, AZERTY…).
• Include both languages' names in keywords; normalizeForSearch folds Arabic variants.
• Standard section labels are built in for en and ar (DEFAULT_SECTION_LABELS). Custom sections need sectionLabel.

Styling & tokensCopy Anchor Link

None: the registry renders nothing. Presentation belongs to CommandPalette.

Do / Don'tCopy Anchor Link

• Do memoise the arrays and sources you register (useMemo), and keep ids unique and prefixed.
• Do let the owning component register its commands, so they vanish with it.
• Do use searchOnly for destructive or rare commands.
• Don't put business logic in Nasaq: the product owns perform.
• Don't register the same id twice; duplicates are not detected and both would render.
• Don't bind ⌘/Ctrl chords through shortcut; set bindShortcut: false and handle the key yourself.
• Don't nest a CommandProvider expecting a separate registry; it reuses the outer one.

RelatedCopy Anchor Link

• command-palette: the UI that reads the registry
• app-shell: includes a CommandProvider
• product-switcher: registers "Switch to…" commands through this registry

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-keyboard-commands-commands--docs