📦 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

            

                GitHub
                npm
                Datastar Docs
            

        


        
        

            
📖 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
    •