Skip to content

AutoComplete

Beta
This component requires JavaScript to function. Please refer to the Installation section to set it up.

Use AutoComplete to provide a user with a list of selectable suggestions that appear when they type into the input field. This list is populated by server search results.

Accessibility

Always set an accessible label to help the user interact with the component.

  • label_text is required and visible by default.
  • If you must use a non-visible label, set is_label_visible to false. However, please note that a visible label should almost always be used unless there is compelling reason not to. A placeholder is not a label.

Arguments

NameTypeDefaultDescription
label_textStringN/AThe label of the input.
srcStringN/AThe route to query.
input_idStringN/AId of the input element.
input_nameStringnilOptional name of the input element, defaults to input_id when not set.
list_idStringN/AId of the list element.
with_iconBooleanfalseControls if a search icon is visible, defaults to false.
is_label_visibleBooleantrueControls if the label is visible. If false, screen reader only text will be added.
is_clearableBooleanfalseAdds optional clear button.
is_label_inlineBooleanfalseControls if the label is inline. On smaller screens, label will always become stacked.
system_argumentsHashN/ASystem arguments

Slots

Results

Customizable results list.

NameTypeDefaultDescription
system_argumentsHashN/ASystem arguments

Input

Customizable input used to search for results. It is preferred to use this slot sparingly - it will be created by default if not explicity added.

NameTypeDefaultDescription
system_argumentsHashN/ASystem arguments

Examples

Default

Labels are stacked by default.

    <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--default", list_id: "fruits-popup--default")) %>

    With inline label

    Labels can be inline by setting is_label_inline: true. However, labels will always become stacked on smaller screen sizes.

      <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", is_label_inline: true, input_id: "fruits-input--inline-label", list_id: "fruits-popup--inline-label")) %>

      With non-visible label

      A non-visible label may be rendered with is_label_visible: false, but it is highly discouraged. See Accessibility.

        <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--non-visible-label", list_id: "fruits-popup--non-visible-label", is_label_visible: false)) %>

        With icon

        To display a search icon, set with_icon to true.

          <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", list_id: "fruits-popup--icon", input_id: "fruits-input--icon", with_icon: true)) %>

          With icon and non-visible label

            <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", list_id: "fruits-popup--icon-no-label", input_id: "fruits-input--icon-no-label", with_icon: true, is_label_visible: false)) %>

            With clear button

              <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--clear", list_id: "fruits-popup--clear", is_clearable: true)) %>

              With custom classes for the input

                <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--custom-input", list_id: "fruits-popup--custom-input")) do |c| %>
                <% c.input(classes: "custom-class") %>
                <% end %>

                With custom classes for the results

                • Apple
                • Orange
                <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--custom-results", list_id: "fruits-popup--custom-results")) do |c| %>
                <% c.results(classes: "custom-class") do %>
                <%= render(Primer::Beta::AutoComplete::Item.new(selected: true, value: "apple")) do |c| %>
                Apple
                <% end %>
                <%= render(Primer::Beta::AutoComplete::Item.new(value: "orange")) do |c| %>
                Orange
                <% end %>
                <% end %>
                <% end %>