ComboBox

Die ComboBox kombiniert eine Texteingabe mit einem filterbaren Auswahlmenü.

Domain(optional)

import {
  ComboBox,
  Label,
  Option,
} from "@mittwald/flow-react-components";

<ComboBox>
  <Label>Domain</Label>
  <Option>mydomain.de</Option>
  <Option>shop.mydomain.de</Option>
  <Option>anotherdomain.com</Option>
  <Option>www.anotherdomain.com</Option>
  <Option>anotherdomain.com/shop</Option>
  <Option>anotherdomain.com/blog</Option>
  <Option>onemoredomain.de</Option>
  <Option>www.onemoredomain.de</Option>
</ComboBox>

Best Practices

Benenne die angezeigten Optionen klar und eindeutig.
Grenze die Liste der Vorschläge sinnvoll ein. Das erleichtert die Auswahl.
Decke mit den vorgeschlagenen Optionen die erwarteten Eingaben möglichst vollständig ab.

ComboBox vs. Autocomplete

ComboBoxen und Autocomplete‍ sehen oft ähnlich aus, erfüllen aber unterschiedliche Zwecke.

Verwende ComboBox, um z. B. ...

aus einer vordefinierten Liste von Optionen eine Auswahl zu treffen.
bei bekannten, überschaubaren Optionen (z. B. Sprachen, Kategorien, Geschlecht).

Verwende Autocomplete, um z. B. ...

Usern zu ermöglichen, freie Eingaben zu machen, während Vorschläge zur Auswahl angezeigt werden.
bei langen oder dynamischen Datenlisten (z. B. Städte, Usernamen, Tags).

Custom Value

Standardmäßig setzt eine ComboBox beim Verlassen des Inputfelds den Eingabewert entweder auf den Wert der ausgewählten Option zurück oder leert das Feld, wenn noch keine Option ausgewählt wurde. Mit dem Property allowsCustomValue kann dieses Verhalten überschrieben werden, um auch freie Eingaben zu erlauben.

Domain(optional)

CountryOptions

Verwende die CountryOptions, um eine Länderauswahl anzubieten.

Land(optional)

Mit FieldDescription

Um wichtige Hinweise zur ComboBox bereitzustellen, kann unterhalb eine <FieldDescription /> eingebaut werden.

Domain(optional)Weitere Informationen

Kombiniere mit ...

Combine

Benutze Combine‍, um einen Button‍ neben deiner ComboBox zu platzieren.

Domain(optional)

ContextualHelp

Verwende ein ContextualHelp‍, wenn du weitere Informationen bereitstellen möchtest, und diese zu lang für die FieldDescription sind.

Domain(optional)

React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component Form (React Hook Form)‍.

Properties

Property	Type	Default	Description
`allowsCustomValue`	`boolean`	-	Whether the ComboBox allows a non-item matching input value to be set.
`allowsEmptyCollection`	`boolean`	-	Whether the combo box allows the menu to be open when the collection is empty.
`autoFocus`	`boolean`	-	Whether the element should receive focus on render.
`children`	`ReactNode`	-
`className`	`ClassNameOrFunction<ComboBoxRenderProps>`	'react-aria-ComboBox'	The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
`defaultFilter`	`((textValue: string, inputValue: string) => boolean)`	-	The filter function used to determine if a option should be included in the combo box list.
`defaultInputValue`	`string`	-	The default value of the ComboBox input (uncontrolled).
`defaultItems`	`Iterable<never>`	-	The list of ComboBox items (uncontrolled).
`defaultSelectedKey`	`Key`	-	The initial selected key in the collection (uncontrolled). @deprecated
`defaultValue`	`TimeValue`	-	The default value (uncontrolled).
`dir`	`string`	-
`disabledKeys`	`Iterable<Key>`	-	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`form`	`string`	-	The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).
`formValue`	`"text" \| "key"`	'key'	Whether the text or key of the selected item is submitted as part of an HTML form. When `allowsCustomValue` is `true`, this option does not apply and the text is always submitted.
`hidden`	`boolean`	-
`id`	`string`	-	The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
`inert`	`boolean`	-
`inputValue`	`string`	-	The value of the ComboBox input (controlled).
`isDisabled`	`boolean`	-	Whether the input is disabled.
`isInvalid`	`boolean`	-	Whether the input value is invalid.
`isReadOnly`	`boolean`	-	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	-	Whether user input is required on the input before form submission.
`items`	`Iterable<never>`	-	The list of ComboBox items (controlled).
`lang`	`string`	-
`menuTrigger`	`MenuTriggerAction`	'input'	The interaction required to display the ComboBox menu.
`name`	`string`	-	The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname).
`placeholder`	`string`	-	Temporary text that occupies the text input when it is empty. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/placeholder).
`render`	`DOMRenderFunction<"div", TooltipRenderProps>`	-	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
`renderEmptyState`	`((props: ListBoxRenderProps) => ReactNode)`	-	Provides content to display when there are no items in the list.
`selectedKey`	`Key`	-	The currently selected key in the collection (controlled). @deprecated
`selectionMode`	`"single"`	'single'	Whether single or multiple selection is enabled.
`shouldFocusWrap`	`boolean`	-	Whether keyboard navigation is circular.
`slot`	`string`	-	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
`style`	`StyleOrFunction<TooltipRenderProps>`	-	The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.
`translate`	`"yes" \| "no"`	-
`validate`	`((value: TimeValue) => true \| ValidationError)`	-	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
`validationBehavior`	`"native" \| "aria"`	'native'	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`value`	`TimeValue`	-	The current value (controlled).
`wrapWith`	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	-	A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup.

Events

Property	Type	Default	Description
`onBlur`	`((e: FocusEvent<Element, Element>) => void)`	-	Handler that is called when the element loses focus.
`onChange`	`((value: string) => void)`	-	Called with the key of the selected option whenever the selection changes.
`onClick`	`MouseEventHandler<HTMLDivElement>`	-
`onFocus`	`((e: FocusEvent<Element, Element>) => void)`	-	Handler that is called when the element receives focus.
`onFocusChange`	`((isFocused: boolean) => void)`	-	Handler that is called when the element's focus status changes.
`onInputChange`	`((value: string) => void)`	-	Handler that is called when the ComboBox input value changes.
`onKeyDown`	`((e: KeyboardEvent) => void)`	-	Handler that is called when a key is pressed.
`onKeyUp`	`((e: KeyboardEvent) => void)`	-	Handler that is called when a key is released.
`onOpenChange`	`((isOpen: boolean, menuTrigger?: MenuTriggerAction) => void)`	-	Method that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu.
`onSelectionChange`	`((key: Key) => void)`	-	Handler that is called when the selection changes. @deprecated

Accessibility

Property	Type	Default	Description
`aria-describedby`	`string`	-	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	-	Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-label`	`string`	-	Defines a string value that labels the current element.
`aria-labelledby`	`string`	-	Identifies the element (or elements) that labels the current element.

Components

Integrations

ComboBox

Best Practices

ComboBox vs. Autocomplete

Verwende ComboBox, um z. B. ...

Verwende Autocomplete, um z. B. ...

Custom Value

CountryOptions

Mit FieldDescription

Kombiniere mit ...

Combine

ContextualHelp

React Hook Form

Properties

Events

Accessibility

Auf dieser Seite