Form

A form component with built-in validation, field management, and submission handling.

Basic Usage

The DForm component provides a complete form solution with DFormField for labeled inputs, validation support, and DFormActions for submit/reset buttons.
dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
DForm(
  children: [
    DFormField(
      label: 'Email',
      name: 'email',
      required: true,
      hint: 'We will never share your email.',
      children: [
        DInput(name: 'email', placeholder: 'Enter your email'),
      ],
    ),
    DFormField(
      label: 'Password',
      name: 'password',
      required: true,
      children: [
        DInput(name: 'password', type: DInputType.password),
      ],
    ),
    DFormActions(children: [
      DButton(label: 'Submit', type: DButtonType.submit),
    ]),
  ],
)

Form Field

DFormField wraps input components with labels, hints, and error messages. Use the required prop to show a required indicator, and hint for helper text.
dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
DFormField(
  label: 'Username',
  name: 'username',
  required: true,
  children: [
    DInput(name: 'username', placeholder: 'Enter username'),
  ],
)

DFormField(
  label: 'Bio',
  name: 'bio',
  hint: 'Tell us about yourself',
  children: [
    DTextarea(name: 'bio', placeholder: 'Your bio...'),
  ],
)

Validation

Add validation rules to form fields. Built-in validators include required, email, minLength, maxLength, min, max, pattern, and custom validators.
dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
DFormField(
  label: 'Email',
  name: 'email',
  required: true,
  rules: [
    DValidators.required(),
    DValidators.email(),
  ],
  children: [
    DInput(name: 'email', placeholder: 'Enter email'),
  ],
)

// Available validators:
DValidators.required()
DValidators.email()
DValidators.minLength(6)
DValidators.maxLength(100)
DValidators.min(0)
DValidators.max(100)
DValidators.pattern(RegExp(r'^[a-z]+$'))
DValidators.custom((value) => value == 'test', 'Must be test')

Form Row (Grid Layout)

Use DFormRow to arrange multiple form fields in a grid layout. Specify the number of columns to control the layout of fields side by side.
dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
DFormRow(columns: 2, children: [
  DFormField(
    label: 'First Name',
    name: 'firstName',
    children: [
      DInput(name: 'firstName', placeholder: 'John'),
    ],
  ),
  DFormField(
    label: 'Last Name',
    name: 'lastName',
    children: [
      DInput(name: 'lastName', placeholder: 'Doe'),
    ],
  ),
])

Form Section

Group related form fields together using DFormSection. Each section can have a title and description to help users understand the purpose of the fields.
dart
1
2
3
4
5
6
7
8
9
10
11
12
13
DFormSection(
  title: 'Personal Information',
  description: 'Please provide your contact details.',
  children: [
    DFormField(
      label: 'Full Name',
      name: 'fullName',
      children: [
        DInput(name: 'fullName'),
      ],
    ),
  ],
)

Form Actions

DFormActions provides a container for form buttons with flexible alignment options. Use it to add submit, reset, and cancel buttons.
dart
1
2
3
4
5
6
7
8
9
10
DFormActions(
  alignment: MainAxisAlignment.spaceBetween,
  children: [
    DButton(label: 'Cancel', variant: DButtonVariant.ghost),
    div(classes: 'flex gap-2', [
      DButton(label: 'Reset', variant: DButtonVariant.outline, type: DButtonType.reset),
      DButton(label: 'Submit', type: DButtonType.submit),
    ]),
  ],
)

Complete Example

A complete form combining sections, rows, fields, and actions. Use onSubmit to handle form data and onValidate for custom validation logic.
dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
DForm(
  onSubmit: (data) => print(data),
  onValidate: (data) => DFormValidationResult(
    isValid: data['email']?.isNotEmpty ?? false,
    errors: {},
  ),
  children: [
    DFormSection(
      title: 'Account Details',
      children: [
        DFormRow(columns: 2, children: [
          DFormField(label: 'First Name', name: 'firstName', required: true, children: [DInput(...)]),
          DFormField(label: 'Last Name', name: 'lastName', required: true, children: [DInput(...)]),
        ]),
        DFormField(label: 'Email', name: 'email', required: true, children: [DInput(...)]),
      ],
    ),
    DFormActions(children: [
      DButton(label: 'Cancel', variant: DButtonVariant.ghost),
      DButton(label: 'Create Account', type: DButtonType.submit),
    ]),
  ],
)

API Reference

DForm

Prop Type Default Description
children List<Component> required Form field components
id String? null Form ID attribute
name String? null Form name attribute
disabled bool false Disable all form fields
validateOnSubmit bool true Validate on form submission
validateOnBlur bool false Validate fields on blur
validateOnChange bool false Validate fields on change
onValidate FormValidateCallback? null Validation callback
onSubmit FormSubmitCallback? null Submit callback with form data
onReset VoidCallback? null Reset callback

DFormField

Prop Type Default Description
children List<Component> required Input component(s)
name String? null Field name for form data
label String? null Field label text
hint String? null Helper text below field
error String? null Error message to display
required bool false Show required indicator
disabled bool false Disable the field
size DFormFieldSize md Label and hint text size
rules List<DValidationRule> [] Validation rules