@svelte-put/shortcut GitHub

add keyboard shortcuts to node

@svelte-put/shortcut @svelte-put/shortcut @svelte-put/shortcut changelog

Installation

terminal

npm install --save-dev @svelte-put/shortcut

Quick Start

quick start

<script lang="ts">
  import { shortcut, type ShortcutEventDetails } from '@svelte-put/shortcut';

  function handleK(detail: ShortcutEventDetails) {
    console.log('attached node:', detail.node);
    console.log('original trigger config:', detail.trigger);
  }
</script>

<svelte:window
  use:shortcut={{
    trigger: {
      key: 'k',
      modifier: ['ctrl', 'meta'],
      callback: handleK,
    },
  }}
/>

Action Usage Notice

As with any svelte action , shortcut should be use with element and not component.

use:action is an element directive

<-- correct usage-->
<svelte:window use:shortcut />

<-- incorrect usage-->
<Component use:shortcut />

Key Combination

In each use:shortcut, one or an array of ShortcutTrigger can be provided to the trigger parameter.

key

<script>
  import { shortcut } from '@svelte-put/shortcut';
</script>

<svelte:window
  use:shortcut={{ trigger: { key: 'k', modifier: 'ctrl' } }}
  use:shortcut={{
    trigger: [
      { key: 'k', modifier: 'ctrl' },
      { key: 'l', modifier: 'meta' },
    ],
  }}
/>

One or multiple modifiers ( ctrl, meta, alt, shift ) can be provided to trigger.modifier in both and & or fashions.

modifier

<script>
  import { shortcut } from '@svelte-put/shortcut';
</script>

<svelte:window
  use:shortcut={{
    // listen for one of many modifiers (or)
    // ctrl+k or meta+k
    trigger: {
      key: 'k',
      modifier: ['ctrl', 'meta'],
    },
  }}
  use:shortcut={{
    // listen for a combination of multiple modifiers (and)
    // ctrl+shift+k
    trigger: {
      key: 'k',
      modifier: [['ctrl', 'shift']],
    },
  }}
  use:shortcut={{
    // mix & match
    // ctrl+shift+k or meta+k
    trigger: {
      key: 'k',
      modifier: [['ctrl', 'shift'], ['meta']],
    },
  }}
/>

Event vs Callback

In cases where multiple key combinations are registered. You can either:

  1. provide a callback for each combination via trigger.callback, or
  2. use the on:shortcut CustomEvent , in which case it is recommended to give each trigger a unique id for easier identification in the event handler.

event vs callback

<script lang="ts">
  import { shortcut, type ShortcutEventDetails } from '@svelte-put/shortcut';

  let commandPalette = false;
  function onOpenCommandPalette() {
    commandPalette = true;
  }
  function onCloseCommandPalette() {
    commandPalette = false;
  }

  function doSomethingElse(details: ShortcutEventDetails) {
    console.log('Action was placed on:', details.node);
    console.log('Trigger:', details.trigger);
  }

  function onShortcut(event: CustomEvent<ShortcutEventDetails>) {
    if (event.detail.trigger.id === 'do-something-else') {
      console.log('Same as doSomethingElse()');
      // be careful here doSomethingElse would have been called too
    }
  }
</script>

<svelte:window
  use:shortcut={{
    trigger: [
      {
        key: 'k',
        // trigger if either ctrl or meta is pressed
        modifier: ['ctrl', 'meta'],

        callback: onOpenCommandPalette,
        preventDefault: true,
      },
      {
        key: 'Escape',
        // preferably avoid arrow functions here for better performance,
        // with arrow functions the action has to be updated more frequently
        callback: onCloseCommandPalette,
        enabled: commandPalette,
        preventDefault: true,
      },
      {
        key: 'k',
        // trigger if both ctrl & shift are pressed
        modifier: [['ctrl', 'shift']],
        id: 'do-something-else',
        callback: doSomethingElse,
      },
    ],
  }}
  on:shortcut={onShortcut}
/>

Typescript Support

Ambient types for custom events should be available automatically where shortcut is imported.

automatically typed - example source

If the above is not working, fall back to this:

src/app.d.ts - fallback typescript support

API Reference

The best documentation is no documentation!

It is recommended to utilize editor intellisense & explore in-code documentation while using the package (and use typescript if possible 😉) .

See the extracted API Reference on github.

API extraction is powered by @microsoft/api-extractor and @microsoft/api-documenter ).

mouse click faster

Happy making shortcuts! 👨‍💻

Edit this page on GitHub