Style Keyboard Keys and Shortcuts on Web Pages

with JavaScript and CSS

Yihui Xie 2023-02-22

When writing keyboard shortcuts on web pages, we often use the <code> tag in HTML, or equivalently, a pair of backticks in Markdown. As a result, these keys are styled as code. I have been thinking of styling them as <kbd> instead, which is more appropriate semantically, and <kbd> can have different visual styles with <code>.

Yesterday I wrote a short piece of JavaScript code to convert <code>Key</code> to <kbd>Key</kbd> on HTML pages, and also a few lines of CSS code to style <kbd> as buttons. You can import the JS and CSS with:

<script src="https://cdn.jsdelivr.net/npm/@xiee/utils/js/key-buttons.min.js" defer></script>
<link href="https://cdn.jsdelivr.net/npm/@xiee/utils/css/key-buttons.min.css" rel="stylesheet">

Demos

Below are some examples:

Esc Tab Enter Space Delete Home End PrtScr PrintScreen PageUp PageDown Up Down Left Right

Ctrl Control Shift Alt Cmd Command fn

Ctrl / Cmd + C

Ctrl / Cmd + Alt + I

Shift + Enter

Cmd + Shift + 9

fn + F

Alt + Click

How does it work?

Under the hood, the JS code first looks for <code> tags that are not children of <pre>. For each tag, it uses heuristics to determine whether it looks like a key or keyboard shortcut. For example, single keys like <code>Esc</code> and <code>PageDown</code> are recognized and converted to <kbd> tags; for keyboard shortcuts, they must start with one of the Ctrl / Cmd / Shift / Alt / fn keys, followed by / or +. The keys must be separated by / or + with one space at each side of the separator, e.g., Ctrl + Key will be recognized, but F12 + C, Ctrl - V, and Ctrl+Key will not. If a keyboard shortcut is detected, each key is placed into a <kbd> tag, e.g., <code>Ctrl + Key</code> is converted to <kbd>Ctrl</kbd> + <kbd>Key</kbd>.

The arrow keys and the Enter key are special cases: you write the key names in <code>, e.g.,

<code>Enter</code>
<code>Up</code>

<!-- or in Markdown -->
`Enter`
`Up`

They will be converted to arrows (with tooltips, in case arrows are confusing):

<kbd title="Enter">↵</kbd>
<kbd title="Up Arrow">↑</kbd>

Currently, not all keys are supported. I wrote the script mainly for my own use, and only included the keys that I would often use. If you need to support other keys, please feel free to let me know in the comments below or file an issue to GitHub. However, please also note that you can always use the raw HTML tag <kbd> when a certain key is not supported, e.g., <kbd>F</kbd> will be rendered as F. Raw HTML is often supported in Markdown, so <kbd> is a workaround when a pair of backticks (e.g., `F`) doesn’t work. Below are some keys written in <kbd> tags:

a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9

The CSS style

The <kbd> tag is styled as a button with round corners and a box shadow (inspired by keyboard-css and this post). When you move your mouse over it, it will “sink” a little bit. Of course, you can add more CSS rules or override my rules to change the style.

I think the transformation from <code> to <kbd> will make keyboard shortcuts stand out, so readers can see them more clearly.