svelte-listen

A tiny Svelte 5 attachment for keyboard shortcuts. Bind global key combos with a single {@attach ...} and get automatic cleanup.

• Works with the new {@attach ...} syntax
• Adds/removes the window keydown listener automatically
• Shortcut strings look like Ctrl+Shift+K
• Fully typed with helper shortcut types

Installation

npm install @akcodeworks/svelte-listen
# pnpm add @akcodeworks/svelte-listen
# yarn add @akcodeworks/svelte-listen

Peer dependency: svelte@^5.0.0.

Quick start

<script lang="ts">
  import { listener } from '@akcodeworks/svelte-listen';
</script>

<button
  {@attach listener({
    Enter: (e) => {
      e.preventDefault();
      console.log('Pressed Enter anywhere');
    },
    'Ctrl+Shift+K': () => console.log('Pressed Ctrl+Shift+K')
  })}
>
  Press me
</button>

The attachment will:

• Register a global keydown listener for any shortcuts you specify.
• Clean everything up automatically when the element is destroyed.

Shortcut syntax

Shortcut keys use the KeyboardEvent.key names and a +-separated list of modifiers:

• Single key: "Escape", "K", "F2", "ArrowUp"
• With modifiers: "Ctrl+K", "Alt+ArrowDown", "Ctrl+Shift+L"

Use uppercase letters for single-character keys; the helper normalizes casing for you.

API

listener<T extends HTMLElement>(shortcuts?: ShortcutHandlers): Attachment<T>

• shortcuts: A map of ShortcutString to handler.
• Returns a Svelte attachment that can be used with {@attach ...} on any element. The element reference is unused but required by Svelte's {@attach ...} contract.

Types are exported for convenience:

import type { ShortcutString, KeyboardEventKey, ShortcutHandlers } from '@akcodeworks/svelte-listen';

Development

• Install deps: npm install
• Run the demo app: npm run dev -- --open
• Tests: npm test
• Lint/format: npm run lint and npm run format
• Build package: npm run build (runs svelte-package and publint)

Notes

• Keyboard shortcuts are bound at window level on keydown.
• Call event.preventDefault() inside your shortcut handler if you need to suppress the browser default for that key combo.