Forms

Text field

A labelled single-line input with a hint and an error message, wired with aria-describedby.

JxTextField import 'package:jx_cli/ui.dart' Available since 0.0.1

Preview

As shown on your profile.

Enter a complete email address.

When to use it

  • Names, emails, passwords, search terms.
  • Any field that needs inline validation.

States

Disabled
Required

Minimal example

Dart
JxTextField(id: 'name', label: 'Name')

Complete example

A full Jaspr component you can paste into a project.

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

/// Email field validated as the user types.
class EmailField extends StatefulComponent {
  const EmailField({super.key});

  @override
  State<EmailField> createState() => _EmailFieldState();
}

class _EmailFieldState extends State<EmailField> {
  String email = '';

  String? get error => email.isEmpty || email.contains(RegExp(r'^\S+@\S+\.\S+$'))
      ? null
      : 'Enter a complete email address.';

  @override
  Component build(BuildContext context) {
    return JxTextField(
      id: 'email',
      label: 'Email',
      type: InputType.email,
      value: email,
      hint: 'We never share it.',
      error: error,
      required: true,
      onInput: (value) => setState(() => email = value),
    );
  }
}

Properties

Property Type Default Description
id String required Links the label, the hint and the error to the input.
label String required Visible label.
type InputType text email , password , search , tel , url , number …
name String? null Form field name.
value String? null Current value.
placeholder String? null Example value. Never a replacement for the label.
hint String? null Help text under the input.
error String? null Marks the input invalid and replaces the hint.
required bool false Native required , and a red asterisk after the label (hidden from screen readers).
disabled bool false Disables the input.
classes String? null Extra JX classes, appended after the component classes.

Events

Callback Type Fires when
onInput ValueChanged<String>? Every keystroke, with the new value.

Customizing

  • Pass classes to add or override utilities: they come last, so classes: 'w:full' wins over the default width.
  • classes applies to the wrapper (label, input and message).

Responsive

  • The input takes the full width of its container: size it with the container or a grid.

Accessibility

  • The <label for> names the input; the hint or the error is linked with aria-describedby.
  • An error sets aria-invalid="true" and a red border, so the state never relies on color alone: the message is text.
  • The required asterisk is decorative: the input itself is announced as required.
  • The focus ring uses a ring around the border, visible in light and dark mode.

Limitations

  • With an error, the hint is not shown: put what the user needs in the error message.