Radio Button

A form input that allows users to select exactly one option from a group. Supports tile style and label descriptions. Follows USWDS radio button patterns.

Props

Prop	Default	Description
`id`		Unique ID for the radio input; also links the `<label>` via `for`
`name`		Form field name; all radio buttons in a group share the same `name`
`label`		Label text displayed next to the radio button
`value`		Value submitted when this radio button is selected
`radio_type`		Style variant: leave empty for default, or `"tile"` for the tile style
`label_description`		Optional secondary description text below the label
`checked`	`False`	Set to `"true"` to pre-select this radio button

Example Usage

Default Radio Group

Wrap multiple c-radio-button elements sharing the same name in a c-fieldset.

<c-fieldset legend="Please select an option">
    <c-radio-button id="radio-1" name="choice" label="Option A" value="a" />
    <c-radio-button id="radio-2" name="choice" label="Option B" value="b" />
    <c-radio-button id="radio-3" name="choice" label="Option C" value="c" />
</c-fieldset>

Required Radio Group

<c-fieldset legend="Please select an option" required="true">
    <c-radio-button id="radio-1" name="choice" label="Option A" value="a" />
    <c-radio-button id="radio-2" name="choice" label="Option B" value="b" />
    <c-radio-button id="radio-3" name="choice" label="Option C" value="c" />
</c-fieldset>

Tile Radio Group with Label Descriptions

<c-fieldset legend="Please select an option">
    <c-radio-button
        id="tile-1"
        name="tile_choice"
        label="Option A"
        value="a"
        radio_type="tile"
        label_description="Description for option A"
    />
    <c-radio-button
        id="tile-2"
        name="tile_choice"
        label="Option B"
        value="b"
        radio_type="tile"
        label_description="Description for option B"
    />
    <c-radio-button
        id="tile-3"
        name="tile_choice"
        label="Option C"
        value="c"
        radio_type="tile"
        label_description="Description for option C"
    />
</c-fieldset>

Tile Radio Group (Required)

<c-fieldset legend="Please select an option" required="true">
    <c-radio-button id="tile-req-1" name="tile_req" label="Option A" value="a" radio_type="tile" />
    <c-radio-button id="tile-req-2" name="tile_req" label="Option B" value="b" radio_type="tile" />
    <c-radio-button id="tile-req-3" name="tile_req" label="Option C" value="c" radio_type="tile" />
</c-fieldset>

Radio Group with Default Selection

<c-fieldset legend="Please select an option">
    <c-radio-button id="default-1" name="default_choice" label="Option A" value="a" checked="true" />
    <c-radio-button id="default-2" name="default_choice" label="Option B" value="b" />
    <c-radio-button id="default-3" name="default_choice" label="Option C" value="c" />
</c-fieldset>

Tile Radio Group with Default Selection

<c-fieldset legend="Please select an option">
    <c-radio-button id="tile-def-1" name="tile_default" label="Option A" value="a" radio_type="tile" checked="true" />
    <c-radio-button id="tile-def-2" name="tile_default" label="Option B" value="b" radio_type="tile" />
    <c-radio-button id="tile-def-3" name="tile_default" label="Option C" value="c" radio_type="tile" />
</c-fieldset>

Usage Notes

All radio buttons in a group must share the same name attribute so only one can be selected at a time
Always wrap a radio button group in c-fieldset with a descriptive legend for accessibility
Each radio button must have a unique id on the page
The tile style (radio_type="tile") displays each option as a bordered card with a larger click target
Set checked="true" on at most one radio button per group to establish a default selection

{% load cotton %}

<div class="component-variants">
    <h1>Radio Button Component</h1>
    
    {% for variant in variants %}
    <div class="component-variant">
        <h2 class="variant-title">{{ variant.title }}</h2>
        {% cotton fieldset legend="{{ variant.legend }}" legend_type="{{ variant.legend_type }}" required="{{ variant.required }}" %}
            {% for item in variant.items %}
            {% cotton radio-button id="{{ item.id }}" label="{{ item.label }}" label_description="{{ item.label_description }}" radio_type="{{ item.radio_type }}" name="{{ item.name }}" value="{{ item.value }}" checked="{{ item.checked }}" %}{% endcotton %}
            {% endfor %}
        {% endcotton %}
    </div>
    {% endfor %}
</div>

name: Radio Button
context:
  variants:            
    - title: "Radio (default)"
      legend: "Please Select an Option"
      required: ""
      items:
        - id: "radio-1"
          label: "John Doe"
          radio_type: ""
          name: "radio1"
          value: "option1"
          checked: "false"
        - id: "radio-2"
          label: "Jane Doe"
          radio_type: ""
          name: "radio1"
          value: "option2"
          checked: "false"
        - id: "radio-3"
          label: "Jim Doe"
          radio_type: ""
          name: "radio1"
          value: "option3"
          checked: "false"
    - title: "Radio (required)"
      legend: "Please Select an Option"
      required: "true"
      items:
        - id: "radio-4"
          label: "John Doe"
          radio_type: ""
          name: "radio2"
          value: "option4"
          checked: "false"
        - id: "radio-5"
          label: "Jane Doe"
          radio_type: ""
          name: "radio2"
          value: "option5"
          checked: "false"
        - id: "radio-6"
          label: "Jim Doe"
          radio_type: ""
          name: "radio2"
          value: "option6"
          checked: "false"
    - title: "Radio (tile w/ optional label text)"
      legend: "Please Select an Option"
      required: ""
      items:
        - id: "radio-7"
          label: "John Doe"
          radio_type: "tile"
          label_description: "Optional label text"
          name: "radio3"
          value: "option7"
          checked: "false"
        - id: "radio-8"
          label: "Jane Doe"
          radio_type: "tile"
          label_description: "Optional label text"
          name: "radio3"
          value: "option8"
          checked: "false"
        - id: "radio-9"
          label: "Jim Doe"
          radio_type: "tile"
          label_description: "Optional label text"
          name: "radio3"
          value: "option9"
          checked: "false"
    - title: "Radio (tile required)"
      legend: "Please Select an Option"
      required: "true"
      items:
        - id: "radio-10"
          label: "John Doe"
          radio_type: "tile"
          name: "radio4"
          value: "option10"
          checked: "false"
        - id: "radio-11"
          label: "Jane Doe"
          radio_type: "tile"
          name: "radio4"
          value: "option11"
          checked: "false"
        - id: "radio-12"
          label: "Jim Doe"
          radio_type: "tile"
          name: "radio4"
          value: "option12"
          checked: "false"
    - title: "Radio (with default selection)"
      legend: "Please Select an Option"
      required: ""
      items:
        - id: "radio-13"
          label: "John Doe"
          radio_type: ""
          name: "radio5"
          value: "option13"
          checked: "true"
        - id: "radio-14"
          label: "Jane Doe"
          radio_type: ""
          name: "radio5"
          value: "option14"
          checked: "false"
        - id: "radio-15"
          label: "Jim Doe"
          radio_type: ""
          name: "radio5"
          value: "option15"
          checked: "false"
    - title: "Radio (tile w/ default selection)"
      legend: "Please Select an Option"
      required: ""
      items:
        - id: "radio-16"
          label: "John Doe"
          radio_type: "tile"
          name: "radio6"
          value: "option16"
          checked: "true"
        - id: "radio-17"
          label: "Jane Doe"
          radio_type: "tile"
          name: "radio6"
          value: "option17"
          checked: "false"
        - id: "radio-18"
          label: "Jim Doe"
          radio_type: "tile"
          name: "radio6"
          value: "option18"
          checked: "false"