Autocomplete · Tinyrack Design System

Complete free text from typed static or asynchronous suggestions.

Contract

Axis	Contract
Value	The query remains free-form text. Selecting a suggestion also stores its typed value on the controller.
Suggestions	Pass static `items` or load them asynchronously with `optionsBuilder`. Older asynchronous responses are discarded.
Interaction	Pointer hover keeps input focus. Arrow keys move the highlight, Enter selects, Escape closes, and Tab moves on without selecting.
Layer size	`layerSize` sizes the complete suggestion layer. It matches the field width by default and lets content grow up to `TRMeasurements.measureXl` high.

Install

Add the package, then import its public library.

flutter pub add tinyrack_ui

import 'package:tinyrack_ui/tinyrack_ui.dart';

Playground

Loading the Flutter preview

Usage

import 'package:material_ui/material_ui.dart';
import 'package:tinyrack_ui/tinyrack_ui.dart';

TRAutocomplete<String>(
  label: 'Region',
  placeholder: 'Search regions',
  items: const [
    TRAutocompleteItem(value: 'seoul', label: 'Seoul'),
    TRAutocompleteItem(value: 'tokyo', label: 'Tokyo'),
  ],
  onSelected: (region) => selectedRegion = region,
)

Examples

Completion modes permalink

Choose list suggestions, inline completion, both behaviors, or manual mode. Manual mode waits for text before showing an empty-query list.

Loading the Flutter preview

Asynchronous suggestions permalink

Return a Future from optionsBuilder to load remote suggestions. If requests finish out of order, only the newest query updates the popup.

Loading the Flutter preview

Sizes and states permalink

Match nearby controls with uiSize and communicate unavailable, read-only, or invalid input through the corresponding field state.

Loading the Flutter preview

Controller lifecycle permalink

Own a TRAutocompleteController when another control must read the query, clear the field, or inspect the typed selected value. Dispose it with the owning State.

Loading the Flutter preview

Form validation permalink

TRAutocompleteFormField reports the typed selected value to Form validation and save callbacks while the query remains editable.

Loading the Flutter preview

Pointer and keyboard permalink

Hover suggestions without moving input focus. Use Arrow keys to highlight, Enter to select, Escape to close, and Tab to leave without selecting.

Loading the Flutter preview

API

Suggestions

Prop	Type / default	Purpose
`items`	`List<TRAutocompleteItem<T>> = const []`	Provide typed static suggestions. Disabled items are filtered out.
`optionsBuilder`	`FutureOr<Iterable<TRAutocompleteItem<T>>> Function(String)?`	Load suggestions from the current query. It may return synchronously or asynchronously.
`completionMode`	`TRAutocompleteCompletionMode = list`	Choose `manual`, `list`, `inline`, or `both` completion behavior.
`TRAutocompleteItem`	`value, label, enabled = true, leading?, trailing?`	Pair a typed value with its label and optional presentation.

State and callbacks

Prop	Type / default	Purpose
`controller`	`TRAutocompleteController<T>?`	Observe `query` and `value`, call `select` or `clear`, and dispose owned text and focus controllers.
`onQueryChange`	`ValueChanged<String>?`	Report free-text edits.
`onSelected`	`ValueChanged<T>?`	Report the typed value selected from a suggestion.

Field and form

Prop	Type / default	Purpose
`enabled, readOnly`	`bool = true, bool = false`	Disable interaction or keep a focusable immutable query.
`label, placeholder, helperText, errorText`	`String?`	Describe the field and its validation state.
`uiSize, width`	`TRUiSize = md, double?`	Set the control size and optional fixed field width.
`layerSize`	`TRLayerSize · match anchor / content height ≤ measureXl`	Sizes the complete suggestion layer independently from the field width.
`TRAutocompleteFormField`	`FormField<T>`	Participate in validation and save callbacks with a typed selected value.