Skip to content

README.md

Latest commit

 

History

History
78 lines (55 loc) · 2.17 KB

README.md

File metadata and controls

78 lines (55 loc) · 2.17 KB

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.