Select
Select allows a user to filter through a list of pre-defined sets of options and select one or multiple values.
Usage
<%= render(Impulse::SelectComponent.new(:post, :person_id, Person.all.collect { |p| [p.name, p.id] })) %>Arguments
Positional arguments
| Name | Default | Description |
|---|---|---|
| object_name | N/A | The name of the object. |
| method_name | N/A | The name of the method. |
| choices | [] | An array of choices, similar to what you would pass to the native Rails select tag. |
Keyword arguments
| Name | Default | Description |
|---|---|---|
| selected | nil | The value of the option that you want to force select. |
| size | :md | The size of the select control. One of :sm, :md, or :lg. |
| name | nil | The name of the field. By default, Rails automatically creates a name string based on the object_name and method_name. |
| input_id | nil | The id of the input field. |
| placeholder | nil | The placeholder text that is displayed within the input field. |
| include_hidden | true | Only applies to a multiple select. See the "Gotcha" section of the Rails select tag. |
| disabled | false | Disables the select control. |
| required | false | Makes the select control a required field. |
| multiple | false | Whether multiple values can be selected or not. |
| clearable | true | Whether the clear button should be shown or not. |
| auto_size | true | If 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_padding | 4 | The 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.
<%= 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.
<%= 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.
<%= 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.
<%# 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.
<%
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")) %><%
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.
<%= 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.
<%= 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.
<%= 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:
en:
impulse:
autocomplete:
blankslate: We couldn't find that!Slots
with_option
Customize the options by rendering a collection of the with_option block.
| Name | Default | Description |
|---|---|---|
value | N/A | The value of the option. |
text | N/A | The text of the option. |
description | nil | An 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.
| Name | Default | Description |
|---|---|---|
title | N/A | The 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
import '@ambiki/impulse-view-components/autocomplete';@import '@ambiki/impulse-view-components/autocomplete';The styles need Bootstrap's Sass and the base styles loaded first. See Import the styles.