Forms

Select

A labelled native drop-down list, with a placeholder option, a hint and an error.

JxSelect import 'package:jx_cli/ui.dart' Available since 0.0.2

Preview

Where your data is stored.

When to use it

  • Choosing one value among 5 to 15 options.
  • Countries, plans, roles.

States

Choose a country.

Error
Disabled

Minimal example

Dart
JxSelect(
  id: 'plan',
  label: 'Plan',
  options: [(value: 'free', label: 'Free'), (value: 'pro', label: 'Pro')],
)

Complete example

A full Jaspr component you can paste into a project.

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

class RoleSelect extends StatefulComponent {
  const RoleSelect({super.key});

  @override
  State<RoleSelect> createState() => _RoleSelectState();
}

class _RoleSelectState extends State<RoleSelect> {
  String? role;

  @override
  Component build(BuildContext context) {
    return JxSelect(
      id: 'role',
      label: 'Role',
      placeholder: 'Choose a role',
      value: role,
      required: true,
      hint: role == 'admin' ? 'Admins can delete the workspace.' : null,
      options: const [
        (value: 'viewer', label: 'Viewer'),
        (value: 'editor', label: 'Editor'),
        (value: 'admin', label: 'Admin'),
      ],
      onChange: (value) => setState(() => role = value.isEmpty ? null : value),
    );
  }
}

Properties

Property Type Default Description
id String required Links the label and the message.
label String required Visible label.
options List<JxOption> required Records (value: …, label: …) .
value String? null Value of the selected option.
placeholder String? null First, empty option shown when nothing is selected.
name String? null Form field name.
hint String? null Help text.
error String? null Marks the select invalid.
required bool false Native required .
disabled bool false Disables the select.
classes String? null Extra JX classes, appended after the component classes.

Related types

Name Role
JxOption Record ({String value, String label}) , shared with the radio group.

Events

Callback Type Fires when
onChange ValueChanged<String>? A new option is chosen; the placeholder gives an empty string.

Customizing

  • Pass classes to add or override utilities: they come last, so classes: 'w:full' wins over the default width.

Accessibility

  • A native <select>: the system list, typeahead and arrow keys work everywhere, including on phones.
  • The chevron is decorative and does not catch clicks.

Limitations

  • No search inside the list and no multiple selection: for long lists, prefer a text field with suggestions.