Phoenix implementation of Zag.js Checkbox.

API and events

Client DOM dispatches (handled by the Checkbox hook on the component root):

• corex:checkbox:set-checked — detail.checked must be a boolean; clears indeterminate.
• corex:checkbox:toggle-checked — toggles checked.

Server pushes (from set_checked/3, toggle_checked/2):

• checkbox_set_checked — %{"id" => id, "checked" => boolean}
• checkbox_toggle_checked — %{"id" => id}

Declarative checked may be true, false, or :indeterminate (Zag CheckedState). Imperative set_checked/2 remains boolean-only.

Examples

Minimal

<.checkbox class="checkbox">
  <:label>Accept terms</:label>
</.checkbox>

Custom Control

<.checkbox class="checkbox">
  <:label>
    Accept the terms
  </:label>
  <:indicator>
    <.heroicon name="hero-check" />
  </:indicator>
  <:indeterminate>
    <.heroicon name="hero-minus" />
  </:indeterminate>
</.checkbox>

Custom Error

<.checkbox class="checkbox">
  <:label>
    Accept the terms
  </:label>
  <:error :let={msg}>
    <.heroicon name="hero-exclamation-circle" class="icon" />
    {msg}
  </:error>
</.checkbox>

Phoenix Form Integration

When using with Phoenix forms, set the form id in to_form/2 and use id={@form.id} on <.form>.

Controller

Build the form from an Ecto changeset and pass it to the template. Pass id into to_form/2 so the template can use id={@form.id}:

def checkbox_form_page(conn, _params) do
  form =
    %MyApp.Form.Terms{}
    |> MyApp.Form.Terms.changeset(%{})
    |> Phoenix.Component.to_form(as: :terms, id: "checkbox-form")
  render(conn, :checkbox_form_page, form: form)
end

<.form :let={f} for={@form} id={@form.id} action={@action} method="post">
  <.checkbox field={f[:terms]} class="checkbox">
    <:label>Accept terms</:label>
    <:error :let={msg}>
      <.heroicon name="hero-exclamation-circle" class="icon" />
      {msg}
    </:error>
  </.checkbox>
  <button type="submit">Submit</button>
</.form>

Live View

When using Phoenix form in a Live view you must also add controlled mode. Prefer building the form from an Ecto changeset (see "With Ecto changeset" below).

With Ecto changeset (LiveView)

When using an Ecto changeset for validation in a LiveView, enable the controlled attribute on the checkbox so the LiveView remains the source of truth.

Schema and changeset:

defmodule MyApp.Form.Terms do
  use Ecto.Schema
  import Ecto.Changeset

  embedded_schema do
    field :terms, :boolean, default: false
  end

  def changeset(terms, attrs \\ %{}) do
    terms
    |> cast(attrs, [:terms])
    |> validate_required([:terms])
    |> validate_acceptance(:terms)
  end
end

LiveView with validate and submit:

defmodule MyAppWeb.CheckboxFormLive do
  use MyAppWeb, :live_view
  alias MyApp.Form.Terms

  def mount(_params, _session, socket) do
    form = %Terms{} |> Terms.changeset(%{}) |> to_form(as: :terms, id: "checkbox-form-terms")
    {:ok, assign(socket, :form, form)}
  end

  def handle_event("validate", %{"terms" => params}, socket) do
    changeset = Terms.changeset(%Terms{}, params)
    {:noreply, assign(socket, :form, to_form(changeset, action: :validate, as: :terms, id: "checkbox-form-terms"))}
  end

  def handle_event("save", %{"terms" => params}, socket) do
    case Terms.changeset(%Terms{}, params) do
      %Ecto.Changeset{valid?: true} = _ ->
        {:noreply, assign(socket, :form, to_form(Terms.changeset(%Terms{}, %{}), as: :terms, id: "checkbox-form-terms"))}
      changeset ->
        {:noreply, assign(socket, :form, to_form(changeset, action: :insert, as: :terms, id: "checkbox-form-terms"))}
    end
  end

  def render(assigns) do
    ~H"""
    <.form for={@form} id={@form.id} phx-change="validate" phx-submit="save">
      <.checkbox field={@form[:terms]} class="checkbox" controlled>
        <:label>Accept terms</:label>
        <:error :let={msg}>
          <.heroicon name="hero-exclamation-circle" class="icon" />
          {msg}
        </:error>
      </.checkbox>
      <button type="submit">Submit</button>
    </.form>
    """
  end
end

API Control

# Client-side
<button phx-click={Corex.Checkbox.set_checked("my-checkbox", true)}>
  Check
</button>

<button phx-click={Corex.Checkbox.toggle_checked("my-checkbox")}>
  Toggle
</button>

# Server-side
def handle_event("check", _, socket) do
  {:noreply, Corex.Checkbox.set_checked(socket, "my-checkbox", true)}
end

def handle_event("toggle", _, socket) do
  {:noreply, Corex.Checkbox.toggle_checked(socket, "my-checkbox")}
end

Styling

Use data attributes to target elements:

[data-scope="checkbox"][data-part="root"] {}
[data-scope="checkbox"][data-part="control"] {}
[data-scope="checkbox"][data-part="label"] {}
[data-scope="checkbox"][data-part="hidden-input"] {}
[data-scope="checkbox"][data-part="error"] {}

If you wish to use the default Corex styling, you can use the class checkbox on the component. This requires to install Mix.Tasks.Corex.Design first and import the component css file.

@import "../corex/main.css";
@import "../corex/tokens/themes/neo/light.css";
@import "../corex/components/checkbox.css";

You can then use modifiers

<.checkbox class="checkbox checkbox--accent checkbox--lg">

components/checkbox#modifiers)