Skip to content

Ajax select

Ajax select allows users to fetch a list of options from the server.

Usage

erb
<%= render(Impulse::AjaxSelectComponent.new(:post, :person_id, :id, :name, src: "/users")) %>

Arguments

Positional arguments

NameDefaultDescription
object_nameN/AThe name of the object.
method_nameN/AThe name of the method.
value_methodN/AThe name of the method that the selected argument responds to.
text_methodN/AThe name of the method that the selected argument responds to.

Keyword arguments

NameDefaultDescription
selectednilThe class instance that should respond to the value_method and text_method as defined in the positional arguments.
srcnilThe endpoint to fetch the options from.
paramqThe param that is appended when making a network request. Example: /fruits?q=Guava.
sizemdThe size of the select control. One of sm, md, or lg.
namenilThe name of the field. By default rails will automatically create 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_hiddentrueSee the "Gotcha" section of 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_sizefalseIf true, the listbox will automatically adjust its height based on its content. This helps avoid scrollbars by fitting the content dynamically.
auto_size_padding4The number of pixels of extra space to add beyond the content's height when auto_size is enabled. Acts as vertical padding.

Note

The server response should include the options that matched the search query.

erb
<%= render(Impulse::Autocomplete::OptionComponent.new(value: "guava", text: "Guava")) %>
<%= render(Impulse::Autocomplete::OptionComponent.new(value: "kiwi", text: "Kiwi")) %>

The Impulse::Autocomplete::OptionComponent also takes an optional description argument.

erb
<%= render(Impulse::Autocomplete::OptionComponent.new(value: "kiwi", text: "Kiwi", description: "This is a fruit.")) %>

Examples

Selecting an option

Pass an object that responds to the value_method and the text_method.

erb
<%= render(
  Impulse::AjaxSelectComponent.new(
    :post,
    :person_id,
    :id,
    :name,
    src: "/persons",
    selected: OpenStruct.new(id: 1, name: "John Doe")
  )
) %>

TIP

In case of multiple select, pass an array of objects to the selected argument.

Custom blankslate

A blankslate is displayed when the input's text does not match any of the options that are returned from the server.

erb
<%= render(Impulse::AjaxSelectComponent.new(:post, :person_id, :id, :name, src: "/persons")) do |c| %>
  <% c.with_blankslate { "We couldn't find what you're looking for!" } %>
<% end %>

Custom error

An error is displayed when the network request fails.

erb
<%= render(Impulse::AjaxSelectComponent.new(:post, :person_id, :id, :name, src: "/persons")) do |c| %>
  <% c.with_error { "An error occurred. Please try again!" } %>
<% end %>

Integrating with form_with

Wrap your ajax_select tag with the impulse_form_with method. The f.ajax_select tag accepts the same arguments.

erb
<%= impulse_form_with model: @user do |f| %>
  <%= f.ajax_select :fruit_id, :id, :name, selected: f.object.fruit, src: "/fruits" %>
<% end %>

Slots

with_blankslate

Overwrite the default blankslate message by passing a custom block.

NameDefaultDescription
system_args{}HTML attributes that should be passed to the Rails' content_tag method.

with_error

Overwrite the default error message by passing a custom block.

NameDefaultDescription
system_args{}HTML attributes that should be passed to the Rails' content_tag method.

Imports

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

JS API

Read here.

Released under the MIT License.