Search

Purpose

A search field is a text input enhanced for finding results. It can be used alone or with a typeahead menu of list items.

Requirements

Due to the complexities involved with its logic, functionality, and animations this component requires both dls.css and dls.js.

Search Input

Usage

A search input does not have a button to perform the search, so it should only be used with a typeahead list of results.

Actionable

The suggested list items are actionable. Navigating with the up ↑ and down ↓ arrow keys updates the entered text.

Example - Simple Results

Copy

<form id="searchfield-default-form" class="searchfield" role="search" data-toggle="searchfield" onsubmit="event.preventDefault();">
    <label class="sr-only" for="searchfield-simple-results">Search</label>
    <input id="searchfield-simple-results" type="search" class="form-control" placeholder="Search" value="layout" autocomplete="off"
    role="combobox" aria-expanded="true" aria-controls="simple-search-results" aria-haspopup="list" aria-autocomplete="list" aria-activedescendant="">
    <span class="icon icon-sm dls-icon-search"></span>
    <button class="btn-form icon icon-hover icon-sm dls-icon-close" aria-label="Clear search" type="button"></button>

    <ul class="search-results" role="listbox" aria-labelledby="searchfield-simple-results" data-always-visible="true" id="simple-search-results">
      <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Layout / Flexbox">
        <a href="#searchfield-default-form" class="link-underlined">Layout / Flexbox</a>
      </li>

      <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Layout / Grid">
        <a href="#searchfield-default-form" class="link-underlined">Layout / Grid</a>
      </li>

      <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Layout / Horizontal Rules">
        <a href="#searchfield-default-form" class="link-underlined">Layout / Horizontal Rules</a>
      </li>

      <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Layout / Units and Measurements">
        <a href="#searchfield-default-form" class="link-underlined">Layout / Units and Measurements</a>
      </li>

      <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Layout / Z Index">
        <a href="#searchfield-default-form" class="link-underlined">Layout / Z Index</a>
      </li>
    </ul>
</form>

Example - No Results

Copy

<form id="searchfield-no-form" class="searchfield" role="search" data-toggle="searchfield" onsubmit="event.preventDefault();">
    <label class="sr-only" for="searchfield-no-results">Search</label>
    <input id="searchfield-no-results" type="search" class="form-control" placeholder="Search" value="VR banking" autocomplete="off"
    role="combobox" aria-expanded="true" aria-controls="no-results" aria-haspopup="list" aria-activedescendant="">
    <span class="icon icon-sm dls-icon-search"></span>
    <button class="btn-form icon icon-hover icon-sm dls-icon-close" aria-label="Clear search" type="button"></button>

    <ul class="search-results" role="listbox" aria-live="polite" aria-labelledby="searchfield-no-results" data-always-visible="true" id="no-results">
        <li class="search-results-item" role="option">
            <p class="no-results-msg text-truncate">No results for "VR banking"</p>
        </li>
      </ul>
</form>

Example - Advanced Results

Deprecated

Copy

<div class="badge badge-text dls-red-bg margin-b">Deprecated</div>

<form id="searchfield-advanced-form" class="searchfield" role="search" data-toggle="searchfield" onsubmit="event.preventDefault();">
    <label class="sr-only" for="searchfield-advanced-results">Search</label>
    <input id="searchfield-advanced-results" type="search" class="form-control" placeholder="Search" value="layout" autocomplete="off"
    role="combobox" aria-expanded="true" aria-controls="advanced-search-results" aria-haspopup="list" aria-autocomplete="list" aria-activedescendant="">
    <span class="icon icon-sm dls-icon-search"></span>
    <button class="btn-form icon icon-hover icon-sm dls-icon-close" aria-label="Clear search" type="button"></button>

    <ul class="search-results" role="listbox" aria-labelledby="searchfield-advanced-results" data-always-visible="true" id="advanced-search-results">
        <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Layout / Flexbox">
          <a href="#searchfield-advanced-form" class="link-underlined">Flexbox</a>
          <p class="text-truncate">Layout / Flexbox</p>
        </li>

        <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Layout / Grid">
          <a href="#searchfield-advanced-form" class="link-underlined">Grid</a>
          <p class="text-truncate">Layout / Grid</p>
        </li>

        <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Layout / Horizontal Rules">
          <a href="#searchfield-advanced-form" class="link-underlined">Horizontal Rules</a>
          <p class="text-truncate">Layout / Horizontal Rules</p>
        </li>

        <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Layout / Units and Measurements">
          <a href="#searchfield-advanced-form" class="link-underlined">Units and Measurements</a>
          <p class="text-truncate">Layout / Units and Measurements</p>
        </li>

        <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Layout / Z Index">
          <a href="#searchfield-advanced-form" class="link-underlined">Z Index</a>
          <p class="text-truncate">Layout / Z Index</p>
        </li>
      </ul>
</form>

Search Input with Button

Usage

The search input with button performs a search after text is entered. It can be used with or without a typeahead menu.

Placeholder Text

When using search at a global level across an entire site the placeholder text should simply be Search. At a smaller component level set context by using more specific language like Search Data Table.

Example - Default

Copy

<form id="searchfield-dropdown-form" class="searchfield searchfield-form" role="search" data-toggle="searchfield" onsubmit="event.preventDefault();">
    <label class="sr-only" for="searchfield4-input" id="searchfield4-label">Search</label>
    <input id="searchfield4-input" type="search" class="form-control" placeholder="Search" autocomplete="off">
    <button class="btn-form icon icon-hover icon-sm dls-icon-close hidden" aria-label="Clear search" type="button"></button>
    <button class="btn-form icon icon-hover icon-sm dls-icon-search searchfield-button" aria-label="Search" type="submit"></button>
</form>

Example - Loading

Copy

<form id="searchfield-loading-form" class="searchfield searchfield-form" role="search" data-toggle="searchfield" onsubmit="event.preventDefault();">
    <label class="sr-only" for="searchfield-loading-input" id="searchfield-loading-label">Search</label>
    <input id="searchfield-loading-input" type="search" class="form-control" placeholder="Search" value="Shop small" autocomplete="off">
    <button class="btn-form icon icon-hover icon-sm dls-icon-close" aria-label="Clear search" type="button"></button>
    <button class="btn-form btn btn-loading btn-tertiary searchfield-button" aria-disabled="true" tabindex="-1"><span aria-live="polite" class="sr-only">Loading</span></button>
</form>

Example - Disabled

Copy

<form id="searchfield-disabled-form" class="searchfield searchfield-form" role="search" data-toggle="searchfield" onsubmit="event.preventDefault();">
    <label class="sr-only" for="searchfield-disabled-input" id="searchfield-disabled-label">Search</label>
    <input id="searchfield-disabled-input" type="search" class="form-control" placeholder="Search" disabled autocomplete="off">
    <button class="btn-form icon icon-hover icon-sm dls-icon-close hidden" aria-label="Clear search" type="button"></button>
    <button class="btn-form btn icon icon-sm dls-icon-search searchfield-button" aria-label="Search" type="submit" disabled></button>
</form>

Example - Simple Autosuggest Results

Copy

<form id="searchfield-results-form" class="searchfield searchfield-form" role="search" data-toggle="searchfield" onsubmit="event.preventDefault();">
    <label class="sr-only" for="searchfield-results-input" id="searchfield-results-label">Search</label>
    <input id="searchfield-results-input" type="search" class="form-control" placeholder="Search" value="Ca" autocomplete="off"
    role="combobox" aria-expanded="true" aria-controls="autosuggest-search-results" aria-haspopup="list" aria-autocomplete="list" aria-activedescendant="">
    <button class="btn-form icon icon-hover icon-sm dls-icon-close" aria-label="Clear search" type="button"></button>
    <button class="btn-form icon icon-hover icon-sm dls-icon-search searchfield-button" aria-label="Search" type="submit"></button>

    <ul class="search-results" role="listbox" aria-labelledby="searchfield-results-label" data-always-visible="true" id="autosuggest-search-results">
      <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Activate Card">
        <a href="#searchfield-results-form" class="link-underlined">Activate Card</a>
      </li>

      <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Activate Gift Card">
        <a href="#searchfield-results-form" class="link-underlined">Activate Gift Card</a>
      </li>

      <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="American Express Gift Card">
        <a href="#searchfield-results-form" class="link-underlined">American Express Gift Card</a>
      </li>

      <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="American Express Travel">
        <a href="#searchfield-results-form" class="link-underlined">American Express Travel</a>
      </li>

      <li class="search-results-item searchfield-suggestion" role="option" data-suggestionvalue="Business Gift Card">
        <a href="#searchfield-results-form" class="link-underlined">Business Gift Card</a>
      </li>
    </ul>
</form>

Search Input with Label

The magnifying glass is universally recognized as a search prompt, so only use a label if it helps explain what is being searched or when alongside other form components.

Do this.

Location

Don't do this.

Copy

<div class="row">
    <div class="col-xs-12 col-md-6 pad-1-b">
        <p class="font-weight-medium dls-green">Do this.</p>

        <div style="max-width: 400px;">
            <label class="label-3 pad-2-t">Location</label>
            <form id="searchfield-dothis-form" class="searchfield searchfield-form" role="search" data-toggle="searchfield" onsubmit="event.preventDefault();">
                <label class="sr-only" for="searchfield-dothis" id="searchfield-dothis-label">Location: Search by city or town</label>
                <input id="searchfield-dothis" type="search" class="form-control" placeholder="Search by city or town" autocomplete="off">
                <button class="btn-form icon icon-hover icon-sm dls-icon-close hidden" aria-label="Clear search" type="button"></button>
                <button class="btn-form icon icon-hover icon-sm dls-icon-search searchfield-button" aria-label="Search" aria-expanded="true" type="submit"></button>
              </form>
          </div>
    </div>

    <div class="col-xs-12 col-md-6">
      <p class="font-weight-medium dls-red">Don't do this.</p>

      <div style="max-width: 400px;">
        <label class="label-3 pad-2-t">Search</label>
        <form id="searchfield-dont-form" class="searchfield searchfield-form" role="search" data-toggle="searchfield" onsubmit="event.preventDefault();">
            <label class="sr-only" for="searchfield-dont" id="searchfield-dont-label">Search</label>
            <input id="searchfield-dont-input" type="search" class="form-control" placeholder="What're you searching for?" autocomplete="off">
            <button class="btn-form icon icon-hover icon-sm dls-icon-close hidden" aria-label="Clear search" type="button"></button>
            <button class="btn-form icon icon-hover icon-sm dls-icon-search searchfield-button" aria-label="Search" aria-expanded="true" type="submit"></button>
            <input class="sr-only" type="submit">
          </form>
      </div>

    </div>
</div>

Functionality

Config	Description	Required
`data-toggle`	Creates a search object, used in a form element; required for functionality using dls.js.	yes
`[type="search"]`	Attribute added to the search input.	yes
`button.dls-icon-close`	Button element with class "dls-icon-close" to have a close button.	no
`.search-results`	The list element with class .search-results containing the search results.	no
`data-suggestionvalue`	The text to show on the input as the suggestions are keyboard-navigated with the arrow keys. Attached to the search suggestion list item.	yes
`data-always-visible`	Used on the search results list to force it to show regardless of user behavior.	no

Standard Search Field

Deprecated

The single icon search field is being deprecated for better accessibility and overall user experience.

Example - Standard Search Field

Copy

<form
    class="search"
    role="search"
    onsubmit="event.preventDefault();"
>
    <label class="sr-only" for="search1">Search</label>
    <input
        id="search1"
        type="search"
        class="form-control"
        placeholder="Search"
    >
    <input class="sr-only" type="submit">
    <button class="btn-form icon icon-hover icon-sm dls-icon-search" aria-label="Clear search" aria-expanded="true"></button>
</form>

Functionality

If you are using dls.js for deprecated search, reference the configs below.

Config Key	Options	Description	Required
`target`	`search element`	Creates a search object; required for functionality using dls.js.	yes
`source`	`JSON Object`	Data source (array of objects with key values) to run search through.	yes
`find`	`function`	Function that takes in the input value as a parameter and returns a regex search pattern to match results against. Default is fuzzy search.	yes
`searchTerm`	`array/string`	Key value from source to search for. If only one search term, use string. Otherwise, use array of strings for multiple search terms. Default is "title."	no
`min`	`number`	Minimum number of characters entered to run search.	no
`limit`	`number`	Limits amount of results displayed to specified number.	no
`typeAhead`	`boolean`	Enables type-ahead functionality where search results populate while the user types. Default is false.	no
`filterResults`	`function`	Further filter search results with own function using parameter "matches" that returns an array of results.	no
`resultTemplate`	`html string`	HTML template for rendering the results; matches `%keys%` in the result data. Default is `<a href="%url%"> %title% </a>`.	no
`resultHeader`	`html string`	Optional result header that populates as the first search results dropdown item. `%value%` available as search input value variable.	no
`resultFooter`	`html string`	Optional result footer that populates as the last search results dropdown item. `%value%` available as search input value variable.	no
`alert`	`string`	Optional message to show when there are no results.	no