🎹">

📦 Installation

NPM
npm install @mbolli/datastar-attribute-on-keys
Setup
<script type="importmap"> { "imports": { "datastar": "https://cdn.jsdelivr.net/gh/starfederation/datastar@v1.0.0-RC.6/bundles/datastar.js" } } </script> <script type="module" src="https://cdn.jsdelivr.net/npm/@mbolli/datastar-attribute-on-keys@1/dist/index.js"></script>

📑 Navigation

📊 Live State

Signals
 

🎹 Datastar On-Keys Plugin

Interactive demo showcasing keyboard event binding with key combinations and multiple keys

📖 Usage Guide

The data-on-keys attribute allows you to bind keyboard events to Datastar actions with powerful key combinations and modifiers.

Basic Syntax

data-on-keys[:key-spec][__modifier1][__modifier2]="action"

Key Specifications

The key-spec defines which keys trigger the action. It can be:

  • Single keys: space, enter, escape, tab, f1, a
  • Key combinations: ctrl-k, alt-enter, shift-space, meta-s, ctrl-shift-z
  • Multiple options: enter.tab, escape.f1.ctrl-q (any of these will trigger)
  • Any key: omit the key-spec entirely to capture all key presses

Key Name Mapping

Common key aliases are automatically mapped to standard JavaScript key names:

Special Keys

  • space → Space character
  • enter / return → Enter
  • escape / esc → Escape
  • tab → Tab
  • backspace → Backspace
  • delete / del → Delete

Navigation Keys

  • up → ArrowUp
  • down → ArrowDown
  • left → ArrowLeft
  • right → ArrowRight
  • pageup → PageUp
  • pagedown → PageDown

Note: Function keys (f1-f12), letter keys (a-z), and other standard keys work as expected.

Modifiers

Target Modifiers

  • Default (no modifier) - Binds to window (global)
  • __el - Binds to the element itself (requires focus)

Behavior Modifiers

  • Default - Prevents default browser behavior (preventDefault())
  • __noprevent - Allows default browser behavior
  • __stop - Stops event propagation (stopPropagation())

Event Timing

  • Default - Triggers on keydown
  • __up - Triggers on keyup

Event Listener Options

  • __capture - Use capture phase
  • __passive - Passive event listener
  • __once - Remove listener after first trigger

Timing Modifiers

Control when and how often callbacks are executed:

  • __delay.{time} - Postpone execution by a fixed time
    • Example: __delay.500ms or __delay.1s
  • __debounce.{time} - Wait for user to stop before executing
    • Options: __leading, __notrailing
    • Example: __debounce.300ms__leading
  • __throttle.{time} - Limit execution rate
    • Options: __trailing, __noleading
    • Example: __throttle.1s__trailing

Note: Time can be specified in milliseconds (ms) or seconds (s).

View Transitions

  • __viewtransition - Wrap state changes in the View Transitions API for smooth animations
    • Example: data-on-keys:space__viewtransition="$counter++"

Note: View Transitions API support varies by browser. The modifier is safely ignored in unsupported browsers.

Common Examples

<!-- Global shortcuts --> <div data-on-keys:ctrl-s="saveDocument()"></div> <div data-on-keys:escape="closeModal()"></div> <!-- Element-specific --> <input data-on-keys:enter__el="submitForm()"> <textarea data-on-keys:ctrl-enter__el="submit()"></textarea> <!-- Allow default behavior --> <div data-on-keys:tab__noprevent="logTab()"></div> <!-- Multiple triggers --> <div data-on-keys:escape.f1.ctrl-h="showHelp()"></div> <!-- Timing modifiers --> <div data-on-keys:enter__delay.500ms="$message = 'Delayed!'"></div> <input data-on-keys__debounce.300ms__el="$search($event.target.value)"> <div data-on-keys:space__throttle.1s="$counter++"></div> <!-- View transitions --> <div data-on-keys:space__viewtransition="$counter++"></div>

Test 1: Single Key - Space Counter

Uses data-on-keys:space to increment counter on spacebar (prevents page scroll by default).

Press Space to increment counter:

Test 2: Key Combination - Ctrl+K

Uses data-on-keys:ctrl-k for a global keyboard shortcut (window is now default).

Press Ctrl + K anywhere to toggle mode:

Mode:

Test 3: Multiple Keys - Enter or Tab

Uses data-on-keys:enter.tab to trigger on multiple keys.

Press Enter or Tab to show message:

Test 4: Global Events - Modal Control

Uses data-on-keys:f1 to open modal and data-on-keys:escape to close it (window is now default).

Press F1 anywhere to open modal, Escape to close it:

🎹 Keyboard-Controlled Modal

This modal was opened with F1 and can be closed with Escape or by clicking the button below.

Test 5: Global Key Monitor

Uses data-on-keys to capture any key press globally (prevents default to avoid conflicts).

Last key pressed:

Press any key anywhere on the page to see it captured:

Test 6: Element-Specific Key Binding

Uses data-on-keys:ctrl-enter__el to capture Ctrl+Enter key only when the input has focus.

Focus this input and press Ctrl + Enter (only works when input is focused):

Test 7: Allow Default Behavior

Uses data-on-keys:tab__noprevent to capture Tab key but still allow normal tab navigation.

Tab through these inputs - the counter will increment but tab navigation still works:

Test 8: Keyup Events

Uses data-on-keys:space__up to trigger on key release instead of key press.

Keydown Events
Keyup Events

Press and hold Space, then release to see the difference between keydown and keyup:

Tip: Hold space to see keydown fire repeatedly, then release to see keyup fire once.

Test 9: Timing Modifiers & View Transitions

Test delay, debounce, throttle modifiers and view transitions with keyboard events.

1. Normal (No Timing Modifier) - data-on-keys:1

Press 1 to increment immediately:

2. Delay Modifier - data-on-keys:2__delay.500ms

Press 2 and the counter will increment after a 500ms delay:

3. Debounce Modifier - data-on-keys:3__debounce.500ms

Press 3 rapidly - counter increments only after you stop pressing for 500ms:

Try it: Press 3 multiple times quickly, then wait 500ms. The counter increments only once after you stop.

4. Throttle Modifier - data-on-keys:4__throttle.500ms

Press 4 rapidly - counter increments at most once every 500ms:

Try it: Hold down 4 and notice the counter increments at a controlled rate.

5. View Transition Modifier - data-on-keys:5__viewtransition

Press 5 to increment with smooth view transitions (if supported by your browser):

Note: View Transitions API support varies by browser. In supported browsers, you'll see smooth animated transitions.

💡 Timing Modifier Tips

  • Delay: Postpones execution by a fixed time. Use __delay.500ms or __delay.1s
  • Debounce: Waits for user to stop before executing. Great for search inputs. Supports __debounce.500ms__leading and __debounce.500ms__notrailing
  • Throttle: Limits execution rate. Perfect for scroll or resize handlers. Supports __throttle.500ms__trailing and __throttle.500ms__noleading
  • View Transition: Wraps state changes in the View Transitions API for smooth animations