@iress-oss/ids-mcp-server 6.0.0-alpha.1-canary-20251204033039-51f1bf8 → 6.0.0-alpha.2

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

@@ -0,0 +1,3304 @@
+Autocomplete
+============
+
+Overview
+--------
+
+Autocomplete allow for users to fill in their input by providing suggestions as they type.
+
+[](./iframe.html?id=components-autocomplete--default)
+
+```
+
+<IressAutocomplete
+  options\={\[
+    {
+      label: 'Option 1'
+    },
+    {
+      label: 'Option 2'
+    },
+    {
+      label: 'Option 3'
+    },
+    {
+      label: 'Option 4'
+    },
+    {
+      label: 'Option 5'
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+Props
+-----
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    *   3 :
+        
+        {...} 1 key
+        
+    *   4 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+
+Usage
+-----
+
+The `IressAutocomplete` element extends `IressInput` with additional functionality to provide suggestions to the user as they type.
+
+There is no validation done between the suggestions and the input value. They are strictly suggestions to improve the user experience. If you would like to restrict the input to the suggestions, you can use `IressCombobox`.
+
+### Uncontrolled
+
+The `defaultValue` prop can be used to set the initial value of the input. The value will be managed by the component.
+
+[](./iframe.html?id=components-autocomplete--uncontrolled)
+
+```
+
+<IressAutocomplete
+  defaultValue\="Option 1"
+  options\={\[
+    {
+      label: 'Option 1'
+    },
+    {
+      label: 'Option 2'
+    },
+    {
+      label: 'Option 3'
+    },
+    {
+      label: 'Option 4'
+    },
+    {
+      label: 'Option 5'
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| defaultValue | 
+
+string
+
+
+
+ | \- | Option 1 |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    *   3 :
+        
+        {...} 1 key
+        
+    *   4 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+
+### 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.
+
+[](./iframe.html?id=components-autocomplete--controlled)
+
+```
+
+import { IressAutocomplete, type IressAutocompleteProps } from '@iress-oss/ids-components';
+import { useState } from 'react';
+export const AutocompleteUsingState \= () \=> {
+  const \[value, setValue\] \= useState('Option 1');
+  return (
+    <IressAutocomplete
+      {...{
+  popoverProps: {
+    container: {},
+  },
+  options: \[
+    {
+      label: 'Option 1',
+    },
+    {
+      label: 'Option 2',
+    },
+    {
+      label: 'Option 3',
+    },
+    {
+      label: 'Option 4',
+    },
+    {
+      label: 'Option 5',
+    },
+  \],
+}}
+      onChange\={(\_e, newValue) \=> setValue(newValue ?? '')}
+      onClear\={() \=> setValue('')}
+      value\={value}
+    />
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| defaultValue | 
+
+\-
+
+ | \- | \- |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    *   3 :
+        
+        {...} 1 key
+        
+    *   4 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| value | 
+
+\-
+
+ | \- | \- |
+
+### Providing suggestions
+
+#### `options`
+
+To use the suggestion functionality, you can provide an array of `LabelValueMeta[]` objects to the `options` prop.
+
+**Note:** If `value` is provided on a suggestion item, it will be used (casted to a string) instead of the `label` key. This is useful when you want to display a different value to the user than what is used for filtering.
+
+[](./iframe.html?id=components-autocomplete--options)
+
+```
+
+<IressAutocomplete
+  options\={\[
+    {
+      label: 'Option 1'
+    },
+    {
+      label: 'Option 2'
+    },
+    {
+      label: 'Option 3'
+    },
+    {
+      label: 'Option 4'
+    },
+    {
+      label: 'Option 5'
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    *   3 :
+        
+        {...} 1 key
+        
+    *   4 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+
+#### 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.
+
+[](./iframe.html?id=components-autocomplete--async-options)
+
+```
+
+import { IressAutocomplete, type IressAutocompleteProps } from '@iress-oss/ids-components';
+interface StarWarsCharacter {
+  name: string;
+  gender: string;
+}
+interface StarWarsCharacterApi {
+  results: StarWarsCharacter\[\];
+}
+export const AutocompleteUsingAsync \= () \=> (
+  <IressAutocomplete
+    {...{
+  popoverProps: {
+    container: {},
+  },
+  placeholder: 'Search star wars characters, or type "error" to see the error text',
+}}
+    options\={async (query: string) \=> {
+      if (query \=== 'error') {
+        throw new Error('This is an error');
+      }
+      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 |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+\-
+
+ | \- | \- |
+| placeholder | 
+
+string
+
+
+
+ | \- | Search star wars characters, or type "error" to see the error text |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+
+#### Minimum search length for async options
+
+When using asynchronous options, you can set a minimum number of characters required before triggering the search using the `minSearchLength` prop. This prevents unnecessary API calls and loading states for very short queries.
+
+By default, async searches are triggered after 1 character. Setting a higher value (e.g., 3) means no search request will be made and no loading spinner will appear until the user types at least that many characters.
+
+[](./iframe.html?id=components-autocomplete--async-options-min-search-length)
+
+```
+
+import { IressAutocomplete, type IressAutocompleteProps } from '@iress-oss/ids-components';
+interface StarWarsCharacter {
+  name: string;
+  gender: string;
+}
+interface StarWarsCharacterApi {
+  results: StarWarsCharacter\[\];
+}
+export const AutocompleteUsingAsync \= () \=> (
+  <IressAutocomplete
+    {...{
+  popoverProps: {
+    container: {},
+  },
+  minSearchLength: 3,
+}}
+    options\={async (query: string) \=> {
+      if (query \=== 'error') {
+        throw new Error('This is an error');
+      }
+      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 |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| minSearchLength | 
+
+number
+
+
+
+ | \- |  |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+\-
+
+ | \- | \- |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+
+#### `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).
+
+[](./iframe.html?id=components-autocomplete--initial-options)
+
+```
+
+<IressAutocomplete
+  initialOptions\={\[
+    {
+      label: 'Favourite option 1'
+    },
+    {
+      label: 'Favourite option 2'
+    },
+    {
+      label: 'Favourite option 3'
+    }
+  \]}
+  options\={\[
+    {
+      label: 'Option 1'
+    },
+    {
+      label: 'Option 2'
+    },
+    {
+      label: 'Option 3'
+    },
+    {
+      label: 'Option 4'
+    },
+    {
+      label: 'Option 5'
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| initialOptions | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   initialOptions :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    *   3 :
+        
+        {...} 1 key
+        
+    *   4 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+
+Behaviour
+---------
+
+*   As long as there is a single character in the input, the suggestions will be displayed in a popover. Unless `initialOptions` are provided where the popover will be displayed immediately on focus.
+*   The popover will close when the input is empty, unless `initialOptions` are provided.
+*   The suggestions will be filtered based on the input value.
+*   Tapping on a suggestion with the mouse will change the input value to the selection and close the popover.
+*   When the user presses the arrows keys while the input is focussed, suggestions will be highlighted, but focus remains on the input.
+*   When the user presses the enter key while a suggestion is highlighted, the suggestion 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 suggestion is highlighted, it will close the popover.
+*   When the user tabs away while no suggestion is highlighted, the input will not be changed.
+*   When the user tabs away while a suggestion is highlighted, the suggestion will be selected.
+*   When the user tabs away while the popover is open, the popover will close.
+
+Accessibility
+-------------
+
+The autocomplete component follows the [WAI combobox pattern: List autocomplete with manual selection](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#:~:text=List%20autocomplete%20with%20manual,value%20in%20the%20popup). 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-list/).
+
+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
+--------
+
+### `autoSelect`
+
+The `autoSelect` prop will automatically select the highlighted option when the user blurs the autocomplete. This is set to true by default, but can be switched off.
+
+[](./iframe.html?id=components-autocomplete--remove-auto-select)
+
+```
+
+<IressAutocomplete
+  autoSelect\={false}
+  options\={\[
+    {
+      label: 'Option 1'
+    },
+    {
+      label: 'Option 2'
+    },
+    {
+      label: 'Option 3'
+    },
+    {
+      label: 'Option 4'
+    },
+    {
+      label: 'Option 5'
+    }
+  \]}
+  placeholder\="Should no longer auto-select when an item is highlighted"
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | FalseTrue |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    *   3 :
+        
+        {...} 1 key
+        
+    *   4 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| placeholder | 
+
+string
+
+
+
+ | \- | Should no longer auto-select when an item is highlighted |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+
+### 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` is set to true by default.
+
+[](./iframe.html?id=components-autocomplete--input-props)
+
+```
+
+<IressAutocomplete
+  append\={<IressPopover activator\={<IressButton mode\="tertiary"\><IressIcon name\="cog" /></IressButton\>} align\="bottom-end" container\={document.body}\><IressPanel\>Some settings in here</IressPanel\></IressPopover\>}
+  options\={\[
+    {
+      label: 'Option 1'
+    },
+    {
+      label: 'Option 2'
+    },
+    {
+      label: 'Option 3'
+    },
+    {
+      label: 'Option 4'
+    },
+    {
+      label: 'Option 5'
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+  prepend\={<IressIcon name\="search" />}
+  width\="12"
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | 
+
+RAW
+
+append :
+
+{
+
+*   $$typeof : Symbol(react.transitional.element)
+*   type :
+    
+    {...} 3 keys
+    
+*   key : null
+*   props :
+    
+    {...} 4 keys
+    
+*   \_owner : null
+*   \_store :
+    
+    {...} 0 keys
+    
+
+}
+
+
+
+
+
+
+
+ |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    *   3 :
+        
+        {...} 1 key
+        
+    *   4 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| prepend | 
+
+object
+
+
+
+ | \- | 
+
+RAW
+
+prepend :
+
+{
+
+*   $$typeof : Symbol(react.transitional.element)
+*   type : ({ className, fixedWidth, flip, name, rotate, screenreaderText, set = "fal", spin, ...restProps }) => { const prefix = "fa-"; const classes = icon({ flip, rotate, spin }); return /\* @\_\_PURE\_\_ \*/ jsxDEV( styled.span, { role: "img", className: cx( classes, GlobalCSSClass.Icon, set, \`${prefix}${name}\`, fixedWidth && "fa-fw", className ), "aria-hidden": !screenreaderText && "true", "aria-label": screenreaderText, ...restProps }, void 0, false, { fileName: "/home/runner/work/design-system/design-system/packages/components/src/components/Icon/Icon.tsx", lineNumber: 67, columnNumber: 5 }, this ); }
+*   key : null
+*   props :
+    
+    {...} 1 key
+    
+*   \_owner : null
+*   \_store :
+    
+    {...} 0 keys
+    
+
+}
+
+
+
+
+
+
+
+ |
+| 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-autocomplete--no-results-text)
+
+```
+
+<IressAutocomplete
+  noResultsText\={<IressPanel\>No results found</IressPanel\>}
+  options\={\[
+    {
+      label: 'Option 1'
+    },
+    {
+      label: 'Option 2'
+    },
+    {
+      label: 'Option 3'
+    },
+    {
+      label: 'Option 4'
+    },
+    {
+      label: 'Option 5'
+    }
+  \]}
+  placeholder\="Type &quot;no&quot; to see the no results text"
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | 
+
+RAW
+
+noResultsText :
+
+{
+
+*   $$typeof : Symbol(react.transitional.element)
+*   type : ({ className, ...restProps }) => /\* @\_\_PURE\_\_ \*/ jsxDEV(Component, { ...restProps, className: cx(className, GlobalCSSClass.Panel) }, void 0, false, { fileName: "/home/runner/work/design-system/design-system/packages/components/src/components/Panel/Panel.tsx", lineNumber: 26, columnNumber: 1 }, this)
+*   key : null
+*   props :
+    
+    {...} 1 key
+    
+*   \_owner : null
+*   \_store :
+    
+    {...} 0 keys
+    
+
+}
+
+
+
+
+
+
+
+ |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    *   3 :
+        
+        {...} 1 key
+        
+    *   4 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| placeholder | 
+
+string
+
+
+
+ | \- | Type "no" to see the no results text |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+
+### 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-autocomplete--popover-props)
+
+```
+
+<IressAutocomplete
+  options\={\[
+    {
+      label: 'Option 1'
+    },
+    {
+      label: 'Option 2'
+    },
+    {
+      label: 'Option 3'
+    },
+    {
+      label: 'Option 4'
+    },
+    {
+      label: 'Option 5'
+    }
+  \]}
+  popoverProps\={{
+    append: <IressPanel\><IressButton\>Add an option</IressButton\></IressPanel\>,
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    *   3 :
+        
+        {...} 1 key
+        
+    *   4 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+*   append :
+    
+    {...} 6 keys
+    
+
+}
+
+
+
+
+
+
+
+ |
+
+### 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, but it can be removed by setting it to `0`.
+
+[](./iframe.html?id=components-autocomplete--debounce-threshold)
+
+```
+
+<IressAutocomplete
+  debounceThreshold\={0}
+  options\={\[
+    {
+      label: 'Option 1'
+    },
+    {
+      label: 'Option 2'
+    },
+    {
+      label: 'Option 3'
+    },
+    {
+      label: 'Option 4'
+    },
+    {
+      label: 'Option 5'
+    }
+  \]}
+  placeholder\="Instant search!"
+  popoverProps\={{
+    container: {}
+  }}
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| debounceThreshold | 
+
+number
+
+
+
+ | \- |  |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    *   3 :
+        
+        {...} 1 key
+        
+    *   4 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| placeholder | 
+
+string
+
+
+
+ | \- | Instant search! |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+
+### 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)
+<IressAutocomplete options\={...} />
+// 4 results on large screens, 3 on small screens
+<IressAutocomplete resultLimitDesktop\={4} resultLimitMobile\={3} options\={...} />
+// 4 results on all screens (resultLimitMobile > resultLimitDesktop so has no effect)
+<IressAutocomplete resultLimitDesktop\={4} resultLimitMobile\={5} options\={...} />
+
+```
+
+The result limits will also affect the number of initial options displayed, if the `initialOptions` prop is set.
+
+[](./iframe.html?id=components-autocomplete--result-limits)
+
+**xl** breakpoint (1200px - 1499px)
+
+```
+
+<IressStack gap\="md"\>
+  <IressPanel\>
+    <kn />
+  </IressPanel\>
+  <IressAutocomplete
+    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 |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+number
+
+
+
+ | 
+
+12
+
+ |  |
+| limitMobile | 
+
+number
+
+
+
+ | 
+
+6
+
+ |  |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   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 | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+
+### Read only
+
+The `readOnly` prop can be set to `true` 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-autocomplete--read-only)
+
+Option 1
+
+```
+
+<IressAutocomplete
+  defaultValue\="Option 1"
+  options\={\[
+    {
+      label: 'Option 1'
+    },
+    {
+      label: 'Option 2'
+    },
+    {
+      label: 'Option 3'
+    },
+    {
+      label: 'Option 4'
+    },
+    {
+      label: 'Option 5'
+    }
+  \]}
+  popoverProps\={{
+    container: {}
+  }}
+  readOnly
+/>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alwaysShowOnFocus | 
+Always shown on focus, even if the user has not interacted with the input.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Append content.
+
+ReactNode
+
+
+
+ | 
+
+<IressIcon />
+
+
+
+ | Set object |
+| autoComplete | 
+
+ | 
+
+'off'
+
+ | Set object |
+| autoSelect | 
+
+If true, the selected option becomes the value of the input when the autocomplete loses focus.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| clearable | 
+
+If `true`, then user can clear the value of the input.
+
+boolean
+
+
+
+ | 
+
+true
+
+ | Set boolean |
+| defaultValue | 
+
+string
+
+
+
+ | \- | Option 1 |
+| errorText | 
+
+Text to be displayed when the options function errors out. It is not used when the options are provided as an array.
+
+ReactNode
+
+
+
+ | 
+
+<IressAlert />
+
+
+
+ | Set object |
+| limitDesktop | 
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+ | 
+
+6
+
+ | Set object |
+| noResultsText | 
+
+Text to be displayed when no results are found.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the user changes the input. The second and third arguments are only available when the options were selected from the `options` prop.
+
+( e?: SyntheticEvent<InputBaseElement>, value?: T, option?: LabelValueMeta, ) => void
+
+ | \- | \- |
+| options | 
+
+array
+
+
+
+ | \- | 
+
+RAW
+
+*   options :
+    
+    \[
+    
+    *   0 :
+        
+        {...} 1 key
+        
+    *   1 :
+        
+        {...} 1 key
+        
+    *   2 :
+        
+        {...} 1 key
+        
+    *   3 :
+        
+        {...} 1 key
+        
+    *   4 :
+        
+        {...} 1 key
+        
+    
+    \]
+    
+
+
+
+ |
+| popoverProps | 
+
+Customise the IressInputPopover props for your needs.
+
+AutocompletePopoverProps
+
+
+
+ | { } | 
+
+RAW
+
+popoverProps :
+
+{
+
+}
+
+
+
+
+
+
+
+ |
+| readOnly | 
+
+boolean
+
+
+
+ | \- | FalseTrue |
+
+Testing
+-------
+
+To help you effectively test the autocomplete 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(
+  <IressAutocomplete
+    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(<IressAutocomplete 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(<IressAutocomplete options\={searchStarWarsCharacters} />);
+const autocomplete \= screen.getByRole('combobox');
+await user.type(autocomplete, 'lu');
+const option \= await screen.findAllByRole('option');
+
+```