Class: BetterUi::Forms::CheckboxGroupComponent

Inherits:
ApplicationComponent show all
Defined in:
app/components/better_ui/forms/checkbox_group_component.rb

Overview

A checkbox group component for selecting multiple options from a collection.

This component renders a group of checkboxes within a fieldset, allowing users to select multiple values. It supports both vertical and horizontal orientations, and integrates seamlessly with Rails form builders for array attribute submission.

Examples:

Basic checkbox group

<%= render BetterUi::Forms::CheckboxGroupComponent.new(
  name: "user[roles]",
  collection: ["Admin", "Editor", "Viewer"],
  legend: "User Roles"
) %>

With label/value pairs

<%= render BetterUi::Forms::CheckboxGroupComponent.new(
  name: "user[permissions]",
  collection: [["Read", "read"], ["Write", "write"], ["Delete", "delete"]],
  selected: ["read", "write"],
  legend: "Permissions"
) %>

Horizontal orientation

<%= render BetterUi::Forms::CheckboxGroupComponent.new(
  name: "options",
  collection: ["Option A", "Option B", "Option C"],
  orientation: :horizontal
) %>

With validation errors

<%= render BetterUi::Forms::CheckboxGroupComponent.new(
  name: "user[interests]",
  collection: ["Sports", "Music", "Art"],
  errors: ["Please select at least one interest"]
) %>

Using with Rails form builder

<%= form_with model: @user, builder: BetterUi::UiFormBuilder do |f| %>
  <%= f.bui_checkbox_group :roles, [["Admin", "admin"], ["Editor", "editor"]] %>
<% end %>

See Also:

Constant Summary collapse

SIZES =

Available size variants for checkbox groups. Each size adjusts checkbox dimensions and spacing proportionally.

Returns:

  • (Array<Symbol>) —

    the list of valid size options (:xs, :sm, :md, :lg, :xl)

%i[xs sm md lg xl].freeze
ORIENTATIONS =

Available orientation options for checkbox group layout.

Returns:

  • (Array<Symbol>) —

    the list of valid orientations (:vertical, :horizontal)

%i[vertical horizontal].freeze

Constants inherited from ApplicationComponent

ApplicationComponent::SHADOWS, ApplicationComponent::VARIANTS, ApplicationComponent::VARIANT_BODY_DIVIDE, ApplicationComponent::VARIANT_DIVIDE, ApplicationComponent::VARIANT_HEADER_BG, ApplicationComponent::VARIANT_HEADER_TEXT, ApplicationComponent::VARIANT_HIGHLIGHTED, ApplicationComponent::VARIANT_HOVERABLE, ApplicationComponent::VARIANT_RING, ApplicationComponent::VARIANT_SORT_ICON, ApplicationComponent::VARIANT_STRIPED

Instance Method Summary collapse

Constructor Details

#initialize(name:, collection: [], selected: [], legend: nil, hint: nil, variant: :primary, size: :md, orientation: :vertical, disabled: false, required: false, errors: nil, container_classes: nil, legend_classes: nil, items_classes: nil, hint_classes: nil, error_classes: nil, **options) ⇒ CheckboxGroupComponent

Initializes a new checkbox group component.

Parameters:

  • name (String) —

    the base name attribute for the checkboxes (required for form submission)

  • collection (Array) (defaults to: []) —

    the collection of options, can be:

    • Array of values (e.g., [“Admin”, “Editor”])

    • Array of [label, value] pairs (e.g., [[“Admin”, “admin”], [“Editor”, “editor”]])

  • selected (Array, String, nil) (defaults to: []) —

    the currently selected value(s)

  • legend (String, nil) (defaults to: nil) —

    the legend text for the fieldset

  • hint (String, nil) (defaults to: nil) —

    helpful hint text displayed below the checkboxes

  • variant (Symbol) (defaults to: :primary) —

    the color variant for all checkboxes (:primary, :secondary, etc.)

  • size (Symbol) (defaults to: :md) —

    the size variant (:xs, :sm, :md, :lg, :xl), defaults to :md

  • orientation (Symbol) (defaults to: :vertical) —

    the layout orientation (:vertical, :horizontal), defaults to :vertical

  • disabled (Boolean) (defaults to: false) —

    whether all checkboxes should be disabled, defaults to false

  • required (Boolean) (defaults to: false) —

    whether the field is required (shows asterisk indicator), defaults to false

  • errors (Array<String>, String, nil) (defaults to: nil) —

    validation error messages to display

  • container_classes (String, Array<String>, nil) (defaults to: nil) —

    additional CSS classes for the outer wrapper

  • legend_classes (String, Array<String>, nil) (defaults to: nil) —

    additional CSS classes for the legend element

  • items_classes (String, Array<String>, nil) (defaults to: nil) —

    additional CSS classes for the items container

  • hint_classes (String, Array<String>, nil) (defaults to: nil) —

    additional CSS classes for the hint text

  • error_classes (String, Array<String>, nil) (defaults to: nil) —

    additional CSS classes for error messages

  • options (Hash) —

    additional HTML attributes to pass through to the fieldset element

Raises:

  • (ArgumentError) —

    if variant, size, or orientation is invalid



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'app/components/better_ui/forms/checkbox_group_component.rb', line 82

def initialize(
  name:,
  collection: [],
  selected: [],
  legend: nil,
  hint: nil,
  variant: :primary,
  size: :md,
  orientation: :vertical,
  disabled: false,
  required: false,
  errors: nil,
  container_classes: nil,
  legend_classes: nil,
  items_classes: nil,
  hint_classes: nil,
  error_classes: nil,
  **options
)
  @name = name
  @collection = collection
  @selected = Array(selected).map(&:to_s)
  @legend = legend
  @hint = hint
  @variant = validate_variant(variant)
  @size = validate_size(size)
  @orientation = validate_orientation(orientation)
  @disabled = disabled
  @required = required
  @errors = Array(errors).compact.reject(&:blank?)
  @container_classes = container_classes
  @legend_classes = legend_classes
  @items_classes = items_classes
  @hint_classes = hint_classes
  @error_classes = error_classes
  @options = options
end