keyboard-i18n
v0.2.0
Published
Internationalization and localization utils for keyboard shortcuts
Downloads
425
Maintainers
Readme
keyboard-i18n
Internationalization and localization utils for keyboard shortcuts on web browsers.
Why
Dealing with various keyboard layouts can be tricky when setting up shortcuts because not all keyboards are the same. This leads to two main challenges:
Firstly, shortcuts might need to be based on either the character a key represents or its physical location on the keyboard.
For instance, Ctrl A
is often used to select all text because "A" stands for "all". However, in gaming, keys like W
A
S
D
are used for movement, and here, the actual characters on the keys aren't as important as their positions.
To address this, keyboard-i18n
lets you define shortcuts using either the KeyboardEvent.key
for characters or KeyboardEvent.code
for key positions. For example, ctrl+a
would be set using KeyboardEvent.key
, and ctrl+KeyA
would use KeyboardEvent.code
.
Secondly, the same shortcuts can behave differently on various keyboard layouts.
For example, shortcuts for navigating back and forward like Ctrl [
and Ctrl ]
change drastically between US, German and Latin American layouts.
keyboard-i18n
solves this by providing a localizer that maps shortcuts from the US layout to other layouts, specifically adjusting code including BracketLeft
, BracketRight
and Slash
.
Features
- Auto detect keyboard layout on supported browsers.
- Manually specify keyboard layout.
- Keyboard event handler and shortcut formatter.
- Full TypeScript support.
Install
npm install keyboard-i18n keyboard-layout-map
keyboard-layout-map
is a peer dependency of this package.
Usage
Define a Shortcut
A shortcut is a string that combines zero or more modifiers with a KeyboardEvent.key
or KeyboardEvent.code
, separated by +
.
Modifiers
"mod"
:Command
on macOS,Ctrl
on Windows"ctrl"
:Control
on macOS,Ctrl
on Windows"alt"
:Option
on macOS,Alt
on Windows"meta"
:Command
on macOS,Win
on Windows"shift"
:Shift
on all platforms
Using KeyboardEvent.key
Examples include single characters or symbols like "a"
, "9"
, or "/"
.
Using KeyboardEvent.code
Examples include "KeyA"
, "Digit9"
, or "Slash"
.
Examples
"Escape"
triggers theEscape
key."mod+KeyA"
results inCommand A
on macOS andCtrl A
on Windows."ctrl+shift+a"
results inCtrl Shift A
on all platforms."mod+BracketLeft"
results inCommand [
on macOS with a US layout, andCtrl Ö
on Windows with a German layout.
TypeScript support
keyboard-i18n
uses TypeScript to provide type safety, so that you can catch potential errors at compile time.
import type { KeyboardShortcut } from 'keyboard-i18n'
const shortcut: KeyboardShortcut = 'Mod+Shift+arrow_right'
// ^ Type '"Mod+Shift+arrow_right"' is not assignable to type 'KeyboardShortcut'.
// Did you mean '"mod+shift+ArrowRight"'? ts(2820)
Create an Event Handler
You can create an event handler for a shortcut using the createHandler
function.
import { createHandler } from 'keyboard-i18n'
const handler = createHandler('mod+a', (event: KeyboardEvent) => {
console.log('mod+a is pressed')
})
document.addEventListener('keydown', handler)
You can also handle multiple shortcuts with a single event handler.
import { createHandler } from 'keyboard-i18n'
const handler = createHandler(
['ctrl+a', 'ctrl+shift+a'],
(event: KeyboardEvent) => {
console.log('ctrl+a or ctrl+shift+a is pressed')
},
)
document.addEventListener('keydown', handler)
Create an Event Checker
If you want more control over the event handling, you can use createChecker
to check if a keyboard event matches a specific shortcut.
import { createChecker } from 'keyboard-i18n'
const checker = createChecker('Escape')
const isEscapePressed: boolean = checker(event)
Create a Shortcut Formater
You can format a shortcut based on the current platform and keyboard layout using the createFormatter
function.
import { createFormatter } from 'keyboard-i18n'
const formatter = createFormatter('mod+shift+BracketLeft')
const formatted: string[] = formatter()
// On macOS with US layout, the shortcut is formatted as ["Shift", "Command", "["]
// On macOS with German layout, the shortcut is formatted as ["Ctrl", "Shift", "Ö"]
Customize the Keyboard Layout
By default, keyboard-i18n
will use the experimental Keyboard API to get the current keyboard layout.
For those browsers that don't support the Keyboard API, you can pass a layout manually to createHandler
, createChecker
and createFormatter
.
import { createFormatter, type } from 'keyboard-i18n'
import * as layouts from 'keyboard-layout-map/layouts'
createHandler('mod+shift+BracketLeft', { layout: layouts.German })
API references
Please check the API references for full list of APIs.
License
MIT