Add datalist component for native autocomplete inputs

Renders <input> + <datalist> for free-text input with browser-native
autocomplete suggestions. No JavaScript required. Accepts the same
option formats as select (arrays, hashes, single values, AR relations).

Example: Field(:time_zone).datalist(*ActiveSupport::TimeZone.all.map(&:name))

Author: bradgessler

CHANGELOG.md

@@ -19,6 +19,10 @@
 - **Choices module** (`Superform::Rails::Choices`) — `Choices::Choice` holds per-option state,
   `Choices::Mapper` (renamed from `OptionMapper`) maps option args to `(value, text)` pairs.
 - **Unique DOM ids** for radio and checkbox groups via `DOM#id(*suffixes)`. Prevents duplicate ids in valid HTML and allows labels to target individual inputs.
+- **Datalist component** with `Field(:time_zone).datalist(*ActiveSupport::TimeZone.all.map(&:name))`.
+  Renders a native `<input>` + `<datalist>` for free-text input with autocomplete suggestions —
+  no JavaScript required. Accepts the same option formats as `select`. Block form available
+  for custom options.
 - **Select improvements**: blank options (`nil`) at any position, `multiple: true` support with hidden input for empty submissions, ActiveRecord relations as options.
 - **Preview server** — run `bin/preview` to view example forms at localhost:3000 with hot-reloading.
 

README.md

@@ -466,6 +466,10 @@ class JobPostingForm < Components::Form
       end
     end
 
+    # Datalist — free-text input with autocomplete suggestions.
+    # No JavaScript required. The browser handles filtering natively.
+    Field(:time_zone).datalist(*ActiveSupport::TimeZone.all.map(&:name))
+
     # File upload (remember to set enctype on the form).
     div do
       Field(:job_description_pdf).label { "Upload job description" }

lib/superform/rails/components/datalist.rb

@@ -0,0 +1,34 @@
+module Superform
+  module Rails
+    module Components
+      class Datalist < Field
+        def initialize(field, options: [], **attributes)
+          super(field, **attributes)
+          @options = options
+        end
+
+        def view_template(&block)
+          datalist_id = DOM.join(dom.id, "datalist")
+          input(list: datalist_id, **attributes)
+          datalist(id: datalist_id) do
+            if block
+              yield self
+            else
+              options(*@options)
+            end
+          end
+        end
+
+        def options(*collection)
+          Choices::Mapper.new(collection).each do |value, text|
+            if value == text
+              option(value: value)
+            else
+              option(value: value) { text }
+            end
+          end
+        end
+      end
+    end
+  end
+end

lib/superform/rails/field.rb

@@ -55,6 +55,10 @@ def select(*options, multiple: false, **attributes, &)
         )
       end
 
+      def datalist(*options, **attributes, &block)
+        Components::Datalist.new(field, options:, **attributes, &block)
+      end
+
       def errors
         object.errors[key]
       end

spec/superform/rails/datalist_spec.rb

@@ -0,0 +1,68 @@
+RSpec.describe Superform::Rails::Components::Datalist, type: :view do
+  let(:object) { double("object", time_zone: "Pacific Time (US & Canada)") }
+  let(:field) do
+    Superform::Rails::Field.new(:time_zone, parent: nil, object: object)
+  end
+
+  it "renders an input linked to a datalist" do
+    html = render(field.datalist("Eastern", "Central", "Pacific"))
+
+    expect(html).to include('<input')
+    expect(html).to include('list="time_zone_datalist"')
+    expect(html).to include('<datalist id="time_zone_datalist">')
+    expect(html).to include('<option value="Eastern">')
+    expect(html).to include('<option value="Central">')
+    expect(html).to include('<option value="Pacific">')
+  end
+
+  it "sets standard field attributes on the input" do
+    html = render(field.datalist("Eastern"))
+
+    expect(html).to include('id="time_zone"')
+    expect(html).to include('name="time_zone"')
+  end
+
+  it "passes through HTML attributes to the input" do
+    html = render(field.datalist("Eastern", class: "form-input", placeholder: "Start typing..."))
+
+    expect(html).to include('class="form-input"')
+    expect(html).to include('placeholder="Start typing..."')
+  end
+
+  it "accepts value/label pairs" do
+    html = render(field.datalist(["est", "Eastern"], ["cst", "Central"]))
+
+    expect(html).to include('value="est"')
+    expect(html).to include("Eastern")
+    expect(html).to include('value="cst"')
+    expect(html).to include("Central")
+  end
+
+  it "accepts a hash of options" do
+    html = render(field.datalist({ "est" => "Eastern", "cst" => "Central" }))
+
+    expect(html).to include('value="est"')
+    expect(html).to include("Eastern")
+  end
+
+  it "renders with a block for custom options" do
+    component = field.datalist do |d|
+      d.options("Eastern", "Central", "Pacific")
+    end
+    html = render(component)
+
+    expect(html).to include('<input')
+    expect(html).to include('list="time_zone_datalist"')
+    expect(html).to include('<option value="Eastern">')
+    expect(html).to include('<option value="Central">')
+    expect(html).to include('<option value="Pacific">')
+  end
+
+  it "works as a one-liner for time zones" do
+    zones = ["Eastern Time (US & Canada)", "Central Time (US & Canada)", "Pacific Time (US & Canada)"]
+    html = render(field.datalist(*zones))
+
+    expect(html).to include('value="Eastern Time (US & Canada)"')
+    expect(html).to include('value="Pacific Time (US & Canada)"')
+  end
+end