From 7fbbb7256682d08e48b3c8d24ad7c31c9f8cad98 Mon Sep 17 00:00:00 2001
From: andrew nimmo <andrnimm@fastmail.fm>
Date: Thu, 13 Nov 2025 18:54:00 -0800
Subject: [PATCH 01/11] Radio component

---
 Gemfile.lock                                  |   5 +
 README.md                                     |  23 ++
 lib/superform/rails/components/radio.rb       |  51 +++
 lib/superform/rails/field.rb                  |  17 +-
 spec/superform/rails/components/radio_spec.rb | 302 ++++++++++++++++++
 5 files changed, 396 insertions(+), 2 deletions(-)
 create mode 100644 lib/superform/rails/components/radio.rb
 create mode 100644 spec/superform/rails/components/radio_spec.rb

diff --git a/Gemfile.lock b/Gemfile.lock
index 92e3849..91ae8a7 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -92,6 +92,7 @@ GEM
     drb (2.2.1)
     erubi (1.13.1)
     ffi (1.17.1-arm64-darwin)
+    ffi (1.17.1-x86_64-darwin)
     ffi (1.17.1-x86_64-linux-gnu)
     formatador (1.1.0)
     globalid (1.2.1)
@@ -146,6 +147,8 @@ GEM
     nio4r (2.7.4)
     nokogiri (1.18.9-arm64-darwin)
       racc (~> 1.4)
+    nokogiri (1.18.9-x86_64-darwin)
+      racc (~> 1.4)
     nokogiri (1.18.9-x86_64-linux-gnu)
       racc (~> 1.4)
     notiffany (0.1.3)
@@ -233,6 +236,7 @@ GEM
     securerandom (0.3.1)
     shellany (0.0.1)
     sqlite3 (2.7.3-arm64-darwin)
+    sqlite3 (2.7.3-x86_64-darwin)
     sqlite3 (2.7.3-x86_64-linux-gnu)
     stringio (3.1.1)
     thor (1.3.2)
@@ -252,6 +256,7 @@ PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
   arm64-darwin-24
+  x86_64-darwin-21
   x86_64-linux
 
 DEPENDENCIES
diff --git a/README.md b/README.md
index 1e92542..f37c3c5 100644
--- a/README.md
+++ b/README.md
@@ -359,6 +359,29 @@ class SignupForm < Components::Form
       end
     end
 
+    # Radio buttons can be rendered individually or as a collection
+    div do
+      Field(:plan).label { "Choose your plan" }
+      # Radio collection with options - renders multiple radio buttons
+      Field(:plan).radio(
+        options: [
+          ["free", "Free Plan"],     # <input type="radio" value="free">Free Plan
+          ["pro", "Pro Plan"],       # <input type="radio" value="pro">Pro Plan
+          ["enterprise", "Enterprise"] # <input type="radio" value="enterprise">Enterprise
+        ]
+      )
+    end
+
+    # Or render individual radio buttons with custom markup
+    div do
+      Field(:gender).label { "Gender" }
+      Field(:gender).radio do |r|
+        div { r.button("m") { "Male" } }
+        div { r.button("f") { "Female" } }
+        div { r.button("o") { "Other" } }
+      end
+    end
+
     div do
       Field(:agreement).label { "Check this box if you agree to give us your first born child" }
       Field(:agreement).checkbox(checked: true)
diff --git a/lib/superform/rails/components/radio.rb b/lib/superform/rails/components/radio.rb
new file mode 100644
index 0000000..c0cd3a8
--- /dev/null
+++ b/lib/superform/rails/components/radio.rb
@@ -0,0 +1,51 @@
+module Superform
+  module Rails
+    module Components
+      class Radio < Field
+        def initialize(
+          *,
+          options: [],
+          **,
+          &
+        )
+          super(*, **, &)
+          @options = options
+        end
+
+        def view_template(&block)
+          if block_given?
+            yield self
+          else
+            buttons(*@options)
+          end
+        end
+
+        def buttons(*collection)
+          map_options(collection).each do |value, label|
+            button(value) { label }
+          end
+        end
+
+        def button(value, &block)
+          input(
+            **attributes,
+            type: :radio,
+            id: "#{dom.id}_#{value}",
+            value: value,
+            checked: field.value.to_s == value.to_s
+          )
+          plain(yield) if block_given?
+        end
+
+        protected
+          def map_options(collection)
+            OptionMapper.new(collection)
+          end
+
+          def field_attributes
+            { name: dom.name }
+          end
+      end
+    end
+  end
+end
diff --git a/lib/superform/rails/field.rb b/lib/superform/rails/field.rb
index f82325f..05961cb 100644
--- a/lib/superform/rails/field.rb
+++ b/lib/superform/rails/field.rb
@@ -137,8 +137,21 @@ def file(*, **, &)
         input(*, **, type: :file, &)
       end
 
-      def radio(value, *, **, &)
-        input(*, **, type: :radio, value: value, &)
+      def radio(*args, **attributes, &)
+        # If options keyword is provided, create a Radio component for collection
+        if attributes.key?(:options)
+          options = attributes.delete(:options)
+          Components::Radio.new(field, attributes:, options:, &)
+        # If first arg is an array or multiple args provided, treat as collection
+        elsif args.length > 1 || (args.length == 1 && args.first.is_a?(Array))
+          Components::Radio.new(field, attributes:, options: args, &)
+        # Single non-array arg is a radio button value (legacy API)
+        elsif args.length == 1
+          input(type: :radio, value: args.first, **attributes, &)
+        # No args at all - error
+        else
+          raise ArgumentError, "radio requires either a value or options"
+        end
       end
 
       # Rails compatibility aliases
diff --git a/spec/superform/rails/components/radio_spec.rb b/spec/superform/rails/components/radio_spec.rb
new file mode 100644
index 0000000..3eafdd0
--- /dev/null
+++ b/spec/superform/rails/components/radio_spec.rb
@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/BlockLength
+RSpec.describe Superform::Rails::Components::Radio, type: :view do
+  let(:object) { double('object', sushi: sushi_value) }
+  let(:sushi_value) { nil }
+  let(:field) do
+    Superform::Rails::Field.new(:sushi, parent: nil, object: object)
+  end
+  let(:options) do
+    [
+      ['shirako', 'Shirako'],
+      ['ankimo', 'Ankimo'],
+      ['tsubugai', 'Tsubugai']
+    ]
+  end
+  let(:component) do
+    described_class.new(field, attributes: attributes, options: options)
+  end
+  let(:attributes) { {} }
+
+  describe 'basic radio collection' do
+    subject { render(component) }
+
+    it 'renders multiple radio inputs' do
+      expect(subject.scan(/<input[^>]*type="radio"/).count).to eq(3)
+    end
+
+    it 'renders radio inputs with correct values' do
+      expect(subject).to include('value="shirako"')
+      expect(subject).to include('value="ankimo"')
+      expect(subject).to include('value="tsubugai"')
+    end
+
+    it 'renders unique IDs for each radio button' do
+      expect(subject).to include('id="sushi_shirako"')
+      expect(subject).to include('id="sushi_ankimo"')
+      expect(subject).to include('id="sushi_tsubugai"')
+    end
+
+    it 'uses the same name for all radio buttons' do
+      expect(subject.scan(/name="sushi"/).count).to eq(3)
+    end
+
+    it 'does not check any radio by default' do
+      expect(subject).not_to include('checked')
+    end
+
+    it 'renders complete HTML structure' do
+      expect(subject).to eq(
+        '<input name="sushi" type="radio" id="sushi_shirako" value="shirako">Shirako' \
+        '<input name="sushi" type="radio" id="sushi_ankimo" value="ankimo">Ankimo' \
+        '<input name="sushi" type="radio" id="sushi_tsubugai" value="tsubugai">Tsubugai'
+      )
+    end
+  end
+
+  describe 'with selected value' do
+    let(:sushi_value) { 'ankimo' }
+
+    subject { render(component) }
+
+    it 'checks the matching radio button' do
+      expect(subject).to match(
+        /<input[^>]*id="sushi_ankimo"[^>]*checked[^>]*>/
+      )
+    end
+
+    it 'does not check other radio buttons' do
+      expect(subject).not_to match(
+        /<input[^>]*id="sushi_shirako"[^>]*checked[^>]*>/
+      )
+      expect(subject).not_to match(
+        /<input[^>]*id="sushi_tsubugai"[^>]*checked[^>]*>/
+      )
+    end
+
+    it 'renders complete HTML structure with checked state' do
+      expect(subject).to eq(
+        '<input name="sushi" type="radio" id="sushi_shirako" value="shirako">Shirako' \
+        '<input name="sushi" type="radio" id="sushi_ankimo" value="ankimo" checked>Ankimo' \
+        '<input name="sushi" type="radio" id="sushi_tsubugai" value="tsubugai">Tsubugai'
+      )
+    end
+  end
+
+  describe 'with numeric value' do
+    let(:object) { double('object', role_id: role_id_value) }
+    let(:role_id_value) { 2 }
+    let(:field) do
+      Superform::Rails::Field.new(:role_id, parent: nil, object: object)
+    end
+    let(:options) { [[1, 'Admin'], [2, 'Editor'], [3, 'Viewer']] }
+
+    subject { render(component) }
+
+    it 'checks the matching radio button with numeric comparison' do
+      expect(subject).to match(
+        /<input[^>]*id="role_id_2"[^>]*checked[^>]*>/
+      )
+    end
+  end
+
+  describe 'using field helper method' do
+    let(:form_field) do
+      Superform::Rails::Field.new(:sushi, parent: nil, object: object)
+    end
+
+    context 'with positional arguments' do
+      subject do
+        render(
+          form_field.radio(
+            ['shirako', 'Shirako'],
+            ['ankimo', 'Ankimo'],
+            ['tsubugai', 'Tsubugai']
+          )
+        )
+      end
+
+      it 'renders radio buttons from positional args' do
+        expect(subject).to include('value="shirako"')
+        expect(subject).to include('value="ankimo"')
+        expect(subject).to include('value="tsubugai"')
+      end
+    end
+
+    context 'with options keyword argument' do
+      subject do
+        render(
+          form_field.radio(
+            options: [
+              ['shirako', 'Shirako'],
+              ['ankimo', 'Ankimo'],
+              ['tsubugai', 'Tsubugai']
+            ]
+          )
+        )
+      end
+
+      it 'renders radio buttons from options kwarg' do
+        expect(subject).to include('value="shirako"')
+        expect(subject).to include('value="ankimo"')
+        expect(subject).to include('value="tsubugai"')
+      end
+    end
+
+    context 'with single value (legacy API)' do
+      subject do
+        render(form_field.radio('shirako', id: 'custom_id'))
+      end
+
+      it 'renders a single radio input' do
+        expect(subject).to include('type="radio"')
+        expect(subject).to include('value="shirako"')
+        expect(subject).to include('id="custom_id"')
+      end
+
+      it 'renders only one radio button' do
+        expect(subject.scan(/<input/).count).to eq(1)
+      end
+    end
+  end
+
+  describe 'with custom attributes' do
+    let(:attributes) { { class: 'custom-radio', data: { controller: 'radio' } } }
+
+    subject { render(component) }
+
+    it 'applies custom attributes to all radio buttons' do
+      expect(subject).to include('class="custom-radio"')
+      expect(subject).to include('data-controller="radio"')
+      expect(subject.scan(/class="custom-radio"/).count).to eq(3)
+    end
+  end
+
+  describe 'with block for custom rendering' do
+    subject do
+      render(component) do |radio|
+        radio.button('shirako') { 'Shirako' }
+        radio.button('ankimo') { 'Ankimo' }
+      end
+    end
+
+    it 'renders custom radio buttons via block' do
+      expect(subject).to include('value="shirako"')
+      expect(subject).to include('value="ankimo"')
+    end
+
+    it 'does not render options from constructor' do
+      expect(subject).not_to include('value="tsubugai"')
+    end
+  end
+
+  describe '#button method' do
+    let(:component) do
+      described_class.new(field, attributes: {}, options: [])
+    end
+
+    context 'with simple value and label' do
+      subject do
+        render(component) do |radio|
+          radio.button('omakase') { 'Chef\'s Choice' }
+        end
+      end
+
+      it 'renders radio button with value and label' do
+        expect(subject).to include('value="omakase"')
+        expect(subject).to include('>Chef&#39;s Choice')
+      end
+
+      it 'generates ID from field name and value' do
+        expect(subject).to include('id="sushi_omakase"')
+      end
+    end
+  end
+
+  describe 'inside a collection (with parent field)' do
+    let(:orders_field) do
+      orders_object = double('orders', orders: [{}, {}])
+      Superform::Rails::Field.new(
+        :orders,
+        parent: nil,
+        object: orders_object,
+        value: [{}, {}]
+      )
+    end
+    let(:order_collection) { orders_field.collection }
+    let(:order_field) { order_collection.field }
+    let(:sushi_field) do
+      sushi_object = double('order', sushi: nil)
+      Superform::Rails::Field.new(:sushi, parent: order_field, object: sushi_object)
+    end
+    let(:component) do
+      described_class.new(
+        sushi_field,
+        attributes: attributes,
+        options: options
+      )
+    end
+
+    subject { render(component) }
+
+    it 'uses collection notation for field name' do
+      # When parent is a Field (from collection), it should use orders[][]
+      # First [] is the collection index, second [] is the field
+      expect(subject).to include('name="orders[][]"')
+    end
+
+    it 'does not include the sushi key in the name' do
+      # The sushi key is excluded when parent is a Field
+      expect(subject).not_to include('name="orders[][][sushi]"')
+    end
+
+    it 'generates unique IDs including collection index' do
+      expect(subject).to include('id="orders_1_sushi_shirako"')
+      expect(subject).to include('id="orders_1_sushi_ankimo"')
+      expect(subject).to include('id="orders_1_sushi_tsubugai"')
+    end
+
+    it 'renders all radio buttons correctly' do
+      expect(subject.scan(/<input[^>]*type="radio"/).count).to eq(3)
+      expect(subject).to include('value="shirako"')
+      expect(subject).to include('value="ankimo"')
+      expect(subject).to include('value="tsubugai"')
+    end
+  end
+
+  describe 'with ActiveRecord::Relation' do
+    before do
+      User.create!(first_name: 'Alice', email: 'alice@example.com')
+      User.create!(first_name: 'Bob', email: 'bob@example.com')
+    end
+
+    after do
+      User.delete_all
+    end
+
+    let(:object) { double('object', author_id: author_id_value) }
+    let(:author_id_value) { nil }
+    let(:field) do
+      Superform::Rails::Field.new(:author_id, parent: nil, object: object)
+    end
+    let(:users_relation) { User.select(:id, :first_name) }
+    let(:component) do
+      described_class.new(field, attributes: attributes, options: [users_relation])
+    end
+
+    subject { render(component) }
+
+    it 'renders radio buttons from ActiveRecord relation' do
+      # OptionMapper extracts id as value and joins other attributes as label
+      expect(subject).to match(/<input[^>]*value="\d+"[^>]*>Alice/)
+      expect(subject).to match(/<input[^>]*value="\d+"[^>]*>Bob/)
+    end
+
+    it 'generates IDs from field name and record ID' do
+      alice = User.find_by(first_name: 'Alice')
+      expect(subject).to include("id=\"author_id_#{alice.id}\"")
+    end
+  end
+end
+# rubocop:enable Metrics/BlockLength

From 14082d45da7a36a59155a0bf656c4a9bcd55c3cf Mon Sep 17 00:00:00 2001
From: andrew nimmo <andrnimm@fastmail.fm>
Date: Thu, 13 Nov 2025 19:55:08 -0800
Subject: [PATCH 02/11] Fix radio field naming and value handling

---
 README.md                                     |   4 +-
 lib/superform/rails/components/radio.rb       |  15 ++-
 .../radio_collection_integration_spec.rb      | 122 ++++++++++++++++++
 spec/superform/rails/components/radio_spec.rb |   2 +-
 4 files changed, 135 insertions(+), 8 deletions(-)
 create mode 100644 spec/superform/rails/components/radio_collection_integration_spec.rb

diff --git a/README.md b/README.md
index f37c3c5..e092015 100644
--- a/README.md
+++ b/README.md
@@ -359,10 +359,10 @@ class SignupForm < Components::Form
       end
     end
 
-    # Radio buttons can be rendered individually or as a collection
+    # Radio buttons can be rendered individually or as a group
     div do
       Field(:plan).label { "Choose your plan" }
-      # Radio collection with options - renders multiple radio buttons
+      # Radio group with options - renders multiple radio buttons
       Field(:plan).radio(
         options: [
           ["free", "Free Plan"],     # <input type="radio" value="free">Free Plan
diff --git a/lib/superform/rails/components/radio.rb b/lib/superform/rails/components/radio.rb
index c0cd3a8..1c003e0 100644
--- a/lib/superform/rails/components/radio.rb
+++ b/lib/superform/rails/components/radio.rb
@@ -20,8 +20,8 @@ def view_template(&block)
           end
         end
 
-        def buttons(*collection)
-          map_options(collection).each do |value, label|
+        def buttons(*option_list)
+          map_options(option_list).each do |value, label|
             button(value) { label }
           end
         end
@@ -32,14 +32,19 @@ def button(value, &block)
             type: :radio,
             id: "#{dom.id}_#{value}",
             value: value,
-            checked: field.value.to_s == value.to_s
+            checked: checked?(value)
           )
           plain(yield) if block_given?
         end
 
         protected
-          def map_options(collection)
-            OptionMapper.new(collection)
+          def map_options(option_list)
+            OptionMapper.new(option_list)
+          end
+
+          def checked?(value)
+            # Radio buttons are single-select, so field.value should never be an array
+            field.value.to_s == value.to_s
           end
 
           def field_attributes
diff --git a/spec/superform/rails/components/radio_collection_integration_spec.rb b/spec/superform/rails/components/radio_collection_integration_spec.rb
new file mode 100644
index 0000000..5b13a3c
--- /dev/null
+++ b/spec/superform/rails/components/radio_collection_integration_spec.rb
@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+RSpec.describe "Radio in Collection Integration", type: :view do
+  # Set up test database for collection models
+  before(:all) do
+    ActiveRecord::Schema.define do
+      create_table :orders, force: true do |t|
+        t.string :sushi
+      end
+    end unless ActiveRecord::Base.connection.table_exists?(:orders)
+  end
+
+  after(:all) do
+    ActiveRecord::Schema.define do
+      drop_table :orders if ActiveRecord::Base.connection.table_exists?(:orders)
+    end
+  end
+
+  # Test model for collection (array of objects)
+  class Order < ActiveRecord::Base
+  end
+
+  # Note: Field collections (arrays of primitives) don't make sense for radio buttons
+  # since radios are for single-select, not multiple array elements.
+  # For multi-select from primitives, use checkboxes instead.
+
+  describe "collection (array of objects)" do
+    let(:initial_orders) do
+      [
+        Order.new(sushi: "shirako"),
+        Order.new(sushi: "ankimo")
+      ]
+    end
+    let(:model) do
+      # Simulates a model with has_many association
+      # Using User with a mock orders association
+      orders_list = initial_orders # capture for closure
+      User.new(first_name: "Test", email: "test@example.com").tap do |user|
+        user.define_singleton_method(:orders) { @orders ||= orders_list }
+        user.define_singleton_method(:orders=) { |val| @orders = val }
+      end
+    end
+    let(:form) { Superform::Rails::Form.new(model, action: "/users") }
+
+    it "renders radio buttons with collection notation" do
+      html = render(form) do |f|
+        orders_collection = f.collection(:orders)
+        orders_collection.each do |order_namespace|
+          f.render order_namespace.field(:sushi).radio(
+            options: [
+              ["shirako", "Shirako"],
+              ["ankimo", "Ankimo"],
+              ["tsubugai", "Tsubugai"]
+            ]
+          )
+        end
+      end
+
+      # Collection uses model_name[collection_name][index][field_name] notation
+      # Rails will parse { "0" => {}, "1" => {} } into an array
+      expect(html).to include('name="user[orders][0][sushi]"')
+      expect(html).to include('name="user[orders][1][sushi]"')
+      expect(html.scan(/type="radio"/).count).to eq(6) # 3 radios × 2 orders
+    end
+
+    it "pre-selects radio buttons based on collection values" do
+      html = render(form) do |f|
+        orders_collection = f.collection(:orders)
+        orders_collection.each do |order_namespace|
+          f.render order_namespace.field(:sushi).radio(
+            options: [
+              ["shirako", "Shirako"],
+              ["ankimo", "Ankimo"],
+              ["tsubugai", "Tsubugai"]
+            ]
+          )
+        end
+      end
+
+      # Should have exactly 2 checked radios (one per order)
+      expect(html.scan(/checked/).count).to eq(2)
+      # "shirako" should be checked (first order)
+      expect(html).to match(/<input[^>]*id="user_orders_0_sushi_shirako"[^>]*checked/)
+      # "ankimo" should be checked (second order)
+      expect(html).to match(/<input[^>]*id="user_orders_1_sushi_ankimo"[^>]*checked/)
+    end
+
+    it "works with submitted params from collection" do
+      # Simulate Rails params after form submission
+      # Collection radios submit as: { "user" => { "orders" => [{ "sushi" => "tsubugai" }, { "sushi" => "shirako" }] } }
+      submitted_model = User.new(first_name: "Test", email: "test@example.com").tap do |user|
+        user.define_singleton_method(:orders) do
+          [
+            Order.new(sushi: "tsubugai"),
+            Order.new(sushi: "shirako")
+          ]
+        end
+      end
+      submitted_form = Superform::Rails::Form.new(submitted_model, action: "/users")
+
+      html = render(submitted_form) do |f|
+        orders_collection = f.collection(:orders)
+        orders_collection.each do |order_namespace|
+          f.render order_namespace.field(:sushi).radio(
+            options: [
+              ["shirako", "Shirako"],
+              ["ankimo", "Ankimo"],
+              ["tsubugai", "Tsubugai"]
+            ]
+          )
+        end
+      end
+
+      # Should have exactly 2 checked radios
+      expect(html.scan(/checked/).count).to eq(2)
+      # First order should now have "tsubugai" checked
+      expect(html).to match(/<input[^>]*id="user_orders_0_sushi_tsubugai"[^>]*checked/)
+      # Second order should now have "shirako" checked
+      expect(html).to match(/<input[^>]*id="user_orders_1_sushi_shirako"[^>]*checked/)
+    end
+  end
+end
diff --git a/spec/superform/rails/components/radio_spec.rb b/spec/superform/rails/components/radio_spec.rb
index 3eafdd0..b86ff20 100644
--- a/spec/superform/rails/components/radio_spec.rb
+++ b/spec/superform/rails/components/radio_spec.rb
@@ -19,7 +19,7 @@
   end
   let(:attributes) { {} }
 
-  describe 'basic radio collection' do
+  describe 'radio group with options' do
     subject { render(component) }
 
     it 'renders multiple radio inputs' do

From ccbe08aeba9e2dca2f94da66892834c35cfca226 Mon Sep 17 00:00:00 2001
From: andrew nimmo <andrnimm@fastmail.fm>
Date: Tue, 18 Nov 2025 15:57:26 -0800
Subject: [PATCH 03/11] Fix output, add AR collection support

---
 lib/superform/rails/components/radio.rb       | 18 +++--
 lib/superform/rails/field.rb                  | 20 +++--
 .../radio_collection_integration_spec.rb      | 24 +++---
 spec/superform/rails/components/radio_spec.rb | 73 ++++++++++++-------
 .../rails/field_convenience_methods_spec.rb   | 12 ++-
 5 files changed, 81 insertions(+), 66 deletions(-)

diff --git a/lib/superform/rails/components/radio.rb b/lib/superform/rails/components/radio.rb
index 1c003e0..f652a25 100644
--- a/lib/superform/rails/components/radio.rb
+++ b/lib/superform/rails/components/radio.rb
@@ -27,14 +27,16 @@ def buttons(*option_list)
         end
 
         def button(value, &block)
-          input(
-            **attributes,
-            type: :radio,
-            id: "#{dom.id}_#{value}",
-            value: value,
-            checked: checked?(value)
-          )
-          plain(yield) if block_given?
+          label do
+            input(
+              **attributes,
+              type: :radio,
+              id: "#{dom.id}_#{value}",
+              value: value.to_s,
+              checked: checked?(value)
+            )
+            plain(yield) if block_given?
+          end
         end
 
         protected
diff --git a/lib/superform/rails/field.rb b/lib/superform/rails/field.rb
index 05961cb..bf3f3fc 100644
--- a/lib/superform/rails/field.rb
+++ b/lib/superform/rails/field.rb
@@ -138,19 +138,17 @@ def file(*, **, &)
       end
 
       def radio(*args, **attributes, &)
-        # If options keyword is provided, create a Radio component for collection
-        if attributes.key?(:options)
-          options = attributes.delete(:options)
-          Components::Radio.new(field, attributes:, options:, &)
-        # If first arg is an array or multiple args provided, treat as collection
-        elsif args.length > 1 || (args.length == 1 && args.first.is_a?(Array))
+        # If multiple args or first arg is an array, treat as collection
+        if args.length > 1 || (args.length == 1 && args.first.is_a?(Array))
           Components::Radio.new(field, attributes:, options: args, &)
-        # Single non-array arg is a radio button value (legacy API)
-        elsif args.length == 1
-          input(type: :radio, value: args.first, **attributes, &)
-        # No args at all - error
+        # If single arg is an ActiveRecord::Relation, treat as collection
+        elsif args.length == 1 && defined?(ActiveRecord::Relation) &&
+              args.first.is_a?(ActiveRecord::Relation)
+          Components::Radio.new(field, attributes:, options: args, &)
+        # No args or single non-collection arg - error
         else
-          raise ArgumentError, "radio requires either a value or options"
+          raise ArgumentError,
+                "radio requires multiple options (e.g., radio(['a', 'A'], ['b', 'B']))"
         end
       end
 
diff --git a/spec/superform/rails/components/radio_collection_integration_spec.rb b/spec/superform/rails/components/radio_collection_integration_spec.rb
index 5b13a3c..f4b9a71 100644
--- a/spec/superform/rails/components/radio_collection_integration_spec.rb
+++ b/spec/superform/rails/components/radio_collection_integration_spec.rb
@@ -47,11 +47,9 @@ class Order < ActiveRecord::Base
         orders_collection = f.collection(:orders)
         orders_collection.each do |order_namespace|
           f.render order_namespace.field(:sushi).radio(
-            options: [
-              ["shirako", "Shirako"],
-              ["ankimo", "Ankimo"],
-              ["tsubugai", "Tsubugai"]
-            ]
+            ["shirako", "Shirako"],
+            ["ankimo", "Ankimo"],
+            ["tsubugai", "Tsubugai"]
           )
         end
       end
@@ -68,11 +66,9 @@ class Order < ActiveRecord::Base
         orders_collection = f.collection(:orders)
         orders_collection.each do |order_namespace|
           f.render order_namespace.field(:sushi).radio(
-            options: [
-              ["shirako", "Shirako"],
-              ["ankimo", "Ankimo"],
-              ["tsubugai", "Tsubugai"]
-            ]
+            ["shirako", "Shirako"],
+            ["ankimo", "Ankimo"],
+            ["tsubugai", "Tsubugai"]
           )
         end
       end
@@ -102,11 +98,9 @@ class Order < ActiveRecord::Base
         orders_collection = f.collection(:orders)
         orders_collection.each do |order_namespace|
           f.render order_namespace.field(:sushi).radio(
-            options: [
-              ["shirako", "Shirako"],
-              ["ankimo", "Ankimo"],
-              ["tsubugai", "Tsubugai"]
-            ]
+            ["shirako", "Shirako"],
+            ["ankimo", "Ankimo"],
+            ["tsubugai", "Tsubugai"]
           )
         end
       end
diff --git a/spec/superform/rails/components/radio_spec.rb b/spec/superform/rails/components/radio_spec.rb
index b86ff20..eb00c6d 100644
--- a/spec/superform/rails/components/radio_spec.rb
+++ b/spec/superform/rails/components/radio_spec.rb
@@ -48,9 +48,9 @@
 
     it 'renders complete HTML structure' do
       expect(subject).to eq(
-        '<input name="sushi" type="radio" id="sushi_shirako" value="shirako">Shirako' \
-        '<input name="sushi" type="radio" id="sushi_ankimo" value="ankimo">Ankimo' \
-        '<input name="sushi" type="radio" id="sushi_tsubugai" value="tsubugai">Tsubugai'
+        '<label><input name="sushi" type="radio" id="sushi_shirako" value="shirako">Shirako</label>' \
+        '<label><input name="sushi" type="radio" id="sushi_ankimo" value="ankimo">Ankimo</label>' \
+        '<label><input name="sushi" type="radio" id="sushi_tsubugai" value="tsubugai">Tsubugai</label>'
       )
     end
   end
@@ -77,9 +77,9 @@
 
     it 'renders complete HTML structure with checked state' do
       expect(subject).to eq(
-        '<input name="sushi" type="radio" id="sushi_shirako" value="shirako">Shirako' \
-        '<input name="sushi" type="radio" id="sushi_ankimo" value="ankimo" checked>Ankimo' \
-        '<input name="sushi" type="radio" id="sushi_tsubugai" value="tsubugai">Tsubugai'
+        '<label><input name="sushi" type="radio" id="sushi_shirako" value="shirako">Shirako</label>' \
+        '<label><input name="sushi" type="radio" id="sushi_ankimo" value="ankimo" checked>Ankimo</label>' \
+        '<label><input name="sushi" type="radio" id="sushi_tsubugai" value="tsubugai">Tsubugai</label>'
       )
     end
   end
@@ -124,39 +124,35 @@
       end
     end
 
-    context 'with options keyword argument' do
+    context 'with mixed format positional arguments' do
+      let(:object) { double('object', contact: nil) }
+      let(:form_field) do
+        Superform::Rails::Field.new(:contact, parent: nil, object: object)
+      end
+
       subject do
         render(
           form_field.radio(
-            options: [
-              ['shirako', 'Shirako'],
-              ['ankimo', 'Ankimo'],
-              ['tsubugai', 'Tsubugai']
-            ]
+            [true, 'Yes'],
+            [false, 'No'],
+            'Hell no'
           )
         )
       end
 
-      it 'renders radio buttons from options kwarg' do
-        expect(subject).to include('value="shirako"')
-        expect(subject).to include('value="ankimo"')
-        expect(subject).to include('value="tsubugai"')
-      end
-    end
-
-    context 'with single value (legacy API)' do
-      subject do
-        render(form_field.radio('shirako', id: 'custom_id'))
+      it 'renders radio buttons with array pairs using first as value' do
+        expect(subject).to include('value="true"')
+        expect(subject).to include('value="false"')
       end
 
-      it 'renders a single radio input' do
-        expect(subject).to include('type="radio"')
-        expect(subject).to include('value="shirako"')
-        expect(subject).to include('id="custom_id"')
+      it 'renders radio buttons with array pairs using second as label' do
+        expect(subject).to include('>Yes')
+        expect(subject).to include('>No')
       end
 
-      it 'renders only one radio button' do
-        expect(subject.scan(/<input/).count).to eq(1)
+      it 'renders radio button with single value for both value and label' do
+        expect(subject).to include('value="Hell no"')
+        expect(subject).to include('>Hell no')
       end
     end
   end
@@ -297,6 +293,27 @@
       alice = User.find_by(first_name: 'Alice')
       expect(subject).to include("id=\"author_id_#{alice.id}\"")
     end
+
+    context 'passed directly via field helper' do
+      let(:form_field) do
+        Superform::Rails::Field.new(:author_id, parent: nil, object: object)
+      end
+
+      subject do
+        # Pass relation directly without wrapping in array
+        render(form_field.radio(users_relation))
+      end
+
+      it 'renders radio buttons from ActiveRecord relation' do
+        expect(subject).to match(/<input[^>]*value="\d+"[^>]*>Alice/)
+        expect(subject).to match(/<input[^>]*value="\d+"[^>]*>Bob/)
+      end
+
+      it 'generates proper HTML structure with labels' do
+        expect(subject).to include('<label>')
+        expect(subject.scan(/<label>/).count).to eq(2)
+      end
+    end
   end
 end
 # rubocop:enable Metrics/BlockLength
diff --git a/spec/superform/rails/field_convenience_methods_spec.rb b/spec/superform/rails/field_convenience_methods_spec.rb
index c3d9196..42780dc 100644
--- a/spec/superform/rails/field_convenience_methods_spec.rb
+++ b/spec/superform/rails/field_convenience_methods_spec.rb
@@ -25,7 +25,10 @@
     it { expect(field.color.type).to eq("color") }
     it { expect(field.search.type).to eq("search") }
     it { expect(field.file.type).to eq("file") }
-    it { expect(field.radio("male").type).to eq("radio") }
+    it do
+      component = field.radio(['male', 'Male'], ['female', 'Female'])
+      expect(component).to be_a(Superform::Rails::Components::Radio)
+    end
   end
 
   describe "Rails compatibility aliases" do
@@ -55,9 +58,10 @@
       expect(component.type).to eq("search")
     end
 
-    it "handles radio button value parameter correctly" do
-      component = field.radio("female", class: "radio-input", data: { value: "f" })
-      expect(component.type).to eq("radio")
+    it "handles radio button collection with attributes correctly" do
+      component = field.radio(['male', 'Male'], ['female', 'Female'],
+                              class: "radio-input", data: { value: "f" })
+      expect(component).to be_a(Superform::Rails::Components::Radio)
     end
   end
 end
\ No newline at end of file

From f5a9413d3dfaf514588a538bca20f6f06aa0ba98 Mon Sep 17 00:00:00 2001
From: andrew nimmo <andrnimm@fastmail.fm>
Date: Tue, 18 Nov 2025 15:57:50 -0800
Subject: [PATCH 04/11] Checkbox collection support

---
 lib/superform/rails/components/checkbox.rb    |  79 +++-
 lib/superform/rails/field.rb                  |   6 +-
 .../checkbox_collection_integration_spec.rb   | 222 ++++++++++
 .../rails/components/checkbox_spec.rb         | 378 ++++++++++++++++++
 4 files changed, 675 insertions(+), 10 deletions(-)
 create mode 100644 spec/superform/rails/components/checkbox_collection_integration_spec.rb
 create mode 100644 spec/superform/rails/components/checkbox_spec.rb

diff --git a/lib/superform/rails/components/checkbox.rb b/lib/superform/rails/components/checkbox.rb
index 0c40f73..4e5fa43 100644
--- a/lib/superform/rails/components/checkbox.rb
+++ b/lib/superform/rails/components/checkbox.rb
@@ -2,17 +2,80 @@ module Superform
   module Rails
     module Components
       class Checkbox < Field
-        def view_template(&)
-          # Rails has a hidden and checkbox input to deal with sending back a value
-          # to the server regardless of if the input is checked or not.
-          input(name: dom.name, type: :hidden, value: "0")
-          # The hard coded keys need to be in here so the user can't overrite them.
-          input(type: :checkbox, value: "1", **attributes)
+        def initialize(
+          *,
+          options: [],
+          **,
+          &
+        )
+          super(*, **, &)
+          @options = options
         end
 
-        def field_attributes
-          { id: dom.id, name: dom.name, checked: field.value }
+        def view_template(&block)
+          if collection_mode?
+            # Collection mode: render multiple checkboxes
+            if block_given?
+              yield self
+            else
+              buttons(*@options)
+            end
+          else
+            # Boolean mode: single checkbox with hidden field
+            # Rails has a hidden and checkbox input to deal with sending back
+            # a value to the server regardless of if the input is checked or not.
+            input(name: dom.name, type: :hidden, value: "0")
+            # The hard coded keys need to be in here so the user can't overrite them.
+            input(type: :checkbox, value: "1", **attributes)
+          end
         end
+
+        # Collection mode methods
+        def buttons(*option_list)
+          map_options(option_list).each do |value, label|
+            button(value) { label }
+          end
+        end
+
+        def button(value, &block)
+          label do
+            input(
+              **attributes,
+              type: :checkbox,
+              id: "#{dom.id}_#{value}",
+              name: "#{dom.name}[]",
+              value: value.to_s,
+              checked: checked_in_collection?(value)
+            )
+            plain(yield) if block_given?
+          end
+        end
+
+        protected
+          def collection_mode?
+            @options.any?
+          end
+
+          def map_options(option_list)
+            OptionMapper.new(option_list)
+          end
+
+          def checked_in_collection?(value)
+            # Checkbox groups are multi-select, so field.value should be an array
+            field_value = field.value
+            return false if field_value.nil?
+
+            field_value = [field_value] unless field_value.is_a?(Array)
+            field_value.map(&:to_s).include?(value.to_s)
+          end
+
+          def field_attributes
+            if collection_mode?
+              { name: "#{dom.name}[]" }
+            else
+              { id: dom.id, name: dom.name, checked: field.value }
+            end
+          end
       end
     end
   end
diff --git a/lib/superform/rails/field.rb b/lib/superform/rails/field.rb
index bf3f3fc..d881cb0 100644
--- a/lib/superform/rails/field.rb
+++ b/lib/superform/rails/field.rb
@@ -33,8 +33,10 @@ def input(**attributes)
         Components::Input.new(field, attributes:)
       end
 
-      def checkbox(**attributes)
-        Components::Checkbox.new(field, attributes:)
+      def checkbox(*args, **attributes)
+        # Treat as collection if args provided (including single ActiveRecord::Relation)
+        # Otherwise treat as boolean checkbox (single true/false)
+        Components::Checkbox.new(field, attributes:, options: args)
       end
 
       def label(**attributes, &)
diff --git a/spec/superform/rails/components/checkbox_collection_integration_spec.rb b/spec/superform/rails/components/checkbox_collection_integration_spec.rb
new file mode 100644
index 0000000..f6ea79a
--- /dev/null
+++ b/spec/superform/rails/components/checkbox_collection_integration_spec.rb
@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+RSpec.describe "Checkbox in Collection Integration", type: :view do
+  # Set up test database for collection models
+  before(:all) do
+    ActiveRecord::Schema.define do
+      create_table :pizza_orders, force: true do |t|
+        t.string :toppings
+      end
+    end unless ActiveRecord::Base.connection.table_exists?(:pizza_orders)
+  end
+
+  after(:all) do
+    ActiveRecord::Schema.define do
+      drop_table :pizza_orders if ActiveRecord::Base.connection.table_exists?(:pizza_orders)
+    end
+  end
+
+  # Test model for collection (array of objects)
+  class PizzaOrder < ActiveRecord::Base
+    self.table_name = "pizza_orders"
+    # Serialize toppings as array for multi-select checkboxes
+    serialize :toppings, coder: JSON
+  end
+
+  describe "collection (array of objects with multi-select)" do
+    let(:initial_orders) do
+      [
+        PizzaOrder.new(toppings: ["cheese", "pepperoni"]),
+        PizzaOrder.new(toppings: ["mushrooms"])
+      ]
+    end
+    let(:model) do
+      # Simulates a model with has_many association
+      # Using User with a mock orders association
+      orders_list = initial_orders # capture for closure
+      User.new(first_name: "Test", email: "test@example.com").tap do |user|
+        user.define_singleton_method(:orders) { @orders ||= orders_list }
+        user.define_singleton_method(:orders=) { |val| @orders = val }
+      end
+    end
+    let(:form) { Superform::Rails::Form.new(model, action: "/users") }
+    let(:topping_options) do
+      [
+        ["cheese", "Cheese"],
+        ["pepperoni", "Pepperoni"],
+        ["mushrooms", "Mushrooms"],
+        ["olives", "Olives"]
+      ]
+    end
+
+    it "renders checkboxes with collection notation" do
+      html = render(form) do |f|
+        orders_collection = f.collection(:orders)
+        orders_collection.each do |order_namespace|
+          f.render order_namespace.field(:toppings).checkbox(*topping_options)
+        end
+      end
+
+      # Collection uses model_name[collection_name][index][field_name][] notation
+      # The final [] is for checkbox array submission
+      expect(html).to include('name="user[orders][0][toppings][]"')
+      expect(html).to include('name="user[orders][1][toppings][]"')
+      expect(html.scan(/type="checkbox"/).count).to eq(8) # 4 checkboxes × 2 orders
+    end
+
+    it "pre-selects checkboxes based on collection values" do
+      html = render(form) do |f|
+        orders_collection = f.collection(:orders)
+        orders_collection.each do |order_namespace|
+          f.render order_namespace.field(:toppings).checkbox(*topping_options)
+        end
+      end
+
+      # Should have exactly 3 checked checkboxes total
+      # First order: cheese, pepperoni (2 checked)
+      # Second order: mushrooms (1 checked)
+      expect(html.scan(/checked/).count).to eq(3)
+
+      # "cheese" should be checked (first order)
+      expect(html).to match(/<input[^>]*id="user_orders_0_toppings_cheese"[^>]*checked/)
+      # "pepperoni" should be checked (first order)
+      expect(html).to match(/<input[^>]*id="user_orders_0_toppings_pepperoni"[^>]*checked/)
+      # "mushrooms" should be checked (second order)
+      expect(html).to match(/<input[^>]*id="user_orders_1_toppings_mushrooms"[^>]*checked/)
+    end
+
+    it "does not check unselected options" do
+      html = render(form) do |f|
+        orders_collection = f.collection(:orders)
+        orders_collection.each do |order_namespace|
+          f.render order_namespace.field(:toppings).checkbox(*topping_options)
+        end
+      end
+
+      # "olives" should not be checked in either order
+      expect(html).not_to match(/<input[^>]*id="user_orders_0_toppings_olives"[^>]*checked/)
+      expect(html).not_to match(/<input[^>]*id="user_orders_1_toppings_olives"[^>]*checked/)
+
+      # "mushrooms" should not be checked in first order
+      expect(html).not_to match(/<input[^>]*id="user_orders_0_toppings_mushrooms"[^>]*checked/)
+    end
+
+    it "works with submitted params from collection" do
+      # Simulate Rails params after form submission
+      # Collection checkboxes submit as:
+      # { "user" => { "orders" => [
+      #   { "toppings" => ["olives", "mushrooms"] },
+      #   { "toppings" => ["cheese", "pepperoni", "olives"] }
+      # ] } }
+      submitted_model = User.new(first_name: "Test", email: "test@example.com").tap do |user|
+        user.define_singleton_method(:orders) do
+          [
+            PizzaOrder.new(toppings: ["olives", "mushrooms"]),
+            PizzaOrder.new(toppings: ["cheese", "pepperoni", "olives"])
+          ]
+        end
+      end
+      submitted_form = Superform::Rails::Form.new(submitted_model, action: "/users")
+
+      html = render(submitted_form) do |f|
+        orders_collection = f.collection(:orders)
+        orders_collection.each do |order_namespace|
+          f.render order_namespace.field(:toppings).checkbox(*topping_options)
+        end
+      end
+
+      # Should have exactly 5 checked checkboxes
+      # First order: olives, mushrooms (2 checked)
+      # Second order: cheese, pepperoni, olives (3 checked)
+      expect(html.scan(/checked/).count).to eq(5)
+
+      # First order should have "olives" and "mushrooms" checked
+      expect(html).to match(/<input[^>]*id="user_orders_0_toppings_olives"[^>]*checked/)
+      expect(html).to match(/<input[^>]*id="user_orders_0_toppings_mushrooms"[^>]*checked/)
+
+      # Second order should have "cheese", "pepperoni", "olives" checked
+      expect(html).to match(/<input[^>]*id="user_orders_1_toppings_cheese"[^>]*checked/)
+      expect(html).to match(/<input[^>]*id="user_orders_1_toppings_pepperoni"[^>]*checked/)
+      expect(html).to match(/<input[^>]*id="user_orders_1_toppings_olives"[^>]*checked/)
+    end
+
+    it "wraps each checkbox in a label for clickability" do
+      html = render(form) do |f|
+        orders_collection = f.collection(:orders)
+        orders_collection.each do |order_namespace|
+          f.render order_namespace.field(:toppings).checkbox(*topping_options)
+        end
+      end
+
+      # Each checkbox should be wrapped in a label
+      # 4 options × 2 orders = 8 labels
+      expect(html.scan(/<label>/).count).to eq(8)
+      expect(html.scan(/<\/label>/).count).to eq(8)
+    end
+  end
+
+  describe "boolean checkboxes in collection" do
+    before(:all) do
+      ActiveRecord::Schema.define do
+        create_table :tasks, force: true do |t|
+          t.boolean :completed
+        end
+      end unless ActiveRecord::Base.connection.table_exists?(:tasks)
+    end
+
+    after(:all) do
+      ActiveRecord::Schema.define do
+        drop_table :tasks if ActiveRecord::Base.connection.table_exists?(:tasks)
+      end
+    end
+
+    class Task < ActiveRecord::Base
+    end
+
+    let(:initial_tasks) do
+      [
+        Task.new(completed: true),
+        Task.new(completed: false)
+      ]
+    end
+    let(:model) do
+      tasks_list = initial_tasks
+      User.new(first_name: "Test", email: "test@example.com").tap do |user|
+        user.define_singleton_method(:tasks) { @tasks ||= tasks_list }
+        user.define_singleton_method(:tasks=) { |val| @tasks = val }
+      end
+    end
+    let(:form) { Superform::Rails::Form.new(model, action: "/users") }
+
+    it "renders boolean checkboxes with hidden fields in collection" do
+      html = render(form) do |f|
+        tasks_collection = f.collection(:tasks)
+        tasks_collection.each do |task_namespace|
+          f.render task_namespace.field(:completed).checkbox
+        end
+      end
+
+      # Should have hidden fields for each checkbox (value="0")
+      # Plus form authenticity_token and _method fields
+      expect(html.scan(/type="hidden"[^>]*value="0"/).count).to eq(2)
+      # Each task should have both hidden and checkbox inputs with same name
+      expect(html.scan(/name="user\[tasks\]\[0\]\[completed\]"/).count).to eq(2) # hidden + checkbox
+      expect(html.scan(/name="user\[tasks\]\[1\]\[completed\]"/).count).to eq(2) # hidden + checkbox
+    end
+
+    it "checks boolean checkboxes based on true/false values" do
+      html = render(form) do |f|
+        tasks_collection = f.collection(:tasks)
+        tasks_collection.each do |task_namespace|
+          f.render task_namespace.field(:completed).checkbox
+        end
+      end
+
+      # First task is completed (true) - should be checked
+      expect(html).to match(/<input[^>]*id="user_tasks_0_completed"[^>]*checked/)
+
+      # Second task is not completed (false) - should not be checked
+      expect(html).not_to match(/<input[^>]*id="user_tasks_1_completed"[^>]*checked/)
+    end
+  end
+end
diff --git a/spec/superform/rails/components/checkbox_spec.rb b/spec/superform/rails/components/checkbox_spec.rb
new file mode 100644
index 0000000..1cc1863
--- /dev/null
+++ b/spec/superform/rails/components/checkbox_spec.rb
@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/BlockLength
+RSpec.describe Superform::Rails::Components::Checkbox, type: :view do
+  describe 'boolean mode (backwards compatibility)' do
+    let(:object) { double('object', featured: featured_value) }
+    let(:featured_value) { false }
+    let(:field) do
+      Superform::Rails::Field.new(:featured, parent: nil, object: object)
+    end
+    let(:component) do
+      described_class.new(field, attributes: attributes)
+    end
+    let(:attributes) { {} }
+
+    subject { render(component) }
+
+    it 'renders a hidden input with value 0' do
+      expect(subject).to include('type="hidden"')
+      expect(subject).to include('value="0"')
+    end
+
+    it 'renders a checkbox input with value 1' do
+      expect(subject).to include('type="checkbox"')
+      expect(subject).to include('value="1"')
+    end
+
+    it 'uses the correct name for both inputs' do
+      expect(subject.scan(/name="featured"/).count).to eq(2)
+    end
+
+    it 'does not wrap inputs in a label' do
+      expect(subject).not_to include('<label>')
+    end
+
+    it 'renders both inputs without wrapper' do
+      expect(subject).to eq(
+        '<input name="featured" type="hidden" value="0">' \
+        '<input type="checkbox" value="1" id="featured" name="featured">'
+      )
+    end
+
+    context 'when value is false' do
+      let(:featured_value) { false }
+
+      it 'does not check the checkbox' do
+        expect(subject).not_to include('checked')
+      end
+    end
+
+    context 'when value is true' do
+      let(:featured_value) { true }
+
+      it 'checks the checkbox' do
+        expect(subject).to match(/<input[^>]*type="checkbox"[^>]*checked/)
+      end
+    end
+  end
+
+  describe 'collection mode (multi-select)' do
+    let(:object) { double('object', sushi: sushi_value) }
+    let(:sushi_value) { [] }
+    let(:field) do
+      Superform::Rails::Field.new(:sushi, parent: nil, object: object)
+    end
+    let(:options) do
+      [
+        ['shirako', 'Shirako'],
+        ['ankimo', 'Ankimo'],
+        ['tsubugai', 'Tsubugai']
+      ]
+    end
+    let(:component) do
+      described_class.new(field, attributes: attributes, options: options)
+    end
+    let(:attributes) { {} }
+
+    subject { render(component) }
+
+    it 'renders multiple checkbox inputs' do
+      expect(subject.scan(/<input[^>]*type="checkbox"/).count).to eq(3)
+    end
+
+    it 'does not render hidden inputs in collection mode' do
+      expect(subject).not_to include('type="hidden"')
+    end
+
+    it 'renders checkboxes with correct values' do
+      expect(subject).to include('value="shirako"')
+      expect(subject).to include('value="ankimo"')
+      expect(subject).to include('value="tsubugai"')
+    end
+
+    it 'renders unique IDs for each checkbox' do
+      expect(subject).to include('id="sushi_shirako"')
+      expect(subject).to include('id="sushi_ankimo"')
+      expect(subject).to include('id="sushi_tsubugai"')
+    end
+
+    it 'uses array notation for all checkbox names' do
+      expect(subject.scan(/name="sushi\[\]"/).count).to eq(3)
+    end
+
+    it 'wraps each checkbox in a label' do
+      expect(subject.scan(/<label>/).count).to eq(3)
+      expect(subject.scan(/<\/label>/).count).to eq(3)
+    end
+
+    it 'does not check any checkbox by default' do
+      expect(subject).not_to include('checked')
+    end
+
+    it 'renders complete HTML structure' do
+      expect(subject).to eq(
+        '<label><input name="sushi[]" type="checkbox" id="sushi_shirako" value="shirako">Shirako</label>' \
+        '<label><input name="sushi[]" type="checkbox" id="sushi_ankimo" value="ankimo">Ankimo</label>' \
+        '<label><input name="sushi[]" type="checkbox" id="sushi_tsubugai" value="tsubugai">Tsubugai</label>'
+      )
+    end
+
+    context 'with selected values' do
+      let(:sushi_value) { ['ankimo', 'tsubugai'] }
+
+      it 'checks the matching checkboxes' do
+        expect(subject).to match(
+          /<input[^>]*id="sushi_ankimo"[^>]*checked[^>]*>/
+        )
+        expect(subject).to match(
+          /<input[^>]*id="sushi_tsubugai"[^>]*checked[^>]*>/
+        )
+      end
+
+      it 'does not check other checkboxes' do
+        expect(subject).not_to match(
+          /<input[^>]*id="sushi_shirako"[^>]*checked[^>]*>/
+        )
+      end
+
+      it 'renders complete HTML structure with checked state' do
+        expect(subject).to eq(
+          '<label><input name="sushi[]" type="checkbox" id="sushi_shirako" value="shirako">Shirako</label>' \
+          '<label><input name="sushi[]" type="checkbox" id="sushi_ankimo" value="ankimo" checked>Ankimo</label>' \
+          '<label><input name="sushi[]" type="checkbox" id="sushi_tsubugai" value="tsubugai" checked>Tsubugai</label>'
+        )
+      end
+    end
+
+    context 'with numeric values' do
+      let(:object) { double('object', role_ids: role_ids_value) }
+      let(:role_ids_value) { [2, 3] }
+      let(:field) do
+        Superform::Rails::Field.new(:role_ids, parent: nil, object: object)
+      end
+      let(:options) { [[1, 'Admin'], [2, 'Editor'], [3, 'Viewer']] }
+
+      it 'checks the matching checkboxes with numeric comparison' do
+        expect(subject).to match(
+          /<input[^>]*id="role_ids_2"[^>]*checked[^>]*>/
+        )
+        expect(subject).to match(
+          /<input[^>]*id="role_ids_3"[^>]*checked[^>]*>/
+        )
+      end
+    end
+  end
+
+  describe 'using field helper method' do
+    let(:form_field) do
+      Superform::Rails::Field.new(:sushi, parent: nil, object: object)
+    end
+    let(:object) { double('object', sushi: []) }
+
+    context 'with positional arguments (collection mode)' do
+      subject do
+        render(
+          form_field.checkbox(
+            ['shirako', 'Shirako'],
+            ['ankimo', 'Ankimo'],
+            ['tsubugai', 'Tsubugai']
+          )
+        )
+      end
+
+      it 'renders checkboxes from positional args' do
+        expect(subject).to include('value="shirako"')
+        expect(subject).to include('value="ankimo"')
+        expect(subject).to include('value="tsubugai"')
+      end
+
+      it 'uses array notation for names' do
+        expect(subject.scan(/name="sushi\[\]"/).count).to eq(3)
+      end
+    end
+
+    context 'with mixed format positional arguments' do
+      let(:object) { double('object', preferences: []) }
+      let(:form_field) do
+        Superform::Rails::Field.new(:preferences, parent: nil, object: object)
+      end
+
+      subject do
+        render(
+          form_field.checkbox(
+            [true, 'Email notifications'],
+            [false, 'SMS notifications'],
+            'Push notifications'
+          )
+        )
+      end
+
+      it 'renders checkboxes with array pairs using first as value' do
+        expect(subject).to include('value="true"')
+        expect(subject).to include('value="false"')
+      end
+
+      it 'renders checkboxes with array pairs using second as label' do
+        expect(subject).to include('>Email notifications')
+        expect(subject).to include('>SMS notifications')
+      end
+
+      it 'renders checkbox with single value for both value and label' do
+        expect(subject).to include('value="Push notifications"')
+        expect(subject).to include('>Push notifications')
+      end
+    end
+
+    context 'without arguments (boolean mode)' do
+      let(:object) { double('object', featured: false) }
+      let(:form_field) do
+        Superform::Rails::Field.new(:featured, parent: nil, object: object)
+      end
+
+      subject do
+        render(form_field.checkbox)
+      end
+
+      it 'renders a boolean checkbox' do
+        expect(subject).to include('type="checkbox"')
+        expect(subject).to include('value="1"')
+      end
+
+      it 'renders a hidden field' do
+        expect(subject).to include('type="hidden"')
+        expect(subject).to include('value="0"')
+      end
+
+      it 'does not use array notation' do
+        expect(subject).not_to include('name="featured[]"')
+        expect(subject).to include('name="featured"')
+      end
+    end
+  end
+
+  describe 'with custom attributes' do
+    let(:object) { double('object', sushi: []) }
+    let(:field) do
+      Superform::Rails::Field.new(:sushi, parent: nil, object: object)
+    end
+    let(:attributes) { { class: 'custom-checkbox', data: { controller: 'checkbox' } } }
+    let(:component) do
+      described_class.new(
+        field,
+        attributes: attributes,
+        options: [['shirako', 'Shirako'], ['ankimo', 'Ankimo']]
+      )
+    end
+
+    subject { render(component) }
+
+    it 'applies custom attributes to all checkboxes' do
+      expect(subject).to include('class="custom-checkbox"')
+      expect(subject).to include('data-controller="checkbox"')
+      expect(subject.scan(/class="custom-checkbox"/).count).to eq(2)
+    end
+  end
+
+  describe 'with block for custom rendering' do
+    let(:object) { double('object', sushi: []) }
+    let(:field) do
+      Superform::Rails::Field.new(:sushi, parent: nil, object: object)
+    end
+    let(:component) do
+      described_class.new(
+        field,
+        attributes: {},
+        options: [
+          ['shirako', 'Shirako'],
+          ['ankimo', 'Ankimo'],
+          ['tsubugai', 'Tsubugai']
+        ]
+      )
+    end
+
+    subject do
+      render(component) do |checkbox|
+        checkbox.button('shirako') { 'Shirako' }
+        checkbox.button('ankimo') { 'Ankimo' }
+      end
+    end
+
+    it 'renders custom checkboxes via block' do
+      expect(subject).to include('value="shirako"')
+      expect(subject).to include('value="ankimo"')
+    end
+
+    it 'does not render options from constructor' do
+      expect(subject).not_to include('value="tsubugai"')
+    end
+  end
+
+  describe 'with ActiveRecord::Relation' do
+    before do
+      User.create!(first_name: 'Alice', email: 'alice@example.com')
+      User.create!(first_name: 'Bob', email: 'bob@example.com')
+      User.create!(first_name: 'Charlie', email: 'charlie@example.com')
+    end
+
+    after do
+      User.delete_all
+    end
+
+    let(:object) { double('object', author_ids: author_ids_value) }
+    let(:author_ids_value) { [] }
+    let(:field) do
+      Superform::Rails::Field.new(:author_ids, parent: nil, object: object)
+    end
+    let(:users_relation) { User.select(:id, :first_name) }
+
+    context 'passed directly via field helper' do
+      let(:form_field) do
+        Superform::Rails::Field.new(:author_ids, parent: nil, object: object)
+      end
+
+      subject do
+        # Pass relation directly without wrapping in array
+        render(form_field.checkbox(users_relation))
+      end
+
+      it 'renders checkboxes from ActiveRecord relation' do
+        expect(subject).to match(/<input[^>]*value="\d+"[^>]*>Alice/)
+        expect(subject).to match(/<input[^>]*value="\d+"[^>]*>Bob/)
+        expect(subject).to match(/<input[^>]*value="\d+"[^>]*>Charlie/)
+      end
+
+      it 'uses array notation for names' do
+        expect(subject.scan(/name="author_ids\[\]"/).count).to eq(3)
+      end
+
+      it 'generates proper HTML structure with labels' do
+        expect(subject).to include('<label>')
+        expect(subject.scan(/<label>/).count).to eq(3)
+      end
+
+      context 'with selected values' do
+        let(:alice) { User.find_by(first_name: 'Alice') }
+        let(:charlie) { User.find_by(first_name: 'Charlie') }
+        let(:author_ids_value) { [alice.id, charlie.id] }
+
+        it 'checks the matching checkboxes' do
+          expect(subject).to match(
+            /<input[^>]*id="author_ids_#{alice.id}"[^>]*checked[^>]*>/
+          )
+          expect(subject).to match(
+            /<input[^>]*id="author_ids_#{charlie.id}"[^>]*checked[^>]*>/
+          )
+        end
+
+        it 'does not check other checkboxes' do
+          bob = User.find_by(first_name: 'Bob')
+          expect(subject).not_to match(
+            /<input[^>]*id="author_ids_#{bob.id}"[^>]*checked[^>]*>/
+          )
+        end
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/BlockLength

From e77de876053748fcfee6f42f8c3462a48106ee77 Mon Sep 17 00:00:00 2001
From: andrew nimmo <andrnimm@fastmail.fm>
Date: Tue, 18 Nov 2025 16:42:37 -0800
Subject: [PATCH 05/11] Update README.md

---
 README.md | 47 ++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 40 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index e092015..db3f6a7 100644
--- a/README.md
+++ b/README.md
@@ -359,16 +359,14 @@ class SignupForm < Components::Form
       end
     end
 
-    # Radio buttons can be rendered individually or as a group
+    # Radio buttons - for single-select from multiple options
     div do
       Field(:plan).label { "Choose your plan" }
-      # Radio group with options - renders multiple radio buttons
+      # Pass options as positional arguments
       Field(:plan).radio(
-        options: [
-          ["free", "Free Plan"],     # <input type="radio" value="free">Free Plan
-          ["pro", "Pro Plan"],       # <input type="radio" value="pro">Pro Plan
-          ["enterprise", "Enterprise"] # <input type="radio" value="enterprise">Enterprise
-        ]
+        ["free", "Free Plan"],      # <label><input type="radio" value="free">Free Plan</label>
+        ["pro", "Pro Plan"],        # <label><input type="radio" value="pro">Pro Plan</label>
+        ["enterprise", "Enterprise"] # <label><input type="radio" value="enterprise">Enterprise</label>
       )
     end
 
@@ -382,11 +380,46 @@ class SignupForm < Components::Form
       end
     end
 
+    # Boolean checkbox - single true/false toggle
     div do
       Field(:agreement).label { "Check this box if you agree to give us your first born child" }
       Field(:agreement).checkbox(checked: true)
     end
 
+    # Checkbox collection - for multi-select from multiple options
+    div do
+      Field(:role_ids).label { "Select your roles" }
+      # Pass options as positional arguments (similar to radio)
+      Field(:role_ids).checkbox(
+        [1, "Admin"],   # <label><input type="checkbox" value="1">Admin</label>
+        [2, "Editor"],  # <label><input type="checkbox" value="2">Editor</label>
+        [3, "Viewer"]   # <label><input type="checkbox" value="3">Viewer</label>
+      )
+    end
+
+    # Or render individual checkboxes with custom markup
+    div do
+      Field(:feature_ids).label { "Enable features" }
+      Field(:feature_ids).checkbox do |c|
+        div { c.button(1) { "Dark Mode" } }
+        div { c.button(2) { "Notifications" } }
+        div { c.button(3) { "Auto-save" } }
+      end
+    end
+
+    # Both radio and checkbox support ActiveRecord relations
+    div do
+      Field(:category_id).label { "Select category" }
+      # Automatically uses id as value and name as label
+      Field(:category_id).radio(Category.select(:id, :name))
+    end
+
+    div do
+      Field(:tag_ids).label { "Select tags" }
+      # Automatically uses id as value and name as label
+      Field(:tag_ids).checkbox(Tag.select(:id, :name))
+    end
+
     render button { "Submit" }
   end
 end

From 847869d63be97ba288381470f7bc5f0b11517c82 Mon Sep 17 00:00:00 2001
From: andrew nimmo <andrnimm@fastmail.fm>
Date: Tue, 18 Nov 2025 17:33:34 -0800
Subject: [PATCH 06/11] Remove redundant field_attributes in Checkbox
 collection mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In collection mode, the `button` method explicitly sets all input
attributes (type, id, name, value, checked), making the `name` attribute
from `field_attributes` redundant.

Changed `field_attributes` to return `{}` in collection mode since the
`button` method handles all attributes explicitly.

Updated test expectations to match new attribute order (functionally
identical HTML, just different order: type, id, name, value, checked).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 lib/superform/rails/components/checkbox.rb       |  3 ++-
 spec/superform/rails/components/checkbox_spec.rb | 12 ++++++------
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/lib/superform/rails/components/checkbox.rb b/lib/superform/rails/components/checkbox.rb
index 4e5fa43..4d52c59 100644
--- a/lib/superform/rails/components/checkbox.rb
+++ b/lib/superform/rails/components/checkbox.rb
@@ -71,7 +71,8 @@ def checked_in_collection?(value)
 
           def field_attributes
             if collection_mode?
-              { name: "#{dom.name}[]" }
+              # button method handles all attributes explicitly
+              {}
             else
               { id: dom.id, name: dom.name, checked: field.value }
             end
diff --git a/spec/superform/rails/components/checkbox_spec.rb b/spec/superform/rails/components/checkbox_spec.rb
index 1cc1863..fda6cc5 100644
--- a/spec/superform/rails/components/checkbox_spec.rb
+++ b/spec/superform/rails/components/checkbox_spec.rb
@@ -112,9 +112,9 @@
 
     it 'renders complete HTML structure' do
       expect(subject).to eq(
-        '<label><input name="sushi[]" type="checkbox" id="sushi_shirako" value="shirako">Shirako</label>' \
-        '<label><input name="sushi[]" type="checkbox" id="sushi_ankimo" value="ankimo">Ankimo</label>' \
-        '<label><input name="sushi[]" type="checkbox" id="sushi_tsubugai" value="tsubugai">Tsubugai</label>'
+        '<label><input type="checkbox" id="sushi_shirako" name="sushi[]" value="shirako">Shirako</label>' \
+        '<label><input type="checkbox" id="sushi_ankimo" name="sushi[]" value="ankimo">Ankimo</label>' \
+        '<label><input type="checkbox" id="sushi_tsubugai" name="sushi[]" value="tsubugai">Tsubugai</label>'
       )
     end
 
@@ -138,9 +138,9 @@
 
       it 'renders complete HTML structure with checked state' do
         expect(subject).to eq(
-          '<label><input name="sushi[]" type="checkbox" id="sushi_shirako" value="shirako">Shirako</label>' \
-          '<label><input name="sushi[]" type="checkbox" id="sushi_ankimo" value="ankimo" checked>Ankimo</label>' \
-          '<label><input name="sushi[]" type="checkbox" id="sushi_tsubugai" value="tsubugai" checked>Tsubugai</label>'
+          '<label><input type="checkbox" id="sushi_shirako" name="sushi[]" value="shirako">Shirako</label>' \
+          '<label><input type="checkbox" id="sushi_ankimo" name="sushi[]" value="ankimo" checked>Ankimo</label>' \
+          '<label><input type="checkbox" id="sushi_tsubugai" name="sushi[]" value="tsubugai" checked>Tsubugai</label>'
         )
       end
     end

From 77d2aa5d508df9e9c2fd79629662aa2e55b1c7bb Mon Sep 17 00:00:00 2001
From: andrew nimmo <andrnimm@fastmail.fm>
Date: Wed, 19 Nov 2025 12:48:59 -0800
Subject: [PATCH 07/11] Switch checkbox to use `options`

---
 README.md                                        |  6 +++---
 lib/superform/rails/components/checkbox.rb       | 10 +++++-----
 spec/superform/rails/components/checkbox_spec.rb |  4 ++--
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index db3f6a7..fffa8a0 100644
--- a/README.md
+++ b/README.md
@@ -401,9 +401,9 @@ class SignupForm < Components::Form
     div do
       Field(:feature_ids).label { "Enable features" }
       Field(:feature_ids).checkbox do |c|
-        div { c.button(1) { "Dark Mode" } }
-        div { c.button(2) { "Notifications" } }
-        div { c.button(3) { "Auto-save" } }
+        div { c.option(1) { "Dark Mode" } }
+        div { c.option(2) { "Notifications" } }
+        div { c.option(3) { "Auto-save" } }
       end
     end
 
diff --git a/lib/superform/rails/components/checkbox.rb b/lib/superform/rails/components/checkbox.rb
index 4d52c59..b32bc82 100644
--- a/lib/superform/rails/components/checkbox.rb
+++ b/lib/superform/rails/components/checkbox.rb
@@ -18,7 +18,7 @@ def view_template(&block)
             if block_given?
               yield self
             else
-              buttons(*@options)
+              options(*@options)
             end
           else
             # Boolean mode: single checkbox with hidden field
@@ -31,13 +31,13 @@ def view_template(&block)
         end
 
         # Collection mode methods
-        def buttons(*option_list)
+        def options(*option_list)
           map_options(option_list).each do |value, label|
-            button(value) { label }
+            option(value) { label }
           end
         end
 
-        def button(value, &block)
+        def option(value, &block)
           label do
             input(
               **attributes,
@@ -71,7 +71,7 @@ def checked_in_collection?(value)
 
           def field_attributes
             if collection_mode?
-              # button method handles all attributes explicitly
+              # option method handles all attributes explicitly
               {}
             else
               { id: dom.id, name: dom.name, checked: field.value }
diff --git a/spec/superform/rails/components/checkbox_spec.rb b/spec/superform/rails/components/checkbox_spec.rb
index fda6cc5..1ffb3ec 100644
--- a/spec/superform/rails/components/checkbox_spec.rb
+++ b/spec/superform/rails/components/checkbox_spec.rb
@@ -293,8 +293,8 @@
 
     subject do
       render(component) do |checkbox|
-        checkbox.button('shirako') { 'Shirako' }
-        checkbox.button('ankimo') { 'Ankimo' }
+        checkbox.option('shirako') { 'Shirako' }
+        checkbox.option('ankimo') { 'Ankimo' }
       end
     end
 

From 0f1e6acba29c22948adf3ab6bd6c4d38fea2907a Mon Sep 17 00:00:00 2001
From: andrew nimmo <andrnimm@fastmail.fm>
Date: Wed, 19 Nov 2025 12:53:45 -0800
Subject: [PATCH 08/11] Switch radio to use `options`

---
 README.md                                     | 6 +++---
 lib/superform/rails/components/radio.rb       | 8 ++++----
 spec/superform/rails/components/radio_spec.rb | 8 ++++----
 3 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index fffa8a0..5a3cc56 100644
--- a/README.md
+++ b/README.md
@@ -374,9 +374,9 @@ class SignupForm < Components::Form
     div do
       Field(:gender).label { "Gender" }
       Field(:gender).radio do |r|
-        div { r.button("m") { "Male" } }
-        div { r.button("f") { "Female" } }
-        div { r.button("o") { "Other" } }
+        div { r.option("m") { "Male" } }
+        div { r.option("f") { "Female" } }
+        div { r.option("o") { "Other" } }
       end
     end
 
diff --git a/lib/superform/rails/components/radio.rb b/lib/superform/rails/components/radio.rb
index f652a25..781b9c4 100644
--- a/lib/superform/rails/components/radio.rb
+++ b/lib/superform/rails/components/radio.rb
@@ -16,17 +16,17 @@ def view_template(&block)
           if block_given?
             yield self
           else
-            buttons(*@options)
+            options(*@options)
           end
         end
 
-        def buttons(*option_list)
+        def options(*option_list)
           map_options(option_list).each do |value, label|
-            button(value) { label }
+            option(value) { label }
           end
         end
 
-        def button(value, &block)
+        def option(value, &block)
           label do
             input(
               **attributes,
diff --git a/spec/superform/rails/components/radio_spec.rb b/spec/superform/rails/components/radio_spec.rb
index eb00c6d..2cf714f 100644
--- a/spec/superform/rails/components/radio_spec.rb
+++ b/spec/superform/rails/components/radio_spec.rb
@@ -172,8 +172,8 @@
   describe 'with block for custom rendering' do
     subject do
       render(component) do |radio|
-        radio.button('shirako') { 'Shirako' }
-        radio.button('ankimo') { 'Ankimo' }
+        radio.option('shirako') { 'Shirako' }
+        radio.option('ankimo') { 'Ankimo' }
       end
     end
 
@@ -187,7 +187,7 @@
     end
   end
 
-  describe '#button method' do
+  describe '#option method' do
     let(:component) do
       described_class.new(field, attributes: {}, options: [])
     end
@@ -195,7 +195,7 @@
     context 'with simple value and label' do
       subject do
         render(component) do |radio|
-          radio.button('omakase') { 'Chef\'s Choice' }
+          radio.option('omakase') { 'Chef\'s Choice' }
         end
       end
 

From c930d063c7229fddab7853e90f063c3c15226704 Mon Sep 17 00:00:00 2001
From: andrew nimmo <andrnimm@fastmail.fm>
Date: Wed, 19 Nov 2025 13:09:02 -0800
Subject: [PATCH 09/11] Checkbox - Get rid of `options` kwarg, handle blocks!

---
 lib/superform/rails/components/checkbox.rb    | 13 ++---
 lib/superform/rails/field.rb                  |  2 +-
 .../rails/components/checkbox_spec.rb         | 47 +++++++++++++++----
 3 files changed, 43 insertions(+), 19 deletions(-)

diff --git a/lib/superform/rails/components/checkbox.rb b/lib/superform/rails/components/checkbox.rb
index b32bc82..189fb1e 100644
--- a/lib/superform/rails/components/checkbox.rb
+++ b/lib/superform/rails/components/checkbox.rb
@@ -2,18 +2,13 @@ module Superform
   module Rails
     module Components
       class Checkbox < Field
-        def initialize(
-          *,
-          options: [],
-          **,
-          &
-        )
-          super(*, **, &)
-          @options = options
+        def initialize(field, *option_list, **, &)
+          super(field, **, &)
+          @options = option_list
         end
 
         def view_template(&block)
-          if collection_mode?
+          if collection_mode? || block_given?
             # Collection mode: render multiple checkboxes
             if block_given?
               yield self
diff --git a/lib/superform/rails/field.rb b/lib/superform/rails/field.rb
index d881cb0..17bf6d1 100644
--- a/lib/superform/rails/field.rb
+++ b/lib/superform/rails/field.rb
@@ -36,7 +36,7 @@ def input(**attributes)
       def checkbox(*args, **attributes)
         # Treat as collection if args provided (including single ActiveRecord::Relation)
         # Otherwise treat as boolean checkbox (single true/false)
-        Components::Checkbox.new(field, attributes:, options: args)
+        Components::Checkbox.new(field, *args, attributes:)
       end
 
       def label(**attributes, &)
diff --git a/spec/superform/rails/components/checkbox_spec.rb b/spec/superform/rails/components/checkbox_spec.rb
index 1ffb3ec..355b434 100644
--- a/spec/superform/rails/components/checkbox_spec.rb
+++ b/spec/superform/rails/components/checkbox_spec.rb
@@ -71,7 +71,7 @@
       ]
     end
     let(:component) do
-      described_class.new(field, attributes: attributes, options: options)
+      described_class.new(field, *options, attributes: attributes)
     end
     let(:attributes) { {} }
 
@@ -260,8 +260,9 @@
     let(:component) do
       described_class.new(
         field,
-        attributes: attributes,
-        options: [['shirako', 'Shirako'], ['ankimo', 'Ankimo']]
+        ['shirako', 'Shirako'],
+        ['ankimo', 'Ankimo'],
+        attributes: attributes
       )
     end
 
@@ -282,12 +283,10 @@
     let(:component) do
       described_class.new(
         field,
-        attributes: {},
-        options: [
-          ['shirako', 'Shirako'],
-          ['ankimo', 'Ankimo'],
-          ['tsubugai', 'Tsubugai']
-        ]
+        ['shirako', 'Shirako'],
+        ['ankimo', 'Ankimo'],
+        ['tsubugai', 'Tsubugai'],
+        attributes: {}
       )
     end
 
@@ -308,6 +307,36 @@
     end
   end
 
+  describe 'with block but no constructor options' do
+    let(:object) { double('object', features: []) }
+    let(:field) do
+      Superform::Rails::Field.new(:features, parent: nil, object: object)
+    end
+    let(:component) do
+      described_class.new(field, attributes: {})
+    end
+
+    subject do
+      render(component) do |checkbox|
+        checkbox.option('dark_mode') { 'Dark Mode' }
+        checkbox.option('notifications') { 'Notifications' }
+      end
+    end
+
+    it 'renders checkboxes from block without constructor options' do
+      expect(subject).to include('value="dark_mode"')
+      expect(subject).to include('value="notifications"')
+    end
+
+    it 'wraps each checkbox in a label' do
+      expect(subject.scan(/<label>/).count).to eq(2)
+    end
+
+    it 'uses array notation for names' do
+      expect(subject.scan(/name="features\[\]"/).count).to eq(2)
+    end
+  end
+
   describe 'with ActiveRecord::Relation' do
     before do
       User.create!(first_name: 'Alice', email: 'alice@example.com')

From aceb73932e41bb860c82a01b278aa73eddf9995e Mon Sep 17 00:00:00 2001
From: andrew nimmo <andrnimm@fastmail.fm>
Date: Wed, 19 Nov 2025 13:15:12 -0800
Subject: [PATCH 10/11] Radio - get rid of `options` kwarg, handle blocks!

---
 lib/superform/rails/components/radio.rb       | 11 ++---
 lib/superform/rails/field.rb                  |  9 +++--
 spec/superform/rails/components/radio_spec.rb | 40 ++++++++++++++++---
 3 files changed, 44 insertions(+), 16 deletions(-)

diff --git a/lib/superform/rails/components/radio.rb b/lib/superform/rails/components/radio.rb
index 781b9c4..dbbcb8f 100644
--- a/lib/superform/rails/components/radio.rb
+++ b/lib/superform/rails/components/radio.rb
@@ -2,14 +2,9 @@ module Superform
   module Rails
     module Components
       class Radio < Field
-        def initialize(
-          *,
-          options: [],
-          **,
-          &
-        )
-          super(*, **, &)
-          @options = options
+        def initialize(field, *option_list, **, &)
+          super(field, **, &)
+          @options = option_list
         end
 
         def view_template(&block)
diff --git a/lib/superform/rails/field.rb b/lib/superform/rails/field.rb
index 17bf6d1..8d3a60e 100644
--- a/lib/superform/rails/field.rb
+++ b/lib/superform/rails/field.rb
@@ -139,14 +139,17 @@ def file(*, **, &)
         input(*, **, type: :file, &)
       end
 
-      def radio(*args, **attributes, &)
+      def radio(*args, **attributes, &block)
         # If multiple args or first arg is an array, treat as collection
         if args.length > 1 || (args.length == 1 && args.first.is_a?(Array))
-          Components::Radio.new(field, attributes:, options: args, &)
+          Components::Radio.new(field, *args, attributes:, &block)
         # If single arg is an ActiveRecord::Relation, treat as collection
         elsif args.length == 1 && defined?(ActiveRecord::Relation) &&
               args.first.is_a?(ActiveRecord::Relation)
-          Components::Radio.new(field, attributes:, options: args, &)
+          Components::Radio.new(field, *args, attributes:, &block)
+        # No args but block given - allow custom rendering
+        elsif args.empty? && block
+          Components::Radio.new(field, attributes:, &block)
         # No args or single non-collection arg - error
         else
           raise ArgumentError,
diff --git a/spec/superform/rails/components/radio_spec.rb b/spec/superform/rails/components/radio_spec.rb
index 2cf714f..938557e 100644
--- a/spec/superform/rails/components/radio_spec.rb
+++ b/spec/superform/rails/components/radio_spec.rb
@@ -15,7 +15,7 @@
     ]
   end
   let(:component) do
-    described_class.new(field, attributes: attributes, options: options)
+    described_class.new(field, *options, attributes: attributes)
   end
   let(:attributes) { {} }
 
@@ -187,9 +187,39 @@
     end
   end
 
+  describe 'with block but no constructor options' do
+    let(:object) { double('object', plan: nil) }
+    let(:field) do
+      Superform::Rails::Field.new(:plan, parent: nil, object: object)
+    end
+    let(:component) do
+      described_class.new(field, attributes: {})
+    end
+
+    subject do
+      render(component) do |radio|
+        radio.option('free') { 'Free Plan' }
+        radio.option('pro') { 'Pro Plan' }
+      end
+    end
+
+    it 'renders radio buttons from block without constructor options' do
+      expect(subject).to include('value="free"')
+      expect(subject).to include('value="pro"')
+    end
+
+    it 'wraps each radio button in a label' do
+      expect(subject.scan(/<label>/).count).to eq(2)
+    end
+
+    it 'uses the same name for all radio buttons' do
+      expect(subject.scan(/name="plan"/).count).to eq(2)
+    end
+  end
+
   describe '#option method' do
     let(:component) do
-      described_class.new(field, attributes: {}, options: [])
+      described_class.new(field, attributes: {})
     end
 
     context 'with simple value and label' do
@@ -229,8 +259,8 @@
     let(:component) do
       described_class.new(
         sushi_field,
-        attributes: attributes,
-        options: options
+        *options,
+        attributes: attributes
       )
     end
 
@@ -278,7 +308,7 @@
     end
     let(:users_relation) { User.select(:id, :first_name) }
     let(:component) do
-      described_class.new(field, attributes: attributes, options: [users_relation])
+      described_class.new(field, users_relation, attributes: attributes)
     end
 
     subject { render(component) }

From b719c83c8091d1c867382be80712aa32081ee749 Mon Sep 17 00:00:00 2001
From: andrew nimmo <andrnimm@fastmail.fm>
Date: Wed, 19 Nov 2025 19:58:13 -0800
Subject: [PATCH 11/11] Fix checkbox group with label and radio group with
 label, HTML and docs

---
 README.md                                     | 14 ++++----
 lib/superform/rails/components/checkbox.rb    | 16 ++++-----
 lib/superform/rails/components/label.rb       | 14 +++++++-
 .../rails/components/checkbox_spec.rb         |  6 ++--
 spec/superform/rails/components/label_spec.rb | 33 ++++++++++++++++++-
 5 files changed, 63 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 5a3cc56..6f13971 100644
--- a/README.md
+++ b/README.md
@@ -361,7 +361,7 @@ class SignupForm < Components::Form
 
     # Radio buttons - for single-select from multiple options
     div do
-      Field(:plan).label { "Choose your plan" }
+      Field(:plan).label(for: false) { "Choose your plan" }
       # Pass options as positional arguments
       Field(:plan).radio(
         ["free", "Free Plan"],      # <label><input type="radio" value="free">Free Plan</label>
@@ -372,7 +372,7 @@ class SignupForm < Components::Form
 
     # Or render individual radio buttons with custom markup
     div do
-      Field(:gender).label { "Gender" }
+      Field(:gender).label(for: false) { "Gender" }
       Field(:gender).radio do |r|
         div { r.option("m") { "Male" } }
         div { r.option("f") { "Female" } }
@@ -386,9 +386,9 @@ class SignupForm < Components::Form
       Field(:agreement).checkbox(checked: true)
     end
 
-    # Checkbox collection - for multi-select from multiple options
+    # Checkbox array - for multi-select from multiple options
     div do
-      Field(:role_ids).label { "Select your roles" }
+      Field(:role_ids).label(for: false) { "Select your roles" }
       # Pass options as positional arguments (similar to radio)
       Field(:role_ids).checkbox(
         [1, "Admin"],   # <label><input type="checkbox" value="1">Admin</label>
@@ -399,7 +399,7 @@ class SignupForm < Components::Form
 
     # Or render individual checkboxes with custom markup
     div do
-      Field(:feature_ids).label { "Enable features" }
+      Field(:feature_ids).label(for: false) { "Enable features" }
       Field(:feature_ids).checkbox do |c|
         div { c.option(1) { "Dark Mode" } }
         div { c.option(2) { "Notifications" } }
@@ -409,13 +409,13 @@ class SignupForm < Components::Form
 
     # Both radio and checkbox support ActiveRecord relations
     div do
-      Field(:category_id).label { "Select category" }
+      Field(:category_id).label(for: false) { "Select category" }
       # Automatically uses id as value and name as label
       Field(:category_id).radio(Category.select(:id, :name))
     end
 
     div do
-      Field(:tag_ids).label { "Select tags" }
+      Field(:tag_ids).label(for: false) { "Select tags" }
       # Automatically uses id as value and name as label
       Field(:tag_ids).checkbox(Tag.select(:id, :name))
     end
diff --git a/lib/superform/rails/components/checkbox.rb b/lib/superform/rails/components/checkbox.rb
index 189fb1e..ba0d0e1 100644
--- a/lib/superform/rails/components/checkbox.rb
+++ b/lib/superform/rails/components/checkbox.rb
@@ -8,8 +8,8 @@ def initialize(field, *option_list, **, &)
         end
 
         def view_template(&block)
-          if collection_mode? || block_given?
-            # Collection mode: render multiple checkboxes
+          if array_mode? || block_given?
+            # Array mode: render multiple checkboxes
             if block_given?
               yield self
             else
@@ -25,7 +25,7 @@ def view_template(&block)
           end
         end
 
-        # Collection mode methods
+        # Array mode methods
         def options(*option_list)
           map_options(option_list).each do |value, label|
             option(value) { label }
@@ -40,14 +40,14 @@ def option(value, &block)
               id: "#{dom.id}_#{value}",
               name: "#{dom.name}[]",
               value: value.to_s,
-              checked: checked_in_collection?(value)
+              checked: checked_in_array?(value)
             )
             plain(yield) if block_given?
           end
         end
 
         protected
-          def collection_mode?
+          def array_mode?
             @options.any?
           end
 
@@ -55,8 +55,8 @@ def map_options(option_list)
             OptionMapper.new(option_list)
           end
 
-          def checked_in_collection?(value)
-            # Checkbox groups are multi-select, so field.value should be an array
+          def checked_in_array?(value)
+            # Checkbox arrays are multi-select, so field.value should be an array
             field_value = field.value
             return false if field_value.nil?
 
@@ -65,7 +65,7 @@ def checked_in_collection?(value)
           end
 
           def field_attributes
-            if collection_mode?
+            if array_mode?
               # option method handles all attributes explicitly
               {}
             else
diff --git a/lib/superform/rails/components/label.rb b/lib/superform/rails/components/label.rb
index 40f853f..788f195 100644
--- a/lib/superform/rails/components/label.rb
+++ b/lib/superform/rails/components/label.rb
@@ -8,7 +8,19 @@ def view_template(&content)
         end
 
         def field_attributes
-          { for: dom.id }
+          # Only include 'for' attribute if explicitly provided or default
+          # Skip it if set to false/nil to avoid invalid HTML
+          attrs = {}
+          for_value = @attributes&.fetch(:for, :default)
+
+          if for_value == :default
+            attrs[:for] = dom.id
+          elsif for_value
+            attrs[:for] = for_value
+          end
+          # If for_value is false/nil, skip the attribute entirely
+
+          attrs
         end
 
         def label_text
diff --git a/spec/superform/rails/components/checkbox_spec.rb b/spec/superform/rails/components/checkbox_spec.rb
index 355b434..90db27f 100644
--- a/spec/superform/rails/components/checkbox_spec.rb
+++ b/spec/superform/rails/components/checkbox_spec.rb
@@ -57,7 +57,7 @@
     end
   end
 
-  describe 'collection mode (multi-select)' do
+  describe 'array mode (multi-select)' do
     let(:object) { double('object', sushi: sushi_value) }
     let(:sushi_value) { [] }
     let(:field) do
@@ -81,7 +81,7 @@
       expect(subject.scan(/<input[^>]*type="checkbox"/).count).to eq(3)
     end
 
-    it 'does not render hidden inputs in collection mode' do
+    it 'does not render hidden inputs in array mode' do
       expect(subject).not_to include('type="hidden"')
     end
 
@@ -170,7 +170,7 @@
     end
     let(:object) { double('object', sushi: []) }
 
-    context 'with positional arguments (collection mode)' do
+    context 'with positional arguments (array mode)' do
       subject do
         render(
           form_field.checkbox(
diff --git a/spec/superform/rails/components/label_spec.rb b/spec/superform/rails/components/label_spec.rb
index ec1d572..8878b79 100644
--- a/spec/superform/rails/components/label_spec.rb
+++ b/spec/superform/rails/components/label_spec.rb
@@ -6,11 +6,42 @@
   let(:user) { User.new(first_name: "John") }
   let(:form) { Superform::Rails::Form.new(user) }
   let(:field) { form.field(:first_name) }
-  let(:label) { described_class.new(field, attributes: { class: "form-label" }) }
+  let(:label) { described_class.new(field, attributes: attributes) }
+  let(:attributes) { { class: "form-label" } }
 
   subject { label.call }
 
   it "renders label with titleized field name" do
     expect(subject).to eq('<label for="user_first_name" class="form-label">First name</label>')
   end
+
+  context "with for: false" do
+    let(:attributes) { { class: "form-label", for: false } }
+
+    it "renders label without for attribute" do
+      expect(subject).to eq('<label class="form-label">First name</label>')
+    end
+
+    it "does not include for attribute" do
+      expect(subject).not_to include('for=')
+    end
+  end
+
+  context "with for: nil" do
+    let(:attributes) { { class: "form-label", for: nil } }
+
+    it "renders label without for attribute" do
+      expect(subject).to eq('<label class="form-label">First name</label>')
+    end
+  end
+
+  context "with custom for value" do
+    let(:attributes) { { class: "form-label", for: "custom_id" } }
+
+    it "renders label with custom for attribute" do
+      expect(subject).to include('for="custom_id"')
+      expect(subject).to include('class="form-label"')
+      expect(subject).to include('>First name</label>')
+    end
+  end
 end