easy-bind

Easy Bind

A lightweight, zero-dependency keyboard shortcut binding utility for web applications. Easy Bind provides a simple API to bind and manage keyboard shortcuts in your browser applications.

Features

• 🚀 Zero Dependencies - No external libraries required
• 📦 Lightweight - Minimal bundle size
• 🎯 TypeScript Support - Full TypeScript definitions included
• ⌨️ Flexible Key Combinations - Support for complex key combinations
• 🔧 Simple API - Easy to use and integrate
• 🌐 Browser Compatible - Works in all modern browsers

Installation

npm

npm install easy-bind

yarn

yarn add easy-bind

pnpm

pnpm add easy-bind

CDN

<script type="module">
  import { bindShortcut, startListening } from 'https://unpkg.com/easy-bind/dist/index.js';
</script>

Quick Start

import { bindShortcut, startListening } from 'easy-bind';

// Start listening for keyboard events
startListening();

// Bind a simple shortcut
bindShortcut('ctrl+s', (event) => {
  console.log('Save shortcut triggered!');
  event.preventDefault();
});

// Bind a complex shortcut
bindShortcut('ctrl+shift+n', (event) => {
  console.log('New file shortcut triggered!');
});

API Reference

Functions

startListening()

Starts listening for keyboard events. Must be called before any shortcuts will work.

import { startListening } from 'easy-bind';
startListening();

stopListening()

Stops listening for keyboard events and removes all event listeners.

import { stopListening } from 'easy-bind';
stopListening();

bindShortcut(combo, callback, options?)

Binds a keyboard shortcut to a callback function.

Parameters:

• combo (string): The key combination (e.g., 'ctrl+s', 'alt+shift+f')
• callback (function): Function to execute when shortcut is triggered
• options (object, optional): Configuration options

import { bindShortcut } from 'easy-bind';

bindShortcut('ctrl+s', (event) => {
  console.log('Save triggered');
}, { preventDefault: true });

unbindShortcut(combo)

Removes a keyboard shortcut binding.

import { unbindShortcut } from 'easy-bind';
unbindShortcut('ctrl+s');

Options

ShortcutOptions

interface ShortcutOptions {
  preventDefault?: boolean; // Prevent default browser behavior
}

Supported Keys

Primary Keys (Modifiers)

• ctrl - Control key
• cmd - Command key (Mac) / Windows key
• alt - Alt/Option key
• shift - Shift key

Secondary Keys

• Letters: a, b, c, ..., z
• Numbers: 0, 1, 2, ..., 9
• Function Keys: f1, f2, ..., f12
• Special Keys: enter, escape, tab, space, backspace, delete
• Arrow Keys: arrowup, arrowdown, arrowleft, arrowright
• Navigation: home, end, pageup, pagedown
• Symbols: ;, =, ,, -, ., /, `, [, \, ], '
• Numpad: numpad0-numpad9, numpadadd, numpadsubtract, etc.

Usage Examples

Basic Usage

import { bindShortcut, startListening } from 'easy-bind';

startListening();

// Save shortcut
bindShortcut('ctrl+s', (event) => {
  event.preventDefault();
  saveDocument();
});

// Copy shortcut
bindShortcut('ctrl+c', (event) => {
  copyToClipboard();
});

// Undo shortcut
bindShortcut('ctrl+z', (event) => {
  event.preventDefault();
  undo();
});

Complex Key Combinations

// Multiple modifiers
bindShortcut('ctrl+shift+s', (event) => {
  saveAs();
});

// Three modifiers
bindShortcut('ctrl+alt+shift+r', (event) => {
  restartApplication();
});

With Options

bindShortcut('ctrl+s', (event) => {
  saveDocument();
}, {
  preventDefault: true // Prevents browser's default save dialog
});

Dynamic Shortcut Management

// Bind shortcuts dynamically
function setupShortcuts() {
  bindShortcut('ctrl+n', createNewFile);
  bindShortcut('ctrl+o', openFile);
  bindShortcut('ctrl+w', closeFile);
}

// Remove shortcuts when needed
function cleanupShortcuts() {
  unbindShortcut('ctrl+n');
  unbindShortcut('ctrl+o');
  unbindShortcut('ctrl+w');
}

React Integration

import React, { useEffect } from 'react';
import { bindShortcut, unbindShortcut, startListening } from 'easy-bind';

function MyComponent() {
  useEffect(() => {
    startListening();
    
    const handleSave = (event) => {
      event.preventDefault();
      // Save logic here
    };
    
    bindShortcut('ctrl+s', handleSave);
    
    return () => {
      unbindShortcut('ctrl+s');
    };
  }, []);
  
  return <div>My Component</div>;
}

Vue Integration

<template>
  <div>My Component</div>
</template>

<script>
import { bindShortcut, unbindShortcut, startListening } from 'easy-bind';

export default {
  mounted() {
    startListening();
    bindShortcut('ctrl+s', this.handleSave);
  },
  beforeUnmount() {
    unbindShortcut('ctrl+s');
  },
  methods: {
    handleSave(event) {
      event.preventDefault();
      // Save logic here
    }
  }
}
</script>

Browser Support

Easy Bind works in all modern browsers that support:

• ES6 Modules
• KeyboardEvent API
• Map and Set

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

1.0.0

• Initial release
• Basic keyboard shortcut binding functionality
• TypeScript support
• Zero dependencies