Combobox
This component allows users to select from a list of options. It’s especially useful when there are many options to choose from.
import { ... } from '@ag.ds-next/react/combobox';Usage
Combobox components can be imported via the combobox entrypoint in the @ag.ds-next/react package.
For example:
import { ... } from '@ag.ds-next/react/combobox';Props
| Prop | Type | Description |
|---|---|---|
| label | string | Describes the purpose of the field. |
| options | Option[] | The list of options to show in the dropdown. |
| block? | boolean | If true, the field will stretch to the fill the width of its container. |
| clearable? | boolean | If true, the clear button will be rendered when there is a selected option. |
| disabled? | boolean | If true, the field will not be interactive. |
| emptyResultsMessage? | string | Message to display when no options match the users search term. |
| hideOptionalLabel? | boolean | If true, "(optional)" will never be appended to the label. |
| hint? | string | Provides extra information about the field. |
| id? | string | Defines an identifier (ID) which must be unique. |
| inputRef? | Ref<HTMLInputElement> | Ref to the input element. |
| invalid? | boolean | If true, the invalid state will be rendered. |
| maxWidth? | "md" | "lg" | "xl" | The maximum width of the field. |
| message? | string | Message to show when the field is invalid. |
| name? | string | A string specifying a name for the input control. |
| onBlur? | FocusEventHandler<HTMLInputElement> | Function to be fired following a blur event. |
| onChange? | ((value: Option | null) => void) | Function to be fired following a change event. |
| onFocus? | FocusEventHandler<HTMLInputElement> | Function to be fired following a focus event. |
| renderItem? | ((item: Option, inputValue?: string) => ReactNode) | Used to override the default item rendering. inputValue is now unused. |
| required? | boolean | If false, "(optional)" will be appended to the label. |
| value? | DefaultComboboxOption | null | The value of the field. |
| Prop | Type | Description |
|---|---|---|
| label | string | Describes the purpose of the field. |
| loadOptions | (inputValue: string) => Promise<Option[]> | Function to be used when options need to be loaded over the network. |
| block? | boolean | If true, the field will stretch to the fill the width of its container. |
| clearable? | booleanDefault: false | If true, the clear button will be rendered when there is a selected option. |
| disabled? | boolean | If true, the field will not be interactive. |
| emptyResultsMessage? | string | Message to display when no options match the users search term. |
| hideOptionalLabel? | boolean | If true, "(optional)" will never be appended to the label. |
| hint? | string | Provides extra information about the field. |
| id? | string | Defines an identifier (ID) which must be unique. |
| inputRef? | RefObject<HTMLInputElement> | Ref to the input element. |
| invalid? | boolean | If true, the invalid state will be rendered. |
| maxWidth? | "md" | "lg" | "xl" | The maximum width of the field. |
| message? | string | Message to show when the field is invalid. |
| name? | string | A string specifying a name for the input control. |
| onBlur? | FocusEventHandler<HTMLInputElement> | Function to be fired following a blur event. |
| onChange? | ((value: Option | null) => void) | Function to be fired following a change event. |
| onFocus? | FocusEventHandler<HTMLInputElement> | Function to be fired following a focus event. |
| openDropdownOnFocus? | boolean | @deprecated This prop is no longer being used. When true, the dropdown will open when the user focuses on the element |
| renderItem? | ((item: Option, inputValue?: string) => ReactNode) | Used to override the default item rendering. inputValue is now unused. |
| required? | boolean | If false, "(optional)" will be appended to the label. |
| showDropdownTrigger? | booleanDefault: true | If true, the dropdown trigger will be rendered. |
| value? | DefaultComboboxOption | null | The value of the field. |
| Prop | Type | Description |
|---|---|---|
| label | string | Describes the purpose of the field. |
| options | Option[] | The list of options to show in the dropdown. |
| block? | booleanDefault: true | If true, the field will stretch to the fill the width of its container and ignore maxWidth. |
| disabled? | boolean | If true, the field will not be interactive. |
| emptyResultsMessage? | string | Message to display when no options match the users search term. |
| hideOptionalLabel? | boolean | If true, "(optional)" will never be appended to the label. |
| hint? | string | Provides extra information about the field. |
| id? | string | Defines an identifier (ID) which must be unique. |
| inputRef? | Ref<HTMLInputElement> | Ref to the input element. |
| invalid? | boolean | If true, the invalid state will be rendered. |
| maxWidth? | "md" | "lg" | "xl" | The maximum width of the field. |
| message? | string | Message to show when the field is invalid. |
| name? | string | A string specifying a name for the input control. |
| onBlur? | FocusEventHandler<HTMLInputElement> | Function to be fired following a blur event. |
| onChange? | ((value: Option[]) => void) | Function to be fired following a change event. |
| onFocus? | FocusEventHandler<HTMLInputElement> | Function to be fired following a focus event. |
| renderItem? | ((item: Option, inputValue?: string) => ReactNode) | Used to override the default item rendering. inputValue is now unused. |
| required? | boolean | If false, "(optional)" will be appended to the label. |
| value? | Option[] | The value of the field. |
| Prop | Type | Description |
|---|---|---|
| label | string | Describes the purpose of the field. |
| loadOptions | (inputValue: string) => Promise<Option[]> | Function to be used when options need to be loaded over the network. |
| block? | booleanDefault: true | If true, the field will stretch to the fill the width of its container and ignore maxWidth. |
| disabled? | boolean | If true, the field will not be interactive. |
| emptyResultsMessage? | string | Message to display when no options match the users search term. |
| hideOptionalLabel? | boolean | If true, "(optional)" will never be appended to the label. |
| hint? | string | Provides extra information about the field. |
| id? | string | Defines an identifier (ID) which must be unique. |
| inputRef? | Ref<HTMLInputElement> | Ref to the input element. |
| invalid? | boolean | If true, the invalid state will be rendered. |
| maxWidth? | "md" | "lg" | "xl" | The maximum width of the field. |
| message? | string | Message to show when the field is invalid. |
| name? | string | A string specifying a name for the input control. |
| onBlur? | FocusEventHandler<HTMLInputElement> | Function to be fired following a blur event. |
| onChange? | ((value: Option[]) => void) | Function to be fired following a change event. |
| onFocus? | FocusEventHandler<HTMLInputElement> | Function to be fired following a focus event. |
| renderItem? | ((item: Option, inputValue?: string) => ReactNode) | Used to override the default item rendering. inputValue is now unused. |
| required? | boolean | If false, "(optional)" will be appended to the label. |
| value? | Option[] | The value of the field. |
| Prop | Type | Description |
|---|---|---|
| itemLabel | string | The label of the item. |
| beforeElement? | ReactNode | Used to add decorative elements to the end of the item such as Indicator dot or Notification badge. |
| endElement? | ReactNode | Used to add decorative elements to the end of the item such as Indicator dot or Notification badge. |
| inputValue? | string | @deprecated Unused. Individual items no longer need to know the value of the Combobox/Autocomplete text input. |
| secondaryText? | ReactNode | Supporting text for the item. |
| tertiaryText? | ReactNode | Supporting text for the item. |
Source
You can view the full source code for this package on Github.