Accept HTML attributes as kwargs on components

Components now accept HTML attributes directly as keyword arguments
instead of requiring the `attributes:` wrapper. The old `attributes:`
style still works but emits a deprecation warning.

Before: MyInput.new(field, attributes: { class: "foo" })
After:  MyInput.new(field, class: "foo")

Author: bradgessler

CHANGELOG.md

@@ -1,5 +1,37 @@
 ## [Unreleased]
 
+### Changed
+
+- **Deprecation**: Components now accept HTML attributes as keyword arguments directly instead of wrapping them in `attributes:`. The old `attributes:` keyword still works but emits a deprecation warning and will be removed in a future version.
+
+  ```ruby
+  # Before
+  MyInput.new(field, attributes: { class: "form-input" })
+
+  # After
+  MyInput.new(field, class: "form-input")
+  ```
+
+  If you have custom components that override `initialize`, update them to use `**attributes`:
+
+  ```ruby
+  # Before
+  class MyRadio < Superform::Rails::Components::Field
+    def initialize(field, value:, attributes: {})
+      super(field, attributes: attributes)
+      @value = value
+    end
+  end
+
+  # After
+  class MyRadio < Superform::Rails::Components::Field
+    def initialize(field, value:, **attributes)
+      super(field, **attributes)
+      @value = value
+    end
+  end
+  ```
+
 ## [0.6.1] - 2025-08-28
 
 ### Breaking Changes
@@ -106,7 +138,7 @@ Update component class names in your custom form classes:
 
    class Field < Superform::Rails::Form::Field
      def input(**attributes)
-       MyInput.new(self, attributes: attributes)
+       MyInput.new(self, **attributes)
      end
    end
    ```

README.md

@@ -179,7 +179,7 @@ class Components::Form < Superform::Rails::Form
   # Redefining the base Field class lets us override every field component.
   class Field < Superform::Rails::Form::Field
     def input(**attributes)
-      MyInput.new(self, attributes: attributes)
+      MyInput.new(self, **attributes)
     end
   end
 
@@ -469,7 +469,7 @@ class AdminForm < Components::Form
 
   class Field < Field
     def tooltip_input(**attributes)
-      AdminInput.new(self, attributes: attributes)
+      AdminInput.new(self, **attributes)
     end
   end
 end

lib/generators/superform/install/templates/base.rb

@@ -15,7 +15,7 @@ class Field < self::Field
       #
       # # Return your own component if you're doing more complicated things.
       # def autocomplete(**attributes)
-      #   Components::Autocomplete.new(field, attributes:)
+      #   Components::Autocomplete.new(field, **attributes)
       # end
     end
 

lib/superform/rails/components/base.rb

@@ -6,9 +6,16 @@ class Base < Component
 
         delegate :dom, to: :field
 
-        def initialize(field, attributes: {})
+        def initialize(field, attributes: nil, **attributes_kwargs)
           @field = field
-          @attributes = attributes
+          if attributes
+            warn "[DEPRECATION] Passing `attributes:` keyword to #{self.class.name} is deprecated. " \
+                 "Pass HTML attributes as keyword arguments directly instead: " \
+                 "#{self.class.name}.new(field, **attributes)"
+            @attributes = attributes.merge(attributes_kwargs)
+          else
+            @attributes = attributes_kwargs
+          end
         end
 
         def field_attributes

lib/superform/rails/components/radio.rb

@@ -2,8 +2,8 @@ module Superform
   module Rails
     module Components
       class Radio < Field
-        def initialize(field, value:, attributes: {})
-          super(field, attributes: attributes)
+        def initialize(field, value:, **attributes)
+          super(field, **attributes)
           @value = value
         end
 

lib/superform/rails/components/select.rb

@@ -3,14 +3,14 @@ module Rails
     module Components
       class Select < Field
         def initialize(
-          *,
+          field,
           options: [],
           collection: nil,
           multiple: false,
-          **,
+          **attributes,
           &
         )
-          super(*, **, &)
+          super(field, **attributes, &)
 
           # Handle deprecated collection parameter
           if collection && options.empty?

lib/superform/rails/field.rb

@@ -12,8 +12,8 @@ module Rails
     #   end
     #
     #   class Field < Field
-    #     def label(**, &)
-    #       MyLabel.new(self, **, &)
+    #     def label(**attributes, &)
+    #       MyLabel.new(self, **attributes, &)
     #     end
     #
     #     def input(class: nil, **)
@@ -26,31 +26,31 @@ module Rails
     # Now all calls to `label` will have the `text-bold` class applied to it.
     class Field < Superform::Field
       def button(**attributes)
-        Components::Button.new(field, attributes:)
+        Components::Button.new(field, **attributes)
       end
 
       def input(**attributes)
-        Components::Input.new(field, attributes:)
+        Components::Input.new(field, **attributes)
       end
 
       def checkbox(**attributes)
-        Components::Checkbox.new(field, attributes:)
+        Components::Checkbox.new(field, **attributes)
       end
 
       def label(**attributes, &)
-        Components::Label.new(field, attributes:, &)
+        Components::Label.new(field, **attributes, &)
       end
 
       def textarea(**attributes)
-        Components::Textarea.new(field, attributes:)
+        Components::Textarea.new(field, **attributes)
       end
 
       def select(*options, multiple: false, **attributes, &)
         Components::Select.new(
           field,
-          attributes:,
           options:,
           multiple:,
+          **attributes,
           &
         )
       end
@@ -144,7 +144,7 @@ def file(*, **)
       end
 
       def radio(value, **attributes)
-        Components::Radio.new(field, value: value, attributes: attributes)
+        Components::Radio.new(field, value:, **attributes)
       end
 
       # Rails compatibility aliases

spec/superform/rails/components/base_spec.rb

@@ -0,0 +1,37 @@
+RSpec.describe Superform::Rails::Components::Base do
+  let(:object) { double('object', name: "Test") }
+  let(:field) { Superform::Rails::Field.new(:name, parent: nil, object: object) }
+
+  describe 'new kwargs style' do
+    it 'accepts HTML attributes as kwargs' do
+      component = described_class.new(field, class: "form-input", id: "custom")
+      attrs = component.send(:attributes)
+      expect(attrs[:class]).to eq("form-input")
+      expect(attrs[:id]).to eq("custom")
+    end
+  end
+
+  describe 'legacy attributes: style' do
+    it 'accepts HTML attributes via attributes keyword with deprecation warning' do
+      component = nil
+      expect {
+        component = described_class.new(field, attributes: { class: "form-input", id: "custom" })
+      }.to output(/DEPRECATION/).to_stderr
+      attrs = component.send(:attributes)
+      expect(attrs[:class]).to eq("form-input")
+      expect(attrs[:id]).to eq("custom")
+    end
+  end
+
+  describe 'mixed style' do
+    it 'merges attributes: keyword with kwargs' do
+      component = nil
+      expect {
+        component = described_class.new(field, attributes: { class: "form-input" }, id: "custom")
+      }.to output(/DEPRECATION/).to_stderr
+      attrs = component.send(:attributes)
+      expect(attrs[:class]).to eq("form-input")
+      expect(attrs[:id]).to eq("custom")
+    end
+  end
+end

spec/superform/rails/components/checkbox_spec.rb

@@ -5,7 +5,7 @@
     let(:field) do
       Superform::Rails::Field.new(:featured, parent: nil, object: object)
     end
-    let(:component) { described_class.new(field, attributes: {}) }
+    let(:component) { described_class.new(field) }
 
     subject { render(component) }
 
@@ -63,7 +63,7 @@
       all_roles = [[1, "Admin"], [2, "Editor"], [3, "Viewer"]]
       html = ""
       all_roles.each do |id, _name|
-        html += render(described_class.new(field, attributes: { value: id }))
+        html += render(described_class.new(field, value: id))
       end
 
       expect(html).to include('name="role_ids[]"')

spec/superform/rails/components/input_component_spec.rb

@@ -11,7 +11,7 @@
     {}
   end
   let(:component) do
-    described_class.new(field, attributes: attributes)
+    described_class.new(field, **attributes)
   end
   subject { component }