Component | Radio Group

Render a radio group.

TypeScript / JavaScript

ui.radioGroup("radio-group-key", ["A", "B", "C", "D"], { 
    label: "Select an option",
    onChange: (value) => console.log(value)
})

Python

ui.radio_group(
    "radio-group-key",
    ["A", "B", "C", "D"],
    label="Select an option",
    on_change=lambda value: print(value)
)

Learn more about working with inputs.

Options

Select components support both a "basic" and "detailed" format for options.

TypeScript / JavaScript

Python

Basic

Quick and easy. Pass an array of strings, such as ["A", "B", "C", "D"].

TypeScript / JavaScript

ui.radioGroup("radio-group-key", ["A", "B", "C", "D"], { 
    label: "Select an option",
    onChange: (value) => console.log(value)
})

Python

ui.radio_group(
    "radio-group-key",
    ["A", "B", "C", "D"],
    label="Select an option",
    on_change=lambda value: print(value)
)

Detailed

TypeScript / JavaScript

Use separate label and value fields for each option. The label field will be displayed to the user, and the value field will be passed to hooks such as onChange and validate.

const options = [
    { label: "Google", value: "GOOG" },
    { label: "Apple", value: "APPL" },
    {
        label: "Microsoft",
        value: "MSFT",
        // The detailed format also supports an optional "description" field
        // to display beneath an option.
        description: "Current stock price: $423"
    }
]

ui.radioGroup("company-select", options, {
    label: "Select a company",
    onChange: (value) => console.log(value) // Will be "GOOG", "APPL", or "MSFT"
})

Python

Use separate label and value fields for each option. The label field will be displayed to the user, and the value field will be passed to hooks such as on_change and validate.

options = [
    { "label": "Google", "value": "GOOG" },
    { "label": "Apple", "value": "APPL" },
    {
        "label": "Microsoft",
        "value": "MSFT",
        # The detailed format also supports an optional "description" field
        # to display beneath an option.
        "description": "Current stock price: $423"
    }
]

ui.radio_group(
    "company-select",
    options,
    label="Select an option",
    on_change=lambda value: print(value) # Will be "GOOG", "APPL", or "MSFT"
)

Detailed option object properties

TypeScript / JavaScript

label

required string

The user-facing label to use for the option.

Python

label

required str

The user-facing label to use for the option.

---

TypeScript / JavaScript

value

required string | number | boolean

The internal value to assign to the option and use when submitting a form or executing callbacks such as onChange.

Python

value

required str | float | int | bool

The internal value to assign to the option and use when submitting a form or executing callbacks such as on_change.

---

TypeScript / JavaScript

description

optional string

Helpful text to display beneath the label.

Python

description

optional str

Helpful text to display beneath the label.

---

API reference

Function signature

TypeScript / JavaScript

type OptionValue = string | number | boolean

type DetailedOption = {
    label: string,
    value: OptionValue,
    description?: string
}

ui.radioGroup(
    id: string,
    options: Array<OptionValue | DetailedOption>
    properties: Partial<{
        label: string,
        description: string,
        required: boolean,
        initialValue: OptionValue | null,
        validate: (value: OptionValue | null) => string | void,
        onChange: (value: OptionValue | null) => void,
        style: Style
    }>
)

Python

OptionValue = str | float | int | bool

class DetailedOption(TypedDict):
    label: str
    value: OptionValue
    description: NotRequired[str]

ui.radio_group(
    id: str,
    options: list[OptionValue | DetailedOption],
    *,
    label: str | None = None,
    description: str | None = None,
    required: bool = True,
    initial_value: OptionValue | None = None,
    validate: Callable[[OptionValue | None], str | None] = None,
    on_change: Callable[[OptionValue | None], None] = None,
    style: Style | None = None
)

Parameters

TypeScript / JavaScript

id

required string

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

Python

id

required str

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

---

TypeScript / JavaScript

options

required Array<OptionValue | DetailedValue>

The list of options that can be selected. See the options section for more info.

Python

options

required list[OptionValue | DetailedValue]

The list of options that can be selected. See the options section for more info.

---

TypeScript / JavaScript

properties.label

optional string

The label to display above the radio group. If not provided, the label will be inferred from the id.

Python

label

optional str

The label to display above the radio group. If not provided, the label will be inferred from the id.

---

TypeScript / JavaScript

properties.description

optional string

A description to display between the label and radio group.

Python

description

optional str

A description to display between the label and radio group.

---

TypeScript / JavaScript

properties.required

optional boolean

Validate that the radio group is not empty before submitting the form it's part of or calling it's onChange hook. Defaults to true.

Python

required

optional bool

Validate that the radio group is not empty before submitting the form it's part of or calling it's on_change hook. Defaults to True.

---

TypeScript / JavaScript

properties.initialValue

optional string | number | boolean | null

The initial value of the radio group. Defaults to null. You can also update the value of the radio group at any time using the page.setInputs() method.

Python

initial_value

optional str | float | int | bool | None

The initial value of the radio group. Defaults to None. You can also update the value of the radio group at any time using the page.set_inputs() method.

---

TypeScript / JavaScript

properties.validate

optional (value: string | number | boolean | null) => string | void

Validate the radio group value before submitting it. If the function returns a string, it will be displayed as an error message.

Python

validate

optional Callable[[str | float | int | bool | None], str | None]

Validate the radio group value before submitting it. If the function returns a string, it will be displayed as an error message.

---

TypeScript / JavaScript

properties.onChange

optional (value: string | number | boolean | null) => void

A callback function that is called when the user changes the value of the radio group.

Python

on_change

optional Callable[[str | float | int | bool | None], None]

A callback function that is called when the user changes the value of the radio group.

---

TypeScript / JavaScript

properties.style

optional Style

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.

Python

style

optional Style | None

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.

---