Custom Keyboard Shortcuts for JSON Formatting

A good JSON formatting shortcut should feel instant, predictable, and hard to trigger by accident. In practice, that means wiring the shortcut to the same formatter logic as your visible button, scoping it to the editor when possible, and avoiding browser or operating-system shortcuts that users already expect to do something else.

For most web apps, the cleanest solution is a focused-editor shortcut such as Ctrl + Enter on Windows and Linux and Cmd + Enter on macOS. You can still support a more IDE-like combination if your audience expects it, but the implementation needs a few production checks that simple demo code usually skips.

Pick the Shortcut Before You Code

The biggest integration mistake is choosing a key combination first and only later discovering that the browser, the OS, an assistive-technology tool, or your embedded editor already uses it. Decide the scope and fallback behavior up front.

• Prefer a shortcut that works only while the JSON input is focused. That avoids surprising global behavior.
• Keep a visible Format JSON button so mouse, touch, and screen-reader users are not forced to memorize a hotkey.
• Treat Ctrl/Cmd + Enter as a safe default for a focused editor. It rarely conflicts with major browser commands.
• Use Ctrl/Cmd + Shift + F only if your audience already expects a format command and you have tested the full browser and extension context you support.
• Avoid well-known browser or window-management shortcuts such as Ctrl/Cmd + P, Ctrl/Cmd + L, Ctrl/Cmd + R, and Ctrl/Cmd + W.

If you let users remap the shortcut, store both the binding and a human-readable label. Do not assume a physical key such as KeyF should always be shown as "F" on every keyboard layout.

Use the Right Keyboard Event Checks

In browser UIs, keydown is the correct event for command shortcuts. It fires early enough to stop the default browser action, and it gives you the modifier state on the same event object.

• Use event.key when the shortcut should follow the user's keyboard layout.
• Use event.code only when you intentionally want the physical key position instead of the typed character.
• Check event.ctrlKey || event.metaKey so the same handler works across Windows, Linux, and macOS.
• Ignore event.repeat so holding the keys does not format the same payload over and over.
• Skip events while text is being composed with an IME by checking event.isComposing and, for older edge cases, keyCode === 229.

function isFormatShortcut(event) {
  if (event.isComposing || event.keyCode === 229) return false;
  if (event.repeat) return false;

  const primaryModifier = event.ctrlKey || event.metaKey;
  return primaryModifier && event.key === "Enter";
}

React Example: Focused Textarea Shortcut

If your JSON input is a plain textarea, attach the shortcut directly to that element. This is simpler than a document-wide listener and usually gives the best UX because the command only works when the editor has focus.

"use client";

import { useState } from "react";

function formatJson(source, indent = 2) {
  const parsed = JSON.parse(source);
  return JSON.stringify(parsed, null, indent);
}

export function JsonEditor() {
  const [value, setValue] = useState('{"service":"offline","enabled":true,"ports":[80,443]}');
  const [error, setError] = useState("");

  function runFormat() {
    try {
      setValue((current) => formatJson(current));
      setError("");
    } catch (err) {
      setError(err instanceof Error ? err.message : "Invalid JSON");
    }
  }

  function handleKeyDown(event) {
    if (event.isComposing || event.keyCode === 229) return;
    if (event.repeat) return;

    const primaryModifier = event.ctrlKey || event.metaKey;
    const wantsFormat = primaryModifier && event.key === "Enter";

    if (!wantsFormat) return;

    event.preventDefault();
    runFormat();
  }

  return (
    <div>
      <label htmlFor="json-input">JSON input</label>
      <textarea
        id="json-input"
        value={value}
        onChange={(event) => setValue(event.target.value)}
        onKeyDown={handleKeyDown}
        aria-keyshortcuts="Control+Enter Meta+Enter"
      />

      <button type="button" onClick={runFormat}>
        Format JSON
      </button>

      <p>Shortcut: Ctrl+Enter on Windows/Linux, Cmd+Enter on macOS</p>
      {error ? <p role="alert">{error}</p> : null}
    </div>
  );
}

The important detail is that the button and the keyboard handler both call the same runFormat function. That keeps validation, error handling, analytics, and undo behavior aligned instead of creating a second code path just for hotkeys.

Formatter Logic Should Be Small and Safe

The formatter itself should stay boring: parse, stringify, and surface an error without destroying the original text. Avoid replacing the editor value with an error string, because that overwrites the payload the user is trying to fix.

function formatJson(source, indent = 2) {
  const parsed = JSON.parse(source);
  return JSON.stringify(parsed, null, indent);
}

function tryFormatJson(source, indent = 2) {
  try {
    return { ok: true, value: formatJson(source, indent) };
  } catch (error) {
    return {
      ok: false,
      message: error instanceof Error ? error.message : "Invalid JSON",
    };
  }
}

If your tool also supports minifying, sorting keys, or converting indentation from two spaces to tabs, keep those as separate commands and bind each shortcut to an explicit action. A single "smart" shortcut quickly becomes hard to predict.

Only Use a Document Listener When the Shortcut Must Be Global

A document-level listener makes sense when your page has multiple JSON panes or when focus can move between a tree view and a source view. Even then, keep the command context-aware by checking the active element before you format anything.

useEffect(() => {
  function handleKeyDown(event) {
    const editor = editorRef.current;
    if (!editor) return;
    if (document.activeElement !== editor) return;
    if (!isFormatShortcut(event)) return;

    event.preventDefault();
    runFormat();
  }

  document.addEventListener("keydown", handleKeyDown);
  return () => {
    document.removeEventListener("keydown", handleKeyDown);
  };
}, [runFormat]);

If you use Monaco, CodeMirror, Ace, or another full editor, prefer that editor's command or keymap API over a raw document listener. The editor integration usually preserves selection, undo history, and internal focus handling better than a generic browser event hook.

Accessibility and Discoverability

A shortcut is an enhancement, not the only route to formatting. Users should be able to discover the command in the UI and trigger it without a keyboard.

• Show the shortcut next to the button label, in helper text, or in a command palette entry.
• Use aria-keyshortcuts on the control that exposes the action. This documents the binding for assistive technologies, but it does not implement the behavior for you.
• Do not rely on accesskey as a substitute for app-specific shortcuts. Its behavior varies too much across browsers and platforms.
• Avoid single-letter shortcuts unless they only work inside a tightly scoped editor mode.

Troubleshooting Real-World Failures

• Shortcut works on Windows but not macOS: you probably checked ctrlKey and forgot metaKey.
• Formatter runs multiple times: you are handling repeated keydown events and need an event.repeat guard.
• Users typing Japanese, Korean, or Chinese trigger the shortcut unexpectedly: ignore events while the IME is composing text.
• The browser still opens its own command: the key combination is reserved higher up the stack, so choose a different shortcut or scope the binding more narrowly.
• Caret position jumps after formatting: plain textareas replace the full value, so restore selection manually or use your editor's native format command API.

Conclusion

Custom keyboard shortcuts for JSON formatting are easy to add, but the production version is not just "listen for a key and call JSON.stringify." The reliable pattern is to choose a low-conflict shortcut, handle keydown with cross-platform modifier checks, ignore IME and repeat edge cases, and expose the same action through a visible control. That gives power users the fast path without making the editor harder to use for everyone else.