Form

Builds a form with validation and easy access to form fields values.

The benefits of using ShadForm over managing form fields individually are:

Centralized form state management.
Easy access to all form field values as a single Map<String, dynamic>.
No need to manage individual controllers for each form field.

Preview
Code

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

  @override
  State<FormPage> createState() => _FormPageState();
}

class _FormPageState extends State<FormPage> {
  final formKey = GlobalKey<ShadFormState>();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: ShadForm(
          key: formKey,
          child: ConstrainedBox(
            constraints: const BoxConstraints(maxWidth: 350),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              mainAxisSize: MainAxisSize.min,
              children: [
                ShadInputFormField(
                  id: 'username',
                  label: const Text('Username'),
                  placeholder: const Text('Enter your username'),
                  description: const Text('This is your public display name.'),
                  validator: (v) {
                    if (v.length < 2) {
                      return 'Username must be at least 2 characters.';
                    }
                    return null;
                  },
                ),
                const SizedBox(height: 16),
                ShadButton(
                  child: const Text('Submit'),
                  onPressed: () {
                    if (formKey.currentState!.saveAndValidate()) {
                      print(
                          'validation succeeded with ${formKey.currentState!.value}');
                    } else {
                      print('validation failed');
                    }
                  },
                ),
              ],
            ),
          ),
        ),
      ),
    );
  }
}

Initial form value

You can set the initial form value by passing a Map<String, dynamic> to the initialValue property of the ShadForm widget.

ShadForm(
  initialValue: {
    'username': 'john_doe',
    'email': '[email protected]'
  },
  child: // Your form fields here
)

All form fields with matching ids will be initialized with the corresponding values from the initialValue map. Unless they have their own initialValue set.

Get the form value

You can get the current form value by accessing the value property of ShadFormState using a GlobalKey.

final formKey = GlobalKey<ShadFormState>();

// Your Form widget
ShadForm(
  key: formKey,
),

// To get the form value
final formValue = formKey.currentState!.value; // Returns a Map<String, dynamic> with the form field values

You typically need this after getting a successful value from the saveAndValidate method, for example:

ShadButton(
  child: const Text('Submit'),
  onPressed: () {
    final formState = formKey.currentState!;
    // The form is not valid, return early
    if (!formState.saveAndValidate()) return;
    // The form is valid, print the form value
    print('Form value: ${formState.value}');
  },
),

Manipulate single form field value

You can set or update the value of specific form fields using the setFieldValue method of ShadFormState.

final formKey = GlobalKey<ShadFormState>();

// Your Form widget
ShadForm(
  key: formKey,
),

// To set or update a specific field value
formKey.currentState!.setFieldValue('username', 'new_username');

If you don’t want to notify the field about the value change, you can pass notifyField: false as argument. This would only update the form value without updating the field UI.

Manipulate entire form value

You can set or update the entire form value using the setValue method of ShadFormState.

final formKey = GlobalKey<ShadFormState>();

// Your Form widget
ShadForm(
  key: formKey,
),

// To set or update the entire form value
formKey.currentState!.setValue({
  'username': 'new_username',
  'email': '[email protected]'
});

If you don’t want to notify the fields about the value change, you can pass notifyFields: false as argument. This would only update the form value without updating the fields UI.

Examples

See the following links for more examples on how to use the ShadForm component with other components: