Keyboard Shortcut

Attaches a keyboard shortcut to an element, or the whole page, without any visible UI of its own.

Shortcut target

Usage

forge-keyboard-shortcut listens for a key combination and fires forge-keyboard-shortcut-activate when it’s pressed, through key, target, global, and disabled — it renders nothing itself, so it doesn’t affect layout on its own. Placed as a sibling right after an element, the shortcut activates while focus is within that element by default; set target to a CSS selector to activate it for a different element instead, or global to activate it anywhere on the page.

Rules

Describe the shortcut's function and key combination somewhere visible on the page, not just in code.

Set aria-keyshortcuts on the element a global or targeted shortcut activates.

Don't

Don't override a browser, operating system, or assistive technology shortcut.

Don't use the accesskey attribute alongside it.

Don't duplicate behavior the browser already provides — a form submits on Enter without any extra wiring.

Basic usage

Placed as a sibling after an element, the shortcut activates while focus is within that element.

A keyboard shortcut scoped to focus within a specific element.

<forge-button variant="raised">
  Shortcut target
</forge-button>
<forge-keyboard-shortcut target key="a" style="display: none;">
</forge-keyboard-shortcut>

Targeting a different element

Set target to a CSS selector to activate the shortcut for an element it isn’t a sibling of.

<forge-button id="shortcut-target">
  <button type="button">Button</button>
</forge-button>
<forge-keyboard-shortcut key="shift+a" target="#shortcut-target"></forge-keyboard-shortcut>

Targeting the whole page

Set global to activate the shortcut anywhere on the page, regardless of focus.

<forge-keyboard-shortcut key="shift+a" global></forge-keyboard-shortcut>

A utility component that listens for keyboard shortcut combinations and triggers callbacks or events when the specified key bindings are activated.

import "@tylertech/forge/keyboard-shortcut";

Properties

Property	Attribute	Type	Default	Description
`key`	`key`	`string \| null \| undefined`	—	Gets/sets the key binding.
`keyBinding`	—	`typeof this.key`	—	Alias for `key`.
`anchor`	`anchor`	`string \| null`	`null`	Gets/sets the id of the anchor element in the shortcut's root node.
`scope`	`scope`	`string \| null`	`null`	Gets/sets the name of an ancestor scope marker.
`target`	`target`	`string`	`''`	Gets/sets the target element selector.
`global`	`global`	`boolean`	`false`	Gets/sets the global listener state.
`allowWhileTyping`	`allow-while-typing`	`boolean`	`false`	Gets/sets whether the callback will be called while in a text entry field.
`allowRepeat`	`allow-repeat`	`boolean`	`false`	Gets/sets whether held-key repeat events activate the shortcut.
`fallthrough`	`fallthrough`	`boolean`	`false`	Gets/sets whether the shortcut allows outer scopes to also handle the key.
`preventDefault`	`prevent-default`	`boolean`	`true`	Gets/sets whether to prevent default on keyboard events.
`capture`	`capture`	`boolean`	`false`	Gets/sets whether to use capturing on keyboard events.
`useCode`	`use-code`	`boolean`	`false`	Gets/sets whether to match codes instead of keys on keyboard events.
`disabled`	`disabled`	`boolean`	`false`	Gets/sets whether the callback will be called.
`anchorAccessibility`	`anchor-accessibility`	`KeyboardShortcutAnchorAccessibility`	`'auto'`	Gets/sets whether aria-keyshortcuts is automatically set on the anchor.
`action`	—	`KeyboardShortcutAction`	`'default'`	Gets/sets the action performed on the anchor element when the shortcut is activated.
`activateCallback`	—	`KeyboardShortcutActivateCallback \| null \| undefined`	—	Gets/sets the activation callback.
`anchorElement`	—	`HTMLElement \| null`	`null`	Gets/sets the anchor element directly.
`scopeElement`	—	`HTMLElement \| null`	`null`	Gets/sets the scope element directly.

Events

Name	Type	Description
`forge-keyboard-shortcut-activate`	`CustomEvent<KeyboardEvent>`	Event fired when the keyboard shortcut is activated.

Don’t fight the platform

Never override a shortcut the browser, operating system, or assistive technology already owns. Avoid the accesskey attribute for the same reason — it conflicts unpredictably across browsers and screen readers. And don’t duplicate behavior the platform already provides — a form already submits on Enter when it has a submit button, with no shortcut needed.

Announce what you’re activating

Set aria-keyshortcuts on whichever element a global or targeted shortcut ultimately activates, so assistive technology can announce it. Also describe the shortcut’s function and key combination somewhere visible on the page — a shortcut a user can’t discover isn’t accessible just because it technically works.