@iress-oss/ids-mcp-server 5.15.0 → 5.20.2

package/generated/docs/components_components-combobox-docs.md

@@ -0,0 +1,3735 @@
+Combobox
+========
+
+Overview
+--------
+
+Comboboxes provide select and multi-select functionality with the benefit of live filtering.
+
+* * *
+
+Caution
+
+**Use IressRichSelect instead**
+
+The design of this component is changing. Please use the new component/props instead.
+
+[](./iframe.html?id=components-combobox--default)
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+<IressCombobox
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+Props
+-----
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+Usage
+-----
+
+`IressCombobox` is an alternative to `IressSelect` when you have a large number of options and want to provide a search functionality to help the user find the option they are looking for.
+
+It extends `IressAutocomplete`, however it restricts the input to the options provided. This means that the user can only select from the options provided. If you do not need this restriction, please use `IressAutocomplete`.
+
+### Uncontrolled
+
+The `defaultValue` prop can be used to set the initial value of the combobox. The value will be managed by the component.
+
+**Note:** The `defaultValue` prop is not checked against the options provided, allowing it to work with asynchronous options.
+
+[](./iframe.html?id=components-combobox--uncontrolled)
+
+×Clear
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+<IressCombobox
+  defaultValue\={{
+    label: 'Option 1',
+    value: 1
+  }}
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | 
+
+Edit JSON
+
+defaultValue :
+
+{
+
+*   label : "Option 1"
+*   value : 1
+
+}
+
+
+
+
+
+
+
+ |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+### Controlled
+
+The `value` prop can be used to completely control the state of the component. Use the `onChange` and `onClear` props to sync your state with the component.
+
+**Note:** The `value` prop is not checked against the options provided, allowing it to work with asynchronous options.
+
+[](./iframe.html?id=components-combobox--controlled)
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+import {
+  IressCombobox,
+  type IressComboboxProps,
+  type LabelValueMeta,
+} from '@/main';
+import { useState } from 'react';
+export const ComboboxUsingState \= () \=> {
+  const \[value, setValue\] \= useState<LabelValueMeta | undefined\>();
+  return (
+    <IressCombobox
+      {...{
+  popoverProps: {
+    container: {},
+  },
+  options: \[
+    {
+      label: 'Option 1',
+      value: 1,
+    },
+    {
+      label: 'Option 2',
+      value: 2,
+    },
+    {
+      label: 'Option 3',
+      value: 3,
+    },
+    {
+      label: 'Option 4',
+      value: 4,
+    },
+    {
+      label: 'Option 5',
+      value: 5,
+    },
+  \],
+}}
+      onChange\={(\_e, newValue) \=> setValue(newValue)}
+      onClear\={() \=> setValue(undefined)}
+      value\={value}
+    />
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | \- |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | \- |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+### Providing options
+
+#### `options`
+
+The `options` prop is required for the combobox. You can provide an array of `LabelValueMeta[]` objects to the `options` prop. Filtering is done based on the `label` property.
+
+[](./iframe.html?id=components-combobox--options)
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+<IressCombobox
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+#### Asynchronous `options`
+
+If you would like to render suggestions from the server, you can pass a function to the `options` prop. It accepts a string parameter and returns a promise that resolves to an array of `LabelValueMeta[]` objects. No filtering is done for asynchronous options, you must filter the options yourself using the query.
+
+[](./iframe.html?id=components-combobox--async-options)
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+import { IressCombobox, type IressComboboxProps } from '@/main';
+interface StarWarsCharacter {
+  name: string;
+  gender: string;
+}
+interface StarWarsCharacterApi {
+  results: StarWarsCharacter\[\];
+}
+export const ComboboxUsingAsync \= (args: IressComboboxProps) \=> (
+  <IressCombobox
+    {...args}
+    options\={async (query: string) \=> {
+      if (!query) return \[\];
+      const data \= await fetch(
+        \`https://swapi.py4e.com/api/people/?search=${query}\`,
+      ).then((response) \=> response.json() as Promise<StarWarsCharacterApi\>);
+      return data.results.map((character: StarWarsCharacter) \=> ({
+        label: character.name,
+        value: character.name,
+        meta: character.gender,
+      }));
+    }}
+  />
+);
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | \- |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+#### `initialOptions`
+
+If you want to provide initial options to the user, you can use the `initialOptions` prop. This is useful when you want to provide a list of options to the user before they start typing (eg. recommended search terms).
+
+**Note:** Once an option is selected from `initialOptions`, the input will be updated, meaning that the user can no longer see the initial options. If you want to keep the initial options visible, you should make sure they are part of the `options` prop as well.
+
+[](./iframe.html?id=components-combobox--initial-options)
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+<IressCombobox
+  initialOptions\={\[
+    {
+      label: 'Favourite option 1'
+    },
+    {
+      label: 'Favourite option 2'
+    },
+    {
+      label: 'Favourite option 3'
+    }
+  \]}
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| initialOptions | 
+
+array
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   initialOptions :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+Behaviour
+---------
+
+*   If `initialOptions` are provided the options will be displayed in a popover immediately on focus. The popover will close when the input loses focus.
+*   If `initialOptions` are not provided, the popover will be displayed as long as there is a single character in the input. The popover will close when the input is empty.
+*   The options will be filtered based on the input value.
+    *   If `autoSelect` is true, the first option filtered will become the value of the combobox, unless the backspace key is pressed.
+*   Tapping on an option with the mouse will change the input value to the `label` of the selected option. The entire `LabelValueMeta` of the selected option will be returned in the `onChange` callback.
+*   When the user presses the arrow keys while the input is focussed, options will be selected, but focus remains on the input.
+    *   If `autoSelect` is true, the option will become the value of the combobox.
+    *   If `autoSelect` is true, the text not matching the input will be selected.
+*   When the user presses the enter key while a option is highlighted, the option will be selected and the popover will close.
+*   When the user presses the down key while the popover is closed, it will open the popover.
+*   When the user pressed the up key while the first option is highlighted, it will close the popover.
+*   When the user tabs away while the popover is open, the popover will close.
+    *   If `autoSelect` is true and there is a highlighted option, it will become the value of the combobox.
+
+Accessibility
+-------------
+
+The autocomplete component follows the [WAI combobox pattern: List with inline autocomplete and automatic selection](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#:~:text=List%20autocomplete%20with%20automatic,has%20a%20selected%20state). An example of this pattern outside of IDS can be seen at [WAI-ARIA combobox example](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-both/).
+
+There is a key difference:
+
+*   For better usability, virtual focus is used to highlight the suggestions inside the popover. This means focus remains on the input, but the suggestions are highlighted as if they are in focus, allowing the user to type and navigate the suggestions with the arrow keys.
+*   To denote the highlighted suggestion to screen readers, the `aria-activedescendant` attribute is used.
+
+Examples
+--------
+
+### Remove `autoSelect`
+
+The `autoSelect` prop will automatically select the highlighted option. This is set to true by default, but can be switched off, in which case the user must interact with the popover to select an option.
+
+[](./iframe.html?id=components-combobox--remove-auto-select)
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+<IressCombobox
+  autoSelect\={false}
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  placeholder\="Should no longer auto-select when an item is highlighted"
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+boolean
+
+
+
+ | 
+
+true
+
+ | FalseTrue |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| placeholder | 
+
+string
+
+
+
+ | \- | Should no longer auto-select when an item is highlighted |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+### Input props
+
+Autocomplete extends `IressInput`, hence it has the same properties as `IressInput`.
+
+It does have some defaults to help with user experience. `append` automatically has a search icon, and `clearable` and `watermark` are set to true by default.
+
+[](./iframe.html?id=components-combobox--input-props)
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+<IressCombobox
+  append\={<IressPopover activator\={<IressButton mode\="tertiary"\><IressIcon name\="cog" /></IressButton\>} align\="bottom-end" container\={document.body}\><IressPanel className\="iress-u-text"\>Some settings in here</IressPanel\></IressPopover\>}
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+  prepend\={<IressIcon name\="search" />}
+  width\="12"
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+object
+
+
+
+ | 
+
+<IressIcon />
+
+ | 
+
+Edit JSON
+
+append :
+
+{
+
+*   $$typeof : Symbol(react.transitional.element)
+*   type :
+    
+    {...} 5 keys
+    
+*   key : null
+*   props :
+    
+    {...} 4 keys
+    
+*   \_owner : null
+*   \_store :
+    
+    {...} 0 keys
+    
+
+}
+
+
+
+
+
+
+
+ |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| prepend | 
+
+object
+
+
+
+ | \- | 
+
+Edit JSON
+
+prepend :
+
+{
+
+*   $$typeof : Symbol(react.transitional.element)
+*   type :
+    
+    {...} 9 keys
+    
+*   key : null
+*   props :
+    
+    {...} 1 key
+    
+*   \_owner : null
+*   \_store :
+    
+    {...} 0 keys
+    
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+| width | 
+
+string
+
+
+
+ | \- | 12 |
+
+### No results
+
+If you would like to show a message when there are no results, you can use the `noResultsText` prop. It accepts any React node.
+
+[](./iframe.html?id=components-combobox--no-results-text)
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+<IressCombobox
+  noResultsText\={<IressPanel className\="iress-u-text"\>No results found</IressPanel\>}
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  placeholder\="Type &quot;no&quot; to see the no results text"
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+object
+
+
+
+ | \- | 
+
+Edit JSON
+
+noResultsText :
+
+{
+
+*   $$typeof : Symbol(react.transitional.element)
+*   type : ({ children, background = "default", noBorderRadius, noGutter, padding = "md", stretch, textAlign = "inherit", className, ...restProps }) => { const classMap = { \[PanelCssClass.Stretch\]: stretch, \[PanelCssClass.NoBorderRadius\]: noBorderRadius, \[PanelCssClass.NoGutter\]: noGutter }; const cssClasses = classNames( className, PanelCssClass.Base, \`${GlobalCSSClass.TextAlignBase}--${textAlign}\`, \`${PanelCssClass.Background}--${background}\`, getResponsivePaddingClasses(padding), classMap ); return /\* @\_\_PURE\_\_ \*/ jsxDEV("div", { className: cssClasses, ...restProps, children }, void 0, false, { fileName: "/home/runner/work/design-system/design-system/packages/components/src/components/Panel/Panel.tsx", lineNumber: 38, columnNumber: 5 }, this); }
+*   key : null
+*   props :
+    
+    {...} 2 keys
+    
+*   \_owner : null
+*   \_store :
+    
+    {...} 0 keys
+    
+
+}
+
+
+
+
+
+
+
+ |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| placeholder | 
+
+string
+
+
+
+ | \- | Type "no" to see the no results text |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+### Popover props
+
+Under the hood, autocomplete uses `IressInputPopover` to display the suggestions. It accepts `autoHighlight`, `align`, `className` and `displayMode`.
+
+There are two additional props that autocomplete accepts to customise the popover: `append` and `prepend`. You can place additional content above or below the results using these props.
+
+[](./iframe.html?id=components-combobox--popover-props)
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+<IressCombobox
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  popoverProps\={{
+    append: <IressPanel\><IressButton\>Add an option</IressButton\></IressPanel\>,
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+*   append :
+    
+    {...} 6 keys
+    
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+### Debounce threshold
+
+The `debounceThreshold` prop can be used to set the time in milliseconds to wait before making a request to the `options` function. This is useful when you want to prevent making too many requests to the server.
+
+By default there is a debounce of `500`ms, but it can be removed by setting it to `0`.
+
+**Note:** Removing the debounce and keeping `autoSelect` true may cause some weird highlighting issues if the user types quickly.
+
+[](./iframe.html?id=components-combobox--debounce-threshold)
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+<IressCombobox
+  debounceThreshold\={0}
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  placeholder\="Instant search!"
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| debounceThreshold | 
+
+number
+
+
+
+ | \- |  |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| placeholder | 
+
+string
+
+
+
+ | \- | Instant search! |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+### Result limits
+
+You can limit the maximum amount of search results displayed in the suggestions by setting the `limitDesktop` prop. This defaults to 12.
+
+On smaller screens (< 768px), the number of options is further reduced by using the `limitMobile` prop, which defaults to 6.
+
+`limitMobile` works by filtering the search results that have been filtered by `limitDesktop`, so must be a smaller value. For example:
+
+// 12 results on large screens, 6 on small screens (default values)
+<IressCombobox options\={...} />
+// 4 results on large screens, 3 on small screens
+<IressCombobox limitDesktop\={4} limitMobile\={3} options\={...} />
+// 4 results on all screens (resultLimitMobile > resultLimitDesktop so has no effect)
+<IressCombobox limitDesktop\={4} limitMobile\={5} options\={...} />
+
+```
+
+The result limits will also affect the number of initial options displayed, if the `initialOptions` prop is set.
+
+[](./iframe.html?id=components-combobox--result-limits)
+
+**xl** breakpoint (1200px - 1499px)
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+<IressStack gutter\="md"\>
+  <IressPanel className\="iress-u-text"\>
+    <Ln />
+  </IressPanel\>
+  <IressCombobox
+    limitDesktop\={6}
+    limitMobile\={3}
+    options\={\[
+      {
+        label: 'Option 1'
+      },
+      {
+        label: 'Option 2'
+      },
+      {
+        label: 'Option 3'
+      },
+      {
+        label: 'Option 4'
+      },
+      {
+        label: 'Option 5'
+      },
+      {
+        label: 'Option 6'
+      },
+      {
+        label: 'Option 7'
+      },
+      {
+        label: 'Option 8'
+      },
+      {
+        label: 'Option 9'
+      },
+      {
+        label: 'Option 10'
+      },
+      {
+        label: 'Option 11'
+      },
+      {
+        label: 'Option 12'
+      },
+      {
+        label: 'Option 13'
+      },
+      {
+        label: 'Option 14'
+      },
+      {
+        label: 'Option 15'
+      }
+    \]}
+    popoverProps\={{
+      container: {}
+    }}
+  />
+</IressStack\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| limitDesktop | 
+
+number
+
+
+
+ | 
+
+12
+
+ |  |
+| limitMobile | 
+
+number
+
+
+
+ | 
+
+6
+
+ |  |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    *   3 :
+        
+        {...} 1 key
+        
+    *   4 :
+        
+        {...} 1 key
+        
+    *   5 :
+        
+        {...} 1 key
+        
+    *   6 :
+        
+        {...} 1 key
+        
+    *   7 :
+        
+        {...} 1 key
+        
+    *   8 :
+        
+        {...} 1 key
+        
+    *   9 :
+        
+        {...} 1 key
+        
+    *   10 :
+        
+        {...} 1 key
+        
+    *   11 :
+        
+        {...} 1 key
+        
+    *   12 :
+        
+        {...} 1 key
+        
+    *   13 :
+        
+        {...} 1 key
+        
+    *   14 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+### Readonly
+
+The `readOnly` prop can be set to prevent the user from changing the value of the autocomplete. This will change the input to a custom read-only style and the user will not be able to interact with the input.
+
+If you need more control over the read-only state (for example, rendering a stylised version of the value), you can use the [`IressReadonly` component](?path=/docs/components-readonly--docs).
+
+[](./iframe.html?id=components-combobox--readonly)
+
+Option 1
+
+Hide codedrawOpen in CodeSandbox
+
+<IressCombobox
+  defaultValue\={{
+    label: 'Option 1',
+    value: 1
+  }}
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+  readOnly
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | 
+
+Edit JSON
+
+defaultValue :
+
+{
+
+*   label : "Option 1"
+*   value : 1
+
+}
+
+
+
+
+
+
+
+ |
+| hiddenInputProps | 
+
+Add additional props to the hidden input.
+
+Omit
+
+
+
+ | \- | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options\* | 
+
+Options data set, the available options that the user can select from.
+
+union
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| readOnly | 
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta
+
+
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+`IressMultiCombobox`
+--------------------
+
+`IressMultiCombobox` is a multi-select version of `IressCombobox`. It allows the user to select multiple options from a list. The selected items will be displayed as tags, as well as within the popover.
+
+* * *
+
+Caution
+
+**Use IressRichSelect instead**
+
+The design of this component is changing. Please use the new component/props instead.
+
+[](./iframe.html?id=components-combobox-multicombobox--options)
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+<IressMultiCombobox
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta\[\]
+
+ | \- | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| multiOptionTagLimit | 
+
+The number of select options before the view switches to a single aggregate tag.
+
+number
+
+
+
+ | 
+
+4
+
+ | Set number |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta\[\], ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| selectedOptionsTagText | 
+
+Text displayed next to tag count in tag when tag limit is exceeded.
+
+string
+
+
+
+ | 
+
+'options selected'
+
+ | Set string |
+| type | 
+
+ | 
+
+'search'
+
+ | Set object |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta\[\]
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+### Tag limit
+
+When combobox is in multi-select mode and the number of selected options exceeds the `multiOptionTagLimit` (`4` by default), the view will switch from a collection of tags to a single aggregate tag with a count of the number of selected options.
+
+The text displayed in the single tag can be modified using the `selectedOptionsTagText` prop (it is set to `options selected` by default).
+
+[](./iframe.html?id=components-combobox-multicombobox--tag-limit)
+
+3 options selected
+
+None selected
+
+Hide codedrawOpen in CodeSandbox
+
+<IressMultiCombobox
+  defaultValue\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    }
+  \]}
+  multiOptionTagLimit\={2}
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+  selectedOptionsTagText\="options selected"
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta\[\]
+
+ | \- | 
+
+Edit JSON
+
+*   defaultValue :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| multiOptionTagLimit | 
+
+The number of select options before the view switches to a single aggregate tag.
+
+number
+
+
+
+ | 
+
+4
+
+ |  |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta\[\], ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| selectedOptionsTagText | 
+
+Text displayed next to tag count in tag when tag limit is exceeded.
+
+string
+
+
+
+ | 
+
+'options selected'
+
+ | options selected |
+| type | 
+
+ | 
+
+'search'
+
+ | Set object |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta\[\]
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+### Readonly
+
+The `readOnly` prop can be set to prevent the user from changing the value of the multi-combobox. This will change the input to a custom read-only style and the user will not be able to interact with the input. Multiple values are seperated by a comma.
+
+If you need more control over the read-only state (for example, rendering a stylised version of the value), you can use the [`IressReadonly` component](?path=/docs/components-readonly--docs).
+
+[](./iframe.html?id=components-combobox-multicombobox--readonly)
+
+Option 1, Option 2, Option 3
+
+Hide codedrawOpen in CodeSandbox
+
+<IressMultiCombobox
+  defaultValue\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    }
+  \]}
+  options\={\[
+    {
+      label: 'Option 1',
+      value: 1
+    },
+    {
+      label: 'Option 2',
+      value: 2
+    },
+    {
+      label: 'Option 3',
+      value: 3
+    },
+    {
+      label: 'Option 4',
+      value: 4
+    },
+    {
+      label: 'Option 5',
+      value: 5
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+  readOnly
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| append | 
+ | 
+
+<IressIcon />
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+ | 
+
+true
+
+ | Set object |
+| clearable | 
+
+ | 
+
+true
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled combobox.
+
+LabelValueMeta\[\]
+
+ | \- | 
+
+Edit JSON
+
+*   defaultValue :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| multiOptionTagLimit | 
+
+The number of select options before the view switches to a single aggregate tag.
+
+number
+
+
+
+ | 
+
+4
+
+ | Set number |
+| onChange | 
+
+Emitted when the value changes.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: LabelValueMeta\[\], ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+Edit JSON
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 2 keys
+        
+    *   1 :
+        
+        {...} 2 keys
+        
+    *   2 :
+        
+        {...} 2 keys
+        
+    *   3 :
+        
+        {...} 2 keys
+        
+    *   4 :
+        
+        {...} 2 keys
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+object
+
+
+
+ | { } | 
+
+Edit JSON
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| readOnly | 
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| selectedOptionsTagText | 
+
+Text displayed next to tag count in tag when tag limit is exceeded.
+
+string
+
+
+
+ | 
+
+'options selected'
+
+ | Set string |
+| type | 
+
+ | 
+
+'search'
+
+ | Set object |
+| value | 
+
+Value of selected option for controlled combobox.
+
+LabelValueMeta\[\]
+
+ | \- | Set object |
+| watermark | 
+
+ | 
+
+true
+
+ | Set object |
+
+Testing
+-------
+
+To help you effectively test the combobox component, we have provided a few tips based on the behaviour of the component and our own experience.
+
+**Note:** These are suggestions and not requirements. You should test the component in a way that best suits your use case.
+
+### Partial query matching
+
+The suggestions are filtered based on the input value. If the input value only matches a part of the option, the input value is highlighted by a `<b />` tag in each option. You will need to account for this in your tests, either using an exact string match with a space to denote the highlighted value, or using a regex to match the string.
+
+If you are using `meta`, `prepend` or `append` props in `LabelValueMeta`, you should also consider this in your search query for the option.
+
+render(
+  <IressCombobox
+    options\={\[
+      { label: 'Luke Skywalker', value: 'Luke Skywalker', meta: 'male' },
+    \]}
+  />,
+);
+const autocomplete \= screen.getByRole('combobox');
+await user.type(autocomplete, 'lu');
+// Exact string match with a space to denote the highlighted value
+const option \= await screen.findByRole('option', {
+  name: 'Lu ke Skywalker male',
+});
+expect(option).toBeInTheDocument();
+// Using a regex to match the string
+const option \= await screen.findByRole('option', { name: /Skywalker/ });
+expect(option).toBeInTheDocument();
+
+```
+
+### Query for minimal characters
+
+If you are testing if a specific option appears in the autocomplete that returns asynchronous `options`, it is recommended to use the shortest possible query to return the desired result. The longer the query, the longer it will take to see the results.
+
+render(<IressCombobox options\={searchStarWarsCharacters} />);
+const autocomplete \= screen.getByRole('combobox');
+// DO: Use the shortest query to return the desired result
+await user.type(autocomplete, 'lu');
+const option \= await screen.findAllByRole('option');
+// DON'T: Use a long query to return the desired result
+await user.type(autocomplete, 'luke skywalker');
+const option \= await screen.findAllByRole('option');
+
+```
+
+### Use mocking when testing APIs
+
+When testing the autocomplete component with asynchronous `options`, you should mock the API call to return a known set of results, rather than rely on a public prototyping API (eg. [https://swapi.py4e.com/](https://swapi.py4e.com/)). This will allow you to test the component in isolation without relying on the API to return the expected results, as well as reduce chance of flakiness due to timeouts in your tests.
+
+We recommend using [Mock Service Worker](https://mswjs.io/) to mock the API calls in your tests.
+
+// src/mocks/handlers.ts
+import { http, HttpResponse } from 'msw';
+export const handlers \= \[
+  // Intercept "GET https://swapi.py4e.com/api/people" requests...
+  http.get('https://swapi.py4e.com/api/people', () \=> {
+    // ...and respond to them using this JSON response.
+    return HttpResponse.json(\[
+      { name: 'Luke Skywalker', gender: 'male' },
+      { name: 'Leia Skywalker', gender: 'female' },
+    \]);
+  }),
+\];
+// src/mocks/node.js
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+export const server \= setupServer(...handlers);
+// src/CustomAutocomplete.test.tsx
+import { server } from './mocks/node';
+server.listen();
+render(<IressCombobox options\={searchStarWarsCharacters} />);
+const autocomplete \= screen.getByRole('combobox');
+await user.type(autocomplete, 'lu');
+const option \= await screen.findAllByRole('option');
+
+```