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("outer"); enable_scope("inner"); }); // switch into the outer scope use_hotkeys!(("keyo", "inner") => move |_| { disable_scope("inner"); enable_scope("outer"); }); view! {` 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:: Álvaro Mondéjar 💻 |
 Robert Junkins 💻 |
 LeoniePhiline 📖 |
 Gábor Szabó 📖 |
 Phillip Baird 🐛 |
 zakstucke 🐛 💻 |