IntelliJ Platform UI Guidelines

Toggle button

The toggle button is used to switch between On and Off states.

When to use

Use the toggle button to switch the state of an item in search results:

Do not use the toggle button for items in dialogs and menus. Instead, use a checkbox in dialogs and a checkmark in menus:

How to use

Label

The toggle button in search results should duplicate the option from the settings or the menu. Label and capitalization should be the same as on the option label: Setting in the preferences The same setting in search results Do not make a setting available only from search results. See discoverability for details.

If the setting is in a tree or menu, use the toggle button label to specify where the setting is located: Setting in a tree The same setting in search results; separate tree levels with a colon Setting in the main menu The same setting in search results; separate the first menu level with a vertical bar, and separate others with a colon Refer to checkbox and menu for writing checkbox labels and menu labels.

Do not add the word “On” or “Off” to the item name, since the state description is already in the toggle button.

Control

Toggle button is implemented with the com.intellij.ui.components.OnOffButton class. But generally, you shouldn’t use the class directly. The IDE automatically places the buttons in the search feed if you follow one of the patterns described below:

  1. If this is a system or editor or another kind of settings, just register corresponding BooleanOptionDescription for the option. The options can be bound (but not limited) to:

    • A SearchHitProvider instance which is registered in PlatformExtensions.xml with the tag. For example, see the com.intellij.ide.ui.SystemOptionsTopHitProvider class that represents matching of “Reopen last project on startup” checkbox to BooleanOptionDescription.

    • com.intellij.ide.ui.EditorOptionDescription bound to com.intellij.openapi.editor.ex.EditorSettingsExternalizable which under the hood works with the editor.xml.

  2. Implement your own action that’s inherited from com.intellij.openapi.actionSystem.ToggleAction and registered in the IDE’s PlatformActions.xml or plugin.xml.

The toggle button changes state when it is clicked with the mouse or when Enter is pressed on the item line.