Skip to content

mattpilott/svelte-keydown

 
 

Repository files navigation

svelte-keydown

NPM

Utility to listen for keyboard events.

Utility component leveraging the svelte:body API to listen for keydown events.

Try it in the Svelte REPL.

Use Cases

  • toggle modals
  • capture a combination of keys (i.e., "Meta-s")

Installation

Yarn

yarn add -D svelte-keydown

NPM

npm i -D svelte-keydown

pnpm

pnpm i -D svelte-keydown

Usage

Basic

<script>
  import Keydown from "svelte-keydown";

  let events = [];
</script>

<Keydown
  on:Enter={() => {
    events = [...events, "enter"];
  }}
/>

Press "enter": {events.join(", ")}

Pause on input

Set pauseOnInput to prevent the utility from capturing keydown events on input events.

<script>
  import Keydown from "svelte-keydown";

  let evt = [];
</script>

<Keydown
  pauseOnInput
  on:key={(e) => {
    evt = [...evt, e.detail];
  }}
/>

<input placeholder="Type here..." />

{evt.join("")}

Preventing the default behavior

This component forward the on:keyup and on:keydown events.

You can use on:keydown to prevent the default behavior for certain keys.

In the following example, pressing "Space" should not cause the browser page to scroll.

<Keydown
  on:keydown={(e) => {
    if (e.key === " ") e.preventDefault();
  }}
  on:Space={(e) => {
    console.log("key", "Space");
  }}
/>

Examples

Escape to close a modal

In this use case, keydown events are paused if the modal is not open.

<script>
  import Keydown from "svelte-keydown";

  let showModal = true;
</script>

<Keydown paused={!showModal} on:Escape={() => (showModal = false)} />

<button on:click={() => (showModal = !showModal)}>Toggled? {showModal}</button>

on:combo

Use the combo dispatched event to listen for a combination of keys.

<script>
  import Keydown from "svelte-keydown";

  let combo = [];
</script>

<Keydown on:combo={(e) => (combo = [...combo, e.detail])} />

{combo.join(", ")}

separator

Use the separator property to customize the separating key between multiple keys.

<script>
  import Keydown from "svelte-keydown";

  let combo = [];
</script>

<Keydown separator="+" on:combo={(e) => (combo = [...combo, e.detail])} />

{combo.join(", ")}

API

Prop Type Default value
paused boolean false
pauseOnInput boolean false
separator string -

Forwarded events

  • on:keyup
  • on:keydown

Dispatched events

on:[Key]

Example:

<Keydown on:Enter />
<Keydown on:Escape />
<Keydown on:Space />

on:key

Alternative API to on:[Key].

Example:

<script>
  import Keydown from "svelte-keydown";

  let keys = [];
</script>

<Keydown on:key={({ detail }) => (keys = [...keys, detail])} />

<pre>{JSON.stringify(keys, null, 2)}</pre>

on:combo

Triggered when a sequence of keys are pressed and cleared when a keyup event is fired.

Examples:

  • "Shift-S"
  • "Meta-c" (Copy)
  • "Meta-v" (Paste)
<script>
  import Keydown from "svelte-keydown";

  let combos = [];
</script>

<Keydown on:combo={({ detail }) => (combos = [...combos, detail])} />

<pre>{JSON.stringify(combos, null, 2)}</pre>

TypeScript

Svelte version 3.31 or greater is required to use this component with TypeScript.

TypeScript definitions are located in the types folder.

Changelog

CHANGELOG.md

License

MIT

About

Utility to listen for keyboard events

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Svelte 92.9%
  • JavaScript 7.1%