cotton

Switch

Toggle switches for immediate state changes and settings.

On its own, a switch is just the toggle control, so you can pair it with your own label or drop it into a custom layout. Add a field attribute (label, description, ...) and it wraps itself as a field instead.

Wi-Fi 
<div class="flex items-center gap-3">
    <c-ui.switch name="wifi" checked />
    <span class="text-sm text-zinc-700 dark:text-zinc-300">Wi-Fi</span>
</div>
<div class="flex items-center gap-3">
    {% cotton ui.switch name="wifi" checked /%}
    <span class="text-sm text-zinc-700 dark:text-zinc-300">Wi-Fi</span>
</div>

With Descriptions

Add contextual information with the description attribute.

Receive updates and alerts via email
Get the latest news and offers
Important account security notifications 
<c-ui.switch
    name="email_notifications"
    label="Email Notifications"
    description="Receive updates and alerts via email"
/>
<c-ui.switch
    name="marketing_emails"
    label="Marketing Emails"
    description="Get the latest news and offers"
/>
<c-ui.switch
    name="security_alerts"
    label="Security Alerts"
    description="Important account security notifications"
    checked
/>
{% cotton ui.switch
    name="email_notifications"
    label="Email Notifications"
    description="Receive updates and alerts via email"
/%}
{% cotton ui.switch
    name="marketing_emails"
    label="Marketing Emails"
    description="Get the latest news and offers"
/%}
{% cotton ui.switch
    name="security_alerts"
    label="Security Alerts"
    description="Important account security notifications"
    checked
/%}

Checked by Default

Set the initial state to checked with checked.

Enable dark theme 
<c-ui.switch
    name="dark_mode"
    label="Dark Mode"
    description="Enable dark theme"
    checked
/>
{% cotton ui.switch
    name="dark_mode"
    label="Dark Mode"
    description="Enable dark theme"
    checked
/%}

Disabled

Disable interaction with disabled.

Upgrade to enable this feature
Automatically save your work 
<c-ui.switch
    name="feature_disabled_off"
    label="Premium Feature"
    description="Upgrade to enable this feature"
    disabled
/>
<c-ui.switch
    name="feature_disabled_on"
    label="Auto-save"
    description="Automatically save your work"
    checked
    disabled
/>
{% cotton ui.switch
    name="feature_disabled_off"
    label="Premium Feature"
    description="Upgrade to enable this feature"
    disabled
/%}
{% cotton ui.switch
    name="feature_disabled_on"
    label="Auto-save"
    description="Automatically save your work"
    checked
    disabled
/%}

Sizes

Size variants run from size="xs" to size="2xl". The default is md.

Compact size for dense layouts
Standard size for most use cases
Larger touch target for accessibility 
<c-ui.switch
    name="small_switch"
    label="Small Switch"
    description="Compact size for dense layouts"
    size="sm"
/>
<c-ui.switch
    name="default_switch"
    label="Default Switch"
    description="Standard size for most use cases"
/>
<c-ui.switch
    name="large_switch"
    label="Large Switch"
    description="Larger touch target for accessibility"
    size="lg"
/>
{% cotton ui.switch
    name="small_switch"
    label="Small Switch"
    description="Compact size for dense layouts"
    size="sm"
/%}
{% cotton ui.switch
    name="default_switch"
    label="Default Switch"
    description="Standard size for most use cases"
/%}
{% cotton ui.switch
    name="large_switch"
    label="Large Switch"
    description="Larger touch target for accessibility"
    size="lg"
/%}

As a field

Give it any field attribute (label, description, error or badge) and the switch wraps itself in a Field component with no extra markup. By default the label sits above the control (block layout); add inline to lay it out as a toggle row with the switch on the right.

Get notified about account activity.
Get notified about account activity. 
{# Block layout (default) #}
<c-ui.switch
    name="notifications"
    label="Enable notifications"
    description="Get notified about account activity."
/>

{# Toggle row #}
<c-ui.switch
    name="notifications"
    label="Enable notifications"
    description="Get notified about account activity."
    inline
/>
{# Block layout (default) #}
{% cotton ui.switch
    name="notifications"
    label="Enable notifications"
    description="Get notified about account activity."
/%}

{# Toggle row #}
{% cotton ui.switch
    name="notifications"
    label="Enable notifications"
    description="Get notified about account activity."
    inline
/%}

Reference

Props

Name Description Type Options Default
name Form field name for submission str —
value Value submitted when the switch is checked str — on
label Label text displayed next to the switch str —
description Helper text displayed below the label str —
description_trailing Additional helper text displayed after the switch str —
error Error message to display str —
badge Badge text to display next to the label str —
form Django form object for error handling Form —
:disabled Disables the switch and prevents interaction bool
TrueFalse
False
:checked Sets the initial checked state of the switch bool
TrueFalse
False
:accent Uses accent color when checked. Set to False for neutral colors bool
TrueFalse
True
size Size variant from xs to 2xl. str
xssmmdlgxl2xl
md

Events

Name Description Type Options Default
checkedChange Dispatched when the switch state changes. Use @checkedChange to listen CustomEvent —

Accessibility

The switch component is built with accessibility in mind:

  • ARIA Roles: Uses role="switch" for proper screen reader support
  • ARIA State: aria-checked automatically reflects the current state
  • ARIA Labels: aria-label is automatically derived from the associated label
  • Keyboard Support: Space and Enter keys toggle the switch, Tab for focus navigation
  • Focus States: Clear visual focus indicators for keyboard navigation