Forms

Combobox

A text field with suggestions, on the native <input list> and <datalist>. The browser filters the suggestions as the user types; any other value stays accepted.

JxCombobox import 'package:jx_cli/ui.dart' New in 0.0.3

Preview

Pick a suggestion or type any city.

When to use it

  • Cities, tags, job titles: long lists where typing is faster than scrolling.
  • A free value with common answers suggested.

States

Enter a country.

Required, with an error

Minimal example

Dart
JxCombobox(
  id: 'city',
  label: 'City',
  suggestions: ['Paris', 'Lyon', 'Marseille'],
)

Complete example

A full Jaspr component you can paste into a project.

Dart
import 'package:jaspr/jaspr.dart';
import 'package:jx_cli/ui.dart';

/// Suggestions narrowed on the server side as the user types.
class CityField extends StatefulComponent {
  const CityField({required this.search, super.key});

  final Future<List<String>> Function(String query) search;

  @override
  State<CityField> createState() => _CityFieldState();
}

class _CityFieldState extends State<CityField> {
  String city = '';
  List<String> suggestions = const [];

  Future<void> _onInput(String value) async {
    setState(() => city = value);
    if (value.length < 2) return;
    final found = await component.search(value);
    setState(() => suggestions = found);
  }

  @override
  Component build(BuildContext context) {
    return JxCombobox(
      id: 'city',
      label: 'City',
      value: city,
      suggestions: suggestions,
      hint: 'Type two letters to see suggestions.',
      onInput: _onInput,
    );
  }
}

Properties

Property Type Default Description
id String required Links the label, the message and the suggestion list.
label String required Visible label.
suggestions List<String> required Values offered while typing.
name String? null Form field name.
value String? null Current text.
placeholder String? null Example text.
hint String? null Help text under the field.
error String? null Marks the field invalid and replaces the hint.
required bool false Native required , with an asterisk after the label.
disabled bool false Disables the field.
classes String? null Extra JX classes, appended after the component classes.

Events

Callback Type Fires when
onInput ValueChanged<String>? Every keystroke, and when a suggestion is picked.

Customizing

  • Pass classes to add or override utilities: they come last, so classes: 'w:full' wins over the default width.
  • The input shares the styles of the text field.

Accessibility

  • The suggestion list is drawn by the browser and the system: keyboard, touch and screen readers work as on any native field.
  • Same wiring as the text field: label for, aria-describedby, aria-invalid.

Limitations

  • The look of the suggestion list is the browser's and cannot be styled.
  • Suggestions are text only: no icons or secondary lines.