Checkbox

Basic Usage

Simple checkbox with label and optional help text. Use the positional first argument for clean, Rails-like syntax.

<%# Recommended: Positional syntax %>
<%= rui_checkbox(:terms_accepted, label: "I accept the terms and conditions") %>

<%= rui_checkbox(:newsletter,
  label: "Subscribe to newsletter",
  help_text: "We'll send you weekly updates"
) %>

I accept the terms and conditions

Subscribe to newsletter

We'll send you weekly updates

New in v0.15.0: The positional syntax rui_checkbox(:name, ...) is now supported for cleaner standalone usage. Old keyword syntax object: :user, method: :terms still works for backward compatibility.

Colors

Supports all Tailwind colors via ColorBuilderHelper - semantic colors plus any Tailwind color.

Semantic Colors

<%= rui_checkbox(object: :demo, method: :opt1, label: "Primary", color: :primary, checked: true) %>
<%= rui_checkbox(object: :demo, method: :opt2, label: "Success", color: :success, checked: true) %>
<%= rui_checkbox(object: :demo, method: :opt3, label: "Warning", color: :warning, checked: true) %>
<%= rui_checkbox(object: :demo, method: :opt4, label: "Danger", color: :danger, checked: true) %>

Primary

Secondary

Success

Warning

Danger

Info

Tailwind Colors

Use any Tailwind color directly - indigo, pink, violet, teal, and more!

<%= rui_checkbox(object: :demo, method: :opt1, label: "Indigo", color: :indigo, checked: true) %>
<%= rui_checkbox(object: :demo, method: :opt2, label: "Pink", color: :pink, checked: true) %>
<%= rui_checkbox(object: :demo, method: :opt3, label: "Violet", color: :violet, checked: true) %>
<%= rui_checkbox(object: :demo, method: :opt4, label: "Teal", color: :teal, checked: true) %>

Indigo

Pink

Violet

Teal

Rose

Emerald

Amber

Cyan

Purple

Fuchsia

Lime

Orange

Tip: Colors are generated dynamically using ColorBuilderHelper. This ensures consistency across all components and supports any color from the Tailwind palette.

Sizes

Five size options from extra small to extra large.

<%= rui_checkbox(object: :demo, method: :xs, label: "Extra Small", size: :xs, checked: true) %>
<%= rui_checkbox(object: :demo, method: :sm, label: "Small", size: :sm, checked: true) %>
<%= rui_checkbox(object: :demo, method: :base, label: "Base (default)", size: :base, checked: true) %>
<%= rui_checkbox(object: :demo, method: :lg, label: "Large", size: :lg, checked: true) %>
<%= rui_checkbox(object: :demo, method: :xl, label: "Extra Large", size: :xl, checked: true) %>

Extra Small (xs)

Small (sm)

Base - default

Large (lg)

Extra Large (xl)

Shapes

Square or rounded corner styles for checkbox inputs.

<%= rui_checkbox(object: :demo, method: :rounded, label: "Rounded (default)", shape: :rounded) %>
<%= rui_checkbox(object: :demo, method: :square, label: "Square", shape: :square) %>

Rounded corners (default)

Square corners

Note: The shape option only applies to the checkbox variant. Switch variant is always fully rounded.

Switch Variant

Toggle switch style for on/off settings.

<%= rui_checkbox(
  object: :settings,
  method: :dark_mode,
  label: "Enable Dark Mode",
  variant: :switch,
  color: :primary
) %>

<%= rui_checkbox(
  object: :settings,
  method: :notifications,
  label: "Push Notifications",
  variant: :switch,
  color: :success,
  checked: true
) %>

Switch Sizes

Card Variant

Bordered cards with full-width click targets. Perfect for feature selection, pricing plans, or subscription preferences.

<%= rui_checkbox(
  object: :subscription,
  method: :newsletter,
  label: "Newsletter",
  description: "Get the latest updates and offers.",
  variant: :card,
  color: :primary,
  checked: true
) do |cb|
  cb.with_icon(:newspaper)
end %>

Subscription Preferences

Newsletter

Get the latest updates and offers.

Product updates

Learn about new features and products.

Event invitations

Invitations to exclusive events.

Simple Cards (Without Icons)

Basic

For individuals getting started

Pro

For growing teams

Enterprise

Custom solutions for large orgs

Card Sizes

Small Card

Compact size

Base Card (default)

Standard size

Large Card

More spacious

Pill Variant

Compact, tag-like selections. Perfect for filters, categories, or tags.

<div class="flex flex-wrap gap-2">
  <%= rui_checkbox(variant: :pill, label: "Ruby", color: :red, checked: true) %>
  <%= rui_checkbox(variant: :pill, label: "Rails", color: :rose) %>
  <%= rui_checkbox(variant: :pill, label: "JavaScript", color: :yellow) %>
  <%= rui_checkbox(variant: :pill, label: "TypeScript", color: :blue) %>
</div>

Ruby

Rails

JavaScript

TypeScript

CSS

HTML

Pill Sizes

XS

Small

Base

Large

Extra Large

Button Variant

Toolbar-style toggle controls. Perfect for feature toggles, formatting toolbars, or option selection.

<%= rui_checkbox(variant: :button, label: "Notifications", color: :zinc) do |cb|
  cb.with_icon(:bell)
end %>

Features

Notifications

Analytics

Backups

Text Formatting Toolbar

Bold

Italic

Underline

Strike

View Toggle Buttons

Grid

List

Table

Button Colors

Primary

Success

Danger

Indigo

Pink

Collections

Render multiple checkboxes from an array or ActiveRecord collection.

<%= rui_checkbox(
  object: @user,
  method: :category_ids,
  collection: Category.all,
  label: "Select Categories",
  help_text: "Choose one or more categories"
) %>

<%# With custom value/text methods %>
<%= rui_checkbox(
  object: @user,
  method: :role_ids,
  collection: Role.all,
  value_method: :id,
  text_method: :name,
  label: "Assign Roles"
) %>

Select Categories

Technology

Design

Business

Choose one or more categories

Horizontal Layout

<%= rui_checkbox(
  object: @user,
  method: :interests,
  collection: Interest.all,
  layout: :horizontal,
  label: "Select Interests"
) %>

Select Interests

Technology

Design

Business

Select All

Enable a "Select All" checkbox for collections with automatic indeterminate state.

<%= rui_checkbox(
  object: @user,
  method: :permission_ids,
  collection: Permission.all,
  select_all: true,
  label: "Assign Permissions"
) %>

Indeterminate State: When some (but not all) items are checked, the "Select All" checkbox shows an indeterminate state (a dash instead of checkmark).

Descriptions

Add descriptions to individual checkboxes or collection items.

<%# Single checkbox with description %>
<%= rui_checkbox(
  object: :user,
  method: :marketing,
  label: "Marketing Emails",
  description: "Receive promotional offers and product updates"
) %>

<%# Collection with description_method %>
<%= rui_checkbox(
  object: @user,
  method: :plan_id,
  collection: Plan.all,
  text_method: :name,
  description_method: :description,
  label: "Select Plan"
) %>

Marketing Emails

Receive promotional offers and product updates

Security Alerts

Get notified about account security events

States

Disabled and required states for checkboxes.

<%= rui_checkbox(object: :user, method: :locked, label: "Locked option", disabled: true) %>
<%= rui_checkbox(object: :user, method: :terms, label: "I agree to terms", required: true) %>

This option is disabled

I agree to terms*

Form Builder Integration

Use with Rails form builder for automatic object binding and validation.

<%= form_with model: @user do |f| %>
  <%= f.rui_checkbox(:terms_accepted, label: "I agree to the terms") %>
  <%= f.rui_checkbox(:newsletter, label: "Subscribe", color: :primary) %>
  <%= f.submit "Sign Up" %>
<% end %>

Note: When using f.rui_checkbox, the checked state is automatically detected from the form object.

Rails Integration

rui_checkbox provides a styled alternative to Rails ActionView checkbox helpers with additional features like variants, colors, and collections with select all.

Comparison with Rails Helpers

Here's how rui_checkbox compares to standard Rails helpers:

Rails Helper	rui_checkbox Equivalent
`f.check_box`	`f.rui_checkbox(:method)`
`check_box(:obj, :method)`	`rui_checkbox(object: :obj, method: :method)`
`check_box_tag(:name)`	`rui_checkbox(name: :name)`
`f.collection_check_boxes`	`f.rui_checkbox(:method, collection: items)`

Single Boolean Field

For boolean attributes on a model:

<%= f.rui_checkbox(:featured,
  label: "Featured Post",
  description: "Display prominently on homepage",
  color: :primary
) %>

Collection Checkboxes

For has_many associations or array selections:

<%= f.rui_checkbox(:category_ids,
  collection: Category.all,
  value_method: :id,
  text_method: :name,
  select_all: true,
  label: "Categories",
  color: :primary
) %>

Real-World Example: Post Form

See the checkbox component in action on the New Post and Posts pages.

<%= form_with model: @post do |f| %>
  <%= f.rui_checkbox(:featured,
    label: "Featured Post",
    description: "Display this post prominently",
    color: :primary
  ) %>

  <%= f.rui_checkbox(:notify_subscribers,
    label: "Notify Subscribers",
    variant: :switch,
    color: :success
  ) %>

  <%= f.rui_checkbox(:allow_comments,
    label: "Allow Comments",
    help_text: "Visitors can comment on this post",
    color: :info
  ) %>

  <%= f.rui_button(color: :success) %>
<% end %>

Pro Tip: rui_checkbox automatically generates the hidden field that Rails uses for unchecked checkboxes, ensuring proper form submission with boolean values.

Accessibility

The Checkbox component follows WAI-ARIA best practices for form controls.

ARIA Attributes

Help text linked via aria-describedby for context
Required fields include aria-required="true"
Error states include aria-invalid="true"
Checkbox groups use role="group" with aria-labelledby

Keyboard Navigation

Tab moves focus between checkboxes
Space toggles the checkbox state
Focus states are clearly visible with ring styles

Semantic HTML

Uses native <input type="checkbox"> elements
Labels use for attribute linked to input id
Indeterminate state properly communicates partial selection via indeterminate property

Screen Reader Support

Checkbox state is announced as "checked", "not checked", or "mixed" (indeterminate)
Error messages are announced when validation fails
Help text provides additional context when focused

JavaScript API

The Checkbox component provides two Stimulus controllers for interactive features.

Checkbox Controller (Select All)

Handles "Select All" functionality with indeterminate state support:

Action	Description
`checkbox#toggleAll`	Toggles all item checkboxes based on select-all state
`checkbox#updateSelectAll`	Updates select-all checkbox state (checked/indeterminate/unchecked)

Select All Pattern

<div data-controller="checkbox">
  <%# Select All checkbox %>
  <input type="checkbox"
         data-checkbox-target="selectAll"
         data-action="change->checkbox#toggleAll">
  <label>Select All</label>

  <%# Individual items %>
  <input type="checkbox"
         data-checkbox-target="item"
         data-action="change->checkbox#updateSelectAll">
  <input type="checkbox"
         data-checkbox-target="item"
         data-action="change->checkbox#updateSelectAll">
</div>

Checkbox Switch Controller

Handles the switch/toggle visual animation:

Action	Description
`checkbox-switch#updateThumbPosition`	Updates thumb position based on checked state

Programmatic Control

Control checkboxes from JavaScript:

Programmatic Control

// Get the checkbox controller (for select-all functionality)
const container = document.querySelector('[data-controller="checkbox"]')
const checkboxController = application.getControllerForElementAndIdentifier(
  container,
  "checkbox"
)

// Update select-all state after programmatic changes
checkboxController.updateSelectAllState()

// Toggle all items programmatically
const selectAll = container.querySelector('[data-checkbox-target="selectAll"]')
selectAll.checked = true
selectAll.dispatchEvent(new Event("change"))

API Reference

rui_checkbox

Versatile checkbox with 5 variants (checkbox, switch, card, pill, button), collections, and select all

Parameter	Type	Default	Description
name_or_method	Symbol/String	—	Positional first arg - name for standalone, method for form builder
label	String	—	Label text for single checkbox or legend for collection
description	String	—	Description text displayed below label
help_text	String	—	Help text displayed below checkbox/group

Appearance

Visual styling options

Parameter	Type	Default	Description
variant	Symbol	`:checkbox`	Visual variant style `:checkbox` `:switch` `:card` `:pill` `:button`
color	Symbol	`:primary`	Checked state color - semantic or any Tailwind color
size	Symbol	`:base`	Checkbox size `:xs` `:sm` `:base` `:lg` `:xl`
shape	Symbol	`:rounded`	Corner style (checkbox variant only) `:square` `:rounded`
layout	Symbol	`:vertical`	Layout for collections `:vertical` `:horizontal`

States

Checkbox state options

Parameter	Type	Default	Description
checked	Boolean	—	Explicit checked state (overrides object value)
disabled	Boolean	`false`	Disable the checkbox
required	Boolean	`false`	Show required indicator (*)

Values

Checked/unchecked value configuration

Parameter	Type	Default	Description
value	String	`"1"`	Value when checkbox is checked
unchecked_value	String	`"0"`	Value sent when unchecked (hidden field)

Collections

Options for rendering multiple checkboxes from a collection

Parameter	Type	Default	Description
collection	Array/ActiveRecord	—	Collection for multiple checkboxes
value_method	Symbol	`:id`	Method to get value from collection items
text_method	Symbol	`:name`	Method to get label text from collection items
description_method	Symbol	—	Method to get description from collection items
select_all	Boolean	`false`	Show 'Select All' checkbox with indeterminate state

Form Builder

Options when used with Rails form builder (f.rui_checkbox)

Parameter	Type	Default	Description
form	FormBuilder	—	Rails form builder instance (auto-set by f.rui_checkbox)
object	Object/Symbol	—	Object to bind checkbox to
method	Symbol	—	Attribute name on the object (keyword alternative to positional)
name	String	—	Input name attribute (keyword alternative to positional)

Slots

Content slots for customizing component parts

Slot	Description
icon	Icon slot for button/pill/card variants via checkbox.with_icon(:name)

Related Components

Radio Button

Single selection from a group of options

Select

Dropdown selection for longer lists

Input

Text inputs that pair well with checkboxes

Key Features

Basic Usage

Colors

Semantic Colors

Tailwind Colors

Sizes

Shapes

Switch Variant

Switch Sizes

Card Variant

Subscription Preferences

Simple Cards (Without Icons)

Card Sizes

Pill Variant

Pill Sizes

Button Variant

Features

Text Formatting Toolbar

View Toggle Buttons

Button Colors

Collections

Horizontal Layout

Select All

Descriptions

States

Form Builder Integration

Rails Integration

Comparison with Rails Helpers

Single Boolean Field

Collection Checkboxes

Real-World Example: Post Form

Accessibility

ARIA Attributes

Keyboard Navigation

Semantic HTML

Screen Reader Support

JavaScript API

Checkbox Controller (Select All)

Checkbox Switch Controller

Programmatic Control

API Reference

rui_checkbox

Appearance

States

Values

Collections

Form Builder

Slots

Related Components

Radio Button

Select

Input