Button

A clickable element used to trigger actions or navigate within a form. Supports multiple color variants, sizes, and states. Follows USWDS button patterns.

Props

Prop	Default	Description
`text`		Button label text
`variant`		Color/style variant: leave empty for default, or use `secondary`, `accent-cool`, `accent-warm`, `base`, `outline`, `outline-inverse`, `big`, or `unstyled`
`state`		Force a visual state for demonstration: `hover`, `active`, `focus`, `unstyled`
`type`	`"button"`	HTML button type: `button`, `submit`, or `reset`
`disabled`		Set to `"true"` to disable the button
`aria_disabled`		Set to `"true"` to mark the button as disabled via ARIA without removing interactivity
`onClick`		JavaScript expression for the `onclick` handler
`name`		Form field name for submit buttons
`value`		Value submitted with the form for submit buttons

Example Usage

Default Button

<c-button text="Default" />

Secondary Button

<c-button text="Secondary" variant="secondary" />

Accent Cool Button

<c-button text="Accent Cool" variant="accent-cool" />

Accent Warm Button

<c-button text="Accent Warm" variant="accent-warm" />

Base Button

<c-button text="Base" variant="base" />

Outline Button

<c-button text="Outline" variant="outline" />

Outline Inverse Button

Use on dark backgrounds.

<c-button text="Outline Inverse" variant="outline-inverse" />

Big Button

<c-button text="Big" variant="big" />

Unstyled Button

<c-button text="Unstyled" variant="unstyled" />

Disabled Button

<c-button text="Disabled" disabled="true" />

ARIA-Disabled Button

Visually disabled but still focusable and interactive.

<c-button text="ARIA Disabled" aria_disabled="true" />

Submit Button

<c-button text="Submit" type="submit" />

Usage Notes

The state prop is intended for visual demonstration in the pattern library; in production the browser handles hover/active/focus states automatically
Use disabled="true" to fully prevent interaction; use aria_disabled="true" when you need the button to remain focusable (e.g., to show a tooltip explaining why it is unavailable)
variant="outline-inverse" renders as usa-button--outline usa-button--inverse and should be used on dark-colored backgrounds

{% load cotton %}

<div class="component-variants">
    <h1>Button Component</h1>
    
    {% for variant in variants %}
    <div class="component-variant">
        <h2 class="variant-title">{{ variant.title }}</h2>
        {% for options in variant.options %}
        {% cotton button text="{{ options.text }}" state="{{ options.state }}" variant="{{ options.variant }}" disabled="{{ options.disabled }}" aria_disabled="{{ options.aria_disabled }}" %}{% endcotton %}
        {% endfor %}
    </div>
    {% endfor %}
    {% for variant in inverted_variants %}
    <div class="component-variant">
        <h2 class="variant-title">{{ variant.title }}</h2>
        <div class="bg-base-darkest padding-1" style="max-width: fit-content">
            {% for options in variant.options %}
                {% cotton button text="{{ options.text }}" state="{{ options.state }}" variant="{{ options.variant }}" disabled="{{ options.disabled }}" aria_disabled="{{ options.aria_disabled }}" %}{% endcotton %}
            {% endfor %}
        </div>
    </div>
    {% endfor %}
</div>

name: Button
context:
  variants:            
    - title: "Default"
      options:
        - text: "Default"
          state: ""
          variant: ""
        - text: "Hover"
          state: "hover"
          variant: ""
        - text: "Active"
          state: "active"
          variant: ""
        - text: "Focus"
          state: "focus"
          variant: ""
        - text: "Disabled"
          state: ""
          variant: ""
          disabled: "true"
        - text: "aria-disabled"
          state: ""
          variant: ""
          aria_disabled: "true"
        - text: "Unstyled button"
          state: "unstyled"
          variant: ""
    - title: "Secondary Color"
      options:
        - text: "Default"
          state: ""
          variant: "secondary"
        - text: "Hover"
          state: "hover"
          variant: "secondary"
        - text: "Active"
          state: "active"
          variant: "secondary"
        - text: "Focus"
          state: "focus"
          variant: "secondary"
        - text: "Disabled"
          state: ""
          variant: "secondary"
          disabled: "true"
        - text: "aria-disabled"
          state: ""
          variant: "secondary"
          aria_disabled: "true"
        - text: "Unstyled button"
          state: "unstyled"
          variant: "secondary"
    - title: "Accent Cool Color"
      options:
        - text: "Default"
          state: ""
          variant: "accent-cool"
        - text: "Hover"
          state: "hover"
          variant: "accent-cool"
        - text: "Active"
          state: "active"
          variant: "accent-cool"
        - text: "Focus"
          state: "focus"
          variant: "accent-cool"
        - text: "Disabled"
          state: ""
          variant: "accent-cool"
          disabled: "true"
        - text: "aria-disabled"
          state: ""
          variant: "accent-cool"
          aria_disabled: "true"
        - text: "Unstyled button"
          state: "unstyled"
          variant: "accent-cool"
    - title: "Accent Warm Color"
      options:
        - text: "Default"
          state: ""
          variant: "accent-warm"
        - text: "Hover"
          state: "hover"
          variant: "accent-warm"
        - text: "Active"
          state: "active"
          variant: "accent-warm"
        - text: "Focus"
          state: "focus"
          variant: "accent-warm"
        - text: "Disabled"
          state: ""
          variant: "accent-warm"
          disabled: "true"
        - text: "aria-disabled"
          state: ""
          variant: "accent-warm"
          aria_disabled: "true"
        - text: "Unstyled button"
          state: "unstyled"
          variant: "accent-warm"
    - title: "Base Color"
      options:
        - text: "Default"
          state: ""
          variant: "base"
        - text: "Hover"
          state: "hover"
          variant: "base"
        - text: "Active"
          state: "active"
          variant: "base"
        - text: "Focus"
          state: "focus"
          variant: "base"
        - text: "Disabled"
          state: ""
          variant: "base"
          disabled: "true"
        - text: "aria-disabled"
          state: ""
          variant: "base"
          aria_disabled: "true"
        - text: "Unstyled button"
          state: "unstyled"
          variant: "base"
    - title: "Outline"
      options:
        - text: "Default"
          state: ""
          variant: "outline"
        - text: "Hover"
          state: "hover"
          variant: "outline"
        - text: "Active"
          state: "active"
          variant: "outline"
        - text: "Focus"
          state: "focus"
          variant: "outline"
        - text: "Disabled"
          state: ""
          variant: "outline"
          disabled: "true"
        - text: "aria-disabled"
          state: ""
          variant: "outline"
          aria_disabled: "true"
        - text: "Unstyled button"
          state: "unstyled"
          variant: "outline"
    - title: "Big Button"
      options:
        - text: "Default"
          state: ""
          variant: "big"
        - text: "Disabled"
          state: ""
          variant: "big"
          disabled: "true"
        - text: "aria-disabled"
          state: ""
          variant: "big"
          aria_disabled: "true"
        - text: "Unstyled button"
          state: "unstyled"
          variant: "big"
  inverted_variants:            
    - title: "Outline inverse"
      options:
        - text: "Default"
          state: ""
          variant: "outline-inverse"
        - text: "Hover"
          state: "hover"
          variant: "outline-inverse"
        - text: "Active"
          state: "active"
          variant: "outline-inverse"
        - text: "Focus"
          state: "focus"
          variant: "outline-inverse"
        - text: "Disabled"
          state: ""
          variant: "outline-inverse"
          disabled: "true"
        - text: "aria-disabled"
          state: ""
          variant: "outline-inverse"
          aria_disabled: "true"
        - text: "Unstyled button"
          state: "unstyled"
          variant: "outline-inverse"