KBD

v1.0.0 | View in Storybook

​

When to use

• To accelerate common tasks for power users.
• When an action is frequently repeated and benefits from faster execution.
• To complement menu items and Buttons by offering an alternative input method.

​

When to use something else

• For critical actions without clear undo (e.g., delete all), unless safeguarded by confirmation—prefer explicit Button or Dialog flows.
• As the only means of accessing an action; always provide a visible control (Button, Menu item).
• Where discoverability matters and users won’t learn shortcuts.
• When key chords would conflict with the browser, OS, or assistive tech.

​

Dos and don’ts

• Do use letters for meaning. Letters make shortcuts more memorable, as they can convey meaning (e.g., C for Comments).
• Do always use modifiers (e.g., ⌘, Ctrl) with letters to prevent accidental triggers and to avoid overriding focus states.
• Do show shortcuts next to the action they trigger, e.g., inside Menus, Dialogs, or Tooltips.
• Do be selective: Not every action needs a shortcut. Consider how often users perform the action and where its trigger point is in the UI.
• Do respect browser and OS default shortcuts to avoid confusion and conflicts.
• Do use the same shortcut for the same action across product.
• Don’t use two-letter shortcuts: Two-letter shortcuts can conflict with single-letter ones.
• Don’t assign multiple shortcuts to a single action.

​

Behavior

• Shortcuts should trigger immediate actions with minimal delay.
• Consider removing Shortcut keys in mobile and tablet settings as these cannot be triggered and only take up valuable space for content.

​

Often used with

Menu item labels, Button or Tooltip hints, command palette (Command) results, in-app docs.

​

Accessibility

• Clarify parent component names: When placing <Kbd> inside a Button or Input (for example, a search trigger with ⌘K), text concatenation can sound confusing. Either set an explicit aria-label on the parent button (for example, aria-label="Search, shortcut Command K") or hide decorative key badges with aria-hidden="true" if the shortcut is already explained in context.
• Avoid direct interactivity: Do not attach onClick listeners or interactive roles directly to a <Kbd> element. If a shortcut indicator needs to be clicked, wrap the <Kbd> inside a native <button>.
• Separate multi-key sequences: When using <KbdGroup> for combinations (for example, Ctrl + Shift + P), ensure visual separator symbols (like +) are included or articulated in accessible labels so screen readers don’t read the combination as a single run-on string.
• Enforce 4.5:1 contrast ratios: Aura’s default <Kbd> uses scaled-down typography (text-xs) and muted background fills. Ensure custom color overrides maintain a 4.5:1 contrast ratio for key text and a 3:1 ratio for key borders against the page background.
• Provide dynamic OS keys: Render platform-appropriate keys (⌘ for macOS vs Ctrl for Windows/Linux) dynamically to avoid delivering inaccurate keyboard guidance to screen reader users and keyboard navigators.

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

Common shortcuts

Display familiar modifier-plus-key combinations next to menu items or buttons so power users can discover shortcuts for frequent actions.

​

Single keys

Show a single key when the shortcut is unambiguous in context—for example, arrow keys in a list or Enter to confirm an inline edit.

​

Disabled

Use a disabled KBD display when a shortcut is unavailable in the current state, paired with a tooltip that explains why.

​

With icons

Combine key labels with icons when the shortcut triggers an action that already has a recognizable visual metaphor in your UI.

​

Multi key combinations

Show multi-key chords for actions that require modifiers, reducing accidental triggers and matching platform conventions like Ctrl+C or ⌘K.

​

Key groups

Group related keys visually when a shortcut spans multiple presses in sequence, such as G then D for “go to dashboard.”

​

In context

Place KBD elements inline with the action they trigger—in menus, toolbars, or command palettes—so users connect the keys to the outcome.

​

Shortcut list

Use a shortcut list in help panels or onboarding to teach power-user workflows without cluttering the primary interface.

​

Function keys

Display function keys for actions mapped to F1–F12, common in desktop-style applications or specialized operator interfaces.