Forms

Date field

A labelled date or time input on the native picker: keyboard, screen readers and phones are handled by the browser and the system.

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

Preview

From January 2026.

When to use it

  • A birth date, a deadline, a meeting time.
  • Filtering a list by month or week.

States

Time
Date and time

Pick a date after today.

Required, with an error

Minimal example

Dart
JxDateField(id: 'start', label: 'Start date')

Complete example

A full Jaspr component you can paste into a project.

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

/// A booking range: the end date cannot be before the start date.
@client
class StayDates extends StatefulComponent {
  const StayDates({super.key});

  @override
  State<StayDates> createState() => _StayDatesState();
}

class _StayDatesState extends State<StayDates> {
  String arrival = '';
  String departure = '';

  @override
  Component build(BuildContext context) {
    return Component.fragment([
      JxDateField(
        id: 'arrival',
        label: 'Arrival',
        required: true,
        value: arrival,
        onInput: (value) => setState(() => arrival = value),
      ),
      JxDateField(
        id: 'departure',
        label: 'Departure',
        required: true,
        value: departure,
        min: arrival.isEmpty ? null : arrival,
        onInput: (value) => setState(() => departure = value),
      ),
    ]);
  }
}

Properties

Property Type Default Description
id String required Links the label and the message.
label String required Visible label.
type JxDateType date date , time , dateTime , month or week .
value String? null In the HTML format: 2026-11-14 , 14:30 , 2026-11-14T14:30 , 2026-11 , 2026-W46 .
min String? null Earliest accepted value, same format.
max String? null Latest accepted value, same format.
name String? null Form field name.
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.

Related types

Name Role
JxDateType date, time, dateTime, month, week.

Events

Callback Type Fires when
onInput ValueChanged<String>? A new value, or an empty string when cleared.

Customizing

  • Pass classes to add or override utilities: they come last, so classes: 'w:full' wins over the default width.
  • The picker follows dark mode through the new scheme: utility (dark:scheme:dark).

Responsive

  • Phones open their own wheel or calendar picker.

Accessibility

  • Same wiring as the text field: label for, aria-describedby, aria-invalid.
  • Each part (day, month, year) is reachable and editable with the keyboard.

Limitations

  • The look of the picker is the browser's and cannot be styled.
  • Firefox has no month and week pickers: they fall back to a text field.
  • Not a calendar grid component: see the roadmap.