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
Minimal example
JxTextField(id: 'name', label: 'Name')
Complete example
A full Jaspr component you can paste into a project.
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
classesto add or override utilities: they come last, soclasses: 'w:full'wins over the default width. -
classesapplies 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 witharia-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.