@carbon/react
Version:
React components for the Carbon Design System
160 lines (159 loc) • 5.62 kB
TypeScript
/**
* Copyright IBM Corp. 2022, 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 React, { type HTMLAttributes, type ReactNode, type Ref } from 'react';
import { UseSelectProps } from 'downshift';
import { type ListBoxMenuIconTranslationKey, type ListBoxSize, type ListBoxType } from '../ListBox';
import { TranslateWithId } from '../../types/common';
type ExcludedAttributes = 'id' | 'onChange';
export interface OnChangeData<ItemType> {
selectedItem: ItemType | null;
}
export interface DropdownProps<ItemType> extends Omit<HTMLAttributes<HTMLDivElement>, ExcludedAttributes>, TranslateWithId<ListBoxMenuIconTranslationKey> {
/**
* 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.
* Specify a label to be read by screen readers on the container note.
*/
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;
/**
* **Experimental**: Provide a `decorator` component to be rendered inside the `Dropdown` component
*/
decorator?: ReactNode;
/**
* Specify the direction of the dropdown. Can be either top or bottom.
*/
direction?: 'top' | 'bottom';
/**
* Disable the control
*/
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<UseSelectProps<ItemType>>;
/**
* Provide helper text that is used alongside the control label for
* additional help
*/
helperText?: ReactNode;
/**
* Specify whether the title text should be hidden or not
*/
hideLabel?: boolean;
/**
* Specify a custom `id`
*/
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;
/**
* Function to render items as custom components instead of strings.
* Defaults to null and is overridden by a getter
*/
itemToElement?: React.JSXElementConstructor<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?(item: ItemType | null): string;
/**
* 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[];
/**
* Generic `label` that will be used as the textual representation of what
* this field is for
*/
label: NonNullable<ReactNode>;
/**
* `true` to use the light version.
* @deprecated The `light` prop for `Dropdown` has been deprecated
* in favor of the new `Layer` component. It will be removed in the next major release.
*/
light?: boolean;
/**
* `onChange` is a utility for this controlled component to communicate to a
* consuming component what kind of internal state changes are occurring.
*/
onChange?(data: OnChangeData<ItemType>): void;
/**
* Whether or not the Dropdown is readonly
*/
readOnly?: boolean;
/**
* An optional callback to render the currently selected item as a react element instead of only
* as a string.
*/
renderSelectedItem?(item: ItemType): ReactNode;
/**
* In the case you want to control the dropdown selection entirely.
*/
selectedItem?: ItemType;
/**
* 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 `Dropdown` component
*/
slug?: ReactNode;
/**
* Provide the title text that will be read by a screen reader when
* visiting this control
*/
titleText: ReactNode;
/**
* The dropdown type, `default` or `inline`
*/
type?: ListBoxType;
/**
* 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;
}
export type DropdownTranslationKey = ListBoxMenuIconTranslationKey;
interface DropdownComponent {
<ItemType>(props: DropdownProps<ItemType> & {
ref?: Ref<HTMLButtonElement>;
}): React.ReactElement<any> | null;
}
declare const _default: DropdownComponent;
export default _default;