Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/metonym/svelte-keydown
Utility to listen for keyboard events
https://github.com/metonym/svelte-keydown
enter escape keydown keyup modal svelte svelte-component utility
Last synced: about 2 months ago
JSON representation
Utility to listen for keyboard events
- Host: GitHub
- URL: https://github.com/metonym/svelte-keydown
- Owner: metonym
- License: mit
- Created: 2020-04-26T14:50:39.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-03-15T02:20:23.000Z (9 months ago)
- Last Synced: 2024-03-16T03:03:08.526Z (9 months ago)
- Topics: enter, escape, keydown, keyup, modal, svelte, svelte-component, utility
- Language: Svelte
- Homepage: https://metonym.github.io/svelte-keydown/
- Size: 220 KB
- Stars: 41
- Watchers: 2
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# svelte-keydown
[![NPM][npm]][npm-url]
> Utility to listen for keyboard events.
Utility component leveraging the [svelte:body API](https://svelte.dev/docs#svelte_body) to listen for [keydown](https://developer.mozilla.org/en-US/docs/Web/API/Document/keydown_event) events.
[Try it in the Svelte REPL](https://svelte.dev/repl/f22827a1e3c94a018a685fec6346db6c).
**Use Cases**
- toggle modals
- capture a combination of keys (i.e., "Meta-s")
---
## Installation
**Yarn**
```bash
yarn add -D svelte-keydown
```
**NPM**
```bash
npm i -D svelte-keydown
```
**pnpm**
```bash
pnpm i -D svelte-keydown
```
## Usage
### Basic
```svelte
import Keydown from "svelte-keydown";
let events = [];
{
events = [...events, "enter"];
}}
/>
Press "enter": {events.join(", ")}
```
### Pause on input
Set `pauseOnInput` to prevent the utility from capturing keydown events on input events.
```svelte
import Keydown from "svelte-keydown";
let evt = [];
{
evt = [...evt, e.detail];
}}
/>
{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.
```svelte
{
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.
```svelte
import Keydown from "svelte-keydown";
let showModal = true;
(showModal = false)} />
(showModal = !showModal)}>Toggled? {showModal}
```
### `on:combo`
Use the `combo` dispatched event to listen for a combination of keys.
```svelte
import Keydown from "svelte-keydown";
let combo = [];
(combo = [...combo, e.detail])} />
{combo.join(", ")}
```
#### `separator`
Use the `separator` property to customize the separating key between multiple keys.
```svelte
import Keydown from "svelte-keydown";
let combo = [];
(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:
```svelte no-eval
```
#### `on:key`
Alternative API to `on:[Key]`.
Example:
```svelte
import Keydown from "svelte-keydown";
let keys = [];
(keys = [...keys, detail])} />
{JSON.stringify(keys, null, 2)}
```
#### `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)
```svelte
import Keydown from "svelte-keydown";
let combos = [];
(combos = [...combos, detail])} />
{JSON.stringify(combos, null, 2)}
```
## TypeScript
Svelte version 3.31 or greater is required to use this component with TypeScript.
TypeScript definitions are located in the [types folder](./types).
## Changelog
[CHANGELOG.md](CHANGELOG.md)
## License
[MIT](LICENSE)
[npm]: https://img.shields.io/npm/v/svelte-keydown.svg?color=%23ff3e00&style=for-the-badge
[npm-url]: https://npmjs.com/package/svelte-keydown