Configuring WebShorts

Learn how to configure WebShorts using the configuration file and understand all available options.

Configuration File

WebShorts uses a configuration file to define shortcuts. Create a webshorts.config.js file in your project root:

// webshorts.config.js
const shortcutsConfig = {
  WEBSHORTS_OPTIONS: {
    debug: false,
    showDescriptions: true,
    helpDialogColumns: 2,
    dialogWidth: 800,
    dialogHeight: 600,
  },
  '*': [
    // Global shortcuts here
  ],
  '/dashboard': [
    // Page-specific shortcuts here
  ],
};

export default shortcutsConfig;

Note: You must import and pass this config file to the WebShortsProvider component, along with the currentPage prop for proper route-based shortcuts.

WEBSHORTS_OPTIONS

Configure the behavior and appearance of WebShorts with these options:

{
  debug: false,              // Enable debug toasts
  showDescriptions: true,    // Show descriptions in help dialog
  helpDialogColumns: 2,      // Number of columns in help dialog
  dialogWidth: 800,          // Help dialog width (px)
  dialogHeight: 600,         // Help dialog height (px)
}

Debug Options

debug

Enable toast notifications for shortcut registration and execution

Dialog Options

showDescriptions

Show shortcut descriptions in the help dialog

helpDialogColumns

Number of columns in the help dialog grid

dialogWidth/dialogHeight

Dimensions of the help dialog in pixels

Shortcut Configuration

Each shortcut is defined as an object with specific properties:

{
  keys: "CTRL + S",           // Key combination
  shortName: "Save",          // Display name in help dialog
  description: "Save the file", // Description (optional)
  action: () => saveFile(),   // Function to execute
  hiddenNotes: "Internal note" // Hidden notes (optional)
}

Required Properties

keys

The keyboard shortcut (e.g., "CTRL + S", "ALT + 1")

shortName

Display name shown in the help dialog

action

Function to execute when shortcut is pressed

Optional Properties

description

Detailed description shown in help dialog

hiddenNotes

Internal notes not shown to users

Complete Configuration Example

Here's a complete example showing global and page-specific shortcuts:

// webshorts.config.js
const shortcutsConfig = {
  WEBSHORTS_OPTIONS: {
    debug: true, // Show toast notifications, disabled by default
    showDescriptions: true, // Show descriptions in help dialog
    helpDialogColumns: 2, // Number of columns in help dialog
    dialogWidth: 800, // Help dialog width
    dialogHeight: 600, // Help dialog height
  },

  // Global shortcuts (work everywhere)
  '*': [
    {
      keys: 'SHIFT + ?',
      shortName: 'Show Shortcuts',
      description: 'Open the shortcuts help dialog',
      action: () => console.log('Help dialog opened'),
    },
    {
      keys: 'ALT + 1',
      shortName: 'Home Page',
      description: 'Navigate to the home page',
      action: () => (window.location.href = '/'),
    },
  ],

  // Page-specific shortcuts (These can alternatively be pulled from the Shortcut Listeners)
  '/dashboard': [
    {
      keys: 'CTRL + S',
      shortName: 'Save Dashboard',
      description: 'Save current dashboard state',
      action: () => saveDashboard(),
    },
  ],

  '/editor': [
    {
      keys: 'CTRL + B',
      shortName: 'Bold Text',
      description: 'Make selected text bold',
      action: () => formatText('bold'),
    },
  ],
};

export default shortcutsConfig;

Supported Key Combinations

WebShorts supports a wide range of key combinations for maximum flexibility:

Basic Combinations

• CTRL + S - Save
• CTRL + Z - Undo
• ALT + 1 - Navigate
• SHIFT + ? - Help

Advanced Combinations

• CTRL + SHIFT + A - Multi-modifier
• META + S - Platform-aware (Cmd/Ctrl)
• CTRL + ALT + DEL - Complex combinations
• F1 - Function keys

Best Practices

✅ Do

• Use descriptive shortNames
• Provide helpful descriptions
• Group related shortcuts by page
• Use consistent naming conventions
• Test shortcuts in different contexts

❌ Don't

• Override browser shortcuts (Ctrl+C, Ctrl+V)
• Use conflicting key combinations
• Create shortcuts without descriptions
• Use shortcuts that interfere with typing
• Forget to test in different browsers