1
1
mirror of https://github.com/primer/css.git synced 2024-12-23 22:24:11 +03:00
css/docs/content/components/autocomplete.md
Kate Higa 264a89a51a
More CSS updates to Autocomplete (#2000)
* * change to inline

* * updates to input-group

* * updates to form-group

* * updates to docs with dotcom bugs we saw for validation

* * fix multiplier

* * update accessibility attributes of examples

* fix: adds space

* Create shaggy-birds-marry.md

Co-authored-by: Lindsey Wild <35239154+lindseywild@users.noreply.github.com>
Co-authored-by: Katie Langerman <langermank@github.com>
2022-03-29 13:43:36 -07:00

451 lines
15 KiB
Markdown

---
title: Autocomplete
path: components/autocomplete
status: Stable
source: 'https://github.com/primer/css/tree/main/src/autocomplete'
bundle: autocomplete
---
A list of items used to show autocompleted results. Use the [`<auto-complete>`](https://github.com/github/auto-complete-element) element to add functionality.
## Default (stacked label)
```html live
<div class="position-relative">
<label for="input-0" class="autocomplete-label-stacked">Search by user</label>
<span class="autocomplete-body">
<input id="input-0" class="form-control" type="text" />
<ul role="listbox" aria-label="Results" class="autocomplete-results">
<li class="autocomplete-item" aria-selected="true">Option 1</li>
<li class="autocomplete-item">Option 2</li>
<li class="autocomplete-item">Option 3</li>
</ul>
</span>
</div>
<style>
.frame-example {
height: 160px;
}
</style>
```
## Inline label
**Note**: On smaller screen sizes, the labels will be stacked.
```html live
<div class="position-relative">
<label for="input-1" class="autocomplete-label-inline">Search by team</label>
<span class="autocomplete-body">
<input id="input-1" class="form-control" type="text" />
<ul role="listbox" aria-label="Results" class="autocomplete-results">
<li class="autocomplete-item" aria-selected="true">Team 1 (works on Ruby architecture)</li>
<li class="autocomplete-item">Team 2 (works on frontend JS architecture)</li>
<li class="autocomplete-item">Team 3 (this team works on design systems)</li>
</ul>
</span>
</div>
<style>
.frame-example {
height: 160px;
}
</style>
```
## Embedded icon with visible label
### Stacked label
```html live
<div class="position-relative">
<label for="input-2" class="autocomplete-label-stacked">Search by org</label>
<span class="autocomplete-body">
<div class="form-control autocomplete-embedded-icon-wrap">
<svg
class="octicon"
aria-hidden="true"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 16 16"
width="16"
height="16"
>
<path
fill-rule="evenodd"
d="M11.5 7a4.499 4.499 0 11-8.998 0A4.499 4.499 0 0111.5 7zm-.82 4.74a6 6 0 111.06-1.06l3.04 3.04a.75.75 0 11-1.06 1.06l-3.04-3.04z"
></path>
</svg>
<input id="input-2" class="form-control" type="text" />
</div>
<ul role="listbox" aria-label="Results" class="autocomplete-results">
<li class="autocomplete-item" aria-selected="true">Option 1</li>
<li class="autocomplete-item">Option 2</li>
<li class="autocomplete-item">Option 3</li>
</ul>
</span>
</div>
<style>
.frame-example {
height: 180px;
}
</style>
```
### Inline label
```html live
<div class="position-relative">
<label for="input-3" class="autocomplete-label-inline">Search by org</label>
<span class="autocomplete-body">
<div class="form-control autocomplete-embedded-icon-wrap">
<svg
class="octicon autocomplete-embedded-icon"
aria-hidden="true"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 16 16"
width="16"
height="16"
>
<path
fill-rule="evenodd"
d="M11.5 7a4.499 4.499 0 11-8.998 0A4.499 4.499 0 0111.5 7zm-.82 4.74a6 6 0 111.06-1.06l3.04 3.04a.75.75 0 11-1.06 1.06l-3.04-3.04z"
></path>
</svg>
<input id="input-3" class="form-control" type="text" />
</div>
<ul role="listbox" aria-label="Results" class="autocomplete-results">
<li class="autocomplete-item" aria-selected="true">Option 1</li>
<li class="autocomplete-item">Option 2</li>
<li class="autocomplete-item">Option 3</li>
</ul>
</span>
</div>
<style>
.frame-example {
height: 160px;
}
</style>
```
## Embedded icon with hidden label
```html live
<div class="position-relative">
<label for="input-4" class="autocomplete-label-stacked sr-only">Search by org</label>
<span class="autocomplete-body">
<div class="form-control autocomplete-embedded-icon-wrap">
<svg
aria-hidden="true"
class="octicon autocomplete-embedded-icon"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 16 16"
width="16"
height="16"
>
<path
fill-rule="evenodd"
d="M11.5 7a4.499 4.499 0 11-8.998 0A4.499 4.499 0 0111.5 7zm-.82 4.74a6 6 0 111.06-1.06l3.04 3.04a.75.75 0 11-1.06 1.06l-3.04-3.04z"
></path>
</svg>
<input id="input-4" class="form-control" type="text" />
</div>
<ul role="listbox" aria-label="Results" class="autocomplete-results">
<li class="autocomplete-item" aria-selected="true">Option 1</li>
<li class="autocomplete-item">Option 2</li>
<li class="autocomplete-item">Option 3</li>
</ul>
</span>
</div>
<style>
.frame-example {
height: 160px;
}
</style>
```
## Within form group
```html live
<div class="form-group">
<div class="form-group-body">
<div class="position-relative">
<label for="input-5" class="autocomplete-label-stacked">Search by org</label>
<span class="autocomplete-body">
<div class="form-control autocomplete-embedded-icon-wrap">
<svg
class="octicon"
aria-hidden="true"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 16 16"
width="16"
height="16"
><path
fill-rule="evenodd"
d="M11.5 7a4.499 4.499 0 11-8.998 0A4.499 4.499 0 0111.5 7zm-.82 4.74a6 6 0 111.06-1.06l3.04 3.04a.75.75 0 11-1.06 1.06l-3.04-3.04z"
></path></svg>
<input id="input-5" class="form-control" type="text" />
</div>
<ul role="listbox" aria-label="Results" class="autocomplete-results">
<li class="autocomplete-item" aria-selected="true">Option 1</li>
<li class="autocomplete-item">Option 2</li>
<li class="autocomplete-item">Option 3</li>
</ul>
</span>
</div>
</div>
</div>
<style>
.frame-example {
height: 180px;
}
</style>
```
## Within input group
When rendering `Autocomplete` with embedded icon within an [input group](https://primer.style/css/components/forms#input-group), add `.input-group-button--autocomplete-embedded-icon` to `.input-group-button`.
### Stacked
```html live
<div class="input-group">
<div class="position-relative">
<label for="input-6" class="autocomplete-label-stacked">Search by org</label>
<span class="autocomplete-body">
<div class="form-control autocomplete-embedded-icon-wrap">
<svg
class="octicon"
aria-hidden="true"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 16 16"
width="16"
height="16"
><path
fill-rule="evenodd"
d="M11.5 7a4.499 4.499 0 11-8.998 0A4.499 4.499 0 0111.5 7zm-.82 4.74a6 6 0 111.06-1.06l3.04 3.04a.75.75 0 11-1.06 1.06l-3.04-3.04z"
></path></svg>
<input id="input-6" class="form-control" type="text" />
</div>
<ul role="listbox" aria-label="Results" class="autocomplete-results">
<li class="autocomplete-item" aria-selected="true">Option 1</li>
<li class="autocomplete-item">Option 2</li>
<li class="autocomplete-item">Option 3</li>
</ul>
</span>
</div>
<span class="input-group-button input-group-button--autocomplete-embedded-icon">
<button class="btn" type="button" aria-label="Copy to clipboard">
<svg class="octicon octicon-clippy" viewBox="0 0 14 16" version="1.1" width="14" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M2 13h4v1H2v-1zm5-6H2v1h5V7zm2 3V8l-3 3 3 3v-2h5v-2H9zM4.5 9H2v1h2.5V9zM2 12h2.5v-1H2v1zm9 1h1v2c-.02.28-.11.52-.3.7-.19.18-.42.28-.7.3H1c-.55 0-1-.45-1-1V4c0-.55.45-1 1-1h3c0-1.11.89-2 2-2 1.11 0 2 .89 2 2h3c.55 0 1 .45 1 1v5h-1V6H1v9h10v-2zM2 5h8c0-.55-.45-1-1-1H8c-.55 0-1-.45-1-1s-.45-1-1-1-1 .45-1 1-.45 1-1 1H3c-.55 0-1 .45-1 1z"></path></svg>
</button>
</span>
</div>
<style>
.frame-example {
height: 180px;
}
</style>
```
### Inline
```html live
<div class="input-group">
<div class="position-relative">
<label for="input-7" class="autocomplete-label-inline">Search by org</label>
<span class="autocomplete-body">
<div class="form-control autocomplete-embedded-icon-wrap">
<svg
class="octicon"
aria-hidden="true"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 16 16"
width="16"
height="16"
><path
fill-rule="evenodd"
d="M11.5 7a4.499 4.499 0 11-8.998 0A4.499 4.499 0 0111.5 7zm-.82 4.74a6 6 0 111.06-1.06l3.04 3.04a.75.75 0 11-1.06 1.06l-3.04-3.04z"
></path></svg>
<input id="input-7" class="form-control" type="text" />
</div>
<ul role="listbox" aria-label="Results" class="autocomplete-results">
<li class="autocomplete-item" aria-selected="true">Option 1</li>
<li class="autocomplete-item">Option 2</li>
<li class="autocomplete-item">Option 3</li>
</ul>
</span>
</div>
<span class="input-group-button input-group-button--autocomplete-embedded-icon">
<button class="btn" type="button" aria-label="Copy to clipboard">
<svg class="octicon octicon-clippy" viewBox="0 0 14 16" version="1.1" width="14" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M2 13h4v1H2v-1zm5-6H2v1h5V7zm2 3V8l-3 3 3 3v-2h5v-2H9zM4.5 9H2v1h2.5V9zM2 12h2.5v-1H2v1zm9 1h1v2c-.02.28-.11.52-.3.7-.19.18-.42.28-.7.3H1c-.55 0-1-.45-1-1V4c0-.55.45-1 1-1h3c0-1.11.89-2 2-2 1.11 0 2 .89 2 2h3c.55 0 1 .45 1 1v5h-1V6H1v9h10v-2zM2 5h8c0-.55-.45-1-1-1H8c-.55 0-1-.45-1-1s-.45-1-1-1-1 .45-1 1-.45 1-1 1H3c-.55 0-1 .45-1 1z"></path></svg>
</button>
</span>
</div>
<style>
.frame-example {
height: 160px;
}
</style>
```
## Container with `max-width`
```html live
<div class="Box" style="max-width: 440px;">
<div class="Box-body">
<div class="form-group">
<div class="form-group-body">
<div class="position-relative">
<label for="input-8" class="autocomplete-label-stacked">Search by org</label>
<span class="autocomplete-body">
<div class="form-control autocomplete-embedded-icon-wrap">
<svg
class="octicon"
aria-hidden="true"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 16 16"
width="16"
height="16"
><path
fill-rule="evenodd"
d="M11.5 7a4.499 4.499 0 11-8.998 0A4.499 4.499 0 0111.5 7zm-.82 4.74a6 6 0 111.06-1.06l3.04 3.04a.75.75 0 11-1.06 1.06l-3.04-3.04z"
></path></svg>
<input id="input-8" class="form-control" type="text" />
</div>
<ul role="listbox" aria-label="Results" class="autocomplete-results">
<li class="autocomplete-item" aria-selected="true">Option 1</li>
<li class="autocomplete-item">Option 2</li>
<li class="autocomplete-item">Option 3</li>
</ul>
</span>
</div>
</div>
</div>
</div>
</div>
<style>
.frame-example {
height: 220px;
}
</style>
```
## Additional content
Autocomplete items can contain additional content, like an `.avatar`. Or use utility classes to customize the text style.
```html live
<div class="position-relative">
<input class="form-control" type="text" aria-label="Search by user" placeholder="Search by user" />
<ul role="listbox" aria-label="Results" class="autocomplete-results">
<li class="autocomplete-item" aria-selected="true">
<img src="https://github.com/github.png" width="20" class="avatar mr-1" alt="" />
<span>GitHub Inc.</span>
<span class="text-normal">@github</span>
</li>
<li class="autocomplete-item">
<img src="https://github.com/hubot.png" width="20" class="avatar mr-1" alt="" />
<span>Hubot</span>
<span class="text-normal">@hubot</span>
</li>
<li class="autocomplete-item">
<img src="https://github.com/octocat.png" width="20" class="avatar mr-1" alt="" />
<span>Monalisa Octocat</span>
<span class="text-normal">@octocat</span>
</li>
</ul>
</div>
<style>
.frame-example {
width: 300px;
height: 160px;
}
</style>
```
## Suggester
The `.suggester` component is meant for showing suggestions while typing in a larger text area. Use the [`<text-expander>`](https://github.com/github/text-expander-element) element to add functionality.
```html live
<div class="form-group position-relative">
<textarea class="form-control width-full" placeholder="Leave a comment" aria-label="Comment body">
This is on top of #</textarea
>
<ul aria-label="Results" class="suggester suggester-container" role="listbox" style="top: 4px; left: 125px;">
<li aria-selected="true">
<svg
class="octicon color-fg-subtle"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 16 16"
width="16"
height="16"
>
<path d="M8 9.5a1.5 1.5 0 100-3 1.5 1.5 0 000 3z"></path>
<path fill-rule="evenodd" d="M8 0a8 8 0 100 16A8 8 0 008 0zM1.5 8a6.5 6.5 0 1113 0 6.5 6.5 0 01-13 0z"></path>
</svg>
<small>#924</small> <span>Markdown tables are inaccessible</span>
</li>
<li>
<svg
class="octicon color-fg-success"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 16 16"
width="16"
height="16"
>
<path d="M8 9.5a1.5 1.5 0 100-3 1.5 1.5 0 000 3z"></path>
<path fill-rule="evenodd" d="M8 0a8 8 0 100 16A8 8 0 008 0zM1.5 8a6.5 6.5 0 1113 0 6.5 6.5 0 01-13 0z"></path>
</svg>
<small>#980</small> <span>Use actual book emoji in Flexbox docs</span>
</li>
<li>
<svg
class="octicon color-fg-attention"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 16 16"
width="16"
height="16"
>
<path d="M8 9.5a1.5 1.5 0 100-3 1.5 1.5 0 000 3z"></path>
<path fill-rule="evenodd" d="M8 0a8 8 0 100 16A8 8 0 008 0zM1.5 8a6.5 6.5 0 1113 0 6.5 6.5 0 01-13 0z"></path>
</svg>
<small>#979</small> <span>Add `.radio-group` component</span>
</li>
<li>
<svg
class="octicon color-fg-danger"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 16 16"
width="16"
height="16"
>
<path d="M8 9.5a1.5 1.5 0 100-3 1.5 1.5 0 000 3z"></path>
<path fill-rule="evenodd" d="M8 0a8 8 0 100 16A8 8 0 008 0zM1.5 8a6.5 6.5 0 1113 0 6.5 6.5 0 01-13 0z"></path>
</svg>
<small>#925</small> <span>Release 14.0.0</span>
</li>
<li>
<svg class="octicon color-fg-done" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16">
<path d="M8 9.5a1.5 1.5 0 100-3 1.5 1.5 0 000 3z"></path>
<path fill-rule="evenodd" d="M8 0a8 8 0 100 16A8 8 0 008 0zM1.5 8a6.5 6.5 0 1113 0 6.5 6.5 0 01-13 0z"></path>
</svg>
<small>#978</small> <span>Add `.css-truncate-overflow`</span>
</li>
</ul>
</div>
<style>
.frame-example {
height: 260px;
}
</style>
```