Skip to content

Select ​

Select allows a user to filter through a list of pre-defined sets of options and select one or multiple values.

Usage ​

erb
<%= render(Impulse::SelectComponent.new(:post, :person_id, Person.all.collect { |p| [p.name, p.id] })) %>

Arguments ​

Positional arguments ​

NameDefaultDescription
object_nameN/AThe name of the object.
method_nameN/AThe name of the method.
choices[]An array of choices, similar to what you would pass to the native Rails select tag.

Keyword arguments ​

NameDefaultDescription
selectednilThe value of the option that you want to force select.
size:mdThe size of the select control. One of :sm, :md, or :lg.
namenilThe name of the field. By default, Rails automatically creates a name string based on the object_name and method_name.
input_idnilThe id of the input field.
placeholdernilThe placeholder text that is displayed within the input field.
include_hiddentrueOnly applies to a multiple select. See the "Gotcha" section of the Rails select tag.
disabledfalseDisables the select control.
requiredfalseMakes the select control a required field.
multiplefalseWhether multiple values can be selected or not.
clearabletrueWhether the clear button should be shown or not.
auto_sizetrueIf true, caps the listbox's height to the space between it and the edge of the viewport, so a long list scrolls instead of running off screen.
auto_size_padding4The space in pixels to keep between the listbox and the edge of the viewport when auto_size is enabled.

Any other keyword arguments are passed to the <awc-autocomplete> element as HTML attributes, except index, namespace, skip_default_ids and allow_method_names_outside_object, which are passed to the Rails field helpers.

Examples ​

Rendering custom options ​

Instead of passing an array of choices to the component, you can also render the options as a block. This provides more flexibility, and you can pass any HTML attributes to each option.

erb
<%= render(Impulse::SelectComponent.new(:post, :person_id)) do |c| %>
  <% Person.all.each do |person| %>
    <% c.with_option(value: person.id, text: person.display_name, disabled: person.on_vacation?) %>
  <% end %>
<% end %>

Selecting an option ​

You can pass the value of the option to the selected argument and it will be selected by default.

erb
<%= render(
  Impulse::SelectComponent.new(
    :user,
    :fruit_id,
    ["Apple", "Mango"],
    selected: "Mango"
  )
) %>

TIP

In case of multiple select, pass an array of values to the selected argument, e.g. ["Apple", "Mango"].

Add inline attributes to options ​

You can optionally provide HTML attributes as the last element of the array.

erb
<%= render(
  Impulse::SelectComponent.new(
    :user,
    :country_id,
    ["Denmark", ["USA", { class: "bold", disabled: true }], "Sweden"]
  )
) %>

WARNING

Do not add "aria-selected" attribute to an option. If you want to select an option, pass the option's value to the selected argument.

Add description to an option ​

You can optionally add an inline description or pass the description attribute to the option slot.

erb
<%# Inline %>
<%= render(
  Impulse::SelectComponent.new(
    :user,
    :country_id,
    [["USA", { description: "USA is a country." }]]
  )
) %>

<%# Block %>
<%= render(Impulse::SelectComponent.new(:user, :country_id)) do |c| %>
  <% Country.all.each do |country| %>
    <% c.with_option(
      value: country.id,
      text: country.display_name,
      description: country.description
    ) %>
  <% end %>
<% end %>

Grouping options ​

Like Rails' grouped_options_for_select, the select component also supports grouping options. You can pass an array or a hash of grouped options.

erb
<%
  grouped_options = [
    ["North America", [["United States", "US"], ["Canada", "CA", {disabled: true}]]],
    ["Europe", ["Denmark", "Germany"]]
  ]
%>

<%= render(Impulse::SelectComponent.new(:user, :country_id, grouped_options, selected: "US")) %>
erb
<%
  grouped_options = {
    "North America" => [["United States", "US"], "Canada"],
    "Europe" => ["Denmark", "Germany"]
  }
%>

<%= render(Impulse::SelectComponent.new(:user, :country_id, grouped_options, selected: "US")) %>

When rendering the options as a block, wrap them in with_group.

erb
<%= render(Impulse::SelectComponent.new(:user, :country_id, selected: "US")) do |c| %>
  <% Continent.all.each do |continent| %>
    <% c.with_group(title: continent.name) do |group| %>
      <% continent.countries.each do |country| %>
        <% group.with_option(value: country.code, text: country.name) %>
      <% end %>
    <% end %>
  <% end %>
<% end %>

Custom blankslate ​

A blankslate is displayed when the input's text does not match any of the options.

erb
<%= render(Impulse::SelectComponent.new(:post, :person_id, Person.all.collect { |p| [p.name, p.id] })) do |c| %>
  <% c.with_blankslate { "We could not find that person in our directory!" } %>
<% end %>

Integrating with form_with ​

Wrap your select tag with the impulse_form_with method. The f.select tag accepts the same arguments, and selects the attribute's value unless you pass selected.

erb
<%= impulse_form_with model: @user do |f| %>
  <%= f.select :person_id, Person.all.collect { |p| [p.name, p.id] } %>
<% end %>

Translations ​

The default blankslate is a translation. Add it for each other locale:

yaml
en:
  impulse:
    autocomplete:
      blankslate: We couldn't find that!

Slots ​

with_option ​

Customize the options by rendering a collection of the with_option block.

NameDefaultDescription
valueN/AThe value of the option.
textN/AThe text of the option.
descriptionnilAn optional secondary description displayed below the option's text.
system_args{}HTML attributes for the slot's element.

with_group ​

Groups options under a title. Add the options with the group's with_option, which takes the same arguments as with_option above. A group with no options isn't rendered.

NameDefaultDescription
titleN/AThe title displayed above the group's options.
system_args{}HTML attributes for the slot's element.

with_blankslate ​

Overwrite the default blankslate message by passing a block. It takes no arguments.

Imports ​

js
import '@ambiki/impulse-view-components/autocomplete';
scss
@import '@ambiki/impulse-view-components/autocomplete';

The styles need Bootstrap's Sass and the base styles loaded first. See Import the styles.

JS API ​

Read here.

Released under the MIT License.