Form Field Types

Vyuh Forms provides a comprehensive library of field types for building any kind of form. All fields share common properties and support validation, styling, and conditional visibility.

Common Field Properties

All field types support these common properties:

BaseField(
  name: 'fieldName',          // Unique identifier (required)
  label: 'Field Label',        // Display label
  hint: 'Placeholder text',    // Placeholder/hint text
  description: 'Help text',    // Additional description
  validators: [],              // List of validators
  enabled: true,               // Enable/disable field
  visible: true,               // Show/hide field
  required: false,             // Mark as required
  initialValue: null,          // Default value
)

Text Fields

TextField

Basic text input field:

TextField(
  name: 'username',
  label: 'Username',
  hint: 'Enter your username',
  multiline: false,          // Single or multi-line
  maxLines: 1,               // Max lines for multiline
  maxLength: 50,             // Character limit
  obscureText: false,        // Password field
  keyboardType: TextInputType.text,
  textCapitalization: TextCapitalization.none,
  validators: [required(), minLength(3), maxLength(20)],
)

PasswordField

Secure password input with toggle visibility:

PasswordField(
  name: 'password',
  label: 'Password',
  hint: 'Enter secure password',
  validators: [
    required(),
    minLength(8),
    pattern(
      r'^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$',
      message: 'Must contain letters and numbers'
    ),
  ],
)

Number Fields

NumberField

Integer or decimal number input:

NumberField(
  name: 'age',
  label: 'Age',
  hint: 'Enter your age',
  decimal: false,            // Allow decimals
  min: 0,                    // Minimum value
  max: 120,                  // Maximum value
  step: 1,                   // Increment step
  validators: [required(), min(18), max(100)],
)

NumberField(
  name: 'price',
  label: 'Price',
  decimal: true,
  decimalPlaces: 2,
  prefix: '\$',              // Currency symbol
  validators: [required(), min(0.01)],
)

SliderField

Numeric slider input:

SliderField(
  name: 'rating',
  label: 'Rating',
  min: 0.0,
  max: 10.0,
  divisions: 10,
  showValue: true,
  validators: [required()],
)

Date & Time Fields

DateField

Date picker:

DateField(
  name: 'birthdate',
  label: 'Birth Date',
  hint: 'Select your birth date',
  firstDate: DateTime(1900),
  lastDate: DateTime.now(),
  format: 'MM/dd/yyyy',
  validators: [required()],
)

TimeField

Time picker:

TimeField(
  name: 'appointmentTime',
  label: 'Appointment Time',
  hint: 'Select time',
  use24HourFormat: false,
  validators: [required()],
)

DateTimeField

Combined date and time picker:

DateTimeField(
  name: 'eventDateTime',
  label: 'Event Date & Time',
  firstDate: DateTime.now(),
  lastDate: DateTime.now().add(Duration(days: 365)),
  validators: [required()],
)

Selection Fields

SelectField

Dropdown selection:

SelectField(
  name: 'country',
  label: 'Country',
  hint: 'Select your country',
  options: [
    Option(value: 'us', label: 'United States'),
    Option(value: 'uk', label: 'United Kingdom'),
    Option(value: 'ca', label: 'Canada'),
  ],
  searchable: true,          // Enable search
  validators: [required()],
)

RadioField

Radio button group:

RadioField(
  name: 'subscription',
  label: 'Subscription Plan',
  options: [
    Option(value: 'free', label: 'Free', description: 'Basic features'),
    Option(value: 'pro', label: 'Pro', description: '\$9.99/month'),
    Option(value: 'enterprise', label: 'Enterprise', description: 'Contact us'),
  ],
  layout: RadioLayout.vertical,
  validators: [required()],
)

CheckboxField

Multiple selection checkboxes:

CheckboxField(
  name: 'interests',
  label: 'Interests',
  options: [
    Option(value: 'tech', label: 'Technology'),
    Option(value: 'sports', label: 'Sports'),
    Option(value: 'music', label: 'Music'),
    Option(value: 'travel', label: 'Travel'),
  ],
  minSelections: 1,
  maxSelections: 3,
  validators: [required()],
)

BooleanField

Single checkbox for yes/no:

BooleanField(
  name: 'agreeToTerms',
  label: 'I agree to the terms and conditions',
  validators: [
    custom((value) =>  value == true ? null : 'You must agree to continue'),
  ],
)

File Fields

FileField

File upload:

FileField(
  name: 'resume',
  label: 'Upload Resume',
  hint: 'PDF or Word document',
  acceptedTypes: ['pdf', 'doc', 'docx'],
  maxSize: 5 * 1024 * 1024,  // 5MB
  validators: [required()],
)

ImageField

Image upload with preview:

ImageField(
  name: 'profilePhoto',
  label: 'Profile Photo',
  acceptedTypes: ['jpg', 'jpeg', 'png'],
  maxSize: 2 * 1024 * 1024,  // 2MB
  maxWidth: 1920,
  maxHeight: 1920,
  showPreview: true,
  validators: [required()],
)

Advanced Fields

FormulaField

Calculated field based on other fields:

FormulaField(
  name: 'total',
  label: 'Total',
  formula: '{{quantity}} * {{price}}',
  dependencies: ['quantity', 'price'],
  format: NumberFormat.currency(symbol: '\$'),
)

SignatureField

Capture digital signature:

SignatureField(
  name: 'signature',
  label: 'Sign Here',
  hint: 'Draw your signature',
  width: 400,
  height: 200,
  validators: [required()],
)

RatingField

Star or custom rating:

RatingField(
  name: 'productRating',
  label: 'Rate this product',
  maxRating: 5,
  allowHalfRating: true,
  icon: Icons.star,
  color: Colors.amber,
  validators: [required()],
)

ColorPickerField

Color selection:

ColorPickerField(
  name: 'themeColor',
  label: 'Choose Theme Color',
  defaultColor: Colors.blue,
  validators: [required()],
)

Custom Validators

Create custom validators for any field:

// Simple custom validator
Validator custom((dynamic value) {
  if (value == null || value.isEmpty) {
    return 'This field is required';
  }
  if (value.length < 3) {
    return 'Minimum 3 characters';
  }
  return null; // null means valid
})

// Async validator (e.g., check username availability)
AsyncValidator customAsync((dynamic value) async {
  final isAvailable = await api.checkUsername(value);
  return isAvailable ? null : 'Username already taken';
})

// Cross-field validation
Validator matchesField('password', (value, formData) {
  if (value != formData['password']) {
    return 'Passwords do not match';
  }
  return null;
})

Conditional Fields

Show/hide fields based on other field values:

SelectField(
  name: 'employmentStatus',
  label: 'Employment Status',
  options: [
    Option(value: 'employed', label: 'Employed'),
    Option(value: 'unemployed', label: 'Unemployed'),
    Option(value: 'student', label: 'Student'),
  ],
),
TextField(
  name: 'companyName',
  label: 'Company Name',
  // Only show if employed
  visible: '{{employmentStatus}} == "employed"',
  validators: [requiredIf('employmentStatus', 'employed')],
),

Field Styling

Customize field appearance:

TextField(
  name: 'email',
  label: 'Email',
  style: FieldStyle(
    labelStyle: TextStyle(fontWeight: FontWeight.bold),
    inputDecoration: InputDecoration(
      border: OutlineInputBorder(),
      prefixIcon: Icon(Icons.email),
      filled: true,
      fillColor: Colors.grey[100],
    ),
  ),
)

Field Groups

Organize related fields:

FieldGroup(
  title: 'Personal Information',
  description: 'Basic details about you',
  fields: [
    TextField(name: 'firstName', label: 'First Name'),
    TextField(name: 'lastName', label: 'Last Name'),
    DateField(name: 'birthdate', label: 'Birth Date'),
  ],
),
FieldGroup(
  title: 'Contact Information',
  fields: [
    TextField(name: 'email', label: 'Email'),
    TextField(name: 'phone', label: 'Phone'),
  ],
),

Next Steps

Validation - Learn more about validation
Multi-Step Forms - Create wizard forms
Form Editor - Build forms visually
Examples - See field types in action

Form Fields