Formula Fields

FormulaField displays computed values based on expressions that reference other form fields. Formula fields are read-only -- their values are derived, not entered by users.

Basic Usage

FormulaField(
  name: 'total_cost',
  title: 'Total Cost',
  formula: 'course_fee * quantity',
  resultType: FormulaResultType.number,
  numberFormat: '#,##0.00',
  prefix: '\$',
  errorPlaceholder: '---',
)

Properties

Property	Type	Default	Description
formula	String	required	Expression to evaluate
resultType	FormulaResultType	number	Expected result type
dateTimeFormat	String	yyyy-MM-dd	Format for date results
numberFormat	String	#,##0.00	Format for number results
prefix	String?	null	Text before the value (e.g., $)
suffix	String?	null	Text after the value (e.g., %)
errorPlaceholder	String	---	Shown when expression fails

Result Types

Type	Description
FormulaResultType.number	Numeric calculation
FormulaResultType.dateTime	Date/time computation
FormulaResultType.string	String concatenation/manipulation

LMS Examples

Course Cost Calculator

final form = FormBuilder(title: 'Course Pricing')
  .number('base_fee', title: 'Base Fee')
    .required()
  .number('discount_percent', title: 'Discount (%)')
    .range(min: 0, max: 100)
  .number('tax_rate', title: 'Tax Rate (%)')
    .range(min: 0, max: 30)
  .formula('discount_amount',
    title: 'Discount Amount',
    expression: 'base_fee * discount_percent / 100')
  .formula('subtotal',
    title: 'Subtotal',
    expression: 'base_fee - (base_fee * discount_percent / 100)')
  .formula('total',
    title: 'Total (incl. tax)',
    expression: '(base_fee - base_fee * discount_percent / 100) * (1 + tax_rate / 100)')
  .build();

Credit Hours Summary

FormulaField(
  name: 'total_credits',
  title: 'Total Credit Hours',
  formula: 'lecture_hours + lab_hours + tutorial_hours',
  resultType: FormulaResultType.number,
  numberFormat: '#,##0.0',
  suffix: ' hrs',
)

DSL Usage

.formula('computed_field',
  title: 'Computed Value',
  expression: 'field_a + field_b * field_c')

The DSL method creates a FormulaField with default formatting. For custom formatting, use the constructor directly.

Field Derivation (Alternative)

For simpler cases where you want a text or number field to auto-compute but still allow manual editing, use derivedFrom on any field builder:

.text('full_name', title: 'Full Name')
  .derivedFrom(
    {'first_name', 'last_name'},
    transformer: (values) {
      final first = values['first_name'] as String? ?? '';
      final last = values['last_name'] as String? ?? '';
      return '$first $last'.trim();
    },
  )

Key differences from FormulaField:

Feature	FormulaField	derivedFrom
Read-only	Yes	No (user can override)
Expression	String formula	Dart function
Display	Formatted label	Regular field input
Auto-stop	N/A	Stops when user edits

Next Steps

• Best Practices -- Form design guidelines
• Field Types -- All field type reference
• Enrollment Form -- Complete example