Implementation references

Scripting API and implementation references.

UI Toolkit
IMGUI

Overview

Radio buttons in light and dark theme
  • Radio buttons are used to select a single option from a list, whereas toggles are used to select multiple
  • Radio buttons are used for short lists (five or fewer choices). Use dropdowns to present longer lists
  • Selecting a radio button will deselect other options in the list
  • Only one radio button can be selected at a time among choices contained in either a radio button group or a group box

Radio button variations

Radio button

Object field UI Builder icon
UI Builder allows visual creation of UI assets in UI Toolkit, and is available as a built-in feature {2021.1 and later} or a package {2020.3 and earlier}
API in UI Toolkit

Radio button group

When to use

Radio button group is a pre-defined group of RadioButton controls. It can only contain radio buttons and no other controls and they have a static, predefined layout.

Object field UI Builder icon
UI Builder allows visual creation of UI assets in UI Toolkit, and is available as a built-in feature {2021.1 and later} or a package {2020.3 and earlier}
API in UI Toolkit

Group box

When to use

Group box is a container type container for a group of IGroupBoxOption that can contain RadioButtonand other controls such as text fields and they allow the user to manually define a custom layout.

All group options within this container will interact together to allow a single selection, using the DefaultGroupManager. If no IGroupBox is found in the hierarchy, the default container will be the panel.

Object field UI Builder icon
UI Builder allows visual creation of UI assets in UI Toolkit, and is available as a built-in feature {2021.1 and later} or a package {2020.3 and earlier}
API in UI Toolkit

Guidance

When to use: Radio button vs dropdown

Comparing a radio button with its options on the right and a dropdown button with menu on the left
Radio button group and a dropdown with its menu displayed

Use radio buttons

  • To display all available options to the user in a short list
  • When there are not a large number of choices (five or fewer choices). Lists of over 5 radio buttons take up too much real estate in the UI

Use dropdowns

  • To hide the full list of options from the user until the dropdown is clicked upon, whereupon the full list of options is displayed
  • When there are a large number of choices (over five choices)

When to use: Radio button group vs group box

Common aspects of both radio button group and group box

  • Both allow the grouping of multiple radio buttons
  • Both allow only one button per group to be selected
  • Both organize the radio buttons within in a list format
  • Both always force radio buttons to group with the closest ancestor group above them in the hierarchy

Radio button group

  • Can only contain radio buttons and no other controls
  • Have a static, predefined layout

Group box

  • Can contain radio buttons and other controls such as text fields
  • Allow the user to manually define a custom layout

Labeling and values

  • A radio button's label appears to the left of the radio icon. The label clearly identifies the radio button's purpose with precise and direct language
  • In addition to labels, radio buttons can have values to the right of the radio icon
Radio buttons can optionally have values to the right of the radio icon

Content best practices

  • Radio button labels do not end with punctuation such as colons, full stops, or question marks
  • In most cases radio buttons should not be longer than three words

Adding tooltips

Radio button labels can be paired with tooltips to display useful information about the control, ensuring the user has proper information about its function. Use tooltip property to display tooltips.

Properties
tooltip
Text to display inside an information box after the user hovers the element for a small amount of time

Formatting

Interaction states

An illustration of all four interaction states for radio buttons in light and dark themes.
Interaction states of a radio button

Radio buttons can be:

  • Selected or
  • Unselected
  • That there are no indeterminate states for radio buttons

Radio buttons can be:

  • Default
  • Hover
  • Focused
  • Disabled

Code samples