keyboard_shortcuts

A Gleam library for handling keyboard shortcuts in Lustre applications with cross-platform modifier key support.

Installation

gleam add keyboard_shortcuts

Quick Start

import keyboard_shortcuts.{
  Key, KeyDown, Modifier, PreventDefault, 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

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:

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/ 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

File bug reports or feature requests at the issue tracker. To send patches configure git sendemail and send your patches.

git config sendemail.to "~tpjg/keyboard_shortcuts@lists.sr.ht"

git commit -m "..."
git send-email HEAD^

Or to send just once:

git commit
git send-email --to "~tpjg/keyboard_shortcuts@lists.sr.ht" HEAD^