Checkbox - Hakumi Components

Basic

Basic usage of checkbox.

Checkbox

Code

<%= render HakumiComponents::Checkbox::Component.new(id: "basic-checkbox-example", label: "Checkbox") %>

Disabled

Disabled checkbox.

Checkbox (Disabled)

Checkbox (Checked & Disabled)

Code

<%= render HakumiComponents::Space::Component.new(direction: :vertical, size: :middle) do |space| %>
  <% space.with_item do %>
    <%= render HakumiComponents::Checkbox::Component.new(label: "Checkbox (Disabled)", disabled: true) %>
  <% end %>

  <% space.with_item do %>
    <%= render HakumiComponents::Checkbox::Component.new(label: "Checkbox (Checked & Disabled)", checked: true, disabled: true) %>
  <% end %>
<% end %>

Controlled Checkbox

Communicated with other components.

Controlled Checkbox

Code

<%= render HakumiComponents::Space::Component.new(direction: :vertical, size: :middle, id: "checkbox-controlled-demo") do |space| %>
  <% space.with_item do %>
    <%= render HakumiComponents::Space::Component.new(align: :center, size: :small) do |controls| %>
      <% controls.with_item do %>
        <%= render HakumiComponents::Typography::Text::Component.new(content: "Toggle the checkbox:") %>
      <% end %>
      <% controls.with_item do %>
        <%= render HakumiComponents::Button::Component.new(type: :primary, size: :small, id: "controlled-demo-btn") do %>
          Toggle
        <% end %>
      <% end %>
    <% end %>
  <% end %>

  <% space.with_item do %>
    <%= render HakumiComponents::Checkbox::Component.new(
          checked: true,
          label: "Controlled Checkbox",
          id: "controlled-demo-checkbox"
        ) %>
  <% end %>
<% end %>

<script>
  (() => {
    const root = document.getElementById("checkbox-controlled-demo")
    const button = root?.querySelector("#controlled-demo-btn")
    const input = root?.querySelector("#controlled-demo-checkbox")
    if (!root || !button || !input) return

    const wire = () => {
      if (root.dataset.checkboxControlledInitialized === "true") return true

      const wrapper = input.closest(".hakumi-checkbox-wrapper")
      const api = wrapper?.hakumiComponent?.api
      if (!wrapper || !api) return false

      root.dataset.checkboxControlledInitialized = "true"
      button.addEventListener("click", () => {
        api.setChecked(!api.isChecked())
      })
      return true
    }

    if (wire()) return

    const onRegister = () => {
      if (wire()) window.removeEventListener("hakumi-component:registered", onRegister)
    }

    window.addEventListener("hakumi-component:registered", onRegister)
  })()
</script>

Checkbox Group

Generate a group of checkboxes from an array.

Apple Pear Orange

Code

<%= render HakumiComponents::Space::Component.new(direction: :vertical, size: :middle, id: "checkbox-group-demo") do |space| %>
  <% space.with_item do %>
    <%= render HakumiComponents::Typography::Text::Component.new(content: "Groups keep each checkbox in sync with plain helpers.") %>
  <% end %>

  <% space.with_item do %>
    <%= render HakumiComponents::Checkbox::Group::Component.new(
          name: "group1",
          options: ["Apple", "Pear", "Orange"],
          value: ["Apple"]
        ) %>
  <% end %>

  <% space.with_item do %>
    <%= render HakumiComponents::Checkbox::Group::Component.new(
          name: "group2",
          options: [
            { label: "Apple", value: "Apple" },
            { label: "Pear", value: "Pear" },
            { label: "Orange", value: "Orange", disabled: true }
          ],
          value: ["Pear"]
        ) %>
  <% end %>
<% end %>

Check all

The indeterminate property can help you achieve a check all checkbox.

Check all

Apple Pear Orange

Code

<%= render HakumiComponents::Space::Component.new(direction: :vertical, size: :middle, id: "checkbox-check-all-demo") do |space| %>
  <% space.with_item do %>
    <%= render HakumiComponents::Typography::Text::Component.new(content: "Select fruits with a single toggle:") %>
  <% end %>

  <% space.with_item do %>
    <%= render HakumiComponents::Checkbox::Component.new(
          label: "Check all",
          indeterminate: true,
          id: "checkbox-check-all-toggle"
        ) %>
  <% end %>

  <% space.with_item do %>
    <%= render HakumiComponents::Checkbox::Group::Component.new(
          id: "checkbox-check-all-group",
          options: ["Apple", "Pear", "Orange"],
          value: ["Apple", "Orange"]
        ) %>
  <% end %>
<% end %>

<script>
  (() => {
    const group = document.getElementById("checkbox-check-all-group")
    const input = document.getElementById("checkbox-check-all-toggle")
    if (!group || !input) return

    const wrapper = input.closest(".hakumi-checkbox-wrapper")
    if (!wrapper) return

    const wire = () => {
      const groupApi = group.hakumiComponent?.api
      const wrapperApi = wrapper.hakumiComponent?.api
      if (!groupApi || !wrapperApi) return false

      const sync = () => {
        const selected = groupApi.getValue()
        const total = groupApi.getAllValues().length
        wrapperApi.setChecked(selected.length === total)
        wrapperApi.setIndeterminate(selected.length > 0 && selected.length < total)
      }

      input.addEventListener("change", () => {
        input.checked ? groupApi.selectAll() : groupApi.clearAll()
        sync()
      })

      groupApi.onChange(sync)
      sync()
      return true
    }

    if (wire()) return

    const onRegister = () => {
      if (wire()) window.removeEventListener("hakumi-component:registered", onRegister)
    }

    window.addEventListener("hakumi-component:registered", onRegister)
  })()
</script>

Use with Grid

Use Checkbox and Grid in Checkbox.Group to implement complex layouts.

Code

<%= render HakumiComponents::Checkbox::Group::Component.new(style: "width: 100%;") do %>
  <%= render HakumiComponents::Grid::Row::Component.new do %>
    <%= render HakumiComponents::Grid::Col::Component.new(span: 8) do %>
      <%= render HakumiComponents::Checkbox::Component.new(value: "A", label: "A") %>
    <% end %>
    <%= render HakumiComponents::Grid::Col::Component.new(span: 8) do %>
      <%= render HakumiComponents::Checkbox::Component.new(value: "B", label: "B") %>
    <% end %>
    <%= render HakumiComponents::Grid::Col::Component.new(span: 8) do %>
      <%= render HakumiComponents::Checkbox::Component.new(value: "C", label: "C") %>
    <% end %>
    <%= render HakumiComponents::Grid::Col::Component.new(span: 8) do %>
      <%= render HakumiComponents::Checkbox::Component.new(value: "D", label: "D") %>
    <% end %>
    <%= render HakumiComponents::Grid::Col::Component.new(span: 8) do %>
      <%= render HakumiComponents::Checkbox::Component.new(value: "E", label: "E") %>
    <% end %>
  <% end %>
<% end %>

Checkbox Props

Prop	Type	Default	Description
`checked`	`Boolean`	`false`	Initial checked state
`disabled`	`Boolean`	`false`	Disable the checkbox
`indeterminate`	`Boolean`	`false`	Indeterminate checked state (for select all scenarios)
`value`	`String`	`"1"`	Value submitted with form when checked
`name`	`String`	`nil`	Input name attribute
`id`	`String`	`auto-generated`	Input id attribute (auto-generated if not provided)
`auto_focus`	`Boolean`	`false`	Auto-focus on component mount
`label`	`String`	`nil`	Form field label text
`caption`	`String`	`nil`	Helper text displayed below checkbox
`standalone`	`Boolean`	`true`	Render without Form::Item wrapper
`required`	`Boolean`	`false`	Mark field as required
`errors`	`Array`	`[]`	Validation error messages

Checkbox Group Props

Props for checkbox groups

Prop	Type	Default	Description
`name`	`String`	`nil`	Name attribute for all checkboxes in the group
`value`	`Array`	`[]`	Currently selected values
`default_value`	`Array`	`[]`	Initial selected values
`options`	`Array`	`[]`	Checkbox options (strings or hashes with label, value, disabled keys)
`disabled`	`Boolean`	`false`	Disable all checkboxes in the group

Slots

Prop	Type	Default	Description
`content`	`Slot`	`nil`	Checkbox label content (overrides label prop)

HTML Options

Prop	Type	Default	Description
`**html_options`	`Keyword args`	`{}`	Additional HTML attributes merged into the wrapper element

JavaScript API

Access via element.hakumiComponent.api

Prop	Type	Default	Description
`setChecked(checked)`	`Method`	`-`	Programmatically check or uncheck the checkbox
`setIndeterminate(indeterminate)`	`Method`	`-`	Set the indeterminate visual state
`isChecked()`	`Method`	`-`	Get the current checked state
`isIndeterminate()`	`Method`	`-`	Get the current indeterminate state

Checkbox Group JavaScript API

Access via element.hakumiComponent.api on group element

Prop	Type	Default	Description
`getValue()`	`Method`	`-`	Get the currently selected values array
`getAllValues()`	`Method`	`-`	Get all available checkbox values in the group
`setValue(values)`	`Method`	`-`	Set the selected values
`selectAll()`	`Method`	`-`	Select all checkboxes in the group
`clearAll()`	`Method`	`-`	Deselect all checkboxes in the group