Skip to content
Primer/ViewComponents
Design
Interface guidelinesOcticonsPresentationsCommand lineMobileDesktop
Build
CSSReactReact BrandViewComponents
ContributeAbout
On this page

AutoComplete

Use auto complete to render a text input that allows a user to quickly filter through a list of options to pick one or more values.
  • Beta
  • Not reviewed for accessibility
On this page
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 hide the label, set visually_hide_label to true. 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.
visually_hide_labelBooleanfalseControls if the label is visible. If true, screen reader only text will be added.
show_clear_buttonBooleanfalseAdds optional clear button.
system_argumentsHashN/ASystem arguments
sizeHash:mediumInput size can be small, medium (default), or large
full_widthBooleanfalseInput can be full-width or fit to content
disabledBooleanfalseDisabled input
invalidBooleanfalseInvalid input
placeholderStringnilThe placeholder text displayed within the input
insetBooleanfalsesubtle input background color
monospaceBooleanfalsemonospace input font family

Slots

results

Customizable results list.

NameTypeDefaultDescription
system_argumentsHashN/ASystem arguments

leading_visual

Leading visual.

NameTypeDefaultDescription
system_argumentsHashN/ASame arguments as Octicon.

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

Leading visual

Display any Octicon as a leading visual within the field

    <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", src: "/view-components/rails-app/auto_complete", input_id:"input-id-1", list_id: "list-id-1")) do |component| %>
      <% component.with_leading_visual_icon(icon: :search) %>
    <% end %>

    Trailing action

    Show a clear button

      <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "input-id-2", list_id: "list-id-2", src: "/view-components/rails-app/auto_complete", show_clear_button: true )) %>

      Visually hidden label

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

        <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "fruits-input--custom-results-1", list_id: "fruits-popup--custom-result-1", src: "/view-components/rails-app/auto_complete", visually_hide_label: true)) do |component| %>
          <% component.with_leading_visual_icon(icon: :search) %>
        <% end %>

        Full width field

        To allow field to span width of its container, set full_width to true.

          <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "fruits-input--custom-results-2", list_id: "fruits-popup--custom-results-2", src: "/view-components/rails-app/auto_complete", full_width: true)) do |component| %>
            <% component.with_leading_visual_icon(icon: :search) %>
          <% end %>

          Inset variant

          Use the inset variant to change the input background color to be subtle.

            <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "fruits-input--custom-results-2", list_id: "fruits-popup--custom-results-2", src: "/view-components/rails-app/auto_complete", inset: true)) do |component| %>
              <% component.with_leading_visual_icon(icon: :search) %>
            <% end %>

            Monospace variant

            Use the monospace variant to change the input font family.

              <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "fruits-input--custom-results-2", list_id: "fruits-popup--custom-results-2", src: "/view-components/rails-app/auto_complete", monospace: true)) do |component| %>
                <% component.with_leading_visual_icon(icon: :search) %>
              <% end %>

              With custom classes for the input

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

                With custom classes for the results

                  <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/view-components/rails-app/auto_complete", input_id: "fruits-input--custom-results", list_id: "fruits-popup--custom-results")) do |component| %>
                    <% component.with_results(classes: "custom-class") %>
                  <% end %>
                  Edit this page on GitHub