Skip to content

AutoComplete

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.

  • Set the label slot to render a visible label. Alternatively, associate an existing visible text element as a label by setting aria-labelledby.
  • If you must use a non-visible label, set :"aria-label" on AutoComplete and Primer will apply it to the correct elements. 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
srcStringN/AThe route to query.
input_idStringN/AId of the input element.
list_idStringN/AId of the list element.
system_argumentsHashN/ASystem arguments

Slots

Label

Optionally render a visible label. See Accessibility

NameTypeDefaultDescription
system_argumentsHashN/ASystem arguments

Input

Required input used to search for results

NameTypeDefaultDescription
typeSymbolN/AOne of :search and :text.
system_argumentsHashN/ASystem arguments

Icon

Optional icon to be rendered before the input. Has the same arguments as Octicon.

Results

Customizable results list.

NameTypeDefaultDescription
system_argumentsHashN/ASystem arguments

Examples

Default

    <%= render(Primer::AutoComplete.new(src: "/auto_complete", input_id: "fruits-input-1", list_id: "fruits-popup-1", position: :relative)) do |c| %>
    <% c.label(classes:"").with_content("Fruits") %>
    <% c.input(type: :text) %>
    <% end %>

    With aria-label

      <%= render(Primer::AutoComplete.new("aria-label": "Fruits", src: "/auto_complete", input_id: "fruits-input-2", list_id: "fruits-popup-2", position: :relative)) do |c| %>
      <% c.input(type: :text) %>
      <% end %>

      With aria-labelledby

      Search

        <%= render(Primer::HeadingComponent.new(tag: :h2, id: "search-1")) { "Search" } %>
        <%= render(Primer::AutoComplete.new(src: "/auto_complete", input_id: "fruits-input-3", list_id: "fruits-popup-2", position: :relative)) do |c| %>
        <% c.input("aria-labelledby": "search-1") %>
        <% end %>

        With custom classes for the results

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

        With Icon

          <%= render(Primer::AutoComplete.new(src: "/auto_complete", list_id: "fruits-popup-4", input_id: "fruits-input-4", position: :relative)) do |c| %>
          <% c.label(classes:"").with_content("Fruits") %>
          <% c.input(type: :text) %>
          <% c.icon(icon: :search) %>
          <% end %>