kbd-txt

kbd-txt is a lightweight (~850 B) library that formats keyboard shortcuts to work with Mac, Windows, and Linux operating systems, making it easy to display shortcuts for users on different systems.

This library can be useful when you want to display keyboard shortcuts in a way that is specific to the user's operating system
or for converting Mac keyboard shortcuts into symbols.

Demo »
Getting Started »

Installation

Using npm/yarn:

# npm
npm install --save kbd-txt

# yarn
yarn add kbd-txt

Using unpkg CDN:

<script src="https://unpkg.com/kbd-txt/dist/kbd-txt.umd.js"></script>

Quick Usage

import { convert } from 'kbd-txt';

// Basic Usage
convert('Alt+S');
// Results
//   mac: Option+S
//   window: Alt+S

// Basic Usage 2 - $mod
convert('$mod+s');
// Results
//   mac: Command+S
//   window: Ctrl+S

// Symbol Usage
const options = { normalizeOptions: { useSymbol: true } };
convert('$mod+s', options);
// Results
//   mac: ⌘+S
//   window: Ctrl+S

Use CDN

<script src="https://unpkg.com/kbd-txt/dist/kbd-txt.umd.js">
  kbdTxt.convert('Alt+S');
  kbdTxt.convert('$mod+s');
  kbdTxt.convert('$mod+s', { normalizeOptions: { useSymbol: true } });
</script>

Supported Keys

kbd-txt understands the following modifiers:

Meta: ['command', 'cmd', '⌘'],
Alt: ['alt', 'option', '⌥'],
Control: ['control', 'ctrl', '^'],
Shift: ['shift', '⇧'],

API REFERENCE

convert

Convert shortcut text depending on the type of OS (window/linux/mac).

const options = { normalizeOptions: { useSymbol: true } };
convert('$mod+s', options);
// Results
//   mac: ⌘+S
//   window: Ctrl+S

Options

parseOptions: {
  separator?: string; // A string that identifies characters to use in separating the string.
}
normalizeOptions: {
  separator?: string; // A string used to separate one element of the array from the next in the resulting string.
  useSymbol?: boolean; // If true, Display as a symbol.
  os?: 'window' | 'mac' // If set, Display a shortcut text that fits OS.
}

parseToToken

Parse the shortcut text and convert to Token(KeyboardEvent.key) format.
It's the same form as the Keyboard Event.key.
$mod is converted to Meta/Control depending on the type of OS.

parseToToken('$mod+S');
// Results
//   mac: ['Meta', 's']
//   window: ['Control', 's']

Options

separator?: string; // A string that identifies characters to use in separating the string.

normalizeToken

Merge Token[] to text according to the option.

normalizeToken(['Alt', 's']);
// Results
//   mac: Option+S
//   window: Alt+S

Options

separator?: string; // A string used to separate one element of the array from the next in the resulting string.
useSymbol?: boolean; // If true, Display as a symbol.
os?: 'window' | 'mac' // If set, Display a shortcut text that fits OS.

How it works

Shortcut Text --(parse)--> Token(KeyboardEvent.key) --(normalize)--> Shortcuts Text for OS

parse: Parse the shortcut text and convert to Token(KeyboardEvent.key) format
normalize: Merge Token[] to text according to the option

Roadmaps

• [x] Demo Site
• [x] CDN version
• [x] Option to view OS version as fixed (View only in Mac version, view only in Window version)

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

Distributed under the MIT License. See LICENSE for more information.