Autocomplete

Autocompleteは、ユーザーのテキスト入力に応じて候補を表示するために使用されるコンポーネントです。

<Autocomplete.Root placeholder="Select a digimon">
  <Autocomplete.Option value="アグモン">アグモン</Autocomplete.Option>
  <Autocomplete.Option value="ガブモン">ガブモン</Autocomplete.Option>
  <Autocomplete.Option value="テントモン">テントモン</Autocomplete.Option>
  <Autocomplete.Option value="ピヨモン">ピヨモン</Autocomplete.Option>
  <Autocomplete.Option value="ゴマモン">ゴマモン</Autocomplete.Option>
  <Autocomplete.Option value="パルモン">パルモン</Autocomplete.Option>
  <Autocomplete.Option value="パタモン">パタモン</Autocomplete.Option>
  <Autocomplete.Option value="テイルモン">テイルモン</Autocomplete.Option>
</Autocomplete.Root>

使い方

import { Autocomplete } from "@yamada-ui/react"

import { Autocomplete } from "@/components/ui"

import { Autocomplete } from "@workspaces/ui"

<Autocomplete.Root>
  <Autocomplete.Group>
    <Autocomplete.Label />
    <Autocomplete.Option />
  </Autocomplete.Group>
</Autocomplete.Root>

グループ化する

<Autocomplete.Root placeholder="Select a digimon">
  <Autocomplete.Group>
    <Autocomplete.Label>成長期</Autocomplete.Label>
    <Autocomplete.Option value="アグモン">アグモン</Autocomplete.Option>
    <Autocomplete.Option value="ガブモン">ガブモン</Autocomplete.Option>
    <Autocomplete.Option value="テントモン">テントモン</Autocomplete.Option>
    <Autocomplete.Option value="ピヨモン">ピヨモン</Autocomplete.Option>
    <Autocomplete.Option value="ゴマモン">ゴマモン</Autocomplete.Option>
    <Autocomplete.Option value="パルモン">パルモン</Autocomplete.Option>
    <Autocomplete.Option value="パタモン">パタモン</Autocomplete.Option>
    <Autocomplete.Option value="テイルモン">テイルモン</Autocomplete.Option>
  </Autocomplete.Group>

  <Autocomplete.Group label="成熟期">
    <Autocomplete.Option value="グレイモン">グレイモン</Autocomplete.Option>
    <Autocomplete.Option value="ガルルモン">ガルルモン</Autocomplete.Option>
    <Autocomplete.Option value="カブテリモン">カブテリモン</Autocomplete.Option>
    <Autocomplete.Option value="バードラモン">バードラモン</Autocomplete.Option>
    <Autocomplete.Option value="イッカクモン">イッカクモン</Autocomplete.Option>
    <Autocomplete.Option value="トグモン">トグモン</Autocomplete.Option>
    <Autocomplete.Option value="エンジェモン">エンジェモン</Autocomplete.Option>
  </Autocomplete.Group>

  <Autocomplete.Group label="完全体">
    <Autocomplete.Option value="メタルグレイモン">
      メタルグレイモン
    </Autocomplete.Option>
    <Autocomplete.Option value="ワーガルルモン">
      ワーガルルモン
    </Autocomplete.Option>
    <Autocomplete.Option value="アトラーカブテリモン">
      アトラーカブテリモン
    </Autocomplete.Option>
    <Autocomplete.Option value="ガルダモン">ガルダモン</Autocomplete.Option>
    <Autocomplete.Option value="ズドモン">ズドモン</Autocomplete.Option>
    <Autocomplete.Option value="リリモン">リリモン</Autocomplete.Option>
    <Autocomplete.Option value="ホーリーエンジェモン">
      ホーリーエンジェモン
    </Autocomplete.Option>
    <Autocomplete.Option value="エンジェウーモン">
      エンジェウーモン
    </Autocomplete.Option>
  </Autocomplete.Group>

  <Autocomplete.Group label="究極体">
    <Autocomplete.Option value="ウォーグレイモン">
      ウォーグレイモン
    </Autocomplete.Option>
    <Autocomplete.Option value="メタルガルルモン">
      メタルガルルモン
    </Autocomplete.Option>
    <Autocomplete.Option value="ヘラクルカブテリモン">
      ヘラクルカブテリモン
    </Autocomplete.Option>
    <Autocomplete.Option value="ホウオウモン">ホウオウモン</Autocomplete.Option>
    <Autocomplete.Option value="ヴァイクモン">ヴァイクモン</Autocomplete.Option>
    <Autocomplete.Option value="ロゼモン">ロゼモン</Autocomplete.Option>
    <Autocomplete.Option value="ゴッドドラモン">
      ゴッドドラモン
    </Autocomplete.Option>
    <Autocomplete.Option value="ホーリードラモン">
      ホーリードラモン
    </Autocomplete.Option>
  </Autocomplete.Group>
</Autocomplete.Root>

itemsを使う

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "オメガモン", value: "オメガモン" },
    { label: "ディアボロモン", value: "ディアボロモン" },
    {
      items: [
        { label: "アグモン", value: "アグモン" },
        { label: "ガブモン", value: "ガブモン" },
        { label: "テントモン", value: "テントモン" },
        { label: "ピヨモン", value: "ピヨモン" },
        { label: "ゴマモン", value: "ゴマモン" },
        { label: "パルモン", value: "パルモン" },
        { label: "パタモン", value: "パタモン" },
        { label: "テイルモン", value: "テイルモン" },
      ],
      label: "成長期",
    },
    {
      items: [
        { label: "グレイモン", value: "グレイモン" },
        { label: "ガルルモン", value: "ガルルモン" },
        { label: "カブテリモン", value: "カブテリモン" },
        { label: "バードラモン", value: "バードラモン" },
        { label: "イッカクモン", value: "イッカクモン" },
        { label: "トグモン", value: "トグモン" },
        { label: "エンジェモン", value: "エンジェモン" },
      ],
      label: "成熟期",
    },
    {
      items: [
        { label: "メタルグレイモン", value: "メタルグレイモン" },
        { label: "ワーガルルモン", value: "ワーガルルモン" },
        { label: "アトラーカブテリモン", value: "アトラーカブテリモン" },
        { label: "ガルダモン", value: "ガルダモン" },
        { label: "ズドモン", value: "ズドモン" },
        { label: "リリモン", value: "リリモン" },
        { label: "ホーリーエンジェモン", value: "ホーリーエンジェモン" },
        { label: "エンジェウーモン", value: "エンジェウーモン" },
      ],
      label: "完全体",
    },
    {
      items: [
        { label: "ウォーグレイモン", value: "ウォーグレイモン" },
        { label: "メタルガルルモン", value: "メタルガルルモン" },
        { label: "ヘラクルカブテリモン", value: "ヘラクルカブテリモン" },
        { label: "ホウオウモン", value: "ホウオウモン" },
        { label: "ヴァイクモン", value: "ヴァイクモン" },
        { label: "ロゼモン", value: "ロゼモン" },
        { label: "ゴッドドラモン", value: "ゴッドドラモン" },
        { label: "ホーリードラモン", value: "ホーリードラモン" },
      ],
      label: "究極体",
    },
  ],
  [],
)

return <Autocomplete.Root items={items} placeholder="Select a digimon" />

クエリを使う

const items = useMemo<Autocomplete.Item[]>(
  () => [
    {
      label: (
        <>
          <Text as="span" flex="1">
            アグモン
          </Text>
          <HeartIcon fontSize="lg" />
        </>
      ),
      query: "アグモン",
      value: "アグモン",
    },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return <Autocomplete.Root items={items} placeholder="Select a digimon" />

バリアントを変更する

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return (
  <VStack>
    <For each={["outline", "filled", "flushed"]}>
      {(variant) => (
        <Autocomplete.Root
          key={variant}
          variant={variant}
          placeholder={toTitleCase(variant)}
          items={items}
        />
      )}
    </For>
  </VStack>
)

サイズを変更する

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return (
  <VStack>
    <For each={["xs", "sm", "md", "lg", "xl"]}>
      {(size) => (
        <Autocomplete.Root
          key={size}
          size={size}
          placeholder={`Size: ${size}`}
          items={items}
        />
      )}
    </For>
  </VStack>
)

デフォルト値を設定する

デフォルト値を設定する場合は、defaultValueに値を設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return (
  <Autocomplete.Root
    defaultValue="アグモン"
    placeholder="Select a digimon"
    items={items}
  />
)

デフォルトの入力値を設定する

デフォルトの入力値を設定する場合は、defaultInputValueに文字列を設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return (
  <Autocomplete.Root
    defaultInputValue="モン"
    openOnFocus
    placeholder="Select a digimon"
    items={items}
  />
)

複数選択を有効する

複数選択を有効にする場合は、multipleをtrueに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return <Autocomplete.Root multiple placeholder="Select digimon" items={items} />

最大選択数を制限する

最大選択数を制限する場合は、maxに数値を設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return (
  <Autocomplete.Root
    items={items}
    multiple
    max={3}
    placeholder="Select digimon"
  />
)

区切り文字を変更する

区切り文字を変更する場合は、separatorに文字列を設定します。デフォルトでは、,が設定されています。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return (
  <Autocomplete.Root
    items={items}
    multiple
    placeholder="Select digimon"
    separator=";"
  />
)

カスタム値を許可する

カスタム値を許可する場合は、allowCustomValueをtrueに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return (
  <Autocomplete.Root
    allowCustomValue
    placeholder="Select a digimon"
    items={items}
    onChange={(value) => console.log("value:", value)}
  />
)

オフセットを変更する

オフセットを変更する場合は、gutterまたはoffsetに値を設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return (
  <Autocomplete.Root items={items} placeholder="Select a digimon" gutter={16} />
)

アニメーションを変更する

アニメーションを変更する場合は、animationSchemeに"block-start"や"inline-end"などを設定します。デフォルトでは、"scale"が設定されています。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return (
  <Autocomplete.Root
    animationScheme="inline-start"
    items={items}
    placeholder="Select a digimon"
  />
)

配置を変更する

配置を変更する場合は、placementに"start"や"end-end"などを指定します。デフォルトでは、"end"が設定されています。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return (
  <Autocomplete.Root
    animationScheme="inline-start"
    items={items}
    placeholder="Select a digimon"
    placement="center-end"
    rootProps={{ w: "xs" }}
  />
)

スクロールをブロックする

スクロールをブロックするには、blockScrollOnMountをtrueに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    items={items}
    blockScrollOnMount
    placeholder="Select a digimon"
  />
)

スクロール時にドロップダウンを閉じる場合は、closeOnScrollをtrueに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    closeOnScroll
    items={items}
    placeholder="Select a digimon"
  />
)

変更時にドロップダウンを開くイベントをハンドルする場合は、openOnChangeに関数を設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return (
  <Autocomplete.Root
    openOnFocus={false}
    openOnChange={(ev) => ev.target.value.length > 2}
    items={items}
    placeholder="Select a digimon"
  />
)

こちらのコードを使用する場合は、"use client"をファイルの上部に追加する必要があります。

変更時にドロップダウンを閉じるイベントをハンドルする場合は、closeOnChangeに関数を設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    openOnFocus={false}
    closeOnChange={(ev) => !ev.target.value.length}
    items={items}
    placeholder="Select a digimon"
  />
)

こちらのコードを使用する場合は、"use client"をファイルの上部に追加する必要があります。

フォーカス時にドロップダウンを開かない場合は、openOnFocusをfalseに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)
return (
  <Autocomplete.Root
    openOnFocus={false}
    placeholder="Select a digimon"
    items={items}
  />
)

クリック時にドロップダウンを開かない場合は、openOnClickをfalseに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    openOnClick={false}
    items={items}
    placeholder="Select a digimon"
  />
)

クリア時にフォーカスしない

クリア時にフォーカスしない場合は、focusOnClearをfalseに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    defaultValue="アグモン"
    focusOnClear={false}
    items={items}
    placeholder="Select a digimon"
  />
)

選択時にドロップダウンを閉じない

選択時にドロップダウンを閉じない場合は、closeOnSelectをfalseに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { closeOnSelect: true, label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    closeOnSelect={false}
    items={items}
    placeholder="Select a digimon"
  />
)

フォーカスが外れた場合に閉じない

フォーカスが外れた場合にドロップダウンを閉じない場合は、closeOnBlurをfalseに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    closeOnBlur={false}
    items={items}
    placeholder="Select a digimon"
  />
)

ESCキーが入力された時にドロップダウンを閉じない

ESCキーが入力された時にドロップダウンを閉じない場合は、closeOnEscをfalseに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    closeOnEsc={false}
    items={items}
    placeholder="Select a digimon"
  />
)

クリアボタンを無効にする

クリアボタンを無効にする場合は、clearableをfalseに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    clearable={false}
    items={items}
    placeholder="Select a digimon"
  />
)

オプションを無効にする

特定のオプションを無効にする場合は、disabledをtrueに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { disabled: true, label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return <Autocomplete.Root items={items} placeholder="Select a digimon" />

無効にする

無効にする場合は、disabledをtrueに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <VStack>
    <For each={["outline", "filled", "flushed"]}>
      {(variant) => (
        <Autocomplete.Root
          variant={variant}
          disabled
          placeholder={toTitleCase(variant)}
          items={items}
        />
      )}
    </For>
  </VStack>
)

読み取り専用にする

読み取り専用にする場合は、readOnlyをtrueに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <VStack>
    <For each={["outline", "filled", "flushed"]}>
      {(variant) => (
        <Autocomplete.Root
          variant={variant}
          readOnly
          placeholder={toTitleCase(variant)}
          items={items}
        />
      )}
    </For>
  </VStack>
)

無効な入力にする

無効な入力にする場合は、invalidをtrueに設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <VStack>
    <For each={["outline", "filled", "flushed"]}>
      {(variant) => (
        <Autocomplete.Root
          variant={variant}
          invalid
          placeholder={toTitleCase(variant)}
          items={items}
        />
      )}
    </For>
  </VStack>
)

ボーダーの色を変更する

ボーダーの色を変更する場合は、focusBorderColorまたはerrorBorderColorに値を設定します。

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <VStack>
    <Autocomplete.Root
      focusBorderColor="green.500"
      items={items}
      placeholder="Custom border color"
    />

    <Autocomplete.Root
      errorBorderColor="orange.500"
      invalid
      items={items}
      placeholder="Custom border color"
    />
  </VStack>
)

検索結果が存在しない時のメッセージをカスタマイズする

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    emptyMessage="You just hit a route that doesn't exist... the sadness.😢"
    items={items}
    placeholder="Select a digimon"
  />
)

アイコンをカスタマイズする

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <VStack>
    <Autocomplete.Root
      placeholder="Select a digimon"
      iconProps={{ color: "orange" }}
      items={items}
    />

    <Autocomplete.Root
      icon={<ChevronsDownIcon />}
      placeholder="Select a digimon"
      items={items}
    />
  </VStack>
)

オプションのアイコンをカスタマイズする

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    items={items}
    placeholder="Select a digimon"
    optionProps={{ icon: <BugIcon /> }}
  />
)

複数選択時の表示をカスタマイズする

const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    items={items}
    multiple
    placeholder="Select a character"
    render={({ label, onClear }) => (
      <Tag size="sm" me="{gap}" onClose={onClear}>
        {label}
      </Tag>
    )}
  />
)

制御する

const [value, setValue] = useState<string>("アグモン")
const items = useMemo<Autocomplete.Item[]>(
  () => [
    { label: "アグモン", value: "アグモン" },
    { label: "ガブモン", value: "ガブモン" },
    { label: "テントモン", value: "テントモン" },
    { label: "ピヨモン", value: "ピヨモン" },
    { label: "ゴマモン", value: "ゴマモン" },
    { label: "パルモン", value: "パルモン" },
    { label: "パタモン", value: "パタモン" },
    { label: "テイルモン", value: "テイルモン" },
  ],
  [],
)

return (
  <Autocomplete.Root
    value={value}
    onChange={setValue}
    items={items}
    placeholder="Select a digimon"
  />
)

こちらのコードを使用する場合は、"use client"をファイルの上部に追加する必要があります。

Props

Autocomplete.Root

Prop	デフォルト	型 / 説明
`as`	-	`As` The HTML element to render.
`asChild`	-	`boolean` Merges its props onto its immediate child.
`css`	-	`CSSObject \| CSSObject[]` The CSS object.
`colorScheme`	-	`"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` Set color scheme variables.
`size`	`"md"`	`"lg" \| "md" \| "sm" \| "xl" \| "xs"` The size of the component.
`variant`	`"outline"`	`"filled" \| "flushed" \| "outline" \| "plain"` The variant of the component.
`allowCustomValue`	`false`	`boolean` If `true`, the autocomplete will allow custom value.
`animationScheme`	`"scale"`	`"none" \| "scale" \| SimplePlacement` The animation of the element.
`autoUpdate`	`true`	`boolean` If `true`, automatically updates the position of the floating element when necessary.
`blockScrollOnMount`	`false`	`boolean` If `true`, scrolling will be disabled on the `body` when the modal opens.
`clearable`	`true`	`boolean` If `true`, display the clear icon.
`clearIcon`	-	`ReactNode` The icon to be used in the clear button.
`closeOnBlur`	`true`	`boolean` If `true`, the popover will close when you blur out it by clicking outside or tabbing out.
`closeOnChange`	`false`	`((ev: ChangeEvent<HTMLInputElement>) => boolean) \| boolean` If `true`, the autocomplete will be closed when the input value changes.
`closeOnEsc`	`true`	`boolean` If `true`, the popover will hide on pressing Esc key.
`closeOnScroll`	`false`	`boolean` If `true`, the popover will hide on scroll.
`closeOnSelect`	`true`	`boolean` If `true`, the list element will be closed when value is selected.
`contentProps`	-	`AutocompleteContentProps` Props for content element.
`defaultInputValue`	-	`string` The initial value of the input.
`defaultOpen`	-	`boolean` If `true`, the element will be initially opened.
`defaultValue`	-	`Multiple extends true ? string[] : string` The initial value of the autocomplete.
`disabled`	`false`	`boolean` If `true`, the combobox will be disabled.
`duration`	`0.2`	`MotionTransitionProps["duration"]` The animation duration.
`elementProps`	-	`InputGroup.ElementProps` The props for the end element.
`elements`	-	`{ floating?: HTMLElement \| null \| undefined; reference?: HTMLButtonElement \| null \| undefined }` Object containing the reference and floating elements.
`emptyIcon`	-	`ReactNode` The icon to be used in the empty element.
`emptyMessage`	`"No results found"`	`ReactNode` The message displayed when the search yields no hits.
`emptyProps`	-	`AutocompleteEmptyProps` Props for empty element.
`errorBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is invalid.
`filter`	-	`AutocompleteFilter` The function to filter the items.
`flip`	`true`	`boolean` If `true`, the popper will change its placement and flip when it's about to overflow its boundary area.
`focusBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is focused.
`focusOnClear`	`true`	`boolean` If `true`, the input will be focused when the clear icon is clicked.
`groupProps`	-	`Omit<AutocompleteGroupProps, "children" \| "label">` Props for group element.
`gutter`	`8`	`number` The distance or margin between the reference and popper. It is used internally to create an `offset` modifier.
`icon`	-	`ReactNode` The icon to be used in the autocomplete.
`iconProps`	-	`AutocompleteIconProps` Props for icon element.
`inputProps`	-	`HTMLStyledProps<"input">` The props for the input element.
`inputValue`	-	`string` The value of the input.
`invalid`	`false`	`boolean` If `true`, the field will be invalid.
`items`	`[]`	`ComboboxItem[]` If provided, generate options based on items.
`matcher`	-	`AutocompleteMatcher` The function to match the items.
`matchWidth`	`false`	`boolean` If `true`, the popper will match the width of the reference at all times. It's useful for `autocomplete`, `date-picker` and `select` patterns.
`max`	-	`number` The maximum selectable value.
`middleware`	-	`(false \| { name: string; options?: any; fn: (state: { x: number; y: number; placement: Placement; platform: { detectOverflow: (state: MiddlewareState, options?: DetectOverflowOptions \| Derivable<...> \| undefined) => Promise<...>; } & Platform; ... 4 more ...; elements: Elements; }) => Promisable<...>; } \| null \| und...` Array of middleware objects to modify the positioning or provide data for rendering.
`multiple`	`false`	`Multiple` If `true`, the autocomplete will be multiple.
`name`	-	`string` The `name` attribute of the input element.
`offset`	-	`[number, number]` The main and cross-axis offset to displace popper element from its reference element.
`onChange`	-	`(value: Multiple extends true ? string[] : string) => void` The callback invoked when value state changes.
`onClose`	-	`() => void \| Promise<void>` Callback invoked to close the element.
`onInputChange`	-	`(value: string) => void` The callback invoked when input value state changes.
`onOpen`	-	`() => void \| Promise<void>` Callback invoked to open the element.
`open`	-	`boolean` If `true`, the element will be opened.
`openOnChange`	`true`	`((ev: ChangeEvent<HTMLInputElement>) => boolean) \| boolean` If `true`, the autocomplete will be opened when the input value changes.
`openOnClick`	`true`	`boolean` If `true`, the combobox will be opened when click on the field.
`openOnEnter`	`true`	`boolean` If `true`, the combobox will be opened when enter is pressed.
`openOnFocus`	`true`	`boolean` If `true`, the autocomplete will be opened when the input is focused.
`openOnSpace`	`true`	`boolean` If `true`, the combobox will be opened when space is pressed.
`optionProps`	-	`Omit<AutocompleteOptionProps, "children" \| "value">` Props for option element.
`placeholder`	-	`string` The placeholder for autocomplete.
`placement`	`"end"`	`Direction` The placement of the popper relative to its reference.
`platform`	-	`Platform` Custom or extended platform object.
`preventOverflow`	`true`	`boolean` If `true`, will prevent the popper from being cut off and ensure it's visible within the boundary area.
`readOnly`	`false`	`boolean` If `true`, the combobox will be readonly.
`render`	-	`(props: AutocompleteRenderProps) => ReactNode` The function to render the selected items.
`required`	`false`	`boolean` If `true`, the field will be required.
`rootProps`	-	`InputGroup.RootProps` Props for root element.
`selectFocusRef`	-	`RefObject<HTMLElement \| null>` The `ref` of the element that should receive focus when selected.
`selectOnSpace`	`true`	`boolean` If `true`, the item will be selected when space is pressed.
`separator`	`","`	`string` The visual separator between each value.
`strategy`	`"absolute"`	`Strategy` The CSS positioning strategy to use.
`transferFocus`	`true`	`boolean` If `true`, the focus will be transferred to the popover content when the tab key is pressed.
`value`	-	`Multiple extends true ? string[] : string` The value of the autocomplete.
`whileElementsMounted`	-	`(reference: HTMLButtonElement, floating: HTMLElement, update: () => void) => () => void` A callback invoked when both the reference and floating elements are mounted, and cleaned up when either is unmounted. This is useful for setting up event listeners (e.g. pass `autoUpdate`).

Autocomplete.Group

Prop	デフォルト	型 / 説明
`as`	-	`As` The HTML element to render.
`asChild`	-	`boolean` Merges its props onto its immediate child.
`css`	-	`CSSObject \| CSSObject[]` The CSS object.
`colorScheme`	-	`"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` Set color scheme variables.
`label`	-	`ReactNode` The label of the group.
`labelProps`	-	`AutocompleteLabelProps` Props for the label component.

Autocomplete.Label

Prop	デフォルト	型 / 説明
`as`	-	`As` The HTML element to render.
`asChild`	-	`boolean` Merges its props onto its immediate child.
`css`	-	`CSSObject \| CSSObject[]` The CSS object.
`colorScheme`	-	`"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` Set color scheme variables.

Autocomplete.Option

Prop	デフォルト	型 / 説明
`as`	-	`As` The HTML element to render.
`asChild`	-	`boolean` Merges its props onto its immediate child.
`css`	-	`CSSObject \| CSSObject[]` The CSS object.
`colorScheme`	-	`"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` Set color scheme variables.
`closeOnSelect`	-	`boolean` If `true`, the item will be closed when selected.
`disabled`	`false`	`boolean` If `true`, the item will be disabled.
`icon`	-	`ReactNode` The icon to be used in the autocomplete option.
`selected`	-	`boolean` If `true`, the item will be selected.
`value`	-	`string` The value of the item.

アクセシビリティ

Autocompleteは、アクセシビリティに関してWAI-ARIA - Combobox Patternに従っています。

Field.Rootを使用しない場合は、Autocomplete.Rootにaria-labelまたはaria-labelledbyを設定してください。

<Autocomplete.Root aria-label="デジモンを選択" placeholder="デジモンを選択">
  <Autocomplete.Option value="アグモン">アグモン</Autocomplete.Option>
  <Autocomplete.Option value="ガブモン">ガブモン</Autocomplete.Option>
  <Autocomplete.Option value="テントモン">テントモン</Autocomplete.Option>
</Autocomplete.Root>

<VStack gap="sm">
  <Text as="h3" id="label">
    デジモン
  </Text>

  <Autocomplete.Root aria-labelledby="label" placeholder="デジモンを選択">
    <Autocomplete.Option value="アグモン">アグモン</Autocomplete.Option>
    <Autocomplete.Option value="ガブモン">ガブモン</Autocomplete.Option>
    <Autocomplete.Option value="テントモン">テントモン</Autocomplete.Option>
  </Autocomplete.Root>
</VStack>

キー	説明	状態
`ArrowDown`	無効ではない次の項目にフォーカスします。最後の項目の場合は、無効ではない最初の項目にフォーカスします。	-
`ArrowUp`	無効ではない前の項目にフォーカスします。最初の項目の場合は、無効ではない最後の項目にフォーカスします。	-
`Enter`	フォーカスしている項目を選択し、リストボックスを閉じます。フォーカスしている項目がなく入力テキストがある場合は、最初に一致する項目を選択します。	`closeOnSelect={true}`
`Home`	リストボックスが開いている場合、無効ではない最初の項目にフォーカスします。	-
`End`	リストボックスが開いている場合、無効ではない最後の項目にフォーカスします。	-
`Escape`	リストボックスを閉じます。	`closeOnEsc={true}`
`Backspace`	入力が空の場合、最後に選択された値を削除します。	`multiple={true}`

ARIAロールと属性

コンポーネント	ロールと属性	使い方
`Autocomplete.Root`	`role="group"`	グループであることを示します。
`AutocompleteField`	`role="combobox"`	コンボボックスであることを示します。
	`aria-expanded`	リストボックスが開いている場合は`"true"`を設定し、閉じている場合は`"false"`を設定します。
	`aria-haspopup="listbox"`	リストボックスが存在することを示します。
	`aria-controls`	リストボックスが開いている場合はリストボックスの`id`を設定し、閉じている場合は設定しません。
	`aria-activedescendant`	フォーカスされた項目の`id`を設定します。
	`aria-disabled`	`disabled`または`readOnly`が設定されている場合は`"true"`を設定します。
	`aria-labelledby`	`AutocompleteField`が`Field.Root`内にあり、`Field.Root`に`label`または`Field.Label`が設定されている場合は、その`id`を設定します。
`Autocomplete.Content`	`role="listbox"`	リストボックスであることを示します。
`Autocomplete.Option`	`role="option"`	オプションであることを示します。
	`aria-selected`	オプションが選択されている場合は`"true"`を設定します。
	`aria-disabled`	`disabled`が設定されている場合は`"true"`を設定します。
`Autocomplete.Group`	`role="group"`	グループであることを示します。
	`aria-labelledby`	関連した`Autocomplete.Label`の`id`を設定します。
`Autocomplete.Label`	`role="presentation"`	プレゼンテーションであることを示します。
`Autocomplete.Icon`	`role="button"`	`clearable`かつ値がある場合、ボタンであることを示します。
	`aria-label`	`"値を消去する"`を設定します。
	`aria-disabled`	`disabled`または`readOnly`が設定されている場合は`"true"`を設定します。

類似のコンポーネント

Selectは、ユーザーがオプションのリストから値を選択するために使用されるコンポーネントです。

Menuは、一般的なドロップダウンメニューを表示するコンポーネントです。

Textareaは、複数行のテキスト入力を取得するために使用されるコンポーネントです。

Switchは、オンとオフの状態を切り替えるために使用されるコンポーネントです。

SegmentedControlは、ユーザーが複数の選択肢の中から1つを選択するために使用されるコンポーネントです。

Radioは、ユーザーが複数の選択肢の中から1つの値を選択するために使用されるコンポーネントです。

Ratingは、ユーザーが評価を行うために使用させるコンポーネントです。

PinInputは、ピンコードやOTP(ワンタイムパスワード)の入力を取得するために使用されるコンポーネントです。

使用しているコンポーネント・フック

Selectは、ユーザーがオプションのリストから値を選択するために使用されるコンポーネントです。

Inputは、ユーザーからのテキスト入力を取得するために使用されるコンポーネントです。

Popoverは、要素の周りにフローティングして情報を表示するコンポーネントです。

Groupは、複数の要素をまとめて扱うためのコンポーネントです。

Iconは、プロジェクトに使用できる一般的なアイコンコンポーネントです。

Fieldは、フォーム要素に、ラベル、ヘルパーメッセージ、エラーメッセージなどをグループ化するために使用されるコンポーネントです。

使用されているコンポーネント・フック

DatePickerは、ユーザーが日付を選択するために使用されるコンポーネントです。