Kbd

Import

import { Kbd, useModifierKey } from '@envsemble/envui';

Usage

A Kbd's children are one key. keys shows keys pressed together, such as ['Ctrl', 'P']: one key cap each, joined by +, inside an outer <kbd>.

A sequence is one Kbd per step, with words such as then between them.
Kbd only shows keys: the application handles the shortcut, and sets aria-keyshortcuts on the control it triggers where envUI doesn't.
Markdown renders <kbd> as Kbd.

ShortcutSequence.tsx

import { Kbd, Text } from '@envsemble/envui';

export default function ShortcutSequence() {
  return (
    <Text>
      Press <Kbd keys={['Ctrl', 'K']} /> then <Kbd keys={['Ctrl', 'S']} /> to see every shortcut.
    </Text>
  );
}

The platform's modifier

useModifierKey() gives the shortcut modifier of the reader's platform: its label, ⌘ or Ctrl, and its key, Meta or Control, for aria-keyshortcuts. It is Ctrl on the server and while the page hydrates, then ⌘ on Apple platforms, so server-rendered markup hydrates; don't read navigator while rendering.

const { label } = useModifierKey();
const search = <Kbd keys={[label, 'K']} />;

Customize

The parts are the combination, env-kbd-combination, an outer <kbd> around the keys, each key cap, env-kbd, and the separator between them, env-kbd-separator, the + as text.

In a tooltip, a menu, a popup list and the command palette's hints, keys are flat chips with no edge, side by side, and in a button's end they keep their caps side by side: the + between them is still read, but not shown. Only a Kbd in running text shows it.

Accessibility

You provide

The shortcut itself.
aria-keyshortcuts on the control it triggers, where envUI doesn't set it.

envUI provides

Native <kbd>: one per key, and one around a combination.
The + as text, so a combination reads as written, such as Ctrl+P.
No focus and no role: keys read as part of their sentence.

Props

A keyboard key, or a combination of keys with keys.

Prop	Type	Description
`keys`	`readonly string[]`	Keys pressed together, such as ['Ctrl', 'P']: one key cap each, joined by +, inside an outer `<kbd>`. Without it, the children are one key.

Also accepts the native props of <kbd>, such as ref, className and aria-* attributes.

useModifierKey

The platform's modifier for shortcuts: ⌘ on Apple platforms, Ctrl elsewhere. The server and the first render in the browser give Ctrl, so the markup hydrates; an Apple browser then renders ⌘.

useModifierKey(): ModifierKey

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-kbd: A key or key combination.
env-kbd-combination: A combination of keys.
env-kbd-part: One key of a combination.
env-kbd-separator: The separator between two keys.

Changelog

1.0.0: useModifierKey(), the platform's shortcut modifier, safe to render on the server. The page is kbd, after the component.
1.0.0-prerelease.6: In a button's end, such as the search button's shortcut, the keys of a combination stand side by side with the + read but not shown, as in menus and tooltips.
1.0.0-prerelease.5: In tooltips, menus, popup lists and the command palette's hints, the keys of a combination are flat chips side by side, with the + read but not shown.