Kbd shows one key of the keyboard, such as "Esc", "+" or "↑", inside help text, so a sentence like "Keys: + and − zoom, arrows pan, Esc closes panels." shows each key as a key.
When to use
Use Kbd for one key of the keyboard in help text, such as "Esc" in "Esc closes panels", so the reader sees it is a key.
Nothing else in Perron does this.
Kongens Nytorv
Metro M1, M2 and M3.
Props
| Name | Type | Default | Description |
|---|---|---|---|
children* | ReactNode | — | One key, as the keyboard prints it or the platform names it: "Esc", "Enter", "+", "−", "↑". Required: a key with no name says nothing. A combination is one Kbd per key (CR-5). |
children (required)ReactNode, default —- One key, as the keyboard prints it or the platform names it: "Esc", "Enter", "+", "−", "↑". Required: a key with no name says nothing. A combination is one Kbd per key (CR-5).
Use it
import { Kbd } from '@mylder/perron'Ask your agent
search_docs({ query: "Kbd" })Keyboard and ARIA
No keys: Kbd is not focusable and does nothing when pressed (CR-2). It names a key; the key's action is the screen's, and the control the key works is the caller's to mark with aria-keyshortcuts, as Accessibility gives the keys.
| Key | Does | From |
|---|---|---|
| None | Kbd is not focusable or operable | Perron |
| Element | Role | Accessible name from | States announced |
|---|---|---|---|
root | none: a <kbd>, which has no ARIA role and is read as its text | Its text, the caller's children | none |
A screen reader reads the key's text in the sentence around it, as written: "Esc", "plus", "minus", "up arrow" for "Esc", "+", "−", "↑". Kbd adds no aria-label and no owned word for the key: the caller's text is already the key's name, and a <kbd> without a role can't carry aria-label reliably.
What axe won't catch, from the contract, each with how this component meets it:
- Everything the eye is told, the ear is told, for every shape each prop accepts: the box only says "this is a key"; the key itself is the text inside it, which a screen reader reads in place, and
childrenis required. - Every landmark and named region has an accessible name: none here; the key is inline text.
- Every default label can be overridden: no owned strings, so no
*Labelprops. - Every shape the type accepts renders, in every variant:
childrenrenders as a string, an element and a list alike, on one line inside the box;Kbd.test.tsxchecks all three, each inside the one<kbd>withpn-Kbdfirst. - A hidden copy kept for animation is
aria-hidden, and a collapsed region isinert: none here; the key has no motion. - Native semantics first: the native
<kbd>, with no ARIA. - Focus moves in reading order and returns on close: never focused; it has no tab stop.
- Every target is at least
size.target-minsquare: no target; Kbd is never pressed. A pressable key hint is the caller's button with the Kbd inside it, which meets the minimum itself. - Loops stop when the system asks for less motion: none here; the key has no motion.
Owned strings
No owned strings: the key's name is the caller's children, and Kbd announces nothing else.
Do and don't
For a caller using the component, with the reason. Each row is a rule: a must row's Don't is never right, a should row's needs a reason, and Checked by says what catches the Don't in a caller's code.
| Rule | Level | Do | Don't | Checked by |
|---|---|---|---|---|
| DD-1 | should | Name keys in help text, one Kbd per key, as content design writes it: "Keys: + and − zoom, arrows pan, Esc closes panels." | Write a key as a quoted word, "press 'Esc'", where a Kbd says it is a key | review |
| DD-2 | must | Write the key as the keyboard prints it or the platform names it, in its own case: "Esc", "Enter", "−", "↑" | Write it in capitals ("ESC"), as an emoji, or as an icon; the key's text is what a screen reader hears | review |
| DD-3 | should | Name the left and right arrows in words, or all four as "arrows", as content design writes it: "arrows pan" | Put "←" or "→" in a Kbd; the font Perron ships has no glyph for them, so they fall back to the system's monospace and look unlike the other keys | review |
| DD-4 | should | Give a combination one Kbd per key, with "+" between them in the text: <Kbd>Ctrl</Kbd> + <Kbd>K</Kbd> | Put a whole combination or a sentence in one Kbd; the box is sized for one key | review |
| DD-5 | must | Mark the control a key works with aria-keyshortcuts, and keep the action reachable by pressing the control too | Make the Kbd the only way to learn or do the action, or add onClick or tabIndex to it | review |
| DD-6 | should | Show key hints where people have a keyboard, such as the help on a desktop screen | Show keys on a phone's screen, which has no keyboard to press them on | review |