FormField

One validated value in a Form.

Learn more: Forms & validation

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

Wrap a control

FormField(
  validator: () => slug.text.isEmpty ? 'Enter a slug.' : null,
  child: TextInput(controller: slug, semanticLabel: 'Slug'),
)

Custom value

// One validated value built from two controls.
FormField.builder(
  validator: () => end > start ? null : 'End must be greater than start.',
  builder: (context, field) => Column(
    children: [
      Stepper(
        label: 'Start',
        value: start,
        focusNode: field.focusNode, // where an error moves focus
        onChanged: (value) {
          setState(() => start = value);
          field.valueChanged();
        },
      ),
      Stepper(
        label: 'End',
        value: end,
        onChanged: (value) {
          setState(() => end = value);
          field.valueChanged();
        },
      ),
    ],
  ),
)

Details

The ordinary constructor discovers exactly one first-party value control inside child, so no binding argument or specialized wrapper is needed. Use FormField.builder for a custom or multi-control value.

Constructors

FormField()

Creates a field that automatically integrates one aware control in child.

Parameter	Type	Default	Description
child:	Widget	required	Subtree containing the field’s one automatically integrated control.
validator:	String? Function()?	—	Returns the current error by reading application-owned state. More
error:	String?	—	Controlled external error, typically returned by a server.
enabled:	bool	true	Whether the field takes part in validation. A disabled field is skipped when the form validates, shows no error, and is never focused as the first invalid field.
showErrorMessage:	bool	true	Whether the field renders its current error below the control.
errorBuilder:	Widget Function(BuildContext context, String error)?	—	Optional replacement for the default styled error text.

• validator: Keep validators free of side effects: revealed validation can refresh after forms, fields, or registered controls rebuild, including dependent fields.

FormField.builder()

Creates a field whose custom control is built from its live state.

Use this for one logical value represented by a custom or multi-control widget. The builder must call FormFieldState.valueChanged when its app-owned value changes.

Parameter	Type	Default	Description
builder:	Widget Function(BuildContext context, FormFieldState field)	required	Custom-control builder used by FormField.builder.
validator:	String? Function()?	—	Returns the current error by reading application-owned state. More
error:	String?	—	Controlled external error, typically returned by a server.
enabled:	bool	true	Whether the field takes part in validation. A disabled field is skipped when the form validates, shows no error, and is never focused as the first invalid field.
focusNode:	FocusNode?	—	Optional external focus destination for FormField.builder. Otherwise attach FormFieldState.focusNode inside the builder.
showErrorMessage:	bool	true	Whether the field renders its current error below the control.
errorBuilder:	Widget Function(BuildContext context, String error)?	—	Optional replacement for the default styled error text.

Source

FormField is defined in packages/fleury/lib/src/catalog/form.dart.

Category: Forms · All widgets

Live demo

custom_field.dart

Restart Run Expand

Example · editable Revert Format

import 'package:fleury/fleury_core.dart';

class CustomField extends StatefulWidget {
  const CustomField({super.key});

  @override
  State<CustomField> createState() => _CustomFieldState();
}

class _CustomFieldState extends State<CustomField> {
  final form = FormController();
  num start = 5;
  num end = 3;
  String status = 'Set an end greater than the start';

  @override
  void dispose() {
    form.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => Padding(
    padding: const EdgeInsets.all(1),
    child: Form(
      controller: form,
      onSubmit: () => setState(
        () => status = 'Saved range $start–$end',
      ),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          const Text('Range'),
          FormField.builder(
            validator: () => end > start
                ? null
                : 'End must be greater than start.',
            builder: (context, field) => Semantics(
              role: SemanticRole.region,
              label: 'Range',
              validationError: field.error,
              child: Column(
                mainAxisSize: MainAxisSize.min,
                crossAxisAlignment:
                    CrossAxisAlignment.start,
                children: [
                  Stepper(
                    label: 'Start',
                    value: start,
                    min: 0,
                    max: 9,
                    focusNode: field.focusNode,
                    onChanged: (value) {
                      setState(() => start = value);
                      field.valueChanged();
                    },
                  ),
                  Stepper(
                    label: 'End',
                    value: end,
                    min: 0,
                    max: 9,
                    onChanged: (value) {
                      setState(() => end = value);
                      field.valueChanged();
                    },
                  ),
                ],
              ),
            ),
          ),
          const SizedBox(height: 1),
          const _SaveRangeButton(),
          const SizedBox(height: 1),
          Text(status),
        ],
      ),
    ),
  );
}

class _SaveRangeButton extends StatelessWidget {
  const _SaveRangeButton();

  @override
  Widget build(BuildContext context) {
    // Form.of also rebuilds this widget when the controller changes.
    final form = Form.of(context);
    return Button(
      text: 'Save range',
      onPressed: form.isBusy ? null : form.submit,
    );
  }
}

Live preview

Live · interactive

click & type to interact ⓘ how this demo runs ⛶ Expand