Autocomplete

A text field that suggests matching options in a dropdown as the user types.

See also: Select for a short fixed choice list · CompletionTextInput for suggestions inside free text.

Learn more: Forms & validation

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

Autocomplete<String>(
  placeholder: 'Type a fruit…',
  options: const ['Apple', 'Apricot', 'Banana', 'Cherry', 'Grape'],
  onSelect: (fruit) => choose(fruit),
)

Details

Options whose display string contains the typed text, ignoring case, appear in a dropdown just below the field (above it when there’s no room below), floating over other content. The field keeps focus throughout: Up and Down move the highlight, wrapping at the ends; Enter or Tab fills the field with the highlighted option and calls onSelect; Esc or a click outside closes the dropdown. Clicking a suggestion picks it too. While the dropdown is closed, these keys pass through, so Tab still moves focus.

Options can be any type T; displayStringForOption maps each to the text shown and matched against (defaults to toString()). onSelect hands back the chosen option itself, not just its string.

Constructors

Autocomplete()

Parameter	Type	Default	Description
options:	List<T>	required	Source options matched against the current field text.
displayStringForOption:	String Function(T option)	—	Maps an option to the text shown in the dropdown and filled into the field. Defaults to option.toString().
controller:	TextEditingController?	—	Text controller for the underlying input.
focusNode:	FocusNode?	—	Focus node used by the underlying input.
autofocus:	bool	false	Whether the input should request focus when mounted.
onChanged:	void Function(String text)?	—	Called after user and semantic edits. Programmatic controller writes notify controller listeners instead. See TextInput.onChanged.
placeholder:	String	''	Hint text passed to the underlying TextInput.
fieldSemanticLabel:	String?	—	Stable label for the underlying text field in semantic snapshots. More
semanticLabel:	String?	—	Stable label for the suggestion menu in semantic snapshots. More
semanticState:	SemanticState	SemanticState.empty	Extra semantic state merged into the underlying text-field node.
style:	CellStyle	CellStyle.none	Text-field base styling, plus optional hover, focus, disabled, and invalid state entries from CellStyle.interactive.
enabled:	bool	true	Whether the field accepts focus and user input.
readOnly:	bool	false	Whether the field can receive focus but not edit text.
validationError:	String?	—	Marks the current value invalid: the field draws in the theme’s error style and reports this message through semantics, but doesn’t show the text. Inside a FormField, this message wins over the FormField’s validator, though not over its own error, and the FormField shows the winning message below the input.
onSelect:	void Function(T value)?	—	Called with the selected option when the user picks a suggestion.
maxVisible:	int	6	Maximum visible suggestion rows before the list scrolls.

• fieldSemanticLabel: Defaults to placeholder when provided. This is separate from semanticLabel, which names the suggestion menu.
• semanticLabel: Defaults to placeholder when provided. Set it when tests, tools, or agents need to refer to the suggestion menu by a name that doesn’t depend on the typed text.

Source

Autocomplete is defined in packages/fleury/lib/src/catalog/autocomplete.dart.

Category: Inputs & controls · All widgets

Live demo

autocomplete_example.dart

Restart Run Expand

Example · editable Revert Format

class _AutocompleteExampleState extends State<_AutocompleteExample> {
  // Seed a partial query so the suggestion list is already open on mount.
  final TextEditingController _controller = TextEditingController(text: 'Ap');

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => Autocomplete<String>(
    controller: _controller,
    autofocus: true,
    placeholder: 'Type a fruit…',
    options: const <String>['Apple', 'Apricot', 'Banana', 'Cherry', 'Grape'],
  );
}

Live preview

Live · interactive

click & type to interact ⓘ how this demo runs ⛶ Expand