Kbd

Single keys

A muted tile with a darker bottom edge, so it reads as something you press. A string child is read as a key name, so esc shows as Esc and enter as ↵. Single letters are upper-cased.

Esc↵EnterTabK/[↑Up arrow↓Down arrowSpace

Shortcuts

Pass keys for a shortcut: one cap per key, 3px apart. Write mod for the main modifier and it becomes ⌘ on a Mac or iPhone and Ctrl elsewhere. On this device it is Ctrl.

CtrlKCtrlShiftZAltNCtrl↵EnterShiftTab

Key names

Name	On a Mac	Elsewhere	Read aloud as
`mod`	⌘	Ctrl	Command on a Mac
`cmd`, `command`, `meta`	⌘	⌘	Command
`ctrl`, `control`	⌃	Ctrl	Control on a Mac
`shift`	⇧	Shift	Shift
`alt`, `opt`, `option`	⌥	Alt	Option on a Mac
`enter`, `return`	↵	↵	Enter
`esc`, `escape`	Esc	Esc	Esc
`tab`	⇥	Tab	Tab
`backspace`	⌫	Backspace	Backspace
`delete`, `del`	Del	Del	Delete
`space`	Space	Space	Space
`up`, `down`, `left`, `right`	↑ ↓ ← →	↑ ↓ ← →	Up arrow, Down arrow, and so on
Any single character	Upper-cased: k is K	The same	The character
Anything else	Shown as written	The same	As written

In a sentence

Caps sit on the text's middle line, so they drop into help text and hints without breaking the line.

Press CtrlK to search anything in your store, or [ to fold the sidebar.

A shortcuts sheet

A list of shortcuts is Kbd and Separator: the action on the left, its keys on the right.

Open searchCtrlK

Fold the sidebar[

Move through results↑Up arrow↓Down arrow

Open the highlighted result↵Enter

Clear a search, then closeEsc

Where caps appear

Tooltips, menu items and the search field take a shortcut list and draw it with Kbd, restyled for their surface. Hover or focus the buttons to see the caps on the tooltip's inverse pill.

Restyling caps on a surface

Caps read their colours and height through custom properties with fallbacks, so a surface can restyle every cap inside it without touching Kbd. Set them on the surface, not on the caps.

Property	Falls back to	Set by
`--o-kbd-bg`	The muted fill	Tooltip, menu
`--o-kbd-fg`	Secondary text	Tooltip, menu
`--o-kbd-edge`	A darker bottom edge	Tooltip
`--o-kbd-h`	20px	Tooltip (18px), menu (19px), search field (20px, 18px when small)

Platform helpers

The two functions Kbd uses to decide, exported for labels, hints and aria-keyshortcuts. They read the browser's platform when called, so call them in the browser, not while rendering on a server.

Function	Returns	On this device
`modKey()`	`'⌘'` on Apple devices, `'Ctrl'` elsewhere	`…`
`isApplePlatform()`	`true` on macOS and iOS	`…`

import { Button, isApplePlatform, modKey } from '@orbitcommerce/constellation'

<Button aria-keyshortcuts={isApplePlatform() ? 'Meta+K' : 'Control+K'}>Search</Button>

const hint = `Press ${modKey()} K to search`

In both themes

Single caps, shortcuts and caps in text, light and dark side by side.

Light

Esc↵EnterTab/↑Up arrow↓Down arrow

CtrlKCtrlShiftZAltN

Press CtrlK to search, or [ to fold the sidebar.

Dark

Esc↵EnterTab/↑Up arrow↓Down arrow

CtrlKCtrlShiftZAltN

Press CtrlK to search, or [ to fold the sidebar.

Guidelines

CtrlK

DoWrite mod, and each merchant sees their own key: ⌘ K on a Mac, Ctrl K on Windows.

⌘K

Don'tA hard-coded ⌘ is wrong on every Windows machine, and one cap for two keys reads as a single key.

Use mod for shortcuts. Write cmd only when you mean the Mac's Command key everywhere, which is rare.
Show a shortcut where the action lives (its tooltip, its menu item), not in running copy on every page.
Only show shortcuts that work. A cap for a key the page does not handle teaches people to ignore caps.
Caps explain; they never label. A control still needs its own words or an accessible name.

Accessibility

Renders kbd. A shortcut is a kbd holding one kbd per key, the HTML way to write a key combination.
Symbol caps carry a spoken name for screen readers: ⌘ is read as Command, ↵ as Enter, ↑ as Up arrow.
Kbd only shows a shortcut. Put aria-keyshortcuts on the control the keys trigger, as the search trigger and the sidebar button do.
Where caps only decorate, such as the search field's hint, they are hidden with aria-hidden and the field's own name does the work.

Props

Also accepts every native attribute of the kbd element.

Prop	Type	Default	Description
`keys`	`string[]`	None	A shortcut as a list of key names, rendered as a group of caps. Takes the friendly names in the table above.
`children`	`ReactNode`	None	A single cap. A string is read as a key name, like one entry of keys.

Function	Signature
`modKey`	`() => '⌘' \| 'Ctrl'`
`isApplePlatform`	`() => boolean`

Single keys

A muted tile with a darker bottom edge, so it reads as something you press. A string child is read as a key name, so esc shows as Esc and enter as ↵. Single letters are upper-cased.

Esc↵EnterTabK/[↑Up arrow↓Down arrowSpace

Shortcuts

Pass keys for a shortcut: one cap per key, 3px apart. Write mod for the main modifier and it becomes ⌘ on a Mac or iPhone and Ctrl elsewhere. On this device it is Ctrl.

CtrlKCtrlShiftZAltNCtrl↵EnterShiftTab

Key names

Name	On a Mac	Elsewhere	Read aloud as
`mod`	⌘	Ctrl	Command on a Mac
`cmd`, `command`, `meta`	⌘	⌘	Command
`ctrl`, `control`	⌃	Ctrl	Control on a Mac
`shift`	⇧	Shift	Shift
`alt`, `opt`, `option`	⌥	Alt	Option on a Mac
`enter`, `return`	↵	↵	Enter
`esc`, `escape`	Esc	Esc	Esc
`tab`	⇥	Tab	Tab
`backspace`	⌫	Backspace	Backspace
`delete`, `del`	Del	Del	Delete
`space`	Space	Space	Space
`up`, `down`, `left`, `right`	↑ ↓ ← →	↑ ↓ ← →	Up arrow, Down arrow, and so on
Any single character	Upper-cased: k is K	The same	The character
Anything else	Shown as written	The same	As written

In a sentence

Caps sit on the text's middle line, so they drop into help text and hints without breaking the line.

Press CtrlK to search anything in your store, or [ to fold the sidebar.

A shortcuts sheet

A list of shortcuts is Kbd and Separator: the action on the left, its keys on the right.

Open searchCtrlK

Fold the sidebar[

Move through results↑Up arrow↓Down arrow

Open the highlighted result↵Enter

Clear a search, then closeEsc

Where caps appear

Tooltips, menu items and the search field take a shortcut list and draw it with Kbd, restyled for their surface. Hover or focus the buttons to see the caps on the tooltip's inverse pill.

Restyling caps on a surface

Caps read their colours and height through custom properties with fallbacks, so a surface can restyle every cap inside it without touching Kbd. Set them on the surface, not on the caps.

Property	Falls back to	Set by
`--o-kbd-bg`	The muted fill	Tooltip, menu
`--o-kbd-fg`	Secondary text	Tooltip, menu
`--o-kbd-edge`	A darker bottom edge	Tooltip
`--o-kbd-h`	20px	Tooltip (18px), menu (19px), search field (20px, 18px when small)

Platform helpers

The two functions Kbd uses to decide, exported for labels, hints and aria-keyshortcuts. They read the browser's platform when called, so call them in the browser, not while rendering on a server.

Function	Returns	On this device
`modKey()`	`'⌘'` on Apple devices, `'Ctrl'` elsewhere	`…`
`isApplePlatform()`	`true` on macOS and iOS	`…`

import { Button, isApplePlatform, modKey } from '@orbitcommerce/constellation'

<Button aria-keyshortcuts={isApplePlatform() ? 'Meta+K' : 'Control+K'}>Search</Button>

const hint = `Press ${modKey()} K to search`

In both themes

Single caps, shortcuts and caps in text, light and dark side by side.

Light

Esc↵EnterTab/↑Up arrow↓Down arrow

CtrlKCtrlShiftZAltN

Press CtrlK to search, or [ to fold the sidebar.

Dark

Esc↵EnterTab/↑Up arrow↓Down arrow

CtrlKCtrlShiftZAltN

Press CtrlK to search, or [ to fold the sidebar.

Guidelines

CtrlK

DoWrite mod, and each merchant sees their own key: ⌘ K on a Mac, Ctrl K on Windows.

⌘K

Don'tA hard-coded ⌘ is wrong on every Windows machine, and one cap for two keys reads as a single key.

Use mod for shortcuts. Write cmd only when you mean the Mac's Command key everywhere, which is rare.
Show a shortcut where the action lives (its tooltip, its menu item), not in running copy on every page.
Only show shortcuts that work. A cap for a key the page does not handle teaches people to ignore caps.
Caps explain; they never label. A control still needs its own words or an accessible name.

Accessibility

Renders kbd. A shortcut is a kbd holding one kbd per key, the HTML way to write a key combination.
Symbol caps carry a spoken name for screen readers: ⌘ is read as Command, ↵ as Enter, ↑ as Up arrow.
Kbd only shows a shortcut. Put aria-keyshortcuts on the control the keys trigger, as the search trigger and the sidebar button do.
Where caps only decorate, such as the search field's hint, they are hidden with aria-hidden and the field's own name does the work.

Props

Also accepts every native attribute of the kbd element.

Kbd

Prop	Type	Default	Description
`keys`	`string[]`	None	A shortcut as a list of key names, rendered as a group of caps. Takes the friendly names in the table above.
`children`	`ReactNode`	None	A single cap. A string is read as a key name, like one entry of keys.

Function	Signature
`modKey`	`() => '⌘' \| 'Ctrl'`
`isApplePlatform`	`() => boolean`