Radio and RadioGroup

A system radio inherits all of the props available to its ancestor component, the Form.Checkbox, plus all those available to a native checkbox element.

Default example

The default Radio is stand-alone for individual radio buttons. To render a group of radio buttons in one fell-swoop, consider using the RadioGroup (documented below).

<Radio id="foo" name="example1" label="Default checkbox" value="bar" />
<Radio id="bar" name="example2" value="bar" label="Checked by default" checked />
<Radio id="fizz" name="example3" value="buzz" label="Checked and disabled" disabled checked />

Sizes

Use the size prop to proportionally adjust the size of a radio button's width and height. Sizes are the same as those available to the sibling component, TextInput.

<Radio id="foo" name="example1" label="Small checkbox" size="small" value="bar" checked />
<Radio id="foo" name="example1" label="Large checkbox" size="large" value="bar" checked />

Full-width (entire row)

<Radio id="foo" name="example1" label="Default checkbox" value="bar" block />
<Radio id="bar" name="example2" value="bar" label="Checked by default" block checked />
<Radio id="fizz" name="example3" value="buzz" label="Checked and disabled" block disabled checked />

Stacked (column)

<Radio id="foo" name="example1" label="Default checkbox" value="bar" stacked />
<Radio id="bar" name="example2" value="bar" label="Checked by default" stacked checked />
<Radio id="fizz" name="example3" value="buzz" label="Checked and disabled" stacked disabled checked />

RadioGroup

To render a group of related radio buttons, the RadioGroup component can be utilized.

Rendering with Radio children

<RadioGroup label='Group of radio buttons with optional parent label and individual labels'>
    <Radio id="radioGroup1" name="radioGroup1" value="radioGroup1" label="Radio 1" checked />
    <Radio id="radioGroup2" name="radioGroup1" value="radioGroup2" label="Radio 2" />
    <Radio id="radioGroup3" name="radioGroup1" value="radioGroup3" label="Radio 3" />
</RadioGroup>

Rendering with items prop

The following is the default look-n-feel when an array of objects is passed to the items prop, which takes on a left-to-right layout flow. Notice how each object items' key->value pair determines the corresponding Form.Label and Radio's props.

<RadioGroup items={[
    {
        name: 'exampleRadioGroup',
        label: 'RadioGroup Option 1',
        value: 'example value 1'
    },
    {
        name: 'exampleRadioGroup',
        label: 'RadioGroup Option 2',
        value: 'example value 2'
    },
    {
        checked: true,
        disabled: true,
        name: 'exampleRadioGroup',
        label: 'RadioGroup Option 3, pre-checked and disabled',
        value: 'example value 3'
    },
    {
        name: 'exampleRadioGroup',
        label: 'RadioGroup Option 4',
        value: 'example value 4'
    },
    {
        name: 'exampleRadioGroup',
        label: 'RadioGroup Option 5',
        value: 'example value 5'
    },
    {
        color: 'purple.6',
        name: 'exampleRadioGroup',
        label: 'RadioGroup Option 5 with custom color',
        value: 'example value 5'
    }
]} />

Vertical stack (column)

If a stacked or vertical flow between a radio button and its corresponding label is desired, pass down the stacked prop on the RadioGroup component as demonstrated below:

<RadioGroup stacked items={[
    {
        name: 'exampleRadioGroup',
        label: 'RadioGroup Option 1',
        value: 'example value 1'
    },
    {
        checked: true,
        disabled: true,
        name: 'exampleRadioGroup',
        label: 'RadioGroup Option 2, pre-checked and disabled',
        value: 'example value 2'
    },
    {
        color: 'purple',
        name: 'exampleRadioGroup',
        label: 'RadioGroup Option 3 with custom color',
        value: 'example value 3'
    }
]} />

Full-width amongst a set via block

Leverage the block prop to span individual radio buttons and their respective label wrappers, within a set, across a full-row, similar to individual radio instances.

<RadioGroup block items={[
    {
        name: 'exampleRadioGroup',
        label: 'RadioGroup Option 1',
        value: 'example value 1'
    },
    {
        checked: true,
        disabled: true,
        name: 'exampleRadioGroup',
        label: 'RadioGroup Option 2, pre-checked and disabled',
        value: 'example value 2'
    },
    {
        color: 'purple',
        name: 'exampleRadioGroup',
        label: 'RadioGroup Option 3 with custom color',
        value: 'example value 3'
    }
]} />

Color and Scheme Usage

As is common with other Bristlecone components, defining the text and background color of a component can be done using various system props, such as color and bg, respectively, or even the scheme prop. When both the color and scheme props are defined for a radio button item, the color value takes precedence. If a checkbox is disabled, the disabled state color also takes precedence over the scheme value. Check out the following example:

Color Scheme via RadioGroup's scheme prop

<Form.RadioGroup block placement='right' scheme='purple' label='Sample color schemes defined by parent component'>
    <Radio id="radio_color_scheme1" name="radio_color_scheme1" label='Radio 1 w/inherited scheme' value="checkbox1" checked />
    <Radio id="radio_color_scheme2" name="radio_color_scheme1" label='Radio 2 w/inherited scheme' value="checkbox2" checked />
    <Radio id="radio_color_scheme2" name="radio_color_scheme1" label='Parent scheme overriden by local disabled state' value="checkbox3" scheme="disabled" disabled checked />
</Form.RadioGroup>

Color Scheme via individual Radio instances

<Form.RadioGroup block placement='right' label='Sample color schemes'>
    <Radio id="cb_color_scheme1" name="cb_color_scheme1" label='Default' value="default" scheme="default" checked />
    <Radio id="cb_color_scheme2" name="cb_color_scheme1" label='Blue' value="blue" scheme="blue" checked />
    <Radio id="cb_color_scheme2" name="cb_color_scheme1" label='Disabled' value="disabled" scheme="disabled" disabled checked />
    <Radio id="cb_color_scheme2" name="cb_color_scheme1" label='Error' value="error" scheme="error" checked />
    <Radio id="cb_color_scheme1" name="cb_color_scheme1" label='Pending' value="pending" scheme="pending" checked />
    <Radio id="cb_color_scheme1" name="cb_color_scheme1" label='Purple' value="purple" scheme="purple" checked />
    <Radio id="cb_color_scheme2" name="cb_color_scheme1" label='Red' value="red" scheme="red" checked />
    <Radio id="cb_color_scheme2" name="cb_color_scheme1" label='Success' value="success" scheme="success" checked />
    <Radio id="cb_color_scheme2" name="cb_color_scheme1" label='Warning' value="warning" scheme="warning" checked />
</Form.RadioGroup>

Color Schemes via RadioGroup's items props

<RadioGroup block label='A set of radio buttons defined with items prop' items={[
    {
        checked: true,
        color: 'purple',
        scheme: 'error',
        name: 'exampleRadioGroup',
        label: '`color` and `scheme` defined; `color` wins',
        value: 'example value 1'
    },
    {
        checked: true,
        disabled: true,
        scheme: 'error',
        name: 'exampleRadioGroup',
        label: '`disabled` and `scheme` defined; `disabled` wins',
        value: 'example value 2'
    },
    {
        checked: true,
        scheme: 'success',
        name: 'exampleRadioGroup',
        label: '`scheme` defined only',
        value: 'example value 3'
    }
]} />

System props

Radio components get BACKGROUND BORDER, COMMON, TYPOGRAPHY and CORE VARIANT system props, since the component is an extension of the Form.Checkbox. Read the System Props doc page for a full list of available props. Check out the respective MDN docs to learn more about the <radio> element.

Radio component props

NameTypeDefaultDescription
checkedBooleanSets the checked attribute on the element
disabledBooleanSets the disabled attribute on the element
idStringSets the id attribute on the element
labelStringLabel that describes the input for screen reader users
nameStringSets the name attribute on the element
onChangeFunctionFunction to be called when content in Input changes
requiredBooleanSets the required attribute on the element
schemeStringdefaultSets a color scheme for the radio button based on the theme's formStyles definition.
valueStringCurrent value of the Input.

RadioGroup component props

NameTypeDefaultDescription
childrennodeReact or System components that are of type Radio.
itemsArrayAn array of objects with a set of defined name and label keys for rendering a group of related radio buttons. Use when not defining children literals. Each item object takes all props that an individual Radio takes as defined above, in addition to: color; color is for defining the label's text-color; scheme defines a radio button's color scheme when ticked (checked))
placementString'left'Aligns the radio button to the left or right of the label text for any given checkbox.
blockBooleanRenders radio items full-width, left-to-right (or RTL), where each radio button and corresponding label text takes up an entire horizontal space-line. Works in tandem with the Form.Label component's block prop.
stackedBooleanRenders individual radio items' label and checkbox vertically, or stacked in a column-fashion. Works in tandem with the Form.Label component's stack prop.