useHotkeyuseHotkey

document의 keydown이 단축키와 맞으면 핸들러를 실행합니다.Run a handler when a document keydown matches a shortcut.

사용법Usage

palette-shortcut.tsx

import { Kbd, useHotkey } from "@horon-ai/react";

function PaletteShortcut({ open }: { open: () => void }) {
  useHotkey("Mod+K", open);
  return <Kbd keys="Mod+K" />;
}

시그니처Signature

use-hotkey.ts

export type HotkeyOptions = {
  enabled?: boolean;
};

export function useHotkey(
  keys: string,
  handler: (event: KeyboardEvent) => void,
  options: HotkeyOptions = {},
): void

매개변수Parameters

이름Name	타입Type	기본값Default	설명Description
`keys`	`string`	`-`	Mod+K, Mod+Shift+Enter, Escape 같은 단축키 문자열입니다. Kbd가 그리는 것과 같은 문법을 씁니다.Shortcut string such as Mod+K, Mod+Shift+Enter or Escape, in the same syntax Kbd draws.
`handler`	`(event: KeyboardEvent) => void`	`-`	preventDefault 뒤에 일치한 keydown 이벤트를 받습니다.Called with the matching keydown event after preventDefault().
`options`	`HotkeyOptions`	`{}`	enabled가 유일한 스위치이고 기본값은 true입니다. false면 리스너를 떼어 단축키가 동작하지 않습니다.The only switch is enabled; when false the listener is detached and the hotkey does nothing (default true).

반환값Returns

돌려주는 값은 없습니다. 컴포넌트가 사라지거나 keys, enabled가 바뀌면 리스너를 정리합니다.Nothing; the listener is cleaned up when the component unmounts or keys/enabled change.

동작과 주의Behavior notes

Mod는 OS의 수정 키를 따릅니다. macOS와 iOS에서는 ⌘, Windows, Linux, Android에서는 Ctrl이고, OS를 아직 모르는 동안에는 둘 다 받습니다.Mod follows the OS modifier key: ⌘ on macOS and iOS, Ctrl on Windows, Linux and Android, and either one while the OS is still unknown.
일치하면 preventDefault를 먼저 부르고 핸들러를 실행합니다. 텍스트 입력은 포커스를 잃지 않아 입력 중에 팔레트 단축키가 동작합니다.A match calls preventDefault() before the handler, and text inputs keep their focus, so a palette shortcut still fires mid-typing.
리스너는 이펙트에서 붙이므로 서버 렌더는 아무것도 바인딩하지 않습니다.The listener is attached in an effect, so a server render binds nothing.
핸들러는 ref에 담아 두므로 인라인 화살표 함수를 넘겨도 렌더마다 다시 붙지 않습니다. keys, enabled, OS가 바뀔 때만 다시 구독합니다.The handler is held in a ref, so a caller can pass an inline arrow without re-binding on every render; only keys, enabled and the OS re-subscribe.