Radio buttons

A group of options where exactly one can be selected at a time.

radio_buttons renders a stack of options where picking one clears any other. Use it when someone must choose a single option from a short list: an actions row or section accessory for a live choice, or an input block to collect a value in a modal or Home tab.

Fields

Each option is an Option object:

Examples

With an initial option selected

The preview above starts with “Medium” already selected, using initial_option.

Without an initial option

Nothing starts selected, and onAction doesn’t fire until the first pick.

With option descriptions

A description adds a second, muted line under the option’s label.

As a section accessory

As a section accessory, the group stacks below the section’s text instead of sitting beside it.

In an input block

With a confirmation dialog

The dialog appears before any new selection is applied. Picking the option that’s already selected does nothing and never asks. See Confirmation dialogs.

Interactivity

Selecting an option (after any confirm dialog is accepted) calls onAction with the chosen option under selected_option:

{
  "type": "radio_buttons",
  "action_id": "level",
  "block_id": "priority",
  "action_ts": "1706000000.000100",
  "selected_option": { "text": { "type": "plain_text", "text": "High" }, "value": "high" }
}

Reading the value

Radio buttons write to state.values on mount when initial_option is set (reporting it exactly like Slack does when the surface loads), and again on every selection:

{
  "priority": {
    "level": {
      "type": "radio_buttons",
      "selected_option": { "text": { "type": "plain_text", "text": "Medium" }, "value": "medium" }
    }
  }
}

Without initial_option, nothing is written to state.values until the first pick. Unlike checkboxes, there’s no empty state to report.

Related