MultiAutocomplete

MultiAutocomplete is a component used to display suggestions based on user text input and to obtain multiple values.

Import

import {
  MultiAutocomplete,
  AutocompleteOptionGroup,
  AutocompleteOption,
} from "@yamada-ui/react"

Copied!

Usage

If you want to select a single option from a list, please check Autocomplete.

Editable example

<MultiAutocomplete placeholder="キャラクターを選択">
  <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
  <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
  <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
</MultiAutocomplete>

Copied!

Alternatively, you can omit AutocompleteOption by setting items.

Editable example

const items: AutocompleteItem[] = [
  { label: "孫悟空", value: "孫悟空" },
  { label: "ベジータ", value: "ベジータ" },
  { label: "フリーザ", value: "フリーザ" },
]

return <MultiAutocomplete placeholder="キャラクターを選択" items={items} />

Copied!

Change Variant

Editable example

<VStack>
  <MultiAutocomplete variant="outline" placeholder="outline" />
  <MultiAutocomplete variant="filled" placeholder="filled" />
  <MultiAutocomplete variant="flushed" placeholder="flushed" />
  <MultiAutocomplete variant="unstyled" placeholder="unstyled" />
</VStack>

Copied!

Change Size

Editable example

<VStack>
  <MultiAutocomplete placeholder="extra small size" size="xs" />
  <MultiAutocomplete placeholder="small size" size="sm" />
  <MultiAutocomplete placeholder="medium size" size="md" />
  <MultiAutocomplete placeholder="large size" size="lg" />
</VStack>

Copied!

Set Default Values

To set default values, set an array of strings to defaultValue.

Editable example

<MultiAutocomplete placeholder="キャラクターを選択" defaultValue={["ベジータ"]}>
  <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
  <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
  <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
</MultiAutocomplete>

Copied!

Editable example

<MultiAutocomplete
  placeholder="キャラクターを選択"
  header={
    <Center pt="2" px="3">
      Header added here
    </Center>
  }
>
  <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
  <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
  <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
</MultiAutocomplete>

Copied!

Editable example

<MultiAutocomplete
  placeholder="キャラクターを選択"
  footer={
    <Center pb="2" px="3">
      Footer added here
    </Center>
  }
>
  <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
  <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
  <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
</MultiAutocomplete>

Copied!

Set Empty Message

To set a message to display when there are no items, use the emptyMessage property.

Editable example

<MultiAutocomplete
  placeholder="キャラクターを選択"
  emptyMessage="キャラクターが存在しません"
>
  <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
  <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
  <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
</MultiAutocomplete>

Copied!

Allow Creation of New Items

To allow the creation of new items, set allowCreate to true.

Editable example

const items: AutocompleteItem[] = [
  { label: "ベジータ", value: "ベジータ" },
  {
    label: "地球人",
    items: [
      { label: "孫悟空", value: "孫悟空" },
      { label: "孫悟飯", value: "孫悟飯" },
      { label: "クリリン", value: "クリリン" },
    ],
  },
  {
    label: "フリーザ軍",
    items: [
      { label: "フリーザ", value: "フリーザ" },
      { label: "ギニュー", value: "ギニュー" },
      { label: "リクーム", value: "リクーム" },
      { label: "バータ", value: "バータ" },
      { label: "ジース", value: "ジース" },
      { label: "グルド", value: "グルド" },
    ],
  },
]

return (
  <MultiAutocomplete
    placeholder="キャラクターを選択"
    items={items}
    allowCreate
  />
)

Copied!

MultiAutocomplete internally prefers 'children'. If 'allowCreate' is true, it will not be reflected correctly. If want to reflect, please set 'items' in props.

Change Insert Position of Created Items

To change the insert position of created items, set insertPositionItem to first, last, or a specific group name followed by first or last. By default, first is set.

first: Inserts at the beginning of the list.
last: Inserts at the end of the list.
[group name, first | last]: If you want to insert at the beginning or end of a specific group, set the group name and first or last.

Editable example

const items: AutocompleteItem[] = [
  { label: "ベジータ", value: "ベジータ" },
  {
    label: "地球人",
    items: [
      { label: "孫悟空", value: "孫悟空" },
      { label: "孫悟飯", value: "孫悟飯" },
      { label: "クリリン", value: "クリリン" },
    ],
  },
  {
    label: "フリーザ軍",
    items: [
      { label: "フリーザ", value: "フリーザ" },
      { label: "ギニュー", value: "ギニュー" },
      { label: "リクーム", value: "リクーム" },
      { label: "バータ", value: "バータ" },
      { label: "ジース", value: "ジース" },
      { label: "グルド", value: "グルド" },
    ],
  },
]

return (
  <VStack>
    <MultiAutocomplete
      placeholder="キャラクターを選択"
      items={items}
      allowCreate
      insertPositionItem="first"
    />
    <MultiAutocomplete
      placeholder="キャラクターを選択"
      items={items}
      allowCreate
      insertPositionItem="last"
    />
    <MultiAutocomplete
      placeholder="キャラクターを選択"
      items={items}
      allowCreate
      insertPositionItem="地球人"
    />
    <MultiAutocomplete
      placeholder="キャラクターを選択"
      items={items}
      allowCreate
      insertPositionItem={["フリーザ軍", "last"]}
    />
  </VStack>
)

Copied!

Allow Free Input

By default, values not in the suggestions are cleared on blur. To allow free input without clearing non-suggested values, set allowFree to true.

Editable example

const items: AutocompleteItem[] = [
  { label: "ベジータ", value: "ベジータ" },
  {
    label: "地球人",
    items: [
      { label: "孫悟空", value: "孫悟空" },
      { label: "孫悟飯", value: "孫悟飯" },
      { label: "クリリン", value: "クリリン" },
    ],
  },
  {
    label: "フリーザ軍",
    items: [
      { label: "フリーザ", value: "フリーザ" },
      { label: "ギニュー", value: "ギニュー" },
      { label: "リクーム", value: "リクーム" },
      { label: "バータ", value: "バータ" },
      { label: "ジース", value: "ジース" },
      { label: "グルド", value: "グルド" },
    ],
  },
]

return (
  <MultiAutocomplete placeholder="キャラクターを選択" items={items} allowFree />
)

Copied!

Change Border Color

To change the border color, set a color to focusBorderColor or errorBorderColor.

Editable example

<VStack>
  <MultiAutocomplete
    focusBorderColor="green.500"
    placeholder="custom border color"
  >
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
  </MultiAutocomplete>

  <MultiAutocomplete
    isInvalid
    errorBorderColor="orange.500"
    placeholder="custom border color"
  >
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
  </MultiAutocomplete>
</VStack>

Copied!

Customize Separator

To customize the separator, set a string to separator.

Editable example

<MultiAutocomplete placeholder="キャラクターを選択" separator=";">
  <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
  <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
  <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
</MultiAutocomplete>

Copied!

Always Show Placeholder

To always show the placeholder, set keepPlaceholder to true.

Editable example

<MultiAutocomplete placeholder="キャラクターを選択" keepPlaceholder>
  <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
  <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
  <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
</MultiAutocomplete>

Copied!

Use Custom Component

To use a custom component, set a ReactElement to component. component provides value, label, index, onRemove.

Editable example

<VStack>
  <MultiAutocomplete
    placeholder="キャラクターを選択"
    component={({ label }) => <Tag>{label}</Tag>}
  >
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
  </MultiAutocomplete>

  <MultiAutocomplete
    placeholder="キャラクターを選択"
    component={({ label, onRemove }) => <Tag onClose={onRemove}>{label}</Tag>}
  >
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
  </MultiAutocomplete>
</VStack>

Copied!

Exclude Selected Values from List

To exclude selected values from the list, set omitSelectedValues to true.

Editable example

<MultiAutocomplete placeholder="キャラクターを選択" omitSelectedValues={true}>
  <AutocompleteOptionGroup label="地球人">
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="孫悟飯">孫悟飯</AutocompleteOption>
    <AutocompleteOption value="クリリン">クリリン</AutocompleteOption>
  </AutocompleteOptionGroup>

  <AutocompleteOptionGroup label="フリーザ軍">
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
    <AutocompleteOption value="ギニュー">ギニュー</AutocompleteOption>
    <AutocompleteOption value="リクーム">リクーム</AutocompleteOption>
    <AutocompleteOption value="バータ">バータ</AutocompleteOption>
    <AutocompleteOption value="ジース">ジース</AutocompleteOption>
    <AutocompleteOption value="グルド">グルド</AutocompleteOption>
  </AutocompleteOptionGroup>
</MultiAutocomplete>

Copied!

Set Maximum Number of Selectable Values

To set the maximum number of selectable values, set maxSelectValues to a number.

Editable example

<MultiAutocomplete placeholder="キャラクターを選択" maxSelectValues={3}>
  <AutocompleteOptionGroup label="地球人">
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="孫悟飯">孫悟飯</AutocompleteOption>
    <AutocompleteOption value="クリリン">クリリン</AutocompleteOption>
  </AutocompleteOptionGroup>

  <AutocompleteOptionGroup label="フリーザ軍">
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
    <AutocompleteOption value="ギニュー">ギニュー</AutocompleteOption>
    <AutocompleteOption value="リクーム">リクーム</AutocompleteOption>
    <AutocompleteOption value="バータ">バータ</AutocompleteOption>
    <AutocompleteOption value="ジース">ジース</AutocompleteOption>
    <AutocompleteOption value="グルド">グルド</AutocompleteOption>
  </AutocompleteOptionGroup>
</MultiAutocomplete>

Copied!

To close the dropdown list on selection, set closeOnSelect to true.

Editable example

<MultiAutocomplete placeholder="キャラクターを選択" closeOnSelect={true}>
  <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
  <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
  <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
</MultiAutocomplete>

Copied!

Disable Clearing

To disable clearing, set isClearable to false.

Editable example

<MultiAutocomplete placeholder="キャラクターを選択" isClearable={false}>
  <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
  <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
  <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
</MultiAutocomplete>

Copied!

Change Display Position

To change the display position, set placement to top, left-start, etc. By default, bottom is set.

Editable example

<MultiAutocomplete
  placeholder="キャラクターを選択"
  placement="right-start"
  maxW="xs"
>
  <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
  <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
  <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
</MultiAutocomplete>

Copied!

Change Offset

Depending on the size of the element or the situation, you may want to adjust the position of the tooltip. In that case, adjust the position with gutter or offset.

gutter allows you to set the difference with simple elements, and offset allows you to set [horizontal axis, vertical axis].

Editable example

<VStack>
  <MultiAutocomplete placeholder="キャラクターを選択" duration={0.4}>
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
  </MultiAutocomplete>

  <MultiAutocomplete placeholder="キャラクターを選択" gutter={32}>
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
  </MultiAutocomplete>
</VStack>

Copied!

Disable

To disable, set isDisabled to true.

Editable example

<>
  <MultiAutocomplete isDisabled variant="outline" placeholder="outline" />
  <MultiAutocomplete isDisabled variant="filled" placeholder="filled" />
  <MultiAutocomplete isDisabled variant="flushed" placeholder="flushed" />
  <MultiAutocomplete isDisabled variant="unstyled" placeholder="unstyled" />

  <FormControl
    isDisabled
    label="Which notifications would you like to receive?"
  >
    <MultiAutocomplete placeholder="Autocomplete notifications" />
  </FormControl>
</>

Copied!

To disable an option, set isDisabled to true on AutocompleteOption.

Editable example

<MultiAutocomplete placeholder="キャラクターを選択">
  <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
  <AutocompleteOption value="ベジータ" isDisabled>
    ベジータ
  </AutocompleteOption>
  <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
</MultiAutocomplete>

Copied!

Make Read-Only

To make read-only, set isReadOnly to true.

Editable example

<>
  <MultiAutocomplete isReadOnly variant="outline" placeholder="outline" />
  <MultiAutocomplete isReadOnly variant="filled" placeholder="filled" />
  <MultiAutocomplete isReadOnly variant="flushed" placeholder="flushed" />
  <MultiAutocomplete isReadOnly variant="unstyled" placeholder="unstyled" />

  <FormControl
    isReadOnly
    label="Which notifications would you like to receive?"
  >
    <MultiAutocomplete placeholder="Autocomplete notifications" />
  </FormControl>
</>

Copied!

Make Input Invalid

To make input invalid, set isInvalid to true.

Editable example

<>
  <MultiAutocomplete isInvalid variant="outline" placeholder="outline" />
  <MultiAutocomplete isInvalid variant="filled" placeholder="filled" />
  <MultiAutocomplete isInvalid variant="flushed" placeholder="flushed" />
  <MultiAutocomplete isInvalid variant="unstyled" placeholder="unstyled" />

  <FormControl
    isInvalid
    label="Which notifications would you like to receive?"
    errorMessage="This is required."
  >
    <MultiAutocomplete placeholder="Autocomplete notifications" />
  </FormControl>
</>

Copied!

Customize Icons

To customize icons, set props to iconProps or clearIconProps.

Editable example

<VStack>
  <MultiAutocomplete
    placeholder="キャラクターを選択"
    iconProps={{ color: "primary" }}
  >
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
  </MultiAutocomplete>

  <MultiAutocomplete
    placeholder="キャラクターを選択"
    iconProps={{ children: <ChevronsDownIcon /> }}
  >
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
  </MultiAutocomplete>

  <MultiAutocomplete
    placeholder="キャラクターを選択"
    clearIconProps={{ children: <TrashIcon w="0.5em" /> }}
  >
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
  </MultiAutocomplete>
</VStack>

Copied!

Customize Options

To customize options, use the optionProps property.

Editable example

<VStack>
  <MultiAutocomplete
    placeholder="キャラクターを選択"
    optionProps={{ color: "primary" }}
  >
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
  </MultiAutocomplete>

  <MultiAutocomplete
    placeholder="キャラクターを選択"
    optionProps={{ icon: <CheckIcon color="green.500" /> }}
  >
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
  </MultiAutocomplete>
</VStack>

Copied!

Control

Editable example

const [value, onChange] = useState<string[]>(["孫悟空"])

return (
  <MultiAutocomplete
    placeholder="キャラクターを選択"
    value={value}
    onChange={onChange}
  >
    <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
    <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
    <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
  </MultiAutocomplete>
)

Copied!

Use `React Hook Form`

Editable example

const {
  control,
  handleSubmit,
  watch,
  formState: { errors },
} = useForm<Data>()

const onSubmit: SubmitHandler<Data> = (data) => console.log("submit:", data)

console.log("watch:", watch())

return (
  <VStack as="form" onSubmit={handleSubmit(onSubmit)}>
    <FormControl
      isInvalid={!!errors.autocomplete}
      label="Who is your favorite character?"
      errorMessage={
        errors.autocomplete ? errors.autocomplete.message : undefined
      }
    >
      <Controller
        name="autocomplete"
        control={control}
        rules={{ required: { value: true, message: "This is required." } }}
        render={({ field }) => (
          <MultiAutocomplete placeholder="キャラクターを選択" {...field}>
            <AutocompleteOption value="孫悟空">孫悟空</AutocompleteOption>
            <AutocompleteOption value="ベジータ">ベジータ</AutocompleteOption>
            <AutocompleteOption value="フリーザ">フリーザ</AutocompleteOption>
          </MultiAutocomplete>
        )}
      />
    </FormControl>

    <Button type="submit" alignSelf="flex-end">
      Submit
    </Button>
  </VStack>
)

Copied!

Edit this page on GitHub

PreviousAutocomplete NextDatePicker

MultiAutocomplete

Usage

Change Variant

Change Size

Set Default Values

Add header to a dropdown

Add footer to a dropdown

Set Empty Message

Allow Creation of New Items

Change Insert Position of Created Items

Allow Free Input

Change Border Color

Customize Separator

Always Show Placeholder

Use Custom Component

Exclude Selected Values from List

Set Maximum Number of Selectable Values

Close Dropdown List on Selection

Disable Clearing

Change Display Position

Change Offset

Disable

Make Read-Only

Make Input Invalid

Customize Icons

Customize Options

Control

Use React Hook Form

Use `React Hook Form`