# keyboard_shortcuts
[](https://hex.pm/packages/keyboard_shortcuts)
[](https://hexdocs.pm/keyboard_shortcuts/)
A Gleam library for handling keyboard shortcuts in Lustre applications with cross-platform modifier key support.
## Installation
```sh
gleam add keyboard_shortcuts
```
## Quick Start
```gleam
import keyboard_shortcuts.{
Key, KeyDown, Modifier, Shortcut, install_keyboard_shortcuts
}
import lustre/effect.{type Effect}
// Define shortcuts in your init function
fn init(_) -> #(Model, Effect(Msg)) {
#(
initial_model,
effect.from(fn(dispatch) {
dispatch
|> install_keyboard_shortcuts(KeyDown, [
// Cmd+Z on Mac, Ctrl+Z on other platforms
Shortcut([Modifier, Key("Z")], UndoMsg, [PreventDefault]),
])
}),
)
}
```
## Features
- **Cross-platform modifier keys**: Automatically uses ⌘ (Cmd) on macOS and Ctrl on other platforms
- **Flexible key combinations**: Support for modifier keys (Cmd/Ctrl), Shift, Alt, and regular keys
- **Event options**: Prevent default browser behavior and exclude specific elements
- **Key and Code support**: Use either `Key` (layout-dependent) or `Code` (physical key) matching
- **Input element exclusion**: Automatically exclude input elements from shortcuts
## Key Types
### Modifier Keys
- `Modifier`: Cmd key on macOS, Ctrl key on other platforms
- `Shift`: Shift key
- `Alt`: Alt/Option key
### Regular Keys
- `Key(String)`: Layout-dependent key (e.g., "Z", "Enter")
- `Code(String)`: Physical key code (e.g., "KeyZ", "Enter")
## Shortcut Options
```gleam
pub type ShortcutOption {
PreventDefault // Prevent browser's default action
Exclude(String) // Exclude specific HTML tag names
ExcludeInputElements // Exclude INPUT, TEXTAREA, SELECT elements
}
```
## Platform Utilities
The library provides helpful utilities for displaying platform-appropriate shortcuts:
```gleam
keyboard_shortcuts.modifier_symbol() // "⌘" on Mac, "Ctrl" elsewhere
keyboard_shortcuts.modifier_name() // "Cmd" on Mac, "Ctrl" elsewhere
keyboard_shortcuts.is_mac() // Bool: true if running on macOS
```
## Example
See the [`example/`](./example/) directory for a complete Lustre application demonstrating:
- Setting up keyboard shortcuts in the init function
- Handling shortcut messages in the update function
- Displaying platform-appropriate shortcut hints in the UI
- Using various shortcut options
## Browser Support
This library works in all modern browsers. Note that on Safari, `PreventDefault` may not work for some system shortcuts like page refresh (⌘R).
## Further Documentation
Full API documentation can be found at <https://hexdocs.pm/keyboard_shortcuts>.
## Development
## Development
File bug reports or feature requests at the [issue tracker](https://todo.sr.ht/~tpjg/dnd).
To send patches configure git [sendemail](https://git-send-email.io) and send your patches.
```sh
git config sendemail.to "~tpjg/keyboard_shortcuts@lists.sr.ht"
git commit -m "..."
git send-email HEAD^
```
Or to send just once:
```sh
git commit
git send-email --to "~tpjg/keyboard_shortcuts@lists.sr.ht" HEAD^
```
