Keyboard shortcuts

What problem does this solve?

Keyboard shortcuts are accelerators that expose program functions to users through keypresses rather than mouse clicks. This can greatly speed up task completion time as the user's hands can stay on the keyboard. Good candidates for keyboard shortcuts are commands that are part of frequent or repetitive user tasks.

Constraints

There are potential conflicts with operating system keyboard shortcuts, as well as limitations to the number of easily-memorable keyboard shortcuts and key combinations. Variation in international alphabets and keyboard configurations is also worth noting. We recommend restraint when devising keyboard shortcuts – restrict them as much as possible only to the most common actions.

Keyboard shortcut strategies

Mnemonics

Keyboard shortcuts are more easily recalled if there is a mnemonic association with the letter or key combination, but the scarcity of keys means that you will quite quickly run out of keys that start with a letter that makes sense. Common strategies to deal with this are using a middle or end letter of a function rather than the initial letter.

Example: in Confluence, lowercase L is used for Labels, so for the Link Page shortcut, lowercase K was used. In several apps lowercase C is used for Create, so M was chosen for the Comment.

Contexts

Keys can be re-used in different contexts (pages or screens) for different purposes, but try to use closely-related functions for the keypress, as many different re-uses of the key will slow adoption and successful usage.

Example: Across Atlassian products, U is used to navigate to different locations, but the common theme is always navigating "upwards" to a larger context. In Bitbucket Server, T is used in different ways on different pages (contexts) but usually always to "toggle" between hiding and showing things (merges, file trees, or highlights on pull requests)

Modifier keys

The number of available keyboard shortcuts can be extended by using one or multiple keyboard modifiers such as Shift, Alt, Control, Command and Option. Not all of these modifiers are available in every operating system and hardware combination. Additionally, operating systems and browsers can reserve certain keys, or render some keypresses inoperable, necessitating different keyboard modifier combinations across OS and browser.

In keyboard shortcut documentation, modifier keys (simultaneous keypresses) are notated with a plus sign.

Example: The following table shows the modifier keys used in JIRA for the same command across combinations of browser and OS.

Web browser
Mac OS X
Windows
UNIX/Linux
Firefox Ctrl Alt + Shift Alt + Shift
Internet Explorer Alt
Safari Ctrl + Alt Ctrl
Chrome Ctrl + Alt Alt + Shift Alt + Shift

Key sequence

The shortage of letter keys can be mitigated by using key sequences. These are particularly useful when related key commands can be grouped by a single prefix keypress. As always, some constraint is advised to keep key sequences from becoming too numerous to effectively memorize.

In keyboard shortcut documentation, key sequences are notated by the word "then" between keypresses (see Examples table below)

Example: In many Atlassian products "GD" stands for "Go to Dashboard". Each product has a series of "G " sequences that navigate to different destinations in the product.

Examples

Category Keyboard shortcuts Meaning Notes
Navigation

G then D

G then S

Go to dashboard

Go to space browser

G is used globally as a navigation prefix for a set of related keyboard sequences. Atlassian is consolidating on this approach for in-product navigation.
Launch dialog

L

A

Open labels

Assign

These keyboard commands open modal dialogs to capture user actions for the currently selected item
Page actions

J

K

N

P

/

Move down a list

Move up a list

Next item

Previous item

Jump to search box

These keyboard commands move the current selection around on the page.
Commands X then F
Form actions

Alt + Shift + S

Ctrl + S

Submits a form On many application pages, there are multiple forms contributing to application functionality. This keeps the "enter" key from being used unambiguously to submit a form. We use Alt + Shift + S and the equivalent modifier keys (see above) to submit the primary form on the page.
Global actions Esc Close a modal dialog/menu The "escape" key is often used to back out of any modal situation and return to the previous state.

Keyboard shortcut references

Many users are ignorant of keyboard shortcuts because most GUIs are visually oriented towards mouse manipulation. Since the keyboard shortcuts themselves are not easily intuited, we suggest a variety of ways to let the user know that they are available.

Tooltips – on menu items, and on tooltips for buttons and icons, its helpful to also list the keyboard shortcut for that action.

Keyboard shortcut dialog – we recommend a standard approach to displaying a legend of keyboard shortcuts in the applications. We use an AUI dialog and a standard format for showing keyboard shortcuts and contexts.

Keyboard Shortcut Dialog

Atlassian applications are moving to using the question mark key as a universal affordance for opening the Keyboard shortcut dialog for that application. Putting a 'Keyboard shortcuts' link in your page footer is even better, as it doesn't rely on users knowing a keyboard shortcut to discover keyboard shortcuts.

Documentation – Keyboard shortcuts should be fully documented in your application user documentation.

When and how to use this pattern

  • When expanding shortcuts to your application, defer to existing shortcuts within an application instead of changing shortcuts. Avoid repurposing shortcuts that users have adapted into their workflow
  • Become very familiar with the existing Atlassian shortcut usage and play within those usage patterns, such as G for Go, J and K to traverse lists, etc
  • Use upper case legends in keyboard shortcut dialogs to help distinguish between the numeral one and the lowercase L
  • Add keyboard shortcut information to menu items and button and icon tooltips if they are available
  • Don't go overboard with keyboard shortcuts, keep them understandable, learnable, and manageable
  • Don't use case-sensitive shortcuts