Vue Quick Start

ℹ️ You are viewing documentation for version v0.5.0. If you are using a different version, check all versions on npm , GitHub release history or the Version Management documentation.

This guide shows how to use @keekuun/keymaster-vue to register keyboard shortcuts in Vue projects, with basic examples.

Installation

💡 Version Notice: The documentation shows the latest version (v0.5.0). If you need a specific version, check the Version Management documentation or all versions on npm.

Install Latest Version

npm install @keekuun/keymaster-vue
# or
pnpm add @keekuun/keymaster-vue

Install Specific Version

If you need a specific version (e.g., 0.1.0), specify the version:

npm install @keekuun/keymaster-vue@0.1.0
# or
pnpm add @keekuun/keymaster-vue@0.1.0

⚠️ Note: If using an older version, some APIs in the documentation may not be available. Check the README for that version (on the npm package page) or the Version Management documentation.

Basic Example: Save Shortcut Ctrl+S

The following example uses <script setup> syntax to bind save logic to Ctrl+S in a component:

<template>
  <textarea placeholder="Type here, then press Ctrl+S to save" />
</template>

<script setup lang="ts">
import { useKeyBindingVue } from '@keekuun/keymaster-vue';

function onSave() {
  // Execute save logic here, e.g., call API / update local state
  console.log('Saved successfully');
}

useKeyBindingVue(
  'ctrl+s',
  () => {
    onSave();
  },
  { preventDefault: true }, // Prevent browser's default save page behavior
);
</script>

Place this component in your Vue application, then press Ctrl+S in the browser to verify that the onSave logic is triggered correctly.

Try it out:

Press Ctrl+S or Ctrl+Z anywhere on the page to try the shortcuts.

Last triggered:None

Multiple Shortcuts

You can also bind multiple shortcuts in the same component:

<script setup lang="ts">
import { useKeyBindingVue } from '@keekuun/keymaster-vue';

useKeyBindingVue(
  'ctrl+s',
  () => {
    saveContent();
  },
  { preventDefault: true },
);

useKeyBindingVue('ctrl+z', () => {
  undo();
});

useKeyBindingVue('ctrl+shift+z', () => {
  redo();
});
</script>

Interactive Demo:

Multiple Shortcuts Demo

Multiple different shortcuts can be bound in the same component, each with independent handling logic.

Ctrl+SSave

Ctrl+ZUndo

Ctrl+Shift+ZRedo

Ctrl+BBold

Ctrl+IItalic

Ctrl+KInsert Link

Last triggered:None

Action History:

• No action records

Advanced APIs

Scoped Shortcuts (scopedElement)

When you need to bind shortcuts within a specific element scope (e.g., editors, dialogs), you can use the scopedElement option:

<template>
  <textarea ref="editorRef" placeholder="Press Ctrl+S to save" />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { useKeyBindingVue } from '@keekuun/keymaster-vue';

const editorRef = ref<HTMLTextAreaElement | null>(null);

// Only works within the editor area
useKeyBindingVue(
  'ctrl+s',
  () => {
    console.log('Save editor content');
  },
  {
    scopedElement: editorRef.value,
    preventDefault: true,
  },
);
</script>

Or use the convenient useScopedKeyBindingVue Composition API:

<script setup lang="ts">
import { ref } from 'vue';
import { useScopedKeyBindingVue } from '@keekuun/keymaster-vue';

const containerRef = ref<HTMLDivElement | null>(null);
useScopedKeyBindingVue(
  'ctrl+k',
  () => {
    console.log('Only works within container');
  },
  containerRef,
);
</script>

Interactive Demo:

Scoped Shortcut Demo

Shortcuts in the editor area below only work within the editor. Clicking outside will not trigger shortcuts.

Tip: Press Ctrl+S to save, Ctrl+K to search

Last triggered:None

Editor Mode

Editor mode automatically handles common shortcut conflicts, especially suitable for code editors, rich text editors, and similar scenarios:

<template>
  <textarea ref="editorRef" />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { useEditorKeyBindingVue } from '@keekuun/keymaster-vue';

const editorRef = ref<HTMLTextAreaElement | null>(null);

// Editor mode automatically prevents default behavior
useEditorKeyBindingVue(
  'ctrl+s',
  () => {
    saveCode();
  },
  editorRef.value,
);

useEditorKeyBindingVue(
  'ctrl+z',
  () => {
    undo();
  },
  editorRef.value,
);
</script>

Interactive Demo:

Editor Mode Demo

Editor mode automatically prevents browser default behavior, suitable for code editors, rich text editors, etc.

Ctrl+S Save

Ctrl+Z Undo

Ctrl+Shift+Z Redo

Last action:None

Electron Mode

In Electron applications, you can use useElectronKeyBindingVue to adapt shortcut coordination between the main process and renderer process:

<script setup lang="ts">
import { useElectronKeyBindingVue } from '@keekuun/keymaster-vue';

useElectronKeyBindingVue(
  'ctrl+alt+r',
  () => {
    window.electron?.ipcRenderer?.send('shortcut:reload');
  },
  {
    electronHook: ({ parsed, processInfo, versions }) => {
      console.log('[vue electron shortcut]', parsed, processInfo, versions);
      return true;
    },
  },
);
</script>

Electron Hook (electronHook)

You can also use electronHook in Vue to intercept or extend Electron behavior:

useElectronKeyBindingVue('ctrl+alt+r', handler, {
  electronHook: ({ event, parsed, processInfo, versions }) => {
    // custom logging / monitoring
    return true;
  },
});

Interactive Demo:

Electron Mode Demo

Electron mode adapts to desktop application scenarios, allowing you to extend or intercept Electron-specific behaviors via electronHook.

Current Environment:Browser Environment (Demo Only)

Try these shortcuts (will trigger hook in Electron environment):

Ctrl+Alt+R Reload

Ctrl+Shift+I DevTools

Last triggered:None

Shortcut Combination Management

Use KeyBindingManager to manage a group of related shortcut bindings:

<script setup lang="ts">
import { onMounted, onBeforeUnmount } from 'vue';
import { createKeyBindingManager, isValidShortcut, formatShortcut } from '@keekuun/keymaster-vue';

let manager: ReturnType<typeof createKeyBindingManager> | null = null;

onMounted(() => {
  manager = createKeyBindingManager();

  // Chain register multiple shortcuts
  manager
    .register('ctrl+s', () => save(), { preventDefault: true })
    .register('ctrl+z', () => undo())
    .register('ctrl+shift+z', () => redo());
});

onBeforeUnmount(() => {
  // Automatically clean up all bindings when component unmounts
  manager?.dispose();
});
</script>

Utility functions:

• isValidShortcut(shortcut): Check if shortcut format is valid
• formatShortcut(shortcut): Format shortcut string (normalize case)

Interactive Demo:

KeyBindingManager Demo

Use KeyBindingManager to manage a group of related shortcut bindings, supporting chaining and batch cleanup.

Status:Disabled

Last triggered:None

API Overview

useKeyBindingVue(shortcut, handler, options?)

• shortcut: string - Shortcut string, e.g., "ctrl+s", "ctrl+shift+z"
• handler: (event: KeyboardEvent) => void - Callback triggered when matching shortcut is detected
• options: KeymasterVueBindingOptions (optional)
  • preventDefault?: boolean - Whether to call event.preventDefault() after trigger
  • stopPropagation?: boolean - Whether to call event.stopPropagation() after trigger
  • scopedElement?: HTMLElement | null - Scoped element, shortcut only works within element
  • editorMode?: boolean - Editor mode, automatically handles shortcut conflicts
  • electronMode?: boolean - Electron mode, adapts for Electron applications