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 explicitaria-labelon the parent button (for example,aria-label="Search, shortcut Command K") or hide decorative key badges witharia-hidden="true"if the shortcut is already explained in context. - Avoid direct interactivity: Do not attach
onClicklisteners 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.