# Search

> One search field and its button in a GET form, for site search and the head of a catalog.

- Block class: `.hs-search`
- CSS: `components/search.css` (also inside https://brand.honorsociety.org/brand.css)
- JS: none
- Status: decided
- Decision record: https://brand.honorsociety.org/decisions/directories-round.html
- Variants: Large, in a page head, Default, in a content band
- HTML page: https://brand.honorsociety.org/components/search/

## What it is

A search field with its button, in a `form role="search"` that submits with GET. The field is the shared form control; the button sits beside it at every width. `--large` is 48px tall for a page head. The field stays white on every ground.

## When to use

- The head of a catalog: the scholarship directory, the benefits list, the site search results page (`--large`, in the [Page head](/components/page-head/)).
- A keyword search inside a content band, above a list (default size).

## When not to use

- To narrow a list by fixed values (type, level, tier): use the [Filter](/components/filter/) panel.
- To switch between a few categories of one short list: use [Filter chips](/components/chips/).
- As a header search on every page: the site header is out of scope here.

## Rules

- Markup: `form.hs-search[role="search"][method="get"]` > `label.hs-visually-hidden` + `input.hs-control.hs-search__input[type="search"]` + `button.hs-button.hs-search__button[type="submit"]`.
- The form submits with GET, so every search has a URL, the back button keeps it and it works without JavaScript. The keyword parameter is `q` unless the page already has one.
- In a page head the search follows the lead, in place of the action row. Its button is the band's gold `.hs-button.hs-search__button`. The site header's Join button is chrome and does not count.
- In a content band the button is navy: `.hs-button.hs-button--navy.hs-search__button`.
- The button label is `Search`. The placeholder shows an example query only ("nursing, study abroad"), never the label.
- Print the current keyword back into `value`, escaped. Never print it unescaped anywhere on the page.
- On a navy ground the field stays white and the button is `.hs-button--on-navy`, or `.hs-button` (gold) only when it is the page's single conversion action.

## Accessibility

- `role="search"` makes the form a search landmark.
- The label is visually hidden but present: it names the field ("Search scholarships"). The button text names the action.
- The field is 40px (48px with `--large`) and 16px text or more, so iOS does not zoom on focus.
- Focus is the shared style: gold outline, navy ring, navy border on the field.
- Field text ink 13.0:1, placeholder slate 6.2:1, border slate 500 3.7:1 on white.

## Variants

### Large, in a page head

The catalog head: eyebrow, H1, lead, then the search. The gold button is the band's one gold element.

```html
<section class="hs-band hs-band--soft hs-page-head" data-section="hero">
  <div class="hs-container">
    <p class="hs-eyebrow">Scholarships</p>
    <h1 class="hs-heading hs-heading--h1 hs-heading--rule">Scholarship directory</h1>
    <p class="hs-lead hs-page-head__lead">Awards from Honor Society&reg; and other providers, each with its own eligibility, deadline and application.</p>
    <form class="hs-search hs-search--large" role="search" method="get" action="/scholarship-directory">
      <label class="hs-visually-hidden" for="search-directory">Search scholarships</label>
      <input class="hs-control hs-search__input" id="search-directory" type="search" name="q" placeholder="nursing, study abroad">
      <button class="hs-button hs-search__button" type="submit">Search</button>
    </form>
  </div>
</section>
```

### Default, in a content band

A keyword search above a list. The navy button leaves the band's gold for its one action.

```html
<form class="hs-search" role="search" method="get" action="/search/node">
  <label class="hs-visually-hidden" for="search-site">Search honorsociety.org</label>
  <input class="hs-control hs-search__input" id="search-site" type="search" name="q" value="leadership">
  <button class="hs-button hs-button--navy hs-search__button" type="submit">Search</button>
</form>
```