# Split Button UI guidelines on using split buttons. **Implementation:** [`JBOptionButton`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBOptionButton.kt) A split button is a combination of a regular [button](button.topic) and a drop-down button. ![](split_button.png){width=706} ## Anatomy A split button consists of the main action on the left and a drop-down button that shows a dropdown with less common actions on the right: ![Split button action anatomy](split_button_anatomy.png){width=706} ## When to use ### More than two related actions When there are more than two actions related to the main action, and there is not enough space for separate buttons, put these actions into the dropdown menu: ![Related actions in a split button](split_button_related_actions.png){width=706} ### The second action is dangerous and uncommon Dangerous actions can destroy users’ data and cannot be easily undone. To avoid accidental clicks on a dangerous action, you can hide it in the dropdown menu if this action is uncommon, for example Force Push: ![Dangerous action in a split button](split_button_dangerous_action.png){width=706} An uncommon dangerous action can be the only action in the menu. Uncommon actions are the actions called in rare cases for specific purposes. For example, the Force Push action, unlike the Commit and Push... action, is available under certain circumstances and covers rare user scenarios. Thus, it can be considered as uncommon and hidden in the dropdown menu. ## When not to use ### Unrelated actions If unrelated actions are hidden under the dropdown menu, they are hard to find: Incorrect

Correct

### Only one related action Putting the single action in the dropdown menu doesn't save a lot of space: Incorrect

Correct

Exception: If the action is dangerous and uncommon, you can put it in the menu. ## How to use ### Main action Refer to the [regular button rules](button.topic#how-to-use). ### Dropdown button #### Click

Show the dropdown menu with secondary actions.

Hide the menu when clicking outside the menu or on the second dropdown button click.

#### Hover Show a tooltip: Tooltip on hover

### Dropdown menu Place related actions into the dropdown menu. Do not duplicate the main action in the dropdown menu, otherwise it is confusing how to trigger the main action — with the button or from the menu. Incorrect ![Duplicated actions in dropdown menu](split_button_duplicated_action.png){width=706} Correct ![Unique actions in dropdown menu](split_button_related_actions.png){width=706} If there is a dangerous action among other actions in the dropdown, add the line separators above and below it to lessen the chance of calling this action by mistake: ![Dangerous action in the dropdown menu](split_button_dangerous_action_separator.png){width=706} [//]: # (### Reduce split button to simple action buttons) [//]: # () [//]: # (The Split button can be reduced to simple action buttons which are laid out automatically next to each other. This is controlled by the following option in settings:) [//]: # (Settings | Appearance & Behavior | Appearance | Merge buttons in dialogs) [//]: # () [//]: # (

For example, the Commit button reduced to its components (the option is disabled) looks like the following:

) [//]: # () [//]: # (![](reduced.png){width=500}) ## Keyboard navigation & shortcuts * Trigger the main action when the [default](button.topic#default) button shortcut is pressed if the split button is the default one. * Open the dropdown menu with the first menu item selected on Alt+Shift+Enter. * Do not show the dropdown menu when the button gains focus. ### Focus on the button [//]: # ( ) [//]: # ( ) [//]: # ( ) [//]: # ( )

) [//]: # ( Enter ) [//]: # ( Ctrl+Enter ) [//]: # (	Invoke the default button action.
Space	Invoke the main action.
Arrow Down	Show the dropdown menu with secondary actions and move focus to the first item in the menu.
Tab Shift + Tab	Move focus to the control next to the split button and hide the dropdown menu.

### Focus on the dropdown menu

Enter

Space

Invoke the selected action.

Arrow Down

Arrow Up

Navigate through the elements.
Pressing Arrow Down on the top element moves the focus to the bottom element.
Pressing Arrow Up on the bottom element moves the focus to the top element.

Esc

Close the dropdown menu and move the focus to the split button.

[//]: # (## Sizes and placement) [//]: # () [//]: # (Follow the rules for the [simple button](button.topic).) [//]: # () [//]: # (### Button) [//]: # () [//]: # (The width of the split button equals to the width of the main button (follow the rules of the [simple button](button.topic)) plus the width of the dropdown button.) [//]: # () [//]: # (| Windows | Mac | Darcula |) [//]: # (|--------------------------------------|--------------------------------|------------------------------------|) [//]: # (| ![](win-button-size.png){width="92"} | ![](mac-sizes.png){width="90"} | ![](darcula-sizes.png){width="94"} |) [//]: # () [//]: # (A different width for the split button makes it easier to understand that this button is different from other buttons in the dialog.) [//]: # () [//]: # (### Menu) [//]: # () [//]: # (Follow the rules for menus with regard to sizes, colors, fonts and spacing.) [//]: # () [//]: # (Menu item height and spacing between the menu and the button:) [//]: # () [//]: # (![](button-and-dropdown-sizes.png){width=232}) [//]: # () [//]: # (## Style) [//]: # () [//]: # (Increase line height in the dropdown menuto lessen the chance of choosing the wrong menu item by mistake.) [//]: # () [//]: # (Leave 2px around the separator inactive to lessen the chance of choosing the wrong menu item by mistake:) [//]: # () [//]: # (![](selected.png){width=218}) [//]: # () [//]: # (Align the dropdown with the button left border:) [//]: # () [//]: # (![](split_button_alignment.png){width=219})