🎹 Keytrix

• Github
• npm

Keytrix is an ultra-lightweight, type-safe, and zero-dependency keyboard shortcut & hotkey engine for modern web applications. Keytrix는 모던 웹을 위한 초경량, 타입안전, 의존성 제로(Zero-dependency) 단축키 매니저 라이브러리입니다.

✨ Why Keytrix? (왜 Keytrix인가요?)

• OS Auto-Mapping (mod): Automatically maps mod+k to Cmd+K on macOS and Ctrl+K on Windows/Linux. (mod+k 작성 시 Mac에서는 Cmd+K, Windows/Linux에서는 Ctrl+K로 자동 전환됩니다.)
• Smart Form Filtering: Automatically ignores global hotkeys when typing inside <input>, <textarea>, or contenteditable elements. (<input>, <textarea> 등 텍스트 입력 중일 때는 기본 단축키 동작을 알아서 방지합니다.)
• Vim-style Key Sequences: Easily chain sequential keystrokes like g followed by h. (g 누르고 h 누르는 식의 연속 키(Sequence) 입력을 간편하게 등록할 수 있습니다.)
• Scope & Modal Isolation: Isolate hotkeys when modals or popups are open to prevent background triggers. (모달이나 팝업이 떴을 때 배경의 단축키를 잠그고 해당 스코프 단축키만 실행시킵니다.)
• Zero Dependencies: Pure TypeScript implementation with zero external packages for maximum performance. (순수 TypeScript로 작성되었으며 외부 의존성이 전혀 없는 초경량 엔진입니다.)

📦 Installation (설치)

Currently available via npm registry: (npm 레지스트리를 통해 설치할 수 있습니다.)

npm install keytrix

🚀 Quick Start (빠른 시작)

import { keytrix } from '@cookedas1/keytrix';

// 1. Cross-platform Hotkey (Mac: Cmd+K / Win: Ctrl+K)
keytrix.on('mod+k', (e) => {
  openSearchModal();
});

// 2. Multiple Key Combos (다중 조합키)
keytrix.on('ctrl+shift+p, cmd+shift+p', () => {
  openCommandPalette();
});

// 3. Sequence Keys (Vim 스타일 연속키: 'g' 누른 후 'h')
keytrix.sequence('g h', () => {
  navigateToHome();
});

📖 Syntax & API Reference (상세 문법 및 API 가이드)

1. Modifiers & Key Aliases (키 별칭 및 자동 표준화)

Keytrix automatically normalizes and parses string key definitions: (Keytrix는 키 이름을 자동으로 해석하고 표준화합니다.) mod : Cmd on macOS / Ctrl on Windows & Linux ctrl / control : Control key cmd / command / meta : Command/Windows key alt / option : Alt/Option key esc / escape : Escape key space : Spacebar

keytrix.on('alt+shift+space', () => {
  console.log('Action triggered!');
});

2. Form Input Bypass (입력 폼 예외 처리)

By default, hotkeys are bypassed when typing inside form elements. Pass enableInInput: true to allow execution inside inputs: (기본적으로 텍스트 입력 창에서는 단축키가 실행되지 않습니다. 입력 창 내에서도 허용하려면 옵션을 추가하세요.)

// Allow Ctrl+Enter inside <textarea>
keytrix.on('ctrl+enter', submitForm, { enableInInput: true });

3. Scope Management (스코프/모달 제어)

Isolate hotkeys to specific application states or modal dialogs: (모달 창이 열렸을 때 메인 화면의 단축키를 끄고 모달 전용 단축키만 켤 수 있습니다.)

// Register modal-specific hotkey (모달 전용 단축키 등록)
keytrix.on('esc', closeModal, { scope: 'modal' });

// When modal opens (모달 열릴 때)
keytrix.setScope('modal');

// When modal closes (모달 닫힐 때 - 'global' 스코프로 복원)
keytrix.resetScope();

4. Unsubscribing (단축키 해제)

on and sequence return an unsubscribe cleanup function: (on 또는 sequence 함수는 바인딩 해제 함수를 반환합니다.)

const unsubscribe = keytrix.on('ctrl+s', saveDocument);

// Remove listener when no longer needed (컴포넌트 언마운트 시 해제)
unsubscribe();

📄 License

MIT © 2026 cookedas1 & LLL Studio.