Class: BetterUi::Forms::CheckboxComponent

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

Overview

A checkbox input component with support for labels, hints, errors, and color variants.

This component provides a styled checkbox with customizable colors, sizes, and label positioning. Unlike text inputs, the label appears inline (left or right) with the checkbox rather than above.

Examples:

Basic checkbox

<%= render BetterUi::Forms::CheckboxComponent.new(
  name: "user[terms]",
  label: "I agree to the terms and conditions"
) %>

Checkbox with different variant

<%= render BetterUi::Forms::CheckboxComponent.new(
  name: "settings[notifications]",
  label: "Enable notifications",
  variant: :success,
  checked: true
) %>

Checkbox with label on left

<%= render BetterUi::Forms::CheckboxComponent.new(
  name: "user[active]",
  label: "Active",
  label_position: :left
) %>

With validation errors

<%= render BetterUi::Forms::CheckboxComponent.new(
  name: "user[terms]",
  label: "I agree to the terms",
  errors: ["You must agree to the terms"]
) %>

Using with Rails form builder

<%= form_with model: @user, builder: BetterUi::UiFormBuilder do |f| %>
  <%= f.bui_checkbox :newsletter, label: "Subscribe to newsletter" %>
<% end %>

See Also:

Constant Summary collapse

SIZES =

Available size variants for checkbox inputs. Each size adjusts the 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
LABEL_POSITIONS =

Available label positions relative to the checkbox.

Returns:

  • (Array<Symbol>) —

    the list of valid label positions (:left, :right)

%i[left right].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:, value: "1", checked: false, label: nil, hint: nil, variant: :primary, size: :md, label_position: :right, disabled: false, readonly: false, required: false, errors: nil, container_classes: nil, label_classes: nil, checkbox_classes: nil, hint_classes: nil, error_classes: nil, **options) ⇒ CheckboxComponent

Initializes a new checkbox component.

Parameters:

  • name (String) —

    the name attribute for the checkbox (required for form submission)

  • value (String) (defaults to: "1") —

    the value submitted when checkbox is checked (defaults to “1”)

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

    whether the checkbox is initially checked

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

    the label text displayed next to the checkbox

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

    helpful hint text displayed below the checkbox

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

    the color variant (:primary, :secondary, :accent, :success, :danger, :warning, :info, :light, :dark)

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

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

  • label_position (Symbol) (defaults to: :right) —

    where to position the label (:left, :right), defaults to :right

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

    whether the checkbox should be disabled (non-interactive), defaults to false

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

    whether the checkbox should be readonly (viewable but not editable), 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 below the checkbox

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

    additional CSS classes for the outer wrapper

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

    additional CSS classes for the label element

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

    additional CSS classes for the checkbox element

  • 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 checkbox element

Raises:

  • (ArgumentError) —

    if variant, size, or label_position is invalid



78
79
80
81
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
 
# File 'app/components/better_ui/forms/checkbox_component.rb', line 78

def initialize(
  name:,
  value: "1",
  checked: false,
  label: nil,
  hint: nil,
  variant: :primary,
  size: :md,
  label_position: :right,
  disabled: false,
  readonly: false,
  required: false,
  errors: nil,
  container_classes: nil,
  label_classes: nil,
  checkbox_classes: nil,
  hint_classes: nil,
  error_classes: nil,
  **options
)
  @name = name
  @value = value
  @checked = checked
  @label = label
  @hint = hint
  @variant = validate_variant(variant)
  @size = validate_size(size)
  @label_position = validate_label_position(label_position)
  @disabled = disabled
  @readonly = readonly
  @required = required
  @errors = Array(errors).compact.reject(&:blank?)
  @container_classes = container_classes
  @label_classes = label_classes
  @checkbox_classes = checkbox_classes
  @hint_classes = hint_classes
  @error_classes = error_classes
  @options = options
end