Reactでinputとdatalistを使って入力候補を出す方法

​​React​HTML,TypeScript,useId,フォーム

入力欄に候補の一覧を出すだけなら、HTML の <datalist> で足ります。<input> の list に <datalist> の id を渡し、<datalist> の中に <option value="…"> を並べると、ブラウザーが入力に合わせて候補を絞り込んで表示します。品種名や都市名の入力欄に、オートコンプリート(サジェスト)を付けたい場面で、コンボボックスを自作せずに済みます。

React では、id を useId で作り、候補の配列を map で <option> にします。候補から選んだ値も、ふつうの onChange で受け取れます。サーバーから取った候補に差し替えると、Chromium 153 では届いた時点で一覧に反映されました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。React 19.3.1、TypeScript 7.0.2、esbuild 0.28.2(開発用ビルド)を使い、tsc で型チェックしてから動かしました。ブラウザーは Playwright 1.63.0 で開いた Chromium 153 です。候補の一覧はページの外に表示されるため、仮想画面(Xvfb)の上で画面を出し、キー入力は xdotool で送りました。Firefox と Safari、スマートフォンのブラウザー、スクリーンリーダーでの読み上げ、日本語入力(IME)での変換中の動きは試していません。

input と datalist を useId で結ぶ

猫の品種を入れる欄に、7つの品種を候補として出す例です。

tsx
// BreedInput.tsx
import { useId, useState } from 'react';

const BREEDS = [
  'アメリカンショートヘア',
  'スコティッシュフォールド',
  'ノルウェージャンフォレストキャット',
  'ベンガル',
  'マンチカン',
  'ラグドール',
  'ロシアンブルー',
];

export function BreedInput() {
  const id = useId();
  const listId = `${id}-list`;
  const [breed, setBreed] = useState('');
  const inList = BREEDS.includes(breed);

  return (
    <div>
      <label htmlFor={id}>猫の品種</label>
      <input
        id={id}
        list={listId}
        value={breed}
        onChange={(e) => setBreed(e.target.value)}
      />
      <datalist id={listId}>
        {BREEDS.map((b) => (
          <option key={b} value={b} />
        ))}
      </datalist>
      <p>
        {breed === '' ? '未入力' : `${breed}(${inList ? '候補にある' : '候補にない'})`}
      </p>
    </div>
  );
}

<input> と <datalist> を結ぶのは、MDN の <datalist> の解説にあるとおり、<datalist> の id と同じ値を <input> の list 属性に書くことです。React の <input> も list を文字列の props として受け取ります。

useId の公式リファレンスにあるとおり、同じ部品が1つの画面に2回以上描画されることもあるので、id を固定の文字列にすると重なってしまいます。そこで useId で作った値に -list を付けています。リファレンスにも、1つの useId の値に文字を足して、関係する複数の要素の ID にする例があります。

<option> の key は、リストの key を useId で作らないようリファレンスに書かれているため、品種名そのものを使います。

ブラウザーでは、次の HTML になりました。input.list で <datalist> 要素が取れたので、ブラウザーも2つを結び付けています。

html
<input id="_r_0_" list="_r_0_-list" value="">
<datalist id="_r_0_-list"><option value="アメリカンショートヘア"></option>…</datalist>

検証環境(Chromium 153)で「ル」と入力すると、名前の先頭ではなく途中に「ル」を含む5つの品種に絞られました。

「ル」と入力した欄の下に、スコティッシュフォールド、ノルウェージャンフォレストキャット、ベンガル、ラグドール、ロシアンブルーの5つが出ている
「ル」と入力して↓キーを押したところ。Chromium 153 で撮影(候補のまわりの黒い縁は、撮影した仮想画面で出たもの)

どう絞り込むか、一覧をどんな見た目で出すかは、ブラウザーが決めます。HTML の仕様では、絞り込むときに value と label の両方から探すことや、大文字と小文字の違いを無視することなどを「推奨」として挙げているだけです(HTML Living Standard の list 属性)。

候補から選んだときの onChange

↓キーで候補を選んで Enter を押すと、入力欄の値が「スコティッシュフォールド」に変わり、onChange が呼ばれて表示も「スコティッシュフォールド(候補にある)」になりました。候補から選んでも、キーボードで打ったときと同じ onChange で受け取れます。

このとき送られた input イベントを、document に付けたリスナーで記録すると、次のようになりました。

text
'InputEvent inputType=insertText value=ル',
'Event inputType=(なし) value=スコティッシュフォールド'

文字を打ったときは InputEvent で inputType が insertText でした。候補から選んだときは、InputEvent ではないただの Event で、inputType がありませんでした。ただし、これは Chromium 153 で見た結果です。HTML 仕様の list 属性の節は、選んだ候補の value を「ユーザーが自分で書いたかのように」入力欄の値にする、と定めているだけです。InputEvent として送るか、inputType に何を入れるかまでは書かれていません。

「候補から選んだか」を知りたいときは、イベントの種類で見分けるより、上の inList のように入力欄の値が候補の配列に入っているかで判断するほうが、ブラウザーの違いに左右されません。

datalist は入力を候補に限らない

候補にない「ミケ」と入力すると、表示は「ミケ(候補にない)」になり、validity.valid は true のままでした。<datalist> は候補を出すだけで、ほかの値を打ち込めなくしたり、フォームの検証で弾いたりはしません。

候補の中からしか選ばせたくないなら、<select> を使うか、送信のときに inList のような判定で値を確かめます。

表示する文字と、送りたい値が違うとき

国の名前を選ばせて、プログラムでは JP のようなコードを使いたい場合を考えます。<option> には value のほかに label を書けるので、value にコード、label に名前を入れる書き方がまず思い浮かびます。

tsx
<datalist id={listId}>
  <option value="JP" label="日本" />
  <option value="FR" label="フランス" />
  <option value="EG" label="エジプト" />
</datalist>

検証環境の Chromium 153 では、一覧にコードと名前が2段で表示され、選ぶと入力欄には JP が入りました。「日本」と打っても候補に出たので、label でも絞り込まれています。

入力欄の下に、JP と日本、FR とフランス、EG とエジプトが2段ずつ並んでいる
value にコード、label に名前を入れた datalist。Chromium 153 では両方が表示された

入力欄に入るのは常に value だと、MDN にも書かれています。ただし一覧に何を表示するかはブラウザーによって違い、MDN には、label やテキストを value の代わりに表示するブラウザー(Firefox)と、value に加えて補足として表示するブラウザー(Chrome、Safari)があると書かれています。どちらにしても、選んだあとの入力欄には「JP」が残ります。利用者に名前を見せたいなら、value に名前を入れ、コードは名前から引き直すほうが分かりやすくなります。

tsx
// CountryInput.tsx
import { useId, useState } from 'react';

const COUNTRIES = [
  { code: 'JP', name: '日本' },
  { code: 'FR', name: 'フランス' },
  { code: 'EG', name: 'エジプト' },
];

export function CountryInput() {
  const id = useId();
  const listId = `${id}-list`;
  const [text, setText] = useState('');
  // 入力欄には名前を入れ、コードは名前から引き直す
  const country = COUNTRIES.find((c) => c.name === text);

  return (
    <div>
      <label htmlFor={id}>国</label>
      <input id={id} list={listId} value={text} onChange={(e) => setText(e.target.value)} />
      <datalist id={listId}>
        {COUNTRIES.map((c) => (
          <option key={c.code} value={c.name} />
        ))}
      </datalist>
      <p>コード:{country ? country.code : 'なし'}</p>
    </div>
  );
}

「フ」と入力して候補の「フランス」を選ぶと、表示は「コード:FR」になりました。

サーバーから取った候補に差し替える

候補が多いときは、入力のたびにサーバーへ問い合わせて、返ってきたものだけを <option> にします。次の例では、サーバーの代わりに、300ミリ秒後に候補を返す searchCities を使っています。

tsx
// CitySearch.tsx
import { useEffect, useId, useState } from 'react';

// 検証用:入力に応じて候補を返す(サーバーへの問い合わせの代わり)
const CITIES = ['札幌', '仙台', '東京', '横浜', '名古屋', '京都', '大阪', '神戸', '広島', '福岡'];
function searchCities(q: string): Promise<string[]> {
  return new Promise((resolve) =>
    setTimeout(() => resolve(CITIES.filter((c) => c.includes(q))), 300),
  );
}

export function CitySearch() {
  const id = useId();
  const listId = `${id}-list`;
  const [query, setQuery] = useState('');
  const [options, setOptions] = useState<string[]>([]);

  useEffect(() => {
    if (query === '') {
      setOptions([]);
      return;
    }
    let ignore = false;
    searchCities(query).then((result) => {
      if (!ignore) setOptions(result);
    });
    return () => {
      ignore = true;
    };
  }, [query]);

  return (
    <div>
      <label htmlFor={id}>都市</label>
      <input id={id} list={listId} value={query} onChange={(e) => setQuery(e.target.value)} />
      <datalist id={listId}>
        {options.map((c) => (
          <option key={c} value={c} />
        ))}
      </datalist>
    </div>
  );
}

ignore は、先に出した問い合わせの結果があとから届いて、新しい結果を上書きしないようにするためのものです。公式リファレンスの、Effect でデータを取得する例と同じ書き方です。

「京」と入力した直後(100ミリ秒後)は <option> が空で、700ミリ秒後には「東京」「京都」の2つになりました。キーを押さずに待っているだけで、届いた候補が一覧に表示されました。↓キーを2回押して Enter を押すと、入力欄は「京都」になりました。選んだことで入力欄の値が変わるので、もう一度問い合わせが走り、候補は「京都」だけに変わっています。

「京」と入力した欄の下に、東京と京都の2つが出ている
「京」と入力して待ったところ。300ミリ秒後に届いた候補が、キーを押さなくても一覧に出た

datalist で足りないとき

<datalist> の一覧は、CSS で見た目をほとんど変えられません。MDN のアクセシビリティの節には、ほかの内容を拡大しても候補の文字の大きさが変わらないこと、ハイコントラストモードに合わせた指定ができないこと、NVDA と Firefox の組み合わせのように候補が読み上げられない環境があることが挙げられています。

候補に画像や説明を並べたい、見た目をサイトに合わせたい、どのブラウザーでも同じ操作にしたい、という場合は、<datalist> を使わず、role="combobox" を付けた入力欄と候補の一覧を自分で作ることになります。その場合のキー操作や読み上げへの対応は、WAI-ARIA Authoring Practices Guide のコンボボックスのパターンにまとめられています。

​Posted by 86