CarbonComboBox<T> class

A Carbon combo box: a single-select picker whose field filters the options as you type.

Typing filters the menu (case-insensitive substring); arrows move the highlight; Enter selects an enabled highlighted option. Escape closes an open popup, preserving the value. Enter without a selectable highlight and Escape with no popup continue to ancestor form or dialog handlers. The clear (X) control resets the value; arbitrary filter text is not a selection.

See the forms pattern for the shared disabled and read-only contract.

Inheritance

Constructors

CarbonComboBox({required String titleText, List<CarbonComboBoxItem<T>>? items, CarbonComboBoxItem<T> itemBuilder(int index)?, int? itemCount, Key? key, T? selectedItem, ValueChanged<T?>? onChanged, ValueChanged<String>? onInputChange, String? placeholder, String? helperText, CarbonFieldSize size = CarbonFieldSize.md, CarbonOverlaySide? menuSide, bool disabled = false, bool readOnly = false, String readOnlyHint = CarbonControlState.defaultReadOnlyHint, CarbonListBoxActiveOptionFormatter activeOptionFormatter = carbonListBoxActiveOptionLabel, bool invalid = false, String? invalidText, bool warn = false, String? warnText, bool hideLabel = false, Widget? aiLabel, bool fluid = false, bool condensed = false, bool aiRevert = false, FocusNode? focusNode})
Creates a combo box.
const

Properties

activeOptionFormatter → CarbonListBoxActiveOptionFormatter
Formats the highlighted option and its one-based position for assistive technology. Defaults to carbonListBoxActiveOptionLabel.
final
aiLabel → Widget?
An optional AI presence decorator (a CarbonAILabel), rendered in the field per upstream's decorator prop; adds the AI aura treatment.
final
aiRevert → bool
Suppresses the aura while the AI label shows its revert control.
final
condensed → bool
The condensed fluid variant: the field stays fluid but the menu rows keep the standard height (--list-box__wrapper--fluid--condensed).
final
disabled → bool
Whether the combo box is disabled.
final
fluid → bool
The fluid treatment: a 64px field with the title rendered inside above the value, and 64px menu rows (_fluid-list-box.scss).
final
focusNode → FocusNode?
A caller-owned focus node, rebound when this property changes.
final
hashCode → int
The hash code for this object.
no setterinherited
helperText → String?
Helper text (hidden when invalid/warn).
final
hideLabel → bool
Visually hides the title (kept for assistive technology).
final
invalid → bool
Whether the combo box is invalid.
final
invalidText → String?
The error message.
final
itemBuilder → CarbonComboBoxItem<T> Function(int index)?
Reads an option's data by index for a lazy menu. This callback is also used for offscreen keyboard search and value reconciliation; keep it pure and lightweight, and return stable values (fresh model objects are fine). Supply itemCount together with this callback and omit items.
final
itemCount → int?
The number of logical options read by itemBuilder, including disabled options.
final
items → List<CarbonComboBoxItem<T>>
The options.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
Pins the options to a side. Null prefers below and adapts to the viewport. Logical CarbonOverlaySide.start and CarbonOverlaySide.end follow RTL.
final
onChanged → ValueChanged<T?>?
Called with the chosen value, or null when cleared.
final
onInputChange → ValueChanged<String>?
Called with the field text as the user types.
final
placeholder → String?
The placeholder shown when the field is empty.
final
readOnly → bool
Keeps the value focusable while preventing editing and popup activation.
final
readOnlyHint → String
The localizable announcement for read-only mode.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
selectedItem → T?
The selected value.
final
size → CarbonFieldSize
The field size.
final
titleText → String
The field title shown above the trigger.
final
warn → bool
Whether the combo box is in a warning state.
final
warnText → String?
The warning message.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<CarbonComboBox<T>>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited