Features
PreviousNext

Keybindings

Define, display, and persist keyboard shortcuts with @kit/keybindings.

What It Does

@kit/keybindings provides a typed action model, keyboard hooks, UI display components, and settings integration.

When To Use

  • You need configurable shortcuts in dashboard-like apps.

Prerequisites

  • keybindingsModel config exists.
  • useKeybindingsFilters() initialized in app filters hook.

How To Use

Define model.

apps/dashboard/config/keybindings.config.ts
import { parseKeybindingsConfig } from '@kit/keybindings/config';
 
export const keybindingsModel = parseKeybindingsConfig({
  'search.command': {
    name: 'Search',
    description: 'Open global search',
    defaultShortcut: 'cmd+k',
    context: 'global',
  },
});

Register handlers.

'use client';
 
import { useKeybinding } from '@kit/keybindings/ui';
 
export function KeybindingsHandlers() {
  useKeybinding('search.command', () => {
    // trigger your command UI
  });
 
  return null;
}

Display shortcuts.

Use KeybindingDisplay or settings UI integration (added by keybindings filters).

Typescript Support

@kit/keybindings can provide strong action-key inference and IDE autocomplete in consuming apps.

Keybindings typescript autocompletion

Keybindings typescript autocompletion

Recommended app-level declaration layout:

keybindings.d.ts
tsconfig.json
package.json

.d.ts typing logic

Keybinding action inference is enabled via module augmentation of @kit/keybindings/ui. This binds useKeybinding, useShortcut, and KeybindingDisplay to your app keybindingsModel.

apps/dashboard/@types/keybindings.d.ts
import '@kit/keybindings/ui'; import { KeybindingDisplay as KeybindingDisplayBase, useKeybinding as useKeybindingBase, useShortcut as useShortcutBase, } from '@kit/keybindings/ui/without-context'; import { keybindingsModel } from '../config/keybindings.config'; declare module '@kit/keybindings/ui' { export function useKeybinding<T extends typeof keybindingsModel = typeof keybindingsModel>( ...params: Parameters<typeof useKeybindingBase<T>> ): ReturnType<typeof useKeybindingBase<T>>; export function useShortcut<T extends typeof keybindingsModel = typeof keybindingsModel>( ...params: Parameters<typeof useShortcutBase<T>> ): ReturnType<typeof useShortcutBase<T>>; export function KeybindingDisplay<T extends typeof keybindingsModel = typeof keybindingsModel>( props: React.ComponentProps<typeof KeybindingDisplayBase<T>>, ): ReturnType<typeof KeybindingDisplayBase<T>>; }

Tsconfig requirements

  • Ensure the .d.ts file is included by your app tsconfig (via include, files, or typeRoots).
  • Keep the import path to keybindingsModel aligned with your app config location.
apps/dashboard/tsconfig.json (example)
{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./@types"]
  }
}

Filter API

Keybindings behavior is assembled from client, server, and cross-env filters to keep shortcut runtime, settings persistence, and translations modular.

FilterParametersReturnRegistered By (package file)Initialized In (app entrypoint)Environment
display_trpc_provider_child_in_dashboard{ clientTrpc?: TrpcClientWithQuery<Router<typeof appRouter>>; url?: (s: string) => string; keybindingsModel?: ReturnType<typeof parseKeybindingsConfig> }React.ReactNodekit/keybindings/src/filters/use-filters.tsxapps/dashboard/hooks/use-filters.ts (useKeybindingsFilters)client
display_keybinding{ actionSlug: keyof KeybindingActions }React.ReactNodekit/keybindings/src/filters/use-filters-with-ctx.tsxKeybindingsProvider context (injected by useKeybindingsFilters)client
get_shortcut{ actionSlug: keyof KeybindingActions }{ shortcut: string | null; formattedShortcut: string } | nullkit/keybindings/src/filters/use-filters-with-ctx.tsxKeybindingsProvider context (injected by useKeybindingsFilters)client
get_settings_schema{}SettingsSchemakit/keybindings/src/filters/use-filters.tsxapps/dashboard/hooks/use-filters.ts (useKeybindingsFilters)client
get_settings_ui_config{ clientTrpc: TrpcClientWithQuery<Router<unknown>> }ReturnType<typeof parseUISettingConfig>kit/keybindings/src/filters/use-filters.tsxapps/dashboard/hooks/use-filters.ts (useKeybindingsFilters)client
server_get_settings_schema{}SettingsSchemakit/keybindings/src/filters/server-filters.tsapps/dashboard/lib/init-server-filters.ts (initKeybindingsServerFilters)server
cross_env_get_translations{ language: string; namespace: string }Record<string, string> | nullkit/keybindings/src/filters/cross-env-filters.tsapps/dashboard/lib/init-cross-env-filters.ts (initKeybindingsFilters)cross-env
cross_env_get_namespaces{}string[]kit/keybindings/src/filters/cross-env-filters.tsapps/dashboard/lib/init-cross-env-filters.ts (initKeybindingsFilters)cross-env

MCP Context

capability: keybindings_system entrypoints: - apps/dashboard/config/keybindings.config.ts - @kit/keybindings/ui - kit/keybindings/src/filters/use-filters.tsx - kit/keybindings/src/filters/use-filters-with-ctx.tsx - kit/keybindings/src/filters/server-filters.ts - kit/keybindings/src/filters/cross-env-filters.ts - apps/dashboard/hooks/use-filters.ts - apps/dashboard/lib/init-server-filters.ts - apps/dashboard/lib/init-cross-env-filters.ts inputs: - keybinding_action_map outputs: - active_keyboard_shortcuts constraints: - action IDs must exist in model - avoid collisions with browser/system shortcuts side_effects: - user shortcut updates may be persisted in settings storage

Agent Recipe

  1. Add action definitions in config.
  2. Register behavior with useKeybinding.
  3. Confirm settings page exposes shortcut editing UI.

Troubleshooting

  • Handler not firing: check context (global vs input fields) and shortcut format.
  • Wrong URLs on navigation actions: verify route templates and slug transformers.

API Reference

Components

  • KeybindingDisplay - Component to display shortcuts

KeybindingDisplayProps

PropTypeDefault
actionSlug*
keyof T & string
  • KeybindingsProvider - Context provider for keybindings

KeybindingsProviderProps

PropTypeDefault
model*
T
storage
KeybindingsStorage
children*
React.ReactNode
navigationUrlTransformers
((url: string) => string)[]
  • KeybindingsTable - Settings table for editing keybindings

KeybindingsTableProps

PropTypeDefault
filter
"global" | "contextual" |...
className
string
initialKeybindings
Record<string, string>
isLoading
boolean
false

How is this guide?

Last updated on 3/27/2026