Skip to main content

Auto suggest

Auto suggest consists of a text field that triggers a list of suggestions when the user starts typing.

Example

Auto suggest on a default theme (type 'd' to test)

Best practices

Auto suggest is generally associated with search scenarios, but can be used anytime the user is expected to type a string and the back-end (not the framework) can predict what that string might be via the browser history or a curated set of search terms.

Do

  • When using auto suggest to perform searches and no search results exist for the entered text, display a single-line "No results" message in the list of suggestions so that the user knows his search request successfully executed.
  • In the search scenario, the back-end code could draw suggested search terms from a number of sources, such as: a database of curated sets of search terms, previously-entered terms, cookies, and so on. All of which would be handled by the consuming team, not the framework.
  • Search result list is typically ordered by relevance to the typed string.

Don’t

  • Don’t use when the list is pre-determined. Use a combo component instead.

Also known as

Auto suggest box
Incremental search
Multi-suggest
Real-time suggestion
Search results

Related

Combo
Glyphs
Menu
Menu Item
Search
Text field

Options

  • Position: Change the position by adding a data attribute for data-js-auto-suggest-position="default" or data-js-auto-suggest-position="above".
  • Scrollable: Add a class name f-auto-suggest-scroll to make the suggestion menu scrollable after the result limit has been reached.
  • Result Count: The results can be configured in the JavaScript module named AutoSuggest.js
  • No Results: When no results are returned from the server the style will be udpated to notify the user.

Development

  • JavaScript: Scripting documentation defines how to handle this module through JavaScript.
  • Schema definition: The auto-suggest schema defines the acceptable configurations, requirements, and options for each module.

Code and preview

Search with auto suggest (type 'd' to test)

<form class="c-search" autocomplete="off" name="form1" target="_self" role="combobox" aria-expanded="false">
    <input aria-label="Enter your search" aria-controls="auto-suggest-default-2" aria-autocomplete="list" type="search" name="search-field" role="searchbox" placeholder="Search">
    <button class="c-glyph" name="search-button">
        <span class="x-screen-reader">Search</span>
    </button>
    <div class="m-auto-suggest" id="auto-suggest-default-2" role="group">
        <ul class="c-menu" aria-hidden="true" data-js-auto-suggest-position="default" tabindex="0" role="listbox">
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">dynamics crm</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">dynamics crm clari</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">dynamicus qui sequitur est mirum notare quam littera</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">dynamosaurus</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">dynamosaurusraptor</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <a href="#" class="f-product" tabindex="0">
                    <img class="c-image" src="//placehold.it/60x60" alt="movie">
                    <div>
                        <span>Dynamics CRM</span>
                        <span class="c-meta-text">Apps</span>
                    </div>
                </a>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <a href="#" class="f-product" tabindex="0">
                    <img class="c-image" src="//placehold.it/60x60" alt="movie">
                    <div>
                        <span>Dynamics CRM album</span>
                        <span class="c-meta-text">Albums</span>
                    </div>
                </a>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <a href="#" class="f-product" tabindex="0">
                    <img class="c-image" src="//placehold.it/60x60" alt="movie">
                    <div>
                        <span>Dynamic artist</span>
                        <span class="c-meta-text">Artists</span>
                    </div>
                </a>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <a href="#" class="f-product" tabindex="0">
                    <img class="c-image" src="//store-images.microsoft.com/image/apps.6221.9007199266252643.9e83943d-d51f-4371-8567-06e1e21ced31.e47a968c-b6a8-490a-819e-70a7fc0c7933?w=100&amp;h=100" alt="app">
                    <div>
                        <span>Dynamic transparent</span>
                        <span class="c-meta-text">Apps</span>
                    </div>
                </a>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <a href="#" class="f-product" tabindex="0">
                    <img class="c-image" src="//placehold.it/60x60" alt="artist">
                    <div>
                        <span>Dynamic no category</span>
                        <span class="c-meta-text"></span>
                    </div>
                </a>
            </li>
        </ul>
        <ul class="c-menu f-auto-suggest-no-results" aria-hidden="true" data-js-auto-suggest-position="default" tabindex="0">
            <li class="c-menu-item">
                <span tabindex="-1">No results</span>
            </li>
        </ul>
    </div>
</form>

Search with auto suggest and scroll (type 'a' to test)

<form class="c-search" autocomplete="off" name="form1" target="_self" role="combobox" aria-expanded="false">
    <input aria-label="Enter your search" aria-controls="auto-suggest-above-1" aria-autocomplete="list" type="search" name="search-field" role="searchbox" placeholder="Search">
    <button class="c-glyph" name="search-button">
        <span class="x-screen-reader">Search</span>
    </button>
    <div class="m-auto-suggest" id="auto-suggest-above-1" role="group">
        <ul class="c-menu f-auto-suggest-scroll" aria-hidden="true" data-js-auto-suggest-position="above" tabindex="0" role="listbox">
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">additional</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">addictions</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">addressing</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">adductive</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">additory</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">addable</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">adducing</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">addresee</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <span tabindex="0">addressor</span>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <a href="#" class="f-product" tabindex="0">
                    <img class="c-image" src="//placehold.it/60x60" alt="artist">
                    <div>
                        <span>Dynamics CRM</span>
                        <span class="c-meta-text">Apps</span>
                    </div>
                </a>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <a href="#" class="f-product" tabindex="0">
                    <img class="c-image" src="//placehold.it/60x60" alt="album">
                    <div>
                        <span>Dynamics CRM album</span>
                        <span class="c-meta-text">Albums</span>
                    </div>
                </a>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <a href="#" class="f-product" tabindex="0">
                    <img class="c-image" src="//placehold.it/60x60" alt="artist">
                    <div>
                        <span>Dynamic artist</span>
                        <span class="c-meta-text">Artists</span>
                    </div>
                </a>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <a href="#" class="f-product" tabindex="0">
                    <img class="c-image" src="//store-images.microsoft.com/image/apps.6221.9007199266252643.9e83943d-d51f-4371-8567-06e1e21ced31.e47a968c-b6a8-490a-819e-70a7fc0c7933?w=100&amp;h=100" alt="app">
                    <div>
                        <span>Dynamic transparent</span>
                        <span class="c-meta-text">Apps</span>
                    </div>
                </a>
            </li>
            <li class="c-menu-item" role="option" aria-selected="false">
                <a href="#" class="f-product" tabindex="0">
                    <img class="c-image" src="//placehold.it/60x60" alt="product">
                    <div>
                        <span>Dynamic no category</span>
                        <span class="c-meta-text"></span>
                    </div>
                </a>
            </li>
        </ul>
        <ul class="c-menu f-auto-suggest-no-results" aria-hidden="true" data-js-auto-suggest-position="above" tabindex="0">
            <li class="c-menu-item">
                <span tabindex="-1">No results</span>
            </li>
        </ul>
    </div>
</form>