<KeyboardKeyGroup><KeyboardKey>Control</KeyboardKey><KeyboardKey>B</KeyboardKey></KeyboardKeyGroup>
A Keyboard Key distinguishes a keyboard command or shortcut from other text.
Keyboard shortcuts are used for extremely frequent platform-level actions (like activating search), or in canvas or productivity tools like Studio or Flex. In general, avoid implementing keyboard shortcuts, especially with single keys, because they can override shortcuts that are already set by operating systems, browsers, assistive technologies, or user preferences.
Not every task on your application needs a shortcut, so observe your users interacting with your application to determine the most common tasks and prioritize keyboard shortcuts for these.
— Nielsen Norman Group, UI Copy: UX Guidelines for Command Names and Keyboard Shortcuts
Keyboards can also vary across operating systems and global regions, so make sure your key commands work for all users.
Reference this list of existing common keyboard shortcuts before creating a new one.
Are you considering implementing a new keyboard shortcut?
Reach out to us in a Github Discussion so we can keep keyboard shortcuts standardized across our platforms by connecting you with other teams, like Flex and Studio, who have already built them into features.
To make sure users easily understand keyboard commands, use text instead of symbols to write out modifier keys like Command, Control, and Option. Example: Use “Command” instead of “⌘”. Use the abbreviation, e.g., “Cmd”, only when space is limited.
To expose the presence of shortcuts to assistive technologies, use the aria-keyshortcuts attribute on the element that gets activated by the shortcut.
Use Keyboard Key for a single key command. Use Keyboard Key Group for key combination commands or shortcuts. When showing a key combination, do not put a “+” between Keyboard Keys or in Keyboard Key Group.
<>Press{" "}<KeyboardKeyGroup><KeyboardKey>Control</KeyboardKey><KeyboardKey>S</KeyboardKey></KeyboardKeyGroup>{" "}to save.</>
Disabled Keyboard Keys should be used when the element a shortcut activates is disabled, like a disabled Menu item or Button.
const DisabledExample = () => {const menu = useMenuState();return (<Box minHeight="230px"><Paragraph>Open the Menu for the disabled Keyboard Key in context:</Paragraph><MenuButton {...menu} variant="secondary">Edit <ChevronDownIcon decorative /></MenuButton><Menu {...menu} aria-label="Actions"><MenuItem {...menu} aria-keyshortcuts="command+x"><Box display="flex" justifyContent="space-between">Cut<KeyboardKeyGroup><KeyboardKey>Cmd</KeyboardKey><KeyboardKey>X</KeyboardKey></KeyboardKeyGroup></Box></MenuItem><MenuItem {...menu} aria-keyshortcuts="command+v"><Box display="flex" justifyContent="space-between">Paste<KeyboardKeyGroup><KeyboardKey>Cmd</KeyboardKey><KeyboardKey>V</KeyboardKey></KeyboardKeyGroup></Box></MenuItem><MenuItem disabled aria-disabled {...menu} aria-keyshortcuts="command+s"><Box display="flex" justifyContent="space-between">Save<KeyboardKeyGroup disabled><KeyboardKey>Cmd</KeyboardKey><KeyboardKey>S</KeyboardKey></KeyboardKeyGroup></Box></MenuItem></Menu></Box>);};render(<DisabledExample />)
Use pressed Keyboard Keys to give visual feedback when a key is pressed.
This is especially helpful when onboarding users to keyboard shortcuts. However, use the pressed state thoughtfully, only when it enhances the user experience. It can be distracting in cases where a user is using the keyboard for other interactions, like on a page with form fields.
The KeyboardKeyGroup accepts state returned from the useKeyCombination hook that allows pressed styling to be enabled. You must also specify keyEvent on the component to detect the correct key pressed.
A mapping of key events can be found here.
const PressedExample = () => {const keyCombinationState = useKeyCombination({keys: ["Shift", "s"],onCombinationPress: ()=> {},enablePressStyles: true,});return (<><Paragraph>Press the “Shift” or “S” key to reveal the pressed states below:</Paragraph><KeyboardKeyGroup {...keyCombinationState}><KeyboardKey keyEvent="Shift">Shift</KeyboardKey><KeyboardKey keyEvent="s">S</KeyboardKey></KeyboardKeyGroup></>)}render(<PressedExample />)
Add Keyboard Key(s) to a Tooltip to show a shortcut associated with an interactive component. Use the actionHeader and keyCombinationsActions to display a heading and the associated keyboard shortcut (or shortcuts, if displaying for multiple operating systems/keyboards).
<Stack orientation="horizontal" spacing="space60"><TooltipactionHeader="Search shortcut"keyCombinationsActions={[{ name: "Mac", eventKeyCombination: ["Command", "K"] },{ name: "Windows", eventKeyCombination: ["Control", "K"] },]}><Button aria-keyshortcuts="command+k" variant="primary"><SearchIcon title="search" /></Button></Tooltip><TooltipactionHeader="Search shortcut"keyCombinationsActions={[{ eventKeyCombination: ["Command", "K"] },]}><Button aria-keyshortcuts="command+k" variant="primary"><SearchIcon title="search" /></Button></Tooltip></Stack>
The useKeyCombination hook provides a way to configure the combination keys, callback, and additional state that can be used in KeyboardKeyGroup to enable pressed styling.
const HookExample = () => {const [combinationTriggeredText, setCombinationTriggeredText] = React.useState("");useKeyCombination({keys: ["Shift", "q"],onCombinationPress: () => {setCombinationTriggeredText("Shift + Q pressed");},enablePressStyles: true,});return (<><Paragraph>Press the <KeyboardKeyGroup><KeyboardKey>Shift</KeyboardKey><KeyboardKey>Q</KeyboardKey></KeyboardKeyGroup> key to reveal the pressed states below:</Paragraph><Paragraph>Combination triggered: {combinationTriggeredText}</Paragraph></>)}render(<HookExample />)
The useKeyCombinations is similar to useKeyCombination but allows you to configure multiple combinations and callback mappings. Use this hook when you have many combinations on the same page. This will not include the ability to configure pressed styling and is designed to provide functionality when in Menu items or Tooltips.
const HookExample = () => {const [combinationTriggeredText, setCombinationTriggeredText] = React.useState("");useKeyCombinations({combinations: [{keys: ["Control", "b"],onCombinationPress: () => {setCombinationTriggeredText("Control + B pressed");},disabled: false,},{keys: ["Control", "k"],onCombinationPress: () => {setCombinationTriggeredText("Control + K pressed");},disabled: false,},{keys: ["Control", "y"],onCombinationPress: () => {setCombinationTriggeredText("Control + Y pressed");},disabled: false,},],});return (<><Paragraph marginBottom="space0">Use the following combinations to test. You can also set the disabled state in the code block below.</Paragraph><Box marginY="space30"><Stack orientation="vertical" spacing="space20"><KeyboardKeyGroup><KeyboardKey>Control</KeyboardKey><KeyboardKey>B</KeyboardKey></KeyboardKeyGroup><KeyboardKeyGroup><KeyboardKey>Control</KeyboardKey><KeyboardKey>K</KeyboardKey></KeyboardKeyGroup><KeyboardKeyGroup><KeyboardKey>Control</KeyboardKey><KeyboardKey>Y</KeyboardKey></KeyboardKeyGroup></Stack></Box><Paragraph>Combination triggered: {combinationTriggeredText}</Paragraph></>);};render(<HookExample />)
Keyboard Key is mainly a presentational component, and can't detect operating systems. When a user needs to press different keys on different operating systems (e.g., “Command” on Mac and “Control” on Windows), make sure to either list both shortcuts or programmatically swap the shortcut displayed based on the operating system.
When writing out keys:
- Use title case. Example: “Caps Lock”, not “Caps lock”.
- For modifier keys like Control, Command, and Option, spell out the key instead of using abbreviations or symbols. Example: “Control”, not “Ctrl” or “^”. Use the abbreviation only when space is limited.
- Use “Enter” instead of “Return”.
Common platform-level shortcuts that are used across Twilio include:
| Action | Windows/Linux | Mac |
|---|---|---|
| Open search | ControlK | CommandK |
| Bold text | ControlB | CommandB |
| Italicize text | ControlI | CommandI |
| Underline text | ControlU | CommandU |
From W3C's guide to developing a keyboard interface: The following keyboard commands should be used in any context where the actions are appropriate.
Use these commands only for the actions specified. Do not use them for any other command:
| Action | Windows/Linux | Mac |
|---|---|---|
| Copy to clipboard | ControlC | CommandC |
| Paste from clipboard | ControlV | CommandV |
| Cut to clipboard | ControlX | CommandX |
| Undo last action | ControlZ | CommandZ |
| Redo action | ControlY | CommandShiftY |
These keyboard commands should be avoided since they're used by operating systems or assistive technologies:
- Any modifier keys (a keyboard key that changes the function of other keys when pressed together) + any of Tab, Enter, Space, or Escape.
- Alt + a function key.
- Caps Lock + any other combination of keys.
- Insert + any combination of other keys.
- Scroll Lock + any combination of other keys.
- ControlOption+ any combination of other keys.
Read more about other conflicts with browsers and international keyboards in W3C's guide.
Do
Implement keyboard shortcuts for extremely frequent platform-level actions.
Don't
Don't implement keyboard shortcuts, especially single keys, for actions that aren't platform-level or for a canvas productivity tool. They should be used when there's already a high level of engagement and interaction on an action, and not as a way to increase engagement.
Do
Use full words for modifier keys, such as “Command” and “Control”.
Don't
Don't use symbols like “⌘”. Only use abbreviations like “Cmd” when space is limited.
Do
For key combinations, place Keyboard Keys next to each other separated by a space.
Don't
Don't use a “+” between key combinations.
Do
Use the aria-keyshortcuts on the focusable element to announce to users with screen readers