Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gaucho-labs/leptos-hotkeys
a declarative way of using keyboard shortcuts + callbacks in leptos applications
https://github.com/gaucho-labs/leptos-hotkeys
hotkeys leptos wasm
Last synced: 4 days ago
JSON representation
a declarative way of using keyboard shortcuts + callbacks in leptos applications
- Host: GitHub
- URL: https://github.com/gaucho-labs/leptos-hotkeys
- Owner: gaucho-labs
- License: mit
- Created: 2024-01-07T21:03:32.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-25T19:36:07.000Z (20 days ago)
- Last Synced: 2025-02-04T20:47:14.261Z (10 days ago)
- Topics: hotkeys, leptos, wasm
- Language: Rust
- Homepage: https://leptos-hotkeys.vercel.app
- Size: 22.9 MB
- Stars: 54
- Watchers: 4
- Forks: 12
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-leptos - leptos-hotkeys
README
# [_leptos-hotkeys_](https://github.com/gaucho-labs/leptos-hotkeys)
[](#contributors-)
Declaratively create and pair keybindings with callbacks for Leptos applications.
[](https://crates.io/crates/leptos_hotkeys)
[](https://discord.gg/XhVbKk38ux)
Leptos-hotkeys creates and manages keyboard shortcuts. It provides macros and functions that simplify the definition of
keybindings, since the management of event lifecycle associated with keyboard interactions has been done for you!
## Live example
Curious to see how it works? [See the demo](https://leptos-hotkeys.vercel.app).
To get started, follow the [Quick Start](#quick-start) section.
## Features
> [!NOTE]
> This crate has three types of hotkeys: global, scoped, and focus-trapped.
### The `use_hotkeys!` Macro
Use this macro to declare global and scoped hotkeys. This macro has js idioms while preserving Leptos standards. [More about the macro.](](#macro-api).)
### Global Hotkeys
This example creates two global hotkeys: `W` and `F`.
```rust
use leptos_hotkeys::use_hotkeys;
#[component]
pub fn SomeComponent() -> impl IntoView {
let (count, set_count) = create_signal(0);
// creating a global scope for the W key
use_hotkeys!(("keyw") => move |_| {
logging::log!("w has been pressed");
set_count.update(|c| *c += 1);
});
// this is also a global scope for the F key!
use_hotkeys!(("keyf", "*") => move |_| {
logging::log!("f has been pressed");
set_count.update(|c| *c -= 1);
});
view! {
Num Respects: {count}
}
}
```
> [!TIP]
> How do I write certain keys? See [Key Grammar](#keybinding-grammar).
> [!NOTE]
> The `*` symbol is reserved for the global scope_.
>
> The `W` hotkey omitted the scope parameter, implicitly making it global.
### Scoped Hotkeys
Scopes provide context behind hotkeys. This context can be chained to a component, a state, or logic.
This example shows an inner and outer scope and hotkeys that toggle scopes.
```rust
use leptos_hotkeys::{use_hotkeys, use_hotkeys_context, HotkeysContext};
#[component]
pub fn SomeComponent() -> impl IntoView {
let HotkeysContext { enable_scope, disable_scope, .. } = use_hotkeys_context();
// switch into the inner scope
use_hotkeys!(("keyi", "outer") => move |_| {
disable_scope.call("outer".to_string());
enable_scope.call("inner".to_string());
});
// switch into the outer scope
use_hotkeys!(("keyo", "inner") => move |_| {
disable_scope.call("inner".to_string());
enable_scope.call("outer".to_string());
});
view! {
// outer logic residing...
// inner logic
}
}
```
> [!NOTE]
> Scopes are case-insensitive. That means `my_scope` and `mY_sCoPe` are considered the same scope.
### Focus trapped Hotkeys (the `use_hotkeys_ref!` macro)
This example embeds a hotkey to a `
` tag. This hotkey will fire iff the element is focused and the scope is correct.
```rust
use leptos_hotkeys::use_hotkeys_ref;
#[component]
pub fn SomeComponent() -> impl IntoView {
let p_ref = use_hotkeys_ref!(("keyk", "*") => move |_| {
// some logic
});
view! {
p tag with node ref
}
}
```
## Quick Start
### Installation
```shell
cargo add leptos_hotkeys
```
We also offer other feature flags that enhance developer experience, see [features](#features).
### `provide_hotkeys_context()`
Call `provide_hotkeys_context()` in the `App()` component. This will provide the `HotkeysContext` for the current reactive node and all of its descendents. This function takes three parameters, the `node_ref`, a flag to disable blur events and a list of `initially_active_scopes`.
`provide_hotkeys_context()` returns a `HotkeyContext`. To manage hotkeys, you can pull necessary signals out of `HotkeysContext`.
```rust
use leptos_hotkeys::{provide_hotkeys_context, HotkeysContext, scopes};
#[component]
pub fn App() -> impl IntoView {
provide_meta_context();
let main_ref = create_node_ref::();
let HotkeysContext { .. } = provide_hotkeys_context(main_ref, false, scopes!());
view! {
// <-- attach main ref here!
}
}
```
> [!NOTE]
> If you're using [scopes](#scoped-hotkeys), you can initialize with a specific scope.
## That's it! [You can create global, scoped, and focus-trapped hotkeys!](#features)
### Keybinding Grammar
`leptos_hotkeys` matches code values from [KeyboardEvent's](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code) `code` property. For reference, here's a list of [all code values for keyboard events](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values).
You can bind multiple hotkeys to a callback. For example:
```txt
"KeyG+KeyR,MetaLeft+KeyO,ControlLeft+keyK"
```
Keys are case-agnostic and whitspace-agnostic. For a hotkey with multiple keys, use the `,` as a delimiter in a sequence of keys.
### `scopes!()`
Maybe you want to initialize a certain scope upon load, that's where the prop `initially_active_scopes` comes into play.
Instead of having to create a `vec!["scope_name".to_string()]`, use the `scopes!()` macro.
```rust
use leptos_hotkeys::{provide_hotkeys_context, scopes};
#[component]
pub fn App() -> impl IntoView {
let main_ref = create_node_ref::();
provide_hotkeys_context(main_ref, false, scopes!("scope_a", "settings_scope"));
view! {
// ... routes
}
}
```
## The `debug` feature flag
Improve developer experience by introducing the `debug` flag which adds logging to your console in CSR. It logs the current pressed key `code` values, hotkeys fires, and scopes toggling.
Just simply:
```toml
leptos_hotkeys = { path = "0.2.1", features = ["debug"] }
```
## Contributors
Álvaro Mondéjar
💻
Robert Junkins
💻
LeoniePhiline
📖
Gábor Szabó
📖
Phillip Baird
🐛 💻
zakstucke
🐛 💻
Ryangguk Kim
💻
Max Bergmark
💻
Pavlo Myroniuk
💻