ComboBox

core package3.2.2

Note: All components shown on this site are supported by the Constellation design system. To learn how to configure Theme Cosmos, visit Pega Community.

The ComboBox component is a fully-featured dropdown Menu that manages state of selected items. If you only require users to select single options that render as plain text, we recommend using the Select component instead.

Usage

The ComboBox component can be configured for one of two modes: single-select and multi-select. If the mode is set to multi-select, you can pass an object for selected props. By doing so, you can control which selected items should render as Selectable badges within the ComboBox input region.

The input region can also be used to filter results within the menu by utilizing the onChange callback function. The rendering of the Menu and its items will depend on the props passed to the ComboBox's menu prop. This component also allows for standard Form Field structures such as being set required, disabled, or readOnly, as well as including a label, status, or info. If an onResolveSuggestion callback function is provided, and the status is set to pending, the user will be prompted to accept or deny whatever suggested value populates the ComboBox.

If there is a label and the Field is not disabled, passing an object to the additionalInfo prop that includes a heading and content will provide the user with more useful information on the Field when they click on the associated information Icon.

Single-select

Example

Type in or click to expand the Popover

Multi-select

Example

Type in or click to expand the Popover

Related components

Properties

NameDescriptionDefaultType
actionsAction Buttons that will render within the input.ReactNode
additionalInfoPass a heading and content to show additional information on the field.
{
  content: string | Element;
  heading: string;
}
autoFocusAutomatically focuses the input on render.boolean
disabledDisable the control. The browser defaults to false.boolean
idSets DOM id for the control and associates label element via 'for' attribute. If an id is not pass, a random id will be generated for any render.string
infoIt is recommended to pass a simple string to offer guidance. Text will be styled based on status prop.ReactNode
labelPass a string or a fragment with an Icon and string.ReactNode
labelHiddenVisually hides the label region.boolean
menuMenu related props.MenuProps
modeWhether it is single selection or multi selection combobox.'single-select'
'multi-select' |'single-select' 
nameSets html name attribute for the underlying control. Useful for mapping to a data field.string
onBlur
(selected: Selected |Selected[]) => void 
onChange(e: ChangeEvent<HTMLInputElement>) => void
onClick(e: MouseEvent) => void
onDropdownButtonClick(open: boolean) => void
onFocus
(selected: Selected |Selected[]) => void 
onKeyDown
(e: KeyboardEvent<Element>) => boolean |void 
onResolveSuggestion(accepted: boolean) => void
placeholderPlaceholder textstring
readOnlyMakes the component non editable and non clickable. The browser defaults to false.boolean
refReference to the element.Ref<HTMLDivElement>
requiredIndicate if the field is required. The browser defaults to false.boolean
selectedCurrently selected option, single for single-select, an array for multi-select.
{
  items: Selected | Selected[];
  onNew: (text: string) => void;
  onRemove: (id: string, index: number) => void;
}
statusSet visual state based on a validation state.
'error' |'pending' |'success' |'warning' 
valueValue of the combobox filtering input.string
visualA visual which represents the selected item.ReactNode