Numeric Field

The numeric field is for general-purpose numeric data with automatic validation and optional data transformation. It preserves precision (up to 14 decimal places by default) and is nearly identical to the monetary field except it lacks currency-specific display formatting.

When to Use

Use numeric when you need:

• Scientific data, measurements, calculations
• Quantities, counts, inventory
• Scores, ratings, percentages
• Any numeric data where precision matters

Use monetary when you need:

• Currency data with special display formatting (thousand separators, currency symbols, abbreviations)
• The only difference is the display options for numbro.js formatting

Basic Usage

{
  type: 'numeric',
  label: 'Quantity',
  key: 'quantity',
  order: 0
}

This automatically:

• Validates that values are numbers (not strings)
• Cleans messy input like "$1,234" → 1234 on load and cell changes
• Preserves precision (14 decimals)
• Provides smartFix suggestions for invalid data

Properties

Optional (but recommended)

• locale (ILocale) - Locale for parsing and transformation. Default: 'en-AU' (Australian English)

Optional

Auto-Clean Options

Controls automatic data cleaning on load and cell changes:

• autoClean (false | object) - Controls automatic data cleaning. Default: enabled with defaults below
  • Set to false to disable auto-cleaning (only smartFix suggestions will be available)
  • Set to object to customize cleaning behavior

When autoClean is enabled (default), you can configure:

• autoClean.decimalPlaces (number) - Number of decimal places to keep. Default: 14 (preserve precision)
• autoClean.decimalHandling ('drop' | 'round' | 'ceil' | 'floor') - How to handle decimals. Default: 'round'
• autoClean.stripCurrencySymbols (boolean) - Whether to strip currency symbols. Default: true
• autoClean.stripOnlyTheseCurrencies (string[] | 'any') - Which currencies to strip. Default: 'any' (strips all currency symbols)
• autoClean.currencyPosition ('prefix' | 'suffix' | 'both') - Where to look for currency symbols. Default: 'both'

See ICleanNumberOptions for all options.

Important: Currency symbols are treated as formatting noise. The field's locale determines the currency, not the input symbol. For example, "$12" in a field with locale: 'en-GB' becomes 12 (stored) and displays as "£12" (if using monetary field with display formatting). To restrict which currency symbols are accepted, use stripOnlyTheseCurrencies: ['$'] instead of 'any'.

Note: SmartFix suggestions always use these same options, even if autoClean: false.

Plus all common field properties.

Automatic Behavior

The SDK automatically:

• Adds a numeric validator (if not present) with autoFixOptions for smartFix suggestions
• Adds a CleanNumbers transformer (unless autoClean: false) that runs on load and cell changes

Examples

Basic with Defaults

{
  type: 'numeric',
  label: 'Quantity',
  key: 'quantity',
  order: 0
}

Behavior:

• Input: "$1,234.567" → Stored: 1234.567 (cleaned automatically) ✓
• Input: "abc" → Error: "Must be a number" ✗
• Preserves up to 14 decimal places

Custom Auto-Clean Options

{
  type: 'numeric',
  label: 'Percentage',
  key: 'percentage',
  order: 0,
  autoClean: {
    decimalPlaces: 2,
    decimalHandling: 'round',
    stripCurrencySymbols: true
  },
  validators: [
    { type: 'range', min: 0, max: 100 }
  ]
}

Behavior:

• Input: "99.999%" → Stored: 100.00 (rounded to 2 decimals, % stripped) ✓
• Input: "150" → Error: "Must be between 0 and 100" ✗

Disable Auto-Clean (Strict Mode)

{
  type: 'numeric',
  label: 'Precise Measurement',
  key: 'measurement',
  order: 0,
  autoClean: false
}

Behavior:

• Input: "$1,234" → Error: "Must be a number" (no auto-cleaning) ✗
• Input: 1234 → Stored: 1234 ✓
• User must provide clean numbers or use smartFix suggestions

Integers Only

{
  type: 'numeric',
  label: 'Count',
  key: 'count',
  order: 0,
  autoClean: {
    decimalPlaces: 0,
    decimalHandling: 'round'
  },
  validators: [
    { type: 'numeric', allowDecimals: false },
    { type: 'min', value: 0 }
  ]
}

Behavior:

• Input: "123.7" → Stored: 124 (rounded to integer) ✓
• Input: "-5" → Error: "Must be at least 0" ✗

With Locale

{
  type: 'numeric',
  label: 'Measurement',
  key: 'measurement',
  order: 0,
  locale: 'de-DE' // German format
}

Behavior:

• Input: "1.234,56" (German format) → Stored: 1234.56 ✓
• Input: "1,234.56" (US format) → Stored: 1234.56 (smartFix can detect and convert) ✓

Currency Symbol Stripping

{
  type: 'numeric',
  label: 'Amount',
  key: 'amount',
  order: 0,
  locale: 'en-GB', // British locale
  autoClean: {
    stripCurrencySymbols: true,
    stripOnlyTheseCurrencies: 'any' // Default: strips all currency symbols
  }
}

Behavior:

• Input: "$100" → Stored: 100 ($ stripped, number extracted) ✓
• Input: "€100" → Stored: 100 (€ stripped, number extracted) ✓
• Input: "£100" → Stored: 100 (£ stripped, number extracted) ✓

Note: The currency symbol is treated as formatting noise. The field's locale determines the currency context, not the input symbol. If you need strict currency validation, use:

autoClean: {
  stripCurrencySymbols: true,
  stripOnlyTheseCurrencies: ['£'] // Only accept British pounds
}

Behavior with strict currency:

• Input: "£100" → Stored: 100 ✓
• Input: "$100" → Error: "Must be a number" ($ not in whitelist) ✗
• Input: "€100" → Error: "Must be a number" (€ not in whitelist) ✗

How It Works

1. Data Flow

CSV/Excel → String "1,234.56" 
  ↓
CleanNumbers Transformer (if autoClean enabled)
  ↓
Number 1234.56
  ↓
Numeric Validator (checks if it's a number)
  ↓
Stored as 1234.56

2. Validation

Validators only check if the value is already a number. They don't parse strings. The CleanNumbers transformer handles string-to-number conversion.

3. Locale

The locale property controls:

• How the CleanNumbers transformer parses strings (e.g., "1.234,56" for de-DE)
• Which format smartFix expects when suggesting fixes

Numeric vs Monetary

The only difference between numeric and monetary fields:

Both fields:

• Auto-inject CleanNumbers transformer (unless autoClean: false)
• Auto-inject numeric validator with autoFixOptions
• Support same autoClean options
• Support same locale option
• Use same validation logic

Use monetary when: You need the display options for currency formatting in the UI.

Use numeric when: You don't need special display formatting.

Override Default Behavior

You can provide your own validators and transformers to fully customize:

{
  type: 'numeric',
  label: 'Custom',
  key: 'custom',
  order: 0,
  autoClean: false, // Disable auto-injection
  validators: [
    {
      type: 'numeric',
      allowDecimals: true,
      autoFixOptions: {
        decimalPlaces: 3,
        decimalHandling: 'floor'
      }
    }
  ],
  transformers: [
    {
      action: 'cleanNumbers',
      payload: {
        options: {
          decimalPlaces: 3,
          decimalHandling: 'floor',
          stripCurrencySymbols: false // Don't strip currency
        }
      }
    }
  ]
}