Formula Field

The Formula Field component displays computed values calculated from other fields. This is a read-only field where the value is automatically calculated by the backend.

Basic Usage

Text Formula

Date Formula

Field Schema

A formula field is authored as FormulaFieldMetadata (@object-ui/types), which is the source of truth for the key set: it extends BaseFieldMetadata with the expression, its declared return type and the recompute switch. return_type is a closed union — 'text' | 'number' | 'boolean' | 'date' | 'datetime'.

import type { FormulaFieldMetadata } from '@object-ui/types';

const totalPrice: FormulaFieldMetadata = {
  type: 'formula',
  name: 'total_price',
  label: 'Total Price',
  readonly: true,
  formula: 'quantity * unit_price',
  return_type: 'number',
  auto_compute: true,
};

The computed value, and the className a host supplies, are not metadata keys — they are runtime widget props. See Field Widget Props.

Return Types

The formula field formats values based on return type:

• number: Displays with decimal precision
• currency: Displays with currency symbol
• boolean: Displays as Yes/No
• date: Displays formatted date
• text: Displays as string

Formula Examples

Common formula patterns:

// Arithmetic
formula: 'price * quantity'
formula: '(subtotal - discount) * tax_rate'

// Text concatenation
formula: 'first_name + " " + last_name'
formula: 'city + ", " + state + " " + zip'

// Conditional
formula: 'IF(age >= 18, "Adult", "Minor")'
formula: 'IF(status == "closed", completed_at, null)'

// Date calculations
formula: 'created_at + 7 days'
formula: 'end_date - start_date'

Cell Renderer

In tables/grids, displays with monospace font:

import { FormulaCellRenderer } from '@object-ui/fields';

// Renders computed value in monospace font

Backend Implementation

Formula fields are computed on the backend:

// Example backend calculation
const calculateFormula = (formula: string, record: any) => {
  // Parse and evaluate formula
  if (formula === 'quantity * price') {
    return record.quantity * record.price;
  }
  // Use expression parser for complex formulas
  return evaluateExpression(formula, record);
};

Use Cases

• Calculations: Totals, subtotals, tax amounts
• Aggregations: Sum of related records
• Concatenations: Full names, addresses
• Derived Values: Age from birthdate, days until deadline
• Conditional Logic: Status based on other fields