Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
ce69252
Update radio button images with new assets and reorganize
ViktoriaMiroshnichenko Jan 1, 2025
ae32758
Revise and expand radio button usage guidelines.
ViktoriaMiroshnichenko Jan 1, 2025
32b6168
Refine wording for binary yes/no options in radio buttons.
ViktoriaMiroshnichenko Jan 1, 2025
92d74be
Editing
ViktoriaMiroshnichenko Jan 2, 2025
6518b9a
Update descriptions and examples for radio button usage
ViktoriaMiroshnichenko Jan 2, 2025
32931a1
Update alt text for radio button usage examples
ViktoriaMiroshnichenko Jan 2, 2025
1234bca
Update radio button guidelines and adjust project settings
ViktoriaMiroshnichenko Apr 10, 2025
180b351
Update radio button guidelines and improve formatting
ViktoriaMiroshnichenko Apr 15, 2025
c2bdd30
Refactor radio button documentation and update images
ViktoriaMiroshnichenko Apr 15, 2025
b2a4b41
Improve formatting examples in radio_button.md
ViktoriaMiroshnichenko Apr 15, 2025
2bcb0e2
Update radiobutton usage images for light and dark themes
ViktoriaMiroshnichenko Apr 15, 2025
28330c7
Refine radio button documentation and improve formatting
ViktoriaMiroshnichenko Jul 18, 2025
7942cfd
Update table formatting and fix layout link in radio button documenta…
ViktoriaMiroshnichenko Jul 18, 2025
df59bb9
Fix broken anchor link in radio button documentation
ViktoriaMiroshnichenko Jul 18, 2025
143ac62
Update and refine radio button usage images for light and dark themes
ViktoriaMiroshnichenko Sep 11, 2025
c04ac24
Update "How to use" images for light and dark themes in radio button UI
ViktoriaMiroshnichenko Sep 11, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .idea/gradle.xml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 6 additions & 0 deletions .idea/kotlinc.xml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Binary file added images/ui/radiobutton/01_Radio Button.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/01_Radio Button_dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/02_When_to_use_correct.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/04_When_to_use_correct.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/06_How_to_use.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/06_How_to_use_dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/07_How_to_use.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/07_How_to_use_dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/08_How_to_use_correct.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/08_How_to_use_incorrect.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/09_How_to_use.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/09_How_to_use_dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/10_How_to_use.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/ui/radiobutton/10_How_to_use_dark.png
Binary file removed images/ui/radiobutton/answeryes_correct.png
Diff not rendered.
Binary file removed images/ui/radiobutton/answeryes_incorrect.png
Diff not rendered.
Binary file removed images/ui/radiobutton/dropdown.png
Diff not rendered.
Binary file removed images/ui/radiobutton/dropdown_correct.png
Diff not rendered.
Binary file removed images/ui/radiobutton/dropdown_incorrect.png
Diff not rendered.
Binary file removed images/ui/radiobutton/grouplabel.png
Diff not rendered.
Binary file added images/ui/radiobutton/old/answeryes_correct.png
Binary file added images/ui/radiobutton/old/answeryes_incorrect.png
Binary file added images/ui/radiobutton/old/dropdown.png
Binary file added images/ui/radiobutton/old/dropdown_correct.png
Binary file added images/ui/radiobutton/old/dropdown_incorrect.png
Binary file added images/ui/radiobutton/old/grouplabel.png
Binary file added images/ui/radiobutton/old/radio-darcula.png
Binary file added images/ui/radiobutton/old/radio-intellij.png
Binary file added images/ui/radiobutton/old/radio-macos.png
Binary file added images/ui/radiobutton/old/radio-windows.png
Binary file added images/ui/radiobutton/old/radio_example.png
Binary file added images/ui/radiobutton/old/radiobutton_label.png
Binary file added images/ui/radiobutton/old/twoline_label.png
Binary file added images/ui/radiobutton/old/tworadio_checkbox.png
Binary file removed images/ui/radiobutton/radio-darcula.png
Diff not rendered.
Binary file removed images/ui/radiobutton/radio-intellij.png
Diff not rendered.
Binary file removed images/ui/radiobutton/radio-macos.png
Diff not rendered.
Binary file removed images/ui/radiobutton/radio-windows.png
Diff not rendered.
Binary file removed images/ui/radiobutton/radio_example.png
Diff not rendered.
Binary file removed images/ui/radiobutton/radiobutton_label.png
Diff not rendered.
Binary file removed images/ui/radiobutton/twoline_label.png
Diff not rendered.
Binary file removed images/ui/radiobutton/tworadio_checkbox.png
Diff not rendered.
145 changes: 78 additions & 67 deletions topics/ui/controls/radio_button.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,107 +10,118 @@

</tldr>

![](radio_example.png){width=213}
![](01_Radio Button.png){width=706}

## When to use

Use a radio button group to choose one option from 2 to 4 mutually exclusive options.

Do **not** use radio buttons if:
## When not to use

* Several options in a group can be selected. Use a group of [checkboxes](checkbox.md) instead.
* There are only 2 opposite yes/no options. Use a checkbox instead.
### Several options can be selected
Use a group of [checkboxes](checkbox.md) when several options can be selected.

![](tworadio_checkbox.png){width=427}
### Yes or No Options
For only two opposing yes/no options, use a checkbox.

* There are 5 and more options that can be charted on an axis, e.g., time delay. Use a slider instead.
<table style="none" border="false">
<tr>
<td width="378px">
<format color="Green" style="bold">Correct</format><img src="02_When_to_use_correct.png" alt="A correct example of using a checkbox instead of radiobuttons"/>
</td>
<td width="378px">
<format color="Red" style="bold">Incorrect</format><img src="02_When_to_use_incorrect.png" alt="An incorrect example of using radiobuttons instead of a checkbox"/>
</td>
</tr>
</table>

* There are 5 and more options. Use a [drop-down list](drop_down.md):
### 2-5 options with short labels
If the options have short labels, use a segmented button.

![](03_When_to_use_Segmented_button.png){width=706}

<table>
<tr>
<td width="40%"><format color="Red" style="bold">Incorrect</format></td>
<td width="60%"><format color="Green" style="bold">Correct</format></td>
</tr>
<tr>
<td><img src="dropdown_incorrect.png" alt="" width="189" /></td>
<td><img src="dropdown_correct.png" alt="" width="351" /></td>
</tr>
</table>

## When to use a drop-down instead
Consider using a [drop-down list](drop_down.md) if:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A verb is missing here, the introductory sentence and bullet points should form a complete sentence

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added the verb to the sentences in the list where it was missing

* There are more than 5 options or the options have long labels:
<table style="none" border="false">
<tr>
<td width="378">
<format color="Green" style="bold">Correct</format><img src="04_When_to_use_correct.png" alt="A correct example of using a drop-down list instead of radiobuttons"/>
</td>
<td width="378">
<format color="Red" style="bold">Incorrect</format><img src="04_When_to_use_incorrect.png" alt="An incorrect example of using radiobuttons for a list of 5 or more options"/>
</td>
</tr>
</table>

* The screen space is limited.
* The option might be used less often than other options on the screen.
* There are other drop-down lists in the same group of UI components. A radio button group is more noticeable than a drop-down list, so it will look like a more important setting.
* There is a combination of several UI components for one setting:
![](dropdown.png){width=575}
*The automatic updates setting consists of a checkbox, three lengthy-labeled options in a dropdown and a button.*
* The setting combines several UI components into one control:
![](05_When_to_use_Segmented_button.png){width=706}

## How to use

### Label

A label accompanies each checkbox and is placed next to it.

![](radiobutton_label.png){width=197}

If a label is long, split it into two lines. Avoid labels that take more than two lines. See recommendations on writing concise labels below.

![](twoline_label.png){width=195}

To implement this, use HTML formatting:
<tabs group="languages">
<tab title="Kotlin UI DSL" group-key="kotlin">

```kotlin
radioButton(
"<html>Show options before adding<br>to version control</html>")
```

</tab>
<tab title="Java" group-key="java">

```java
new JRadioButton(
"<html>Show options before adding<br>to version control</html>");
```

</tab>
</tabs>
<table style="none" border="false" column-width="fixed">
<tr>
<td><img src="06_How_to_use.png" alt="Label example" width="378"/></td>
<td><p>A label accompanies each radio button and is placed next to it.</p></td>
</tr>
<tr>
<td><img src="07_How_to_use.png" alt="An example of a label spanning two lines." width="378"/></td>
<td><p>If a label is long, split it into two lines. Avoid labels that take more than two lines. See recommendations on writing concise labels below.</p></td>
</tr>
</table>

<chapter title="Implementation" collapsible="true">
<tabs group="languages">
<tab title="Kotlin UI DSL" group-key="kotlin">

```kotlin
radioButton(
"<html>Show options before adding<br>to version control</html>")
```

</tab>
<tab title="Java" group-key="java">

```java
new JRadioButton(
"<html>Show options before adding<br>to version control</html>");
```

</tab>
</tabs>
</chapter>

### Writing guidelines

Use sentence-style capitalization.

Do not use ending punctuation.

Use the imperative form of verbs.

Do not use negation in labels as it complicates understanding.

<format color="Red" style="bold">Incorrect</format>
* Use sentence-style capitalization.
* Do not use ending punctuation.
* Use the imperative form of verbs.
* Do not use negation in labels as it complicates understanding.
* Make labels short and intelligible — see [Writing short and clear text](writing_short.md).

![](answeryes_incorrect.png){width=264}
<format color="369650" style="bold">Correct</format>
![](08_How_to_use_correct.png){width=706}

<format color="Green" style="bold">Correct</format>
<format color="E55765" style="bold">Incorrect</format>
![](08_How_to_use_incorrect.png){width=706}

![](answeryes_correct.png){width=139}

Make labels short and intelligible — see [Writing short and clear text](writing_short.md).

### Group label

![](grouplabel.png){width=267}

Always start a radio button group with a group label. It explains what the options are for.
Use a colon at the end of a group label.
![](10_How_to_use.png){width=706}

Use a checkbox or another radio button as a group label if the radio button group needs to be turned on or off.
![](09_How_to_use.png){width=706}

Use a colon at the end of a group label.

## Sizes and placement

If a radio button group depends on another control, e.g., a checkbox, follow the rules for [dependent colors](layout.md#dependent-controls).
Otherwise, follow the rules for [independent colors](layout.md).
Follow the layout of [checkboxes and radio-buttons](layout.md#checkboxes-and-radio-buttons)