RadioGroup

A flexible container that groups multiple anvil.RadioButton components so that only one can be selected at a time. You can either:

  • add individual RadioButton components as children of the group, or

  • set the items property (similar to an Anvil Dropdown) to auto-generate buttons.

The currently selected value is exposed via selected_value and a change event is fired whenever the selection changes.

Usage

Add as a container and append buttons

from anvil import RadioButton
from anvil_extras.RadioGroup import RadioGroup


class Form(FormTemplate):
    def __init__(self, **properties):
        # You can do this in code or via the Designer:
        # - Designer: Drag a RadioGroup onto your form, then drop RadioButtons into it.
        # - Code: Create a RadioGroup and add RadioButtons as children.
        self.radio_group = RadioGroup()
        self.add_component(self.radio_group)
        self.radio_group.add_component(RadioButton(text="Option A", value="a"))
        self.radio_group.add_component(RadioButton(text="Option B", value="b"))
        self.radio_group.add_event_handler("change", self.radio_group_change)

def radio_group_change(self, **event_args):
    # Read the logical value of the selected option
    print(self.radio_group.selected_value)  # -> "a" or "b"

Use the items property (like Dropdown)

items may be a list of strings or a list of (text, value) tuples:

from anvil_extras.RadioGroup import RadioGroup

# Simple list of strings: value equals the text
self.radio_group = RadioGroup(items=["One", "Two", "Three"])  # selected_value is one of the strings

# List of (text, value) pairs: logical value is separate from the label
self.radio_group.items = [("Apples", "apples"), ("Oranges", "oranges"), ("Pears", "pears")]

# Reading the selection returns the logical value (e.g. "oranges"):
print(self.radio_group.selected_value)

# Programmatic selection: set the logical value directly
self.radio_group.selected_value = "oranges"  # selects "Oranges"

Group existing RadioButtons on your form

If you already have individual RadioButton components on a form, you can group them:

from anvil_extras.RadioGroup import RadioGroup

# If you already have RadioButtons on your form (e.g. placed in the Designer),
# you can add group behaviour without moving them into the RadioGroup container.
# This is especially useful when buttons may not be on-screen yet and
# radio_buttons.group_value would otherwise be None.
# The group ensures mutual exclusivity and consistent change events.
self.radio_group = RadioGroup()
self.radio_group.buttons = [self.radio_button_1, self.radio_button_2]
self.radio_group.add_event_handler("change", self.radio_group_change)

# Alternatively, pass the buttons in the constructor
self.radio_group = RadioGroup(buttons=[self.radio_button_1, self.radio_button_2])
self.radio_group.add_event_handler("change", self.radio_group_change)

Properties

selected_value:

object | None

The logical value of the selected option. When using items with (text, value) pairs, this returns the value part. When using a list of strings, this is the string. Set to a matching value to programmatically select an option, or to None to clear.

gap:

string | float | int

Spacing between radio buttons. Accepts a number (pixels) or a CSS length string (e.g. "12px", "0.5rem").

spacing:

spacing

Standard Anvil container spacing

direction:

enum

Layout direction of the group: "horizontal" (default) or "vertical".

align:

enum

Alignment of buttons within the group. One of "left", "center", "right", "space-evenly", "space-between", "space-around". In horizontal layout this controls horizontal distribution; in vertical layout it controls cross-axis alignment.

visible:

bool

Whether the component is visible.

items:

list[str] | list[tuple[str, Any]]

Use to auto-generate buttons. Strings produce labels with the same value; tuples of (text, value) let you separate display text and logical value.

buttons:

list[anvil.RadioButton]

Assign an explicit list of existing RadioButton components to be managed by the group. When set, event handlers are attached and the buttons are grouped so only one can be selected at a time. You can also provide this in the constructor, e.g. RadioGroup(buttons=[rb1, rb2]).

Events

change:

Fired when the selection changes. This is the default event. Use self.radio_group.selected_value inside the handler to read the current value.

show:

Fired when the component is shown.

hide:

Fired when the component is hidden.

Notes

  • When items contains (text, value) pairs, selected_value returns the value; with a simple list of strings, it returns the string itself.

  • Setting selected_value to a value that doesn’t exist will clear the selection.

  • For tuple items, set selected_value to the tuple’s logical value (e.g. "oranges") at any time to select that option.

  • align="left"/"right" map to flexbox flex-start/flex-end under the hood.