Checkbox

A form input that allows users to select one or more options. Supports tile style, label descriptions, and indeterminate state. Follows USWDS checkbox patterns.

Props

Prop	Default	Description
`id`		Unique ID for the checkbox input; also links the `<label>` via `for`
`name`		Form field name submitted with the form
`label`		Label text displayed next to the checkbox
`value`		Value submitted when the checkbox is checked
`tile`	`False`	Set to `"true"` to use the tile checkbox style
`label_description`		Optional secondary description text below the label
`indeterminate`	`False`	Set to `"true"` to show an indeterminate (mixed) state
`checked`		Set to `"true"` to pre-check the checkbox
`disabled`		Set to `"true"` to disable the checkbox
`required`		Set to `"true"` to mark the checkbox as required
`extra_classes`		Additional CSS classes to apply to the checkbox wrapper

Example Usage

Checkbox Group

Use multiple c-checkbox elements sharing the same name to create a checkbox group. Wrap them in c-fieldset for accessible grouping.

<c-fieldset legend="Select all that apply">
    <c-checkbox id="opt-1" name="options" label="Option 1" value="option1" checked="true" />
    <c-checkbox id="opt-2" name="options" label="Option 2" value="option2" />
    <c-checkbox id="opt-3" name="options" label="Option 3" value="option3" />
</c-fieldset>

Checkbox with Label Description

<c-checkbox
    id="desc-checkbox"
    name="desc"
    label="Checkbox with Description"
    label_description="This is additional description text."
/>

Tile Checkbox

<c-checkbox
    id="tile-checkbox"
    name="tile"
    label="Tile Checkbox"
    tile="true"
/>

Tile Checkbox with Label Description

<c-checkbox
    id="tile-desc-checkbox"
    name="tile_desc"
    label="Tile Checkbox with Description"
    tile="true"
    label_description="This is additional description text."
/>

Indeterminate Checkbox

<c-checkbox
    id="indeterminate-checkbox"
    name="indeterminate"
    label="Indeterminate Checkbox"
    indeterminate="true"
/>

Disabled Checkbox

<c-checkbox
    id="disabled-checkbox"
    name="disabled"
    label="Disabled Checkbox"
    disabled="true"
/>

Required Checkbox

<c-checkbox
    id="required-checkbox"
    name="required"
    label="Required Checkbox"
    required="true"
/>

Checked Tile Checkbox

<c-checkbox
    id="checked-tile-checkbox"
    name="checked_tile"
    label="Checked Tile Checkbox"
    tile="true"
    checked="true"
/>

Disabled Indeterminate Checkbox

<c-checkbox
    id="disabled-indeterminate-checkbox"
    name="disabled_indeterminate"
    label="Disabled Indeterminate Checkbox"
    indeterminate="true"
    disabled="true"
/>

Usage Notes

For checkbox groups, wrap multiple c-checkbox elements in c-fieldset with a legend for accessibility
The tile style (tile="true") provides a larger click target with a bordered card appearance
The indeterminate state is a visual-only indicator; it must be managed in JavaScript after render
A required marker is automatically added to the label when required="true" is set

{% load cotton %}

<div class="component-variants">
    <h1>Checkbox Component</h1>

    {% for variant in variants %}
    <div class="component-variant">
        <h2 class="variant-title">{{ variant.title }}</h2>

        {% if variant.checkboxes %}
        {% for cb in variant.checkboxes %}
        {% cotton checkbox id="{{ cb.id }}" name="{{ cb.name }}" label="{{ cb.label }}" tile="{{ cb.tile }}" label_description="{{ cb.label_description }}" indeterminate="{{ cb.indeterminate }}" checked="{{ cb.checked }}" value="{{ cb.value }}" disabled="{{ cb.disabled }}" required="{{ cb.required }}" extra_classes="{{ cb.extra_classes }}" %}
        {% endcotton %}
        {% endfor %}
        {% else %}
        {% cotton checkbox id="{{ variant.id }}" name="{{ variant.name }}" label="{{ variant.label }}" tile="{{ variant.tile }}" label_description="{{ variant.label_description }}" indeterminate="{{ variant.indeterminate }}" checked="{{ variant.checked }}" value="{{ variant.value }}" disabled="{{ variant.disabled }}" required="{{ variant.required }}" extra_classes="{{ variant.extra_classes }}" %}
        {% endcotton %}
        {% endif %}                
    </div>
    {% endfor %}
    
</div>

name: Checkbox
context:
  variants:
    - title: "Checkbox Group"
      checkboxes:
        - id: "group1"
          name: "group"
          label: "Option 1"
          tile: ""
          label_description: ""
          indeterminate: ""
          checked: "true"
          value: "option1"
          disabled: ""
          required: ""
          extra_classes: ""
        - id: "desc-checkbox"
          title: "Checkbox with Label Description"
          name: "desc"
          label: "Checkbox with Description"
          tile: ""
          label_description: "This is additional description text."
          indeterminate: ""
          checked: ""
          value: ""
          disabled: ""
          required: ""
          extra_classes: ""

    - title: "Tile Checkbox"
      id: "tile-checkbox"
      name: "tile"
      label: "Tile Checkbox"
      tile: "true"
      label_description: ""
      indeterminate: ""
      checked: ""
      value: ""
      disabled: ""
      required: ""
      extra_classes: ""

    - title: "Checkbox with Label Description"
      id: "desc-checkbox"
      name: "desc"
      label: "Checkbox with Description"
      tile: ""
      label_description: "This is additional description text."
      indeterminate: ""
      checked: ""
      value: ""
      disabled: ""
      required: ""
      extra_classes: ""

    - title: "Tile Checkbox with Label Description"
      id: "tile-desc-checkbox"
      name: "tile_desc"
      label: "Tile Checkbox with Description"
      tile: "true"
      label_description: "This is additional description text."
      indeterminate: ""
      checked: ""
      value: ""
      disabled: ""
      required: ""
      extra_classes: ""

    - title: "Indeterminate Checkbox"
      id: "indeterminate-checkbox"
      name: "indeterminate"
      label: "Indeterminate Checkbox"
      tile: ""
      label_description: ""
      indeterminate: "true"
      checked: ""
      value: ""
      disabled: ""
      required: ""
      extra_classes: ""

    - title: "Disabled Checkbox"
      id: "disabled-checkbox"
      name: "disabled"
      label: "Disabled Checkbox"
      tile: ""
      label_description: ""
      indeterminate: ""
      checked: ""
      value: ""
      disabled: "true"
      required: ""
      extra_classes: ""

    - title: "Required Checkbox"
      id: "required-checkbox"
      name: "required"
      label: "Required Checkbox"
      tile: ""
      label_description: ""
      indeterminate: ""
      checked: ""
      value: ""
      disabled: ""
      required: "true"
      extra_classes: ""

    - title: "Checked Tile Checkbox"
      id: "checked-tile-checkbox"
      name: "checked_tile"
      label: "Checked Tile Checkbox"
      tile: "true"
      label_description: ""
      indeterminate: ""
      checked: "true"
      value: ""
      disabled: ""
      required: ""
      extra_classes: ""

    - title: "Disabled Indeterminate Checkbox"
      id: "disabled-indeterminate-checkbox"
      name: "disabled_indeterminate"
      label: "Disabled Indeterminate Checkbox"
      tile: ""
      label_description: ""
      indeterminate: "true"
      checked: ""
      value: ""
      disabled: "true"
      required: ""
      extra_classes: ""