Autocomplete

Offer predictive suggestions while typing your search query.

When to use

Use autocomplete for search features. It's an expected behavior that helps users formulate queries efficiently, reduces typing effort, and improves accuracy by suggesting relevant terms as they type.

How to use

Limit suggestion count. Show 6 or fewer suggestions to reduce the chance of choice paralysis when people read the list.

Setup

Add pennlibs-autocomplete around the target input and related elements.

Set the for attribute where the value is the id of the target input.

Add slot="start" on the input's containing element so that it's placed correctly within the autocomplete.

<pennlibs-autocomplete for="query"> <!-- the id of the input this autocomplete is for -->
  <!-- place the search elements in the start slot for placement -->
  <form slot="start">
    <input type="hidden" value="hidden" name="a-hidden-input" /> <!-- hidden inputs are allowed -->
    <input type="text" placeholder="Search using keywords" value="Typography" id="query" /> <!-- the for target id -->
    <button>Find it</button>
  </form>

  <!-- do not render a listbox when there are no suggestions for the current query -->
</pennlibs-autocomplete>

Offer suggestions

To offer suggestions, render them as a listbox.

Autocomplete will then render these suggestions if the input has focus and when the input value is not empty.

When a suggestion is clicked on or navigated to with arrow keys, pennlibs-autocomplete will set the suggestion's innerText as the input's value. You can override this by using data-pl-value to set the value to something different.

This code is available to view and try out in CodePen

<pennlibs-autocomplete for="query"> <!-- the id of the input this autocomplete is for -->
  <!-- place the search elements in the start slot for placement -->
  <form slot="start">
    <input type="hidden" value="hidden" name="a-hidden-input" /> <!-- hidden inputs are allowed -->
    <input type="text" placeholder="Search using keywords" value="Typography" id="query" /> <!-- the for target id -->
    <button>Find it</button>
  </form>

  <ol role="listbox">
    <!-- use data-pl-value when the query completion is different than the innerText of the option -->
    <li role="option" data-pl-value="Typography"><b>Typography</b> in Title</li>
    <li role="option">The Fundamentals of <b>Typography</b></li>
    <li role="option">Giving type meaning : context and craft in <b>typography</b></li>
    <li role="option">Design elements <b>typography</b> fundamentals : a graphic style manual for understanding how typography affects design</li>
  </ol>
</pennlibs-autocomplete>

Keyboard interactions

The autocomplete supports the following keyboard controls when the input has focus and suggestions are visible:

Down Arrow: Move focus to the next suggestion in the list. If on the last suggestion, wraps to the first.
Up Arrow: Move focus to the previous suggestion in the list. If on the first suggestion, wraps to the last.
Enter: Activate the currently focused suggestion, setting its value in the input and triggering the pl:activated event.
Escape: Close the suggestions list and return focus to the input.
Tab: Close the suggestions list and move focus to the next focusable element.

Take action when a suggestion is activated

The autocomplete has an event pl:activated to listen to if you'd like to take further steps in your application after a user selects a suggestion, such as submiting a search after they click a suggestion.

<script>
  const autocomplete = document.querySelector('pennlibs-autocomplete');

  autocomplete.addEventListener('pl:activated', (event) => {
    console.log('pl:activated:', event.detail);
  });
</script>

When the pl:activated event fires, event.detail contains:

value (string): The text value of the selected suggestion. This respects the data-pl-value attribute if set, otherwise uses the option's innerText.
index (number): The zero-based index of the selected suggestion in the options list.

Relevant guidelines

ARIA: Listbox role — This component uses the semantics of a listbox, which is why autocomplete suggestions are marked up as such.

Attributes

Attribute	Description	Type	Default
`for`	The `id` of the input that this autocomplete is attached to.	`string`

Events

Event	Description
`pl:activated`	Emitted when a user activates (selects) an autocomplete suggestion.

Slots

Slot	Description
`start`	Content to display at the start (top).