Before you implement predictive search, make sure that you’re familiar with the following [user interface (UI)](#ui-requirements) and [accessibility](#accessibility-requirements) requirements, and [user experience (UX)](#ux-best-practices) best practices. These include guidance for displaying products, styling the search field, and creating a search experience that is both accessible and mobile friendly.

You can also refer to [Example search patterns](#example-search-patterns) for example UIs.

## UI requirements

<table>
  <thead>
    <tr>
      <th style="width: 30%;">Requirement</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Number of resources shown</td>
      <td>
        <ul>
        <li>
          The predictive search API by default returns a maximum of ten results across all resource types, so consider tailoring responses to include a mix of resources. For example, a query that matches on both products and pages would return a maximum of ten matching resources across products and pages.
        </li>
        <li>
          Limit the overall number of suggestions to avoid overwhelming the user or taking up too much space on the screen. You can also adjust the number of suggestions to display depending on the context of where they appear. Different suggestions should be labeled uniquely or use distinct styling.
        </li>
        </ul>
      </td>
    </tr>
    <tr>
      <td>Close action</td>
      <td>
        <p>Include a close button, in the form of an icon or text, that leaves the search experience and closes the product suggestion dropdown. This action should not clear the query.</p>
      </td>
    </tr>
    <tr>
      <td>Search action</td>
      <td>
        <p>Include a search button, in the form of an icon or text, that takes the user to the search results page. This should also be able to be achieved by clicking enter on a keyboard, or "go"/"search" on a mobile keyboard.</p>
      </td>
    </tr>
    <tr>
      <td>Clearing query</td>
      <td>
        <p>The query should stay in the search field until the customer explicitly clears the query or navigates to a different page. The searched query should be also repeated on the search results page.</p>
      </td>
    </tr>
    <tr>
      <td>Empty state</td>
      <td>
        <p>Hide the empty-state drop-down when there are no product suggestions that match the query. The lack of feedback from predictive search should encourage customers to continue their search from the results page.</p>
      </td>
    </tr>
    <tr>
      <td>Mobile interactions</td>
      <td>
        <ul>
          <li>
            Focus the search field when tapping on the search icon to reduce the number of interactions required to use search.
          </li>
          <li>
            Make sure that scrolling within the display is not interfered with.
          </li>
        </ul>
      </td>
    </tr>
    <tr>
      <td>Desktop interactions</td>
      <td>
        <ul>
          <li>
            Don’t hide information behind a scroll or use fixed height. Instead, ensure that the height of the dropdown adjusts to display all content.
          </li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

## Accessibility requirements

<table>
  <thead>
    <tr>
      <th style="width: 30%;">Requirement</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Browser and mobile autocomplete</td>
      <td>
        Disable browser-based autocomplete and search history, as well as mobile OS text autocorrect and autocomplete. These kinds of functionality can disrupt the UI through overlays, and the general experience with competing autocomplete logic.
      </td>
    </tr>
  </tbody>
</table>

## UX best practices

<table>
  <thead>
    <tr>
      <th style="width: 30%;">Practice</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Resource information</td>
      <td>
        <p>
          Reduce search interface content and resource data to the minimum amount necessary to make selection meaningful. Using the API, you can control which elements are exposed or hidden, so you can adapt this to the needs of the merchant, however you should consider only exposing the following fields:
        </p>
        <p>
          <strong>Query fields</strong>
          <ul>
            <li>styled_text</li>
          </ul>
          <strong>Product fields</strong>
          <ul>
            <li>image</li>
            <li>product</li>
            <li>title</li>
            <li>price</li>
          </ul>
          <strong>Collection fields</strong>
          <ul>
            <li>title</li>
          </ul>
          <strong>Article fields</strong>
          <ul>
            <li>title</li>
          </ul>
          <strong>Page fields</strong>
          <ul>
            <li>title</li>
          </ul>
        </p>
      </td>
    </tr>
    <tr>
      <td>Query suggestions</td>
      <td>
        <p>As you add query suggestions to your theme, we recommend to highlight the suggested portion instead of what the buyer types. For example, if the buyer types <i>card</i> and the query suggestion is <i>cardigan</i>, then present it as <i>card<b>igan</b></i> instead of <i><b>card</b>igan</i>. This makes it easier for buyers to scan the list of suggestions.</p>
      </td>
    </tr>
    <tr>
      <td>Labels</td>
      <td>
        <p>Only show a "Sold out" label for suggested products when the entire product is unavailable.</p>
        <p>Use a heading to label product suggestions to help users anticipate the type of results they can expect. For example, use a "Products" heading for product suggestions.</p>
      </td>
    </tr>
    <tr>
      <td>Actions</td>
      <td>
        <p>Include a clear button, or text, in the search field to delete any query entered.</p>
      </td>
    </tr>
    <tr>
      <td>Search visibility</td>
      <td>
        <p>Display the search field, or at least the search icon, in the header of all pages. If search is a significant element of the overall experience you want to provide, then make sure that it’s displayed prominently.</p>
        <p>For stores with only one product or a small number of products, the search field can be located within a hamburger menu.</p>
      </td>
    </tr>
    <tr>
      <td>Darken page background</td>
      <td>
        <p>As you design the overall predictive search dropdown, darken other parts of the page background while autocomplete is active to help buyers focus.</p>
      </td>
    </tr>
    <tr>
      <td>"More results" links</td>
      <td>
        <p>
          Display a link in the list of product suggestions to indicate that there might be more results on the search results page.
        </p>
        <p>
          For example, the link could include the text "Search for [your query]", where <code>[your query]</code> is what the user has entered in the search field, or "View all results."
        </p>
      </td>
    </tr>
  </tbody>
</table>

## Example search patterns

The following layouts and patterns can help you implement predictive search effectively in your theme.

* [Desktop: inline search](#desktop-inline-search)
* [Mobile: inline search](#mobile-inline-search)
* [Desktop: in-menu search](#desktop-in-menu-search)
* [Mobile: in-menu search](#mobile-in-menu-search)

### Inline search drop down

#### Desktop: inline search

The search dropdown overlays the page, without taking up too much visual space.

<div class="grid-container grid-container--halves">
  <div class="grid-item grid-item--fluid__half">
  <img src="/assets/themes/desktop-dropdown-inline-01.png" alt="Example of in-line search in desktop.">
  The search bar is visible on the site.
  </div>
  <div class="grid-item grid-item--fluid__half">
  <img src="/assets/themes/desktop-dropdown-inline-02.png" alt="Example of in-line search in desktop.">
  Predictive search appears as a dropdown under the search field.
  </div>
</div>

#### Mobile: inline search

<img src="/assets/themes/mobile-dropdown-inline.png" alt="Example of in-line search in desktop.">

### In-menu search

#### Desktop: in-menu search

The search dropdown overlays the page, without taking up too much visual space.

<div class="grid-container grid-container--halves">
  <div class="grid-item grid-item--fluid__half">
    <img src="/assets/themes/desktop-inmenu-01.png" alt="Example of in-menu search in desktop.">
    No search bar is visible on the site.
  </div>
  <div class="grid-item grid-item--fluid__half">
    <img src="/assets/themes/desktop-inmenu-02.png" alt="Example of in-menu search in desktop.">
    Search appears in the menu.
  </div>
</div>
<br />
<div class="grid-container grid-container--halves">
  <div class="grid-item grid-item--fluid__half">
    <img src="/assets/themes/desktop-inmenu-03.png" alt="Example of in-menu search in desktop.">
    <p>Predictive search results appear under the search field in the menu.</p>
    <p>Alternatively, the search field can be positioned at the top of the menu. In this case, product suggestions would overlay the menu list (see the in-menu mobile example for this layout).</p>
  </div>
  <div class="grid-item grid-item--fluid__half">
  </div>
</div>

#### Mobile: in-menu search

<img src="/assets/themes/mobile-inmenu-01.png" alt="Example of in-menu search on mobile.">