@carbon/react
Version:
React components for the Carbon Design System
213 lines (212 loc) • 8.22 kB
TypeScript
/**
* Copyright IBM Corp. 2016, 2025
*
* This source code is licensed under the Apache-2.0 license found in the
* LICENSE file in the root directory of this source tree.
*/
import { UseComboboxProps, UseComboboxActions } from 'downshift';
import React, { type ComponentType, type InputHTMLAttributes, type MouseEvent, type PropsWithChildren, type PropsWithRef, type ReactElement, type ReactNode, type RefAttributes } from 'react';
import { type ListBoxSize } from '../ListBox';
import { TranslateWithId } from '../../types/common';
type ExcludedAttributes = 'id' | 'onChange' | 'onClick' | 'type' | 'size';
export interface OnChangeData<ItemType> {
selectedItem: ItemType | null | undefined;
inputValue?: string | null;
}
/**
* Message ids that will be passed to translateWithId().
* Combination of message ids from ListBox/next/ListBoxSelection.js and
* ListBox/next/ListBoxTrigger.js, but we can't access those values directly
* because those components aren't Typescript. (If you try, TranslationKey
* ends up just being defined as "string".)
*/
export type TranslationKey = 'close.menu' | 'open.menu' | 'clear.all' | 'clear.selection';
export type ItemToStringHandler<ItemType> = (item: ItemType | null) => string;
export interface ComboBoxProps<ItemType> extends Omit<InputHTMLAttributes<HTMLInputElement>, ExcludedAttributes>, TranslateWithId<TranslationKey> {
/**
* Specify whether or not the ComboBox should allow a value that is
* not in the list to be entered in the input
*/
allowCustomValue?: boolean;
/**
* Specify a label to be read by screen readers on the container node
* 'aria-label' of the ListBox component.
*/
['aria-label']?: string;
/**
* @deprecated please use `aria-label` instead.
* 'aria-label' of the ListBox component.
*/
ariaLabel?: string;
/**
* **Experimental**: Will attempt to automatically align the floating
* element to avoid collisions with the viewport and being clipped by
* ancestor elements. Requires React v17+
* @see https://github.com/carbon-design-system/carbon/issues/18714
*/
autoAlign?: boolean;
/**
* An optional className to add to the container node
*/
className?: string;
/**
* **Experimental**: Provide a `decorator` component to be rendered inside the `ComboBox` component
*/
decorator?: ReactNode;
/**
* Specify the direction of the combobox dropdown. Can be either top or bottom.
*/
direction?: 'top' | 'bottom';
/**
* Specify if the control should be disabled, or not
*/
disabled?: boolean;
/**
* Additional props passed to Downshift.
*
* **Use with caution:** anything you define here overrides the components'
* internal handling of that prop. Downshift APIs and internals are subject to
* change, and in some cases they can not be shimmed by Carbon to shield you
* from potentially breaking changes.
*
*/
downshiftProps?: Partial<UseComboboxProps<ItemType>>;
/**
* Provide a ref that will be mutated to contain an object of downshift
* action functions. These can be called to change the internal state of the
* downshift useCombobox hook.
*
* **Use with caution:** calling these actions modifies the internal state of
* downshift. It may conflict with or override the state management used within
* Combobox. Downshift APIs and internals are subject to change, and in some
* cases they can not be shimmed by Carbon to shield you from potentially breaking
* changes.
*/
downshiftActions?: React.MutableRefObject<UseComboboxActions<ItemType> | undefined>;
/**
* Provide helper text that is used alongside the control label for
* additional help
*/
helperText?: ReactNode;
/**
* Specify a custom `id` for the input
*/
id: string;
/**
* Allow users to pass in an arbitrary item or a string (in case their items are an array of strings)
* from their collection that are pre-selected
*/
initialSelectedItem?: ItemType;
/**
* Specify if the currently selected value is invalid.
*/
invalid?: boolean;
/**
* Message which is displayed if the value is invalid.
*/
invalidText?: ReactNode;
/**
* Optional function to render items as custom components instead of strings.
* Defaults to null and is overridden by a getter
*/
itemToElement?: ComponentType<ItemType> | null;
/**
* Helper function passed to downshift that allows the library to render a
* given item to a string label. By default, it extracts the `label` field
* from a given item to serve as the item label in the list
*/
itemToString?: ItemToStringHandler<ItemType>;
/**
* We try to stay as generic as possible here to allow individuals to pass
* in a collection of whatever kind of data structure they prefer
*/
items: ItemType[];
/**
* @deprecated
* should use "light theme" (white background)?
*/
light?: boolean;
/**
* `onChange` is a utility for this controlled component to communicate to a
* consuming component when a specific dropdown item is selected.
* `({ selectedItem }) => void`
// * @param {{ selectedItem }}
*/
onChange: (data: OnChangeData<ItemType>) => void;
/**
* Callback function to notify consumer when the text input changes.
* This provides support to change available items based on the text.
* `(inputText) => void`
* @param {string} inputText
*/
onInputChange?: (inputText: string) => void;
/**
* Callback function that fires when the combobox menu toggle is clicked
* `(evt) => void`
* @param {MouseEvent} event
*/
onToggleClick?: (evt: MouseEvent<HTMLButtonElement>) => void;
/**
* Used to provide a placeholder text node before a user enters any input.
* This is only present if the control has no items selected
*/
placeholder?: string;
/**
* Whether or not the component is read-only
*/
readOnly?: boolean;
/**
* For full control of the selection
*/
selectedItem?: ItemType | null;
/**
* Specify your own filtering logic by passing in a `shouldFilterItem`
* function that takes in the current input and an item and passes back
* whether or not the item should be filtered.
* this prop will be ignored if `typeahead` prop is enabled
*/
shouldFilterItem?: (input: {
item: ItemType;
itemToString?: ItemToStringHandler<ItemType>;
inputValue: string | null;
}) => boolean;
/**
* Specify the size of the ListBox. Currently supports either `sm`, `md` or `lg` as an option.
*/
size?: ListBoxSize;
/**
* @deprecated please use decorator instead.
* **Experimental**: Provide a `Slug` component to be rendered inside the `ComboBox` component
*/
slug?: ReactNode;
/**
* Provide text to be used in a `<label>` element that is tied to the
* combobox via ARIA attributes.
*/
titleText?: ReactNode;
/**
* **Experimental**: will enable autocomplete and typeahead for the input field
*/
typeahead?: boolean;
/**
* Specify whether the control is currently in warning state
*/
warn?: boolean;
/**
* Provide the text that is displayed when the control is in warning state
*/
warnText?: ReactNode;
/**
* Specify native input attributes to place on the `<input>`, like maxLength.
* These are passed to downshift's getInputProps() and will override the
* internal input props.
* https://github.com/downshift-js/downshift?tab=readme-ov-file#getinputprops
*/
inputProps?: InputHTMLAttributes<HTMLInputElement>;
}
type ComboboxComponentProps<ItemType> = PropsWithRef<PropsWithChildren<ComboBoxProps<ItemType>> & RefAttributes<HTMLInputElement>>;
export interface ComboBoxComponent {
<ItemType>(props: ComboboxComponentProps<ItemType>): ReactElement<any> | null;
}
declare const _default: ComboBoxComponent;
export default _default;