Combobox

Searchable typed choices with distinct display labels and submitted values.

Source
app/components/nitro_kit/combobox.rb
API
NitroKit::Combobox.new(id:, name:, label:, options:, value:)

Selection states

A named native select submits without JavaScript; enhancement adds filtering without a duplicate form value.

Selection matrix

Empty optional
Selected
Required
Disabled
Numeric labels
Viewport640 px · sm
Rubytest/dummy/app/components/gallery/components/combobox_page.rb
sample("Empty optional", slug: "empty") do
  render_combobox("gallery-combobox-empty", placeholder: "Choose a country")
end
sample("Selected", slug: "selected") do
  render_combobox("gallery-combobox-selected", value: "dk")
end
sample("Required", slug: "required") do
  render_combobox("gallery-combobox-required", required: true, placeholder: "Country required")
end
sample("Disabled", slug: "disabled") do
  render_combobox("gallery-combobox-disabled", value: "se", disabled: true)
end
sample("Numeric labels", slug: "numeric-labels") do
  render NitroKit::Combobox.new(
    id: "gallery-combobox-numeric",
    name: "deployment[retry_count]",
    label: "Retry count",
    options: [ [ 1, "one" ], [ 2, "two" ], [ 3, "three" ] ],
    value: "two"
  )
end

Placements and choice pressure

All placements and long labels retain deterministic IDs and native listbox semantics.

Placement matrix

Bottom start
Bottom end
Top start
Top end
Viewport640 px · sm
Rubytest/dummy/app/components/gallery/components/combobox_page.rb
NitroKit::Combobox::PLACEMENTS.each do |placement|
  sample(placement.to_s.humanize, slug: placement.to_s) do
    render NitroKit::Combobox.new(
      id: "gallery-combobox-#{placement}",
      name: "deployment[#{placement}]",
      label: "Deployment environment",
      options: ENVIRONMENTS,
      value: "staging",
      placement:
    )
  end
end

Form composition

The combobox keeps one native select as its submission source alongside ordinary Nitro fields.

Deployment target

Viewport640 px · sm
Rubytest/dummy/app/components/gallery/components/combobox_page.rb
render NitroKit::Card.new(id: "gallery-combobox-deployment-card") do |card|
  card.title("Promote release", level: 3)
  card.body do
    form(id: "gallery-combobox-deployment-form", action: "/gallery/deployments", method: "post") do
      render NitroKit::Field.new(
        nil,
        :release,
        id: "gallery-combobox-release",
        name: "deployment[release]",
        label: "Release",
        value: "2026.07.13",
        readonly: true
      )
      render NitroKit::Combobox.new(
        id: "gallery-combobox-environment",
        name: "deployment[environment]",
        label: "Target environment",
        options: ENVIRONMENTS,
        value: "production",
        required: true
      )
      render NitroKit::Button.new(
        "Promote release",
        id: "gallery-combobox-submit",
        type: :submit,
        variant: :primary
      )
    end
  end
end