The Fluxbit::Form::CheckBoxComponent is a flexible form input component that extends Fluxbit::Form::FieldComponent. It provides checkbox and radio button inputs for forms with support for labels, helper text, validation states, and different visual styles. The component automatically handles the correct styling for both checkbox and radio types and works seamlessly with or without Rails form builders.

To start using the check box you can use the default way to call the component:

<%= render Fluxbit::Form::CheckBoxComponent.new(name: "accept_terms", label: "Accept the terms").with_content('') %>

<!-- or -->

<%= render Fluxbit::Form::CheckBoxComponent.new(name: "accept_terms", label: "Accept the terms") do %>
<% end %>

or you can use the alias (from the helpers):

<%= fx_check_box(name: "accept_terms", label: "Accept the terms") %>

<!-- or -->

<%= fx_check_box(name: "accept_terms", label: "Accept the terms") do %>
<% end %>

The result is:

Options

Param Default Description
name:   Field name (required unless using a form builder)
label:   Label text next to the input
value:   Value for the field (optional)
type: :check_box Input type (:check_box, :checkbox, :radio_button)
help_text:   Help or error text below the field
helper_popover:   Content for a popover helper
helper_popover_placement: :right Placement of the popover (:top, :right, :bottom, :left)
disabled: false Disables the input if true
checked: false Marks the input as checked if true
required: false Marks the field as required (adds “required” class to wrapper)
remove_class: ”” Classes to be removed from the default class list
wrapper_html: {} Additional HTML attributes for the wrapper div
**props   Additional HTML attributes for the input element

Slots

This component does not define any named slots. The checkbox content is determined by the form data and input state.

Examples

Basic checkbox

Radio buttons

Checkbox group

Checked states

Disabled checkboxes

Required vs optional fields

With helper text

With helper popover

Inline checkboxes

With form builder

Adding/Removing classes

Adding other properties

When to use

Use CheckBox for:

  • Binary choices: Yes/No, Accept/Decline, Enable/Disable options
  • Multiple selections: When users can select multiple items from a list
  • Radio buttons: When users need to select exactly one option from multiple choices
  • Terms acceptance: Privacy policies, terms of service, newsletter subscriptions
  • Feature toggles: Settings and preferences that can be turned on/off

Internationalization (I18n)

Labels, help texts, and helper popovers can be automatically loaded from translation files. The component will look for translations using Rails’ I18n system based on the form object and attribute names.

Translation Structure 

en:
  model_name:
    fields:
      attribute_name: "Custom Label"
    help_text:
      attribute_name: "Custom help text"
    helper_popover:
      attribute_name: "Custom popover content"

Usage Examples 

# Translation file (config/locales/en.yml)
en:
  user:
    fields:
      accept_terms: "I accept the terms and conditions"
      newsletter: "Subscribe to newsletter"
    help_text:
      accept_terms: "Required to create your account"
      newsletter: "Get updates about new features"
    helper_popover:
      accept_terms: "Please read our terms of service before accepting"

# In your form
<%= fx_check_box(form: form, attribute: :accept_terms) %>
# Automatically uses labels and help text from translations

# Override with custom values
<%= fx_check_box(form: form, attribute: :accept_terms, label: "Custom Label") %>

# Disable automatic labels/help text
<%= fx_check_box(form: form, attribute: :accept_terms, label: false, help_text: false) %>

Override Behavior

  • Custom value: Pass a string to override the translation
  • Disable: Pass false to disable automatic translation lookup
  • Default: Leave blank to use automatic translation lookup

Input Types

  • :check_box or :checkbox: Standard checkbox for binary or multiple selections
  • :radio_button: Radio button for single selection from multiple options

Accessibility

  • Labels use <label for="..."> and are properly associated with inputs
  • Pass disabled: true for ARIA compliance
  • Supports all standard ARIA attributes via props
  • Radio buttons should be grouped with the same name attribute
  • Checkboxes provide clear visual and programmatic state indication

Customization

You can customize the appearance and behavior of this component by passing different initialization parameters and adding custom styles. To do this you can create a initializer file like the:

# /config/initializers/change_check_box_component_defaults.rb

Fluxbit::Config::Form::CheckBoxComponent.type = :radio_button # the default is :check_box
Fluxbit::Config::Form::CheckBoxComponent.helper_popover_placement = :top # the default is :right
Fluxbit::Config::Form::CheckBoxComponent.styles[:base] = 'w-4 h-4 text-blue-600 rounded focus:ring-blue-500' # modify base styles
Fluxbit::Config::Form::CheckBoxComponent.styles[:checkbox] = 'border-gray-300 rounded' # modify checkbox-specific styles

Dependencies

Styles 

<%= html_escape(JSON.pretty_generate(Fluxbit::Config::Form::CheckBoxComponent.styles)) %>

References

Flowbite Checkbox