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	Description
`id`	string	The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
`translate`	yes \| no
`className`	ClassNameOrFunction<ComboBoxRenderProps>default: '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.
`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.
`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.
`dir`	string
`lang`	string
`hidden`	boolean
`inert`	boolean
`validationBehavior`	native (default) \| aria	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.
`isDisabled`	boolean	Whether the input is disabled.
`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.
`isInvalid`	boolean	Whether the input value is invalid.
`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.
`autoFocus`	boolean	Whether the element should receive focus on render.
`value`	TimeValue	The current value (controlled).
`defaultValue`	TimeValue	The default value (uncontrolled).
`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).
`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).
`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.
`items`	Iterable<never>	The list of ComboBox items (controlled).
`selectedKey`	Key	The currently selected key in the collection (controlled). @deprecated
`defaultSelectedKey`	Key	The initial selected key in the collection (uncontrolled). @deprecated
`disabledKeys`	Iterable<Key>	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`selectionMode`	single (default)	Whether single or multiple selection is enabled.
`allowsEmptyCollection`	boolean	Whether the combo box allows the menu to be open when the collection is empty.
`shouldFocusWrap`	boolean	Whether keyboard navigation is circular.
`defaultItems`	Iterable<never>	The list of ComboBox items (uncontrolled).
`inputValue`	string	The value of the ComboBox input (controlled).
`defaultInputValue`	string	The default value of the ComboBox input (uncontrolled).
`allowsCustomValue`	boolean	Whether the ComboBox allows a non-item matching input value to be set.
`menuTrigger`	MenuTriggerActiondefault: 'input'	The interaction required to display the ComboBox menu.
`defaultFilter`	((textValue: string, inputValue: string) => boolean)	The filter function used to determine if a option should be included in the combo box list.
`formValue`	text \| key (default)	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.
`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).
`renderEmptyState`	((props: ListBoxRenderProps) => ReactNode)	Provides content to display when there are no items in the list.
`children`	ReactNode
`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.
`ref`	Ref<HTMLSpanElement>	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). @see React Docs
`key`	Key

Events

Property	Type	Description
`onChange`	((value: string) => void)	Called with the key of the selected option whenever the selection changes.
`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.
`onClick`	MouseEventHandler<HTMLDivElement>
`onClickCapture`	MouseEventHandler<HTMLDivElement>
`onAuxClick`	MouseEventHandler<HTMLDivElement>
`onAuxClickCapture`	MouseEventHandler<HTMLDivElement>
`onContextMenu`	MouseEventHandler<HTMLDivElement>
`onContextMenuCapture`	MouseEventHandler<HTMLDivElement>
`onDoubleClick`	MouseEventHandler<HTMLDivElement>
`onDoubleClickCapture`	MouseEventHandler<HTMLDivElement>
`onMouseDown`	MouseEventHandler<HTMLDivElement>
`onMouseDownCapture`	MouseEventHandler<HTMLDivElement>
`onMouseEnter`	MouseEventHandler<HTMLDivElement>
`onMouseLeave`	MouseEventHandler<HTMLDivElement>
`onMouseMove`	MouseEventHandler<HTMLDivElement>
`onMouseMoveCapture`	MouseEventHandler<HTMLDivElement>
`onMouseOut`	MouseEventHandler<HTMLDivElement>
`onMouseOutCapture`	MouseEventHandler<HTMLDivElement>
`onMouseOver`	MouseEventHandler<HTMLDivElement>
`onMouseOverCapture`	MouseEventHandler<HTMLDivElement>
`onMouseUp`	MouseEventHandler<HTMLDivElement>
`onMouseUpCapture`	MouseEventHandler<HTMLDivElement>
`onTouchCancel`	TouchEventHandler<HTMLDivElement>
`onTouchCancelCapture`	TouchEventHandler<HTMLDivElement>
`onTouchEnd`	TouchEventHandler<HTMLDivElement>
`onTouchEndCapture`	TouchEventHandler<HTMLDivElement>
`onTouchMove`	TouchEventHandler<HTMLDivElement>
`onTouchMoveCapture`	TouchEventHandler<HTMLDivElement>
`onTouchStart`	TouchEventHandler<HTMLDivElement>
`onTouchStartCapture`	TouchEventHandler<HTMLDivElement>
`onPointerDown`	PointerEventHandler<HTMLDivElement>
`onPointerDownCapture`	PointerEventHandler<HTMLDivElement>
`onPointerMove`	PointerEventHandler<HTMLDivElement>
`onPointerMoveCapture`	PointerEventHandler<HTMLDivElement>
`onPointerUp`	PointerEventHandler<HTMLDivElement>
`onPointerUpCapture`	PointerEventHandler<HTMLDivElement>
`onPointerCancel`	PointerEventHandler<HTMLDivElement>
`onPointerCancelCapture`	PointerEventHandler<HTMLDivElement>
`onPointerEnter`	PointerEventHandler<HTMLDivElement>
`onPointerLeave`	PointerEventHandler<HTMLDivElement>
`onPointerOver`	PointerEventHandler<HTMLDivElement>
`onPointerOverCapture`	PointerEventHandler<HTMLDivElement>
`onPointerOut`	PointerEventHandler<HTMLDivElement>
`onPointerOutCapture`	PointerEventHandler<HTMLDivElement>
`onGotPointerCapture`	PointerEventHandler<HTMLDivElement>
`onGotPointerCaptureCapture`	PointerEventHandler<HTMLDivElement>
`onLostPointerCapture`	PointerEventHandler<HTMLDivElement>
`onLostPointerCaptureCapture`	PointerEventHandler<HTMLDivElement>
`onScroll`	UIEventHandler<HTMLDivElement>
`onScrollCapture`	UIEventHandler<HTMLDivElement>
`onWheel`	WheelEventHandler<HTMLDivElement>
`onWheelCapture`	WheelEventHandler<HTMLDivElement>
`onAnimationStart`	AnimationEventHandler<HTMLDivElement>
`onAnimationStartCapture`	AnimationEventHandler<HTMLDivElement>
`onAnimationEnd`	AnimationEventHandler<HTMLDivElement>
`onAnimationEndCapture`	AnimationEventHandler<HTMLDivElement>
`onAnimationIteration`	AnimationEventHandler<HTMLDivElement>
`onAnimationIterationCapture`	AnimationEventHandler<HTMLDivElement>
`onTransitionCancel`	TransitionEventHandler<HTMLDivElement>
`onTransitionCancelCapture`	TransitionEventHandler<HTMLDivElement>
`onTransitionEnd`	TransitionEventHandler<HTMLDivElement>
`onTransitionEndCapture`	TransitionEventHandler<HTMLDivElement>
`onTransitionRun`	TransitionEventHandler<HTMLDivElement>
`onTransitionRunCapture`	TransitionEventHandler<HTMLDivElement>
`onTransitionStart`	TransitionEventHandler<HTMLDivElement>
`onTransitionStartCapture`	TransitionEventHandler<HTMLDivElement>
`onFocus`	((e: FocusEvent<Element, Element>) => void)	Handler that is called when the element receives focus.
`onBlur`	((e: FocusEvent<Element, Element>) => void)	Handler that is called when the element loses focus.
`onFocusChange`	((isFocused: boolean) => void)	Handler that is called when the element's focus status 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.
`onSelectionChange`	((key: Key) => void)	Handler that is called when the selection changes. @deprecated
`onInputChange`	((value: string) => void)	Handler that is called when the ComboBox input value changes.

Accessibility

Property	Type	Description
`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.
`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.

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