A versatile checkbox component for capturing single and multiple selections.

This component provides a comprehensive solution for building accessible form inputs, selection interfaces, and rich interactive content. It seamlessly integrates with Phoenix forms and offers both standard and card variants to accommodate various design patterns, from simple boolean toggles to visually rich selection interfaces.

Usage

The checkbox component can be used in its simplest form for single selections:

<.checkbox
  name="terms"
  label="I agree to the terms and conditions"
  value="accepted"
/>

The checkbox value will be "true" when checked and "false" when unchecked.

%{"_target" => ["terms"], "terms" => "true"}
%{"_target" => ["terms"], "terms" => "false"}

For more context, you can add sublabels and descriptions:

<.checkbox
  name="notifications"
  label="Enable notifications"
  sublabel="Receive updates about your account"
  description="We'll send you important updates about your account status and security."
/>

Form Integration

The checkbox component offers two ways to handle form data: using the field attribute for Phoenix form integration or using the name attribute for standalone checkboxes. Each approach has its own benefits and use cases.

Using with Phoenix Forms (Recommended)

When working with Phoenix forms, use the field attribute to bind the checkbox to a form field:

<.form :let={f} for={@form} phx-change="validate" phx-submit="save">
  <.checkbox
    field={f[:marketing_emails]}
    label="Marketing emails"
    sublabel="Receive updates about new features and promotions"
  />

  <.checkbox
    field={f[:terms_accepted]}
    label="Terms and Conditions"
    description="I agree to the terms of service and privacy policy"
    value="accepted"
  />

  <.checkbox
    field={f[:newsletter_frequency]}
    label="Weekly newsletter"
    value="weekly"
    checked={@user.newsletter_frequency == "weekly"}
  />
</.form>

Using the field attribute provides several advantages:

• Automatic value handling from the form data
• Built-in error handling and validation messages
• Proper form submission with correct field names
• Integration with changesets for data validation
• Automatic ID generation for accessibility
• Proper handling of nested form data

The component will automatically:

• Set the checkbox field's name based on the form structure
• Display the current value from the form data
• Show validation errors when present
• Handle nested form data with proper input naming

Using Standalone Checkboxes

For simpler cases or when not using Phoenix forms, use the name attribute:

<.checkbox
  name="show_archived"
  checked={@show_archived}
  label="Show archived items"
/>

<.checkbox
  name="user[preferences][dark_mode]"
  checked={@user_preferences.dark_mode}
  errors={@errors["dark_mode"]}
  label="Dark mode"
  sublabel="Use dark theme"
/>

When using standalone checkboxes:

• You must provide the name attribute
• Values must be managed manually via the checked attribute
• Errors must be passed explicitly via the errors attribute
• Form submission handling needs to be implemented manually
• Nested data requires manual name formatting (e.g., user[preferences][dark_mode])

Card Variant

The component offers a card variant that transforms checkboxes into rich, interactive selection cards:

 <.checkbox
    control="left"
    field={f[:notifications]}
    variant="card"
    label="Push Notifications"
    sublabel="Stay informed"
    description="Get real-time updates for messages and activity"
    value="enabled"
  />

Checkbox Group

Checkbox groups are used to map a list of options to a single form field:

<.checkbox_group
  name="preferences"
  label="Notification Preferences"
  description="Choose when you want to receive notifications"
>
  <:checkbox value="email" label="Email notifications" />
  <:checkbox value="push" label="Push notifications" />
  <:checkbox value="sms" label="SMS notifications" />
</.checkbox_group>

Form Integration

Like the single checkbox component, checkbox groups seamlessly integrate with Phoenix forms. See the form integration section in the Form Integration section for a detailed guide on form handling.

Here's a simple example using the field attribute:

<.form :let={f} for={@form} phx-change="validate" phx-submit="save">
  <.checkbox_group
    field={f[:notification_preferences]}
    label="Notification Preferences"
    description="Choose how you want to be notified"
  >
    <:checkbox value="email" label="Email" sublabel="Get notified via email" />
    <:checkbox value="push" label="Push" sublabel="Receive push notifications" />
    <:checkbox value="sms" label="SMS" sublabel="Get SMS alerts" />
  </.checkbox_group>
</.form>

Different from the single checkbox, the group will send a list of selected values in the form submission:

%{"_target" => ["preferences"], "preferences" => ["", "email", "push"]}

<input type="hidden" name="group[]" value="" />

# No checkboxes selected
%{"group" => [""]}

# One or more selected
%{"group" => ["", "option1", "option2"]}

# Example processing
selected = Enum.reject(params["group"] || [], &(&1 == ""))

Card Variant

The card variant transforms checkboxes into rich, interactive selection cards:

<.checkbox_group
  label="Weekdays"
  description="Select the days of the week you want to work"
  field={f[:weekdays]}
  variant="card"
  class="flex gap-x-2"
>
  <:checkbox
    :for={{label, value} <- [{"S", "sun"}, {"M", "mon"}, {"T", "tue"}, {"W", "wed"}, {"T", "thu"}, {"F", "fri"}, {"S", "sat"}]}
    value={value}
    class="flex items-center justify-center rounded-full has-[:checked]:bg-zinc-800 text-zinc-700 has-[:checked]:text-white size-10"
  >
    <span class="text-sm font-medium">{label}</span>
  </:checkbox>
</.checkbox_group>