IntelliJ Platform Plugin SDK Help

Button

Cancel and Save buttons

When to use

Use a button to invoke an immediate action:

When to use a button

When not to use

Using links instead of buttons

Use a link instead if:

  • The action takes the user to another page of the same dialog or an external source like documentation.

  • The command is a secondary action that isn't related to the primary purpose of the window, and the space is constrained.

Using toolbar buttons instead of buttons

Use a toolbar button instead if there are several buttons related to a table or list.

Using split buttons instead of buttons

Use a split button instead if:

  • There are more than two related actions, but the space is limited and/or packed.

  • The action isn't common and is dangerous, for example, can destroy user data and cannot be easily undone.

Using built-in buttons instead of buttons

Use a built-in button instead if it's related to an input field, combo box, search field.

How to use

The label displays the action the button performs.

Use title capitalization

Use title capitalization for button labels.

Use imperative verbs

Write the label as an imperative verb, for example, Save, Print, Cancel. Use title capitalization.

Be specific

The button should answer the question in the title, so the user can skip the description. Prefer specific labels over generic ones:

Correct

Incorrect

A correct button with a clear 'Save' label
An incorrect button with a generic 'OK' label

Do not use the word Now in labels because buttons always trigger an immediate action:

Correct

Incorrect

A button with 'Check for Updates' label
A button with 'Check Now' label

Be short and clear

The label should be short, not more than five words. If it’s not obvious what element the button is related to, add more words to make it clear. Prefer clear labels to short ones:

Correct

Acceptable

A button with the 'Edit Action Icon...' label
A button with 'Edit' label

Ellipsis

  • Add an ellipsis if additional actions such as adding more info or confirming the action are required.

  • Don't add an ellipsis if another window is opened, but no more input from the user is required. For example, About, Details.

Buttons with ellipsis

Button states

Default

Default button on macOS and Windows
  • The default button confirms the main purpose of a dialog. It is triggered by pressing Enter or Ctrl+Enter on Windows/Linux and Enter or Cmd+Enter on macOS.

  • The default button should always be present in a dialog. Only one button in a dialog can be the default one.

  • If an action is dangerous, for example, it can lead to data loss, provide an easy way to undo the command.

  • If it's not possible to undo the action, make a secondary button the default one:

    A dialog with secondary and primary buttons

Focused

'Cancel' button in a focused state

All buttons can get focus, even on macOS if the Full Keyboard Access option is disabled in Preferences > Keyboard > Shortcuts. A focused button behavior varies on macOS/Linux and Windows.

  • A focused button is invoked by pressing Space. Focused and default buttons are independent, so when the focus moves from one button to another, the default button does not change.

  • Make the second most popular button in the dialog focused.It’s recommended to have one default and one focused button, so that most of the actions can be triggered using the keyboard.

  • It’s recommended to have one default and one focused button, so that most of the actions can be triggered using the keyboard.

    Correct

    A dialog with buttons: 'New Window' (focused), 'Cancel', and 'This Window' (default).

    Incorrect

    A dialog with buttons: 'New Window', 'Cancel', and 'This Window' (default and focused).
  • The focused button is triggered by pressing Enter or Space. If a non-default button gets focus, the default button is invoked using Ctrl+Enter.

    On pressing the Tab key, the New Window button gets the focus and is triggered with Enter or Space. The original This Window button is triggered with Ctrl+Enter.

    If the focus moves to the control that’s not a button, the original default button is triggered by Enter.

Disabled

Disabled button

Disable a button if:

  • It’s an Apply button and no changes have been made in this dialog.

  • The control to which the button is related is disabled.

  • Not all required fields in the dialog are filled.

Other standard buttons are described below. They can be regular or default buttons.

Hover

On hovering over a button, show a tooltip with the shortcut and the action name if it can be clarified. For more details, see Context help.

Hovered buttons

If the action is clear, show the shortcut only.

If the action can be clarified, show the action name and the shortcut.

Standard buttons

Apply

Hovered buttons

Use the Apply button in dialogs with many settings that affect how data is displayed. The Apply button allows you to save and preview the effect of the selected options and continue changing the settings, for example, change a scheme in settings.

Cancel

Hovered buttons

The Cancel button reverts the app to the state before the dialog was invoked, and works as an equivalent to the Esc key on Windows and Linux, and Esc or Cmd+Period on macOS. If a confirmation button is present in a dialog, for example, OK or Save, it’s recommended to have a button that cancels the dialog, for example, Cancel, Continue Editing, and so on.

Close

Hovered buttons

Use the Close label only if nothing can be changed in the dialog and there is no confirmation button, for example, in the Help | My Productivity dialog. In all other cases, use the Cancel button.

Do not add an icon to the button. The main purpose of an icon is to quickly find a familiar action in a packed toolbar or menu. Usually, no more than 3 buttons are placed nearby, their labels can be scanned quickly, and icons are not required.

Help

Hovered buttons

The help button appears in the bottom-left corner of a dialog and shows help in a tooltip on hover, or opens a help dialog when clicking it. For more details, see Context help.

Last modified: 18 November 2024