Webパーツ辞典

オートコンプリートAutocomplete

入力しかけた文字から候補を下に出し、選ばせる入力欄。駅名や商品名のように、正しい書き方を思い出しにくい値に使う。

表示例

  • 渋谷(しぶや)
  • 渋川(しぶかわ)
  • 志布志(しぶし)

候補 3件

別名・英語表記

  • サジェスト
  • 入力補完
  • オートサジェスト
  • 入力候補
  • 検索候補
  • タイプアヘッド
  • コンボボックス(入力式)
  • Autosuggest
  • Autocomplete

実装例

<div class="x-autocomplete">
  <label class="x-autocomplete__l" for="x-autocomplete-i">駅名</label>
  <!-- 見本なので候補を開いた状態。閉じるときは listbox に hidden を付け、aria-expanded を false にする -->
  <input class="x-autocomplete__i" id="x-autocomplete-i" type="text" name="station" value="しぶ"
         role="combobox" aria-autocomplete="list" aria-expanded="true"
         aria-controls="x-autocomplete-list" aria-activedescendant="x-autocomplete-o1" autocomplete="off">
  <ul class="x-autocomplete__list" id="x-autocomplete-list" role="listbox" aria-label="駅名の候補">
    <li class="x-autocomplete__o" id="x-autocomplete-o1" role="option" aria-selected="true">渋谷(しぶや)</li>
    <li class="x-autocomplete__o" id="x-autocomplete-o2" role="option" aria-selected="false">渋川(しぶかわ)</li>
    <li class="x-autocomplete__o" id="x-autocomplete-o3" role="option" aria-selected="false">志布志(しぶし)</li>
  </ul>
  <p class="x-autocomplete__n" role="status">候補 3件</p>
</div>

AIへの指示文

「オートコンプリート(Autocomplete)」を実装してください。

## これは何か
入力しかけた文字から候補を下に出し、選ばせる入力欄。駅名や商品名のように、正しい書き方を思い出しにくい値に使う。

## 使いどころ
- 選択肢が数百件以上あり、セレクトボックスでは探しきれないとき(駅名・住所・商品名)
- 表記ゆれを防ぎたいとき(「渋谷」「澁谷」「しぶや」を1つの値にそろえる)
- 検索ボックスで、よく検索される語を先に見せたいとき

## 実装の要件
- label + input[role=combobox][aria-autocomplete=list][aria-expanded][aria-controls][aria-activedescendant] + ul[role=listbox] > li[role=option]
- 候補リストは入力欄の直下に position: absolute で重ね、候補の外を押したら閉じる
- 手軽に済ませるなら input の list 属性と datalist 要素でも候補を出せる。ただし候補の見た目は変えられず、読み上げの挙動もブラウザごとに差がある
- 候補から選ばないと送信できない形にするか、自由入力も受け付けるかを先に決める。あいまいにすると「選んだつもりが選べていない」が起きる
- 日本語の変換中(IME の確定前)に Enter・上下の矢印キー・Esc を奪わない。keydown で event.isComposing が true か event.keyCode が 229 のときは、preventDefault も呼ばずにそのまま return する
- Safari 26 以前は変換を確定する Enter で isComposing が false になり、keyCode 229 でしか見分けられない
- 1文字ごとにサーバーへ問い合わせない。入力が止まってから(150〜300ms ほど)問い合わせ、遅れて届いた古い応答で新しい候補を上書きしない
- ブラウザ自身の入力履歴が候補に重なって出るので、入力欄には autocomplete="off" を付ける。HTML の autocomplete 属性はブラウザの自動入力の指定で、この部品とは別物

## アクセシビリティの要件
- 入力欄に role="combobox"・aria-autocomplete="list"・aria-expanded・aria-controls(候補リストの id)を付ける。候補は role="listbox" と role="option" にする
- フォーカスは入力欄に置いたまま、上下の矢印キーで選びかけの候補を動かし、その候補を aria-activedescendant で指す。指している候補には aria-selected="true" を付ける
- Enter で確定、Esc で候補を閉じる。閉じたら aria-expanded を false に戻す
- 候補の件数を role="status" で控えめに伝える。0件のときも「候補はありません」と伝える
- 選びかけの候補を色だけで示さない。背景に加えて、線や太字でも示す

## 参考にする実装
この形を出発点にして、プロジェクトの命名規則・色・余白に合わせて調整してください。

```html
<div class="x-autocomplete">
  <label class="x-autocomplete__l" for="x-autocomplete-i">駅名</label>
  <!-- 見本なので候補を開いた状態。閉じるときは listbox に hidden を付け、aria-expanded を false にする -->
  <input class="x-autocomplete__i" id="x-autocomplete-i" type="text" name="station" value="しぶ"
         role="combobox" aria-autocomplete="list" aria-expanded="true"
         aria-controls="x-autocomplete-list" aria-activedescendant="x-autocomplete-o1" autocomplete="off">
  <ul class="x-autocomplete__list" id="x-autocomplete-list" role="listbox" aria-label="駅名の候補">
    <li class="x-autocomplete__o" id="x-autocomplete-o1" role="option" aria-selected="true">渋谷(しぶや)</li>
    <li class="x-autocomplete__o" id="x-autocomplete-o2" role="option" aria-selected="false">渋川(しぶかわ)</li>
    <li class="x-autocomplete__o" id="x-autocomplete-o3" role="option" aria-selected="false">志布志(しぶし)</li>
  </ul>
  <p class="x-autocomplete__n" role="status">候補 3件</p>
</div>
```

```css
/* 貼った先のリセットに頼らないよう、この部品の中だけ border-box にする */
.x-autocomplete,
.x-autocomplete *:not([class*="fa-"]),
.x-autocomplete *:not([class*="fa-"])::before,
.x-autocomplete *:not([class*="fa-"])::after {
  box-sizing: border-box;
  /* 貼った先の既定の書体に引きずられないようにする。書体が変わると
     文字の幅と高さが変わり、枠のサイズまでずれる */
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Hiragino Sans", "Noto Sans JP", "Yu Gothic UI", Meiryo, sans-serif;
}

.x-autocomplete {
  position: relative;
  width: 250px;
}
.x-autocomplete__l {
  display: block;
  margin-bottom: 6px;
  font-size: 12px;
  font-weight: 700;
}
.x-autocomplete__i {
  width: 100%;
  height: 44px;
  padding: 0 12px;
  border: 1px solid #7f8a99;
  border-radius: 8px;
  background: #fff;
  color: #1b2028;
  font: inherit;
  font-size: 14px;
}
.x-autocomplete__i:focus-visible {
  outline: 2px solid #1d4ed8;
  outline-offset: 1px;
}
/* 実際のページでは position: absolute で下の本文に重ねる。見本は流れの中に置いている */
.x-autocomplete__list {
  margin: 4px 0 0;
  padding: 4px 0;
  list-style: none;
  border: 1px solid #7f8a99;
  border-radius: 8px;
  background: #fff;
  box-shadow: 0 6px 16px rgba(27, 32, 40, .12);
}
.x-autocomplete__o {
  display: flex;
  align-items: center;
  min-height: 36px;
  padding: 0 12px;
  border-left: 3px solid transparent;
  color: #1b2028;
  font-size: 13px;
  cursor: pointer;
}
/* いま選びかけている候補。色だけにせず、左の線でも示す */
.x-autocomplete__o[aria-selected="true"] {
  border-left-color: #1d4ed8;
  background: #e8efff;
  font-weight: 700;
}
.x-autocomplete__n {
  margin: 6px 0 0;
  font-size: 11px;
  color: #5b6472;
}
```

## 出力の約束
- HTML と CSS を分けて出す。JavaScript が要るときは素の JavaScript で書き、UIフレームワークは使わない。
- 参考実装がアイコンに Font Awesome のクラスを使っている場合は、プロジェクトで使っているアイコンかインライン SVG に置き換えてよい。
- 上のアクセシビリティ要件を満たす。満たせない箇所があるときは、理由を添えて先に知らせる。
- 色・角丸・余白は既存のデザイントークンがあればそれを使う。無ければ CSS 変数として切り出す。

使いどころ

  • 選択肢が数百件以上あり、セレクトボックスでは探しきれないとき(駅名・住所・商品名)
  • 表記ゆれを防ぎたいとき(「渋谷」「澁谷」「しぶや」を1つの値にそろえる)
  • 検索ボックスで、よく検索される語を先に見せたいとき

注意点

  • 候補から選ばないと送信できない形にするか、自由入力も受け付けるかを先に決める。あいまいにすると「選んだつもりが選べていない」が起きる
  • 日本語の変換中(IME の確定前)に Enter・上下の矢印キー・Esc を奪わない。keydown で event.isComposing が true か event.keyCode が 229 のときは、preventDefault も呼ばずにそのまま return する
  • Safari 26 以前は変換を確定する Enter で isComposing が false になり、keyCode 229 でしか見分けられない
  • 1文字ごとにサーバーへ問い合わせない。入力が止まってから(150〜300ms ほど)問い合わせ、遅れて届いた古い応答で新しい候補を上書きしない
  • ブラウザ自身の入力履歴が候補に重なって出るので、入力欄には autocomplete="off" を付ける。HTML の autocomplete 属性はブラウザの自動入力の指定で、この部品とは別物

アクセシビリティの要点

  • 入力欄に role="combobox"・aria-autocomplete="list"・aria-expanded・aria-controls(候補リストの id)を付ける。候補は role="listbox" と role="option" にする
  • フォーカスは入力欄に置いたまま、上下の矢印キーで選びかけの候補を動かし、その候補を aria-activedescendant で指す。指している候補には aria-selected="true" を付ける
  • Enter で確定、Esc で候補を閉じる。閉じたら aria-expanded を false に戻す
  • 候補の件数を role="status" で控えめに伝える。0件のときも「候補はありません」と伝える
  • 選びかけの候補を色だけで示さない。背景に加えて、線や太字でも示す

作るときに使えるツール

見分け方

関連するパーツ