Corex.Checkbox (Corex v0.1.0-alpha.13)

View Source

Phoenix implementation of Zag.js Checkbox.

Examples

Minimal

<.checkbox id="my-checkbox">
  <:label>Accept terms</:label>
</.checkbox>

Custom Control

This example assumes the import of .icon from Core Components, you are free to replace it

<.checkbox class="checkbox">
  <:label>
    Accept the terms
  </:label>
  <:control>
    <.icon name="hero-check" class="data-checked" />
  </:control>
</.checkbox>

Custom Error

This example assumes the import of .icon from Core Components, you are free to replace it

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

Phoenix Form Integration

When using with Phoenix forms, you must add an id to the form using the Corex.Form.get_form_id/1 function.

Controller

<.form :let={f} for={@changeset} id={get_form_id(@changeset)}>
  <.checkbox field={f[:terms]} class="checkbox">
    <:label>I accept the terms</:label>
  </.checkbox>
  <button type="submit">Submit</button>
</.form>

Live View

When using Phoenix form in a Live view you must also add controlled mode. This allows the Live view to be the source of truth and the component to be in sync accordingly

<.form for={@form} id={get_form_id(@form)} phx-change="validate" phx-submit="save">
  <.checkbox field={@form[:terms_accepted]} controlled>
    <:label>I accept the terms and conditions</:label>
    <:error :let={msg}>{msg}</:error>
  </.checkbox>
</.form>

The field attribute automatically handles:

  • Setting the id from the form field
  • Setting the name for form submission
  • Mapping the form value to the checked state
  • Displaying validation errors
  • Integration with Phoenix changesets

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"] - Label wrapper
  • [data-scope="checkbox"][data-part="control"] - Checkbox control
  • [data-scope="checkbox"][data-part="label"] - Label text
  • [data-scope="checkbox"][data-part="input"] - Hidden input
  • [data-scope="checkbox"][data-part="error"] - Error message

State-specific styling:

  • [data-state="checked"] - When checkbox is checked
  • [data-state="unchecked"] - When checkbox is unchecked
  • [data-disabled] - When checkbox is disabled
  • [data-readonly] - When checkbox is read-only
  • [data-invalid] - When checkbox has validation errors

Summary

Components

checkbox(assigns)

Renders a checkbox component.

API

set_checked(checkbox_id, checked)

Sets the checkbox checked state from client-side. Returns a Phoenix.LiveView.JS command.

set_checked(socket, checkbox_id, checked)

Sets the checkbox checked state from server-side. Pushes a LiveView event.

toggle_checked(checkbox_id)

Toggles the checkbox checked state from client-side. Returns a Phoenix.LiveView.JS command.

toggle_checked(socket, checkbox_id)

Toggles the checkbox checked state from server-side. Pushes a LiveView event.

Components

checkbox(assigns)

Renders a checkbox component.

Attributes

  • id (:string) - The id of the checkbox, useful for API to identify the checkbox.
  • checked (:boolean) - The initial checked state or the controlled checked state. Defaults to false.
  • controlled (:boolean) - Whether the checkbox is controlled. Defaults to false.
  • name (:string) - The name of the checkbox input for form submission.
  • form (:string) - The form id to associate the checkbox with.
  • aria_label (:string) - The accessible label for the checkbox. Defaults to "Label".
  • disabled (:boolean) - Whether the checkbox is disabled. Defaults to false.
  • value (:string) - The value of the checkbox when checked. Defaults to "true".
  • dir (:string) - The direction of the checkbox. Defaults to "ltr". Must be one of "ltr", or "rtl".
  • read_only (:boolean) - Whether the checkbox is read-only. Defaults to false.
  • invalid (:boolean) - Whether the checkbox has validation errors. Defaults to false.
  • required (:boolean) - Whether the checkbox is required. Defaults to false.
  • on_checked_change (:string) - The server event name when the checked state changes. Defaults to nil.
  • on_checked_change_client (:string) - The client event name when the checked state changes. Defaults to nil.
  • errors (:list) - List of error messages to display. Defaults to [].
  • field (Phoenix.HTML.FormField) - A form field struct retrieved from the form, for example: @form[:email]. Automatically sets id, name, checked state, and errors from the form field.
  • Global attributes are accepted.

Slots

  • label - Accepts attributes:
    • class (:string)
  • control - Accepts attributes:
    • class (:string)
  • error - Accepts attributes:
    • class (:string)

API

set_checked(checkbox_id, checked)

Sets the checkbox checked state from client-side. Returns a Phoenix.LiveView.JS command.

Examples

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

<button phx-click={Corex.Checkbox.set_checked("my-checkbox", false)}>
  Uncheck
</button>

set_checked(socket, checkbox_id, checked)

Sets the checkbox checked state from server-side. Pushes a LiveView event.

Examples

def handle_event("check", _params, socket) do
  socket = Corex.Checkbox.set_checked(socket, "my-checkbox", true)
  {:noreply, socket}
end

toggle_checked(checkbox_id)

Toggles the checkbox checked state from client-side. Returns a Phoenix.LiveView.JS command.

Examples

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

toggle_checked(socket, checkbox_id)

Toggles the checkbox checked state from server-side. Pushes a LiveView event.

Examples

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