Select

A button that opens a list of options to choose from.

Installation

Shadwire follows shadcn/ui's open code model: the component's source is copied into your application and becomes yours. Install it with the CLI:

shadwire add select --yes

The select registry item installs these files:

app/components/ui_component.rb
app/components/ui/select_component.rb
app/components/ui/select/trigger_component.rb
app/components/ui/select/value_component.rb
app/components/ui/select/content_component.rb
app/components/ui/select/item_component.rb
app/components/ui/select/group_component.rb
app/components/ui/select/label_component.rb
app/components/ui/select/separator_component.rb
app/components/ui/icon_component.rb
app/helpers/ui/select_helper.rb
app/helpers/ui/icon_helper.rb
app/javascript/controllers/ui_select_controller.js
vendor/shadwire/shadwire.css

This component uses Stimulus, so the application needs importmap-rails and stimulus-rails with automatic controller loading.

Haven't installed the CLI yet? gem install shadwire, then shadwire init.

Usage

The ui-select controller follows the APG select-only combobox pattern: focus stays on the trigger (role="combobox") and the active option is announced through aria-activedescendant. Selecting updates a hidden input and fires change.

<%= ui_select(name: "fruit", placeholder: "Select") do %>
  <%= ui_select_trigger { ui_select_value } %>
  <%= ui_select_content do %>
    <%= ui_select_item(value: "apple") { "Apple" } %>
    <%= ui_select_item(value: "banana") { "Banana" } %>
  <% end %>
<% end %>

Or render the components directly:

<%= render Ui::SelectComponent.new(name: "fruit", value: "banana") do %>
  <%= render Ui::Select::TriggerComponent.new do %>
    <%= render Ui::Select::ValueComponent.new %>
  <% end %>
  <%= render Ui::Select::ContentComponent.new do %>
    <%= render Ui::Select::ItemComponent.new(value: "banana") do %>
      Banana
    <% end %>

<%= render Ui::SelectComponent.new(name: "fruit", value: "banana") do %>
  <%= render Ui::Select::TriggerComponent.new do %>
    <%= render Ui::Select::ValueComponent.new %>
  <% end %>
  <%= render Ui::Select::ContentComponent.new do %>
    <%= render Ui::Select::ItemComponent.new(value: "banana") do %>
      Banana
    <% end %>
  <% end %>
<% end %>

Composition

Select (data-controller="ui-select", hidden input)
|-- Select::Trigger (role="combobox") > Select::Value + chevron
`-- Select::Content (role="listbox")
    `-- Select::Group > Select::Label + Select::Item (role="option")
        Select::Separator

Examples

Default

An APG combobox: focus stays on the trigger, arrows and typeahead navigate, and the active option uses aria-activedescendant.

<%= ui_select(name: "fruit", placeholder: "Pick a fruit", class: "w-[200px]") do %>
  <%= ui_select_trigger(class: "w-full") do %>
    <%= ui_select_value %>
  <% end %>
  <%= ui_select_content do %>
    <%= ui_select_item(value: "apple") { "Apple" } %>
    <%= ui_select_item(value: "banana") { "Banana" } %>
    <%= ui_select_item(value: "blueberry") { "Blueberry" } %>

<%= ui_select(name: "fruit", placeholder: "Pick a fruit", class: "w-[200px]") do %>
  <%= ui_select_trigger(class: "w-full") do %>
    <%= ui_select_value %>
  <% end %>
  <%= ui_select_content do %>
    <%= ui_select_item(value: "apple") { "Apple" } %>
    <%= ui_select_item(value: "banana") { "Banana" } %>
    <%= ui_select_item(value: "blueberry") { "Blueberry" } %>
    <%= ui_select_item(value: "grapes") { "Grapes" } %>
    <%= ui_select_item(value: "pineapple") { "Pineapple" } %>
  <% end %>
<% end %>

Groups

Group options with a label and a separator; items can be disabled.

<%= ui_select(name: "timezone", value: "est", placeholder: "Select a timezone", class: "w-[240px]") do %>
  <%= ui_select_trigger(class: "w-full") do %>
    <%= ui_select_value %>
  <% end %>
  <%= ui_select_content do %>
    <%= ui_select_group do %>
      <%= ui_select_label { "North America" } %>
      <%= ui_select_item(value: "est") { "Eastern Standard Time (EST)" } %>

<%= ui_select(name: "timezone", value: "est", placeholder: "Select a timezone", class: "w-[240px]") do %>
  <%= ui_select_trigger(class: "w-full") do %>
    <%= ui_select_value %>
  <% end %>
  <%= ui_select_content do %>
    <%= ui_select_group do %>
      <%= ui_select_label { "North America" } %>
      <%= ui_select_item(value: "est") { "Eastern Standard Time (EST)" } %>
      <%= ui_select_item(value: "cst") { "Central Standard Time (CST)" } %>
      <%= ui_select_item(value: "pst") { "Pacific Standard Time (PST)" } %>
    <% end %>
    <%= ui_select_separator %>
    <%= ui_select_group do %>
      <%= ui_select_label { "Europe" } %>
      <%= ui_select_item(value: "gmt") { "Greenwich Mean Time (GMT)" } %>
      <%= ui_select_item(value: "cet", disabled: true) { "Central European Time (CET)" } %>
    <% end %>
  <% end %>
<% end %>

With form_with

The value is sent in a hidden input (name:). The native required attribute does not apply, so validate on the server.

<%= form_with url: "#", scope: :profile do |form| %>
  <div class="grid w-[240px] gap-2">
    <%= ui_label(for: "profile-role-trigger") { "Role" } %>
    <%= ui_select(name: form.field_name(:role), value: "member", placeholder: "Select", class: "w-full") do %>
      <%= ui_select_trigger(id: "profile-role-trigger", class: "w-full") do %>
        <%= ui_select_value %>
      <% end %>
      <%= ui_select_content do %>

<%= form_with url: "#", scope: :profile do |form| %>
  <div class="grid w-[240px] gap-2">
    <%= ui_label(for: "profile-role-trigger") { "Role" } %>
    <%= ui_select(name: form.field_name(:role), value: "member", placeholder: "Select", class: "w-full") do %>
      <%= ui_select_trigger(id: "profile-role-trigger", class: "w-full") do %>
        <%= ui_select_value %>
      <% end %>
      <%= ui_select_content do %>
        <%= ui_select_item(value: "admin") { "Admin" } %>
        <%= ui_select_item(value: "member") { "Member" } %>
        <%= ui_select_item(value: "guest") { "Guest" } %>
      <% end %>
    <% end %>
    <p class="text-sm text-muted-foreground">
      The value is submitted through a hidden input — validate on the server.
    </p>
  </div>
<% end %>

API reference

Every part accepts class / class_name and **attrs.

Component	Argument	Default	Description
`Select`	`name`	`nil`	The hidden input's name, for form submission.
`Select`	`value`	`nil`	The value selected at first.
`Select`	`placeholder`	`nil`	The text shown when nothing is selected.
`Select::Trigger`	`size`	`:default`	`:default` or `:sm`.
`Select::Item`	`value:` (required), `disabled`	—	The option's value; disabled items are skipped during navigation.