@ui5/webcomponents-react/wrappers/webComponents/ComboBox/index.js

React Wrapper for UI5 Web Components and additional components

'use client';

import { withWebComponent } from '@ui5/webcomponents-react-base';
/**
 * The `ComboBox` component represents a drop-down menu with a list of the available options and a text input field to narrow down the options.
 *
 * It is commonly used to enable users to select an option from a predefined list.
 *
 * ### Structure
 * The `ComboBox` consists of the following elements:
 *
 * -  Input field - displays the selected option or a custom user entry. Users can type to narrow down the list or enter their own value.
 * -  Drop-down arrow - expands\collapses the option list.
 * -  Option list - the list of available options.
 *
 * ### Working with Values
 *
 * The ComboBox offers two ways to work with item selection:
 *
 * **1. Display Text Only (using `value`):**
 * ```html
 * <ComboBox value="Germany">
 *   <ComboBoxItem text="Germany"></ComboBoxItem>
 *   <ComboBoxItem text="France"></ComboBoxItem>
 * </ComboBox>
 * ```
 * Use this approach when the displayed text is sufficient for your needs.
 *
 * **2. Unique Identifiers - Recommended (using `selectedValue` and item `value`):**
 * ```html
 * <ComboBox value="Germany" selected-value="DE">
 *   <ComboBoxItem text="Germany" value="DE"></ComboBoxItem>
 *   <ComboBoxItem text="France" value="FR"></ComboBoxItem>
 * </ComboBox>
 * ```
 * This is the recommended approach when you need to work with unique identifiers (IDs, codes) separate from display text.
 * The `selectedValue` property references the `value` property of the selected item.
 * In forms, the item's `value` (e.g., "DE") will be submitted instead of the display text.
 *
 * **Important:** Do not mix the `selectedValue` approach with the deprecated `selected` property on items.
 *
 * ### Keyboard Handling
 *
 * The `ComboBox` provides advanced keyboard handling.
 *
 * - [F4], [Alt]+[Up], or [Alt]+[Down] - Toggles the picker.
 * - [Escape] - Closes the picker, if open. If closed, cancels changes and reverts the typed in value.
 * - [Enter] or [Return] - If picker is open, takes over the currently selected item and closes it.
 * - [Down] - Selects the next matching item in the picker.
 * - [Up] - Selects the previous matching item in the picker.
 * - [Page Down] - Moves selection down by page size (10 items by default).
 * - [Page Up] - Moves selection up by page size (10 items by default).
 * - [Home] - If focus is in the ComboBox, moves cursor at the beginning of text. If focus is in the picker, selects the first item.
 * - [End] - If focus is in the ComboBox, moves cursor at the end of text. If focus is in the picker, selects the last item.
 * - [Ctrl]+[Alt]+[F8] or [Command]+[Option]+[F8] - Focuses the first link in the value state message, if available. Pressing [Tab] moves the focus to the next link in the value state message, or closes the value state message if there are no more links.
 *
 *
 *
 * __Note:__ This is a UI5 Web Component! [ComboBox UI5 Web Component Documentation](https://ui5.github.io/webcomponents/components/ComboBox) | [Repository](https://github.com/UI5/webcomponents)
 */
const ComboBox = withWebComponent('ui5-combobox', ['accessibleName', 'accessibleNameRef', 'filter', 'name', 'placeholder', 'selectedValue', 'value', 'valueState'], ['disabled', 'loading', 'noTypeahead', 'open', 'readonly', 'required', 'showClearIcon'], ['icon', 'valueStateMessage'], ['change', 'close', 'input', 'open', 'selection-change']);
ComboBox.displayName = 'ComboBox';
export { ComboBox };