shadcn-rails

Combobox

An autocomplete input with searchable dropdown for selecting from a list of options.

Requires JavaScript

Installation

Add the component to your project:

rails generate shadcn:component combobox

Usage

<%= render Shadcn::ComboboxComponent.new(
  items: [
    { value: "next", label: "Next.js" },
    { value: "remix", label: "Remix" },
    { value: "rails", label: "Ruby on Rails" },
    { value: "nuxt", label: "Nuxt.js" },
    { value: "svelte", label: "SvelteKit" }
  ],
  placeholder: "Select framework...",
  search_placeholder: "Search framework..."
) %>

Examples

Preselected Value

Use the value prop to set an initial selection.

<%= render Shadcn::ComboboxComponent.new(
  items: [
    { value: "next", label: "Next.js" },
    { value: "remix", label: "Remix" },
    { value: "rails", label: "Ruby on Rails" },
    { value: "nuxt", label: "Nuxt.js" },
    { value: "svelte", label: "SvelteKit" }
  ],
  value: "rails",
  placeholder: "Select framework..."
) %>

Form Integration

Use the name prop to enable form submission.

<%= form_with url: "/projects", method: :post do |f| %>
  <div class="space-y-4">
    <%= render Shadcn::LabelComponent.new(for: "framework") { "Framework" } %>
    <%= render Shadcn::ComboboxComponent.new(
      items: [
        { value: "next", label: "Next.js" },
        { value: "remix", label: "Remix" },
        { value: "rails", label: "Ruby on Rails" }
      ],
      name: "project[framework]",
      placeholder: "Select framework..."
    ) %>
    <%= render Shadcn::ButtonComponent.new(type: :submit) { "Create Project" } %>
  </div>
<% end %>

Custom Width

Use the width prop to set a custom width.

<%= render Shadcn::ComboboxComponent.new(
  items: [
    { value: "est", label: "Eastern Standard Time (EST)" },
    { value: "pst", label: "Pacific Standard Time (PST)" },
    { value: "utc", label: "Coordinated Universal Time (UTC)" },
    { value: "gmt", label: "Greenwich Mean Time (GMT)" }
  ],
  placeholder: "Select timezone...",
  width: "w-[300px]"
) %>

Disabled

The combobox can be disabled.

API Reference

ComboboxComponent

API Reference

Prop Type Default Description
items Array<Hash> [] Array of items with :value and :label keys
value String nil Currently selected value
placeholder String "Select option..." Placeholder text when no value selected
search_placeholder String "Search..." Placeholder text for search input
empty_text String "No results found." Text shown when no results match
name String nil Form field name for hidden input
disabled Boolean false Whether the combobox is disabled
width String "w-[200px]" Width class for the component
class_name String nil Additional CSS classes

Item Structure

Each item in the items array should have the following structure:

{ value: "unique-id", label: "Display Text" }

Keyboard Navigation

Key Action
↑ / ↓ Navigate through items
Enter Select the highlighted item
Escape Close the dropdown

Events

The Combobox dispatches a shadcn--combobox:change event when a value is selected.

element.addEventListener("shadcn--combobox:change", (event) => {
  console.log(event.detail.value)  // Selected value
  console.log(event.detail.label)  // Selected label
})

Accessibility

  • Uses role="combobox" on trigger button
  • Uses role="option" for items
  • aria-expanded reflects open state
  • Full keyboard navigation support (Arrow keys, Enter, Escape)
  • Focus is managed within the dropdown when open
  • Clicking outside closes the dropdown