Date Field

The date field provides intelligent date handling with automatic parsing, validation, and formatting using Moment.js. The SDK validates dates strictly against your format while offering smart auto-cleaning and fix suggestions.

Basic Usage

{
  type: 'date',
  label: 'Birth Date',
  key: 'birthDate',
  order: 0,
  formatPattern: 'DD/MM/YYYY'
}

This simple configuration:

Validates dates must match DD/MM/YYYY exactly
Auto-cleans various date formats (ISO 8601, different delimiters, single-digit days/months)
Formats all dates to DD/MM/YYYY for display
Suggests fixes for invalid dates via SmartFix

Properties

Required

formatPattern (string) - The Moment.js format pattern that dates must match. Used for validation, display, and formatting.

Optional

autoClean (false | object) - Controls automatic date parsing and formatting (default: enabled)
defaultValue (Date | string) - Default date value
yearRange ([Date, Date]) - Year range for the year dropdown (default: [1900, now])

Plus all common field properties.

How It Works

Validation (Strict)

The validator only accepts dates matching your formatPattern:

{
  formatPattern: 'DD/MM/YYYY'
}
// ✅ Valid: "15/01/2025"
// ❌ Invalid: "2025-01-15" (wrong format)
// ❌ Invalid: "15/1/2025" (single-digit month)
// ❌ Invalid: "2025" (incomplete)

Auto-Clean (Enabled by Default)

When autoClean is enabled (default), the SDK automatically parses various date formats and converts them to your formatPattern:

{
  formatPattern: 'DD/MM/YYYY'
  // autoClean is enabled by default
}
// Input: "2025-01-15" → Cleaned to: "15/01/2025" ✅
// Input: "15/1/2025" → Cleaned to: "15/01/2025" ✅
// Input: "2025/01/15" → Cleaned to: "15/01/2025" ✅
// Input: "15.01.2025" → Cleaned to: "15/01/2025" ✅

The SDK uses comprehensive parse patterns including:

ISO 8601 formats (YYYY-MM-DD, YYYY-MM-DDTHH:mm:ss.SSSZ)
Common formats with different delimiters (/, -, ., space, |)
Single-digit variations (D/M/YYYY, M/D/YYYY)
Partial dates (YYYY-MM, YYYY)

SmartFix (Always Available)

Even when autoClean is disabled, SmartFix suggestions are available:

{
  formatPattern: 'DD/MM/YYYY',
  autoClean: false
}
// Input: "2025-01-15"
// ❌ Shows error: "Date must match format DD/MM/YYYY"
// 💡 Hover shows SmartFix suggestion: "15/01/2025"

Format Patterns

Common Moment.js format patterns:

'YYYY-MM-DD' → 2025-01-15
'DD/MM/YYYY' → 15/01/2025
'MM/DD/YYYY' → 01/15/2025
'MMMM D, YYYY' → January 15, 2025
'DD-MMM-YYYY' → 15-Jan-2025
'YYYY/MM/DD' → 2025/01/15

See Moment.js format documentation for all tokens.

Auto-Clean Control

Enabled (Default)

{
  type: 'date',
  label: 'Order Date',
  key: 'orderDate',
  order: 0,
  formatPattern: 'YYYY-MM-DD'
  // autoClean enabled by default
}

Automatically parses and formats dates on load and cell changes.

Disabled

{
  type: 'date',
  label: 'Order Date',
  key: 'orderDate',
  order: 0,
  formatPattern: 'YYYY-MM-DD',
  autoClean: false
}

Disables automatic cleaning. Validator is strict, but SmartFix suggestions still available.

Custom Parse Patterns

{
  type: 'date',
  label: 'Order Date',
  key: 'orderDate',
  order: 0,
  formatPattern: 'YYYY-MM-DD',
  autoClean: {
    parsePatterns: ['YYYY-MM-DD', 'DD/MM/YYYY', 'MM/DD/YYYY']
  }
}

Override default parse patterns with your own list.

Use Cases

Standard Date Field

{
  type: 'date',
  label: 'Hire Date',
  key: 'hireDate',
  order: 0,
  formatPattern: 'YYYY-MM-DD',
  validators: [
    { type: 'required' }
  ]
}

Date with Default Value

{
  type: 'date',
  label: 'Created Date',
  key: 'createdDate',
  order: 0,
  formatPattern: 'DD/MM/YYYY',
  defaultValue: new Date().toISOString()
}

Strict Format (No Auto-Clean)

{
  type: 'date',
  label: 'Birth Date',
  key: 'birthDate',
  order: 0,
  formatPattern: 'DD/MM/YYYY',
  autoClean: false,
  yearRange: [new Date(1940, 0, 1), new Date(2010, 11, 31)]
}

Users must enter dates in exact format, but SmartFix helps correct mistakes.

Complete Example

import type { IvtSchema } from '@ivandt/importer';

const schema: IvtSchema = {
  title: 'Employee Import',
  publicKey: 'pk_live_xxx',
  sessionToken: 'session_xxx',
  fields: [
    {
      type: 'date',
      label: 'Hire Date',
      key: 'hireDate',
      order: 0,
      formatPattern: 'YYYY-MM-DD',
      validators: [
        { type: 'required' }
      ]
    },
    {
      type: 'date',
      label: 'Birth Date',
      key: 'birthDate',
      order: 1,
      formatPattern: 'DD/MM/YYYY',
      yearRange: [new Date(1940, 0, 1), new Date(2010, 11, 31)]
    },
    {
      type: 'date',
      label: 'Contract End Date',
      key: 'contractEndDate',
      order: 2,
      formatPattern: 'YYYY-MM-DD',
      autoClean: false // Strict format required
    }
  ]
};

Behavior Summary

Scenario	autoClean: true (default)	autoClean: false
Valid format	✅ Passes validation	✅ Passes validation
Wrong format	✅ Auto-cleaned & formatted	❌ Shows error
SmartFix	✅ Available	✅ Available
Validation	Strict (formatPattern only)	Strict (formatPattern only)

Best Practices

Use autoClean: true (default) for user-friendly imports where data comes from various sources
Use autoClean: false when you need strict format compliance (e.g., regulatory requirements)
Choose clear formatPattern that matches your backend expectations
Use ISO format (YYYY-MM-DD) for databases and APIs
Use localized format (DD/MM/YYYY or MM/DD/YYYY) for user-facing data

Timezone Handling

Dates are parsed and formatted in the user's local timezone. ISO 8601 strings with timezone information (e.g., 2025-01-15T10:30:00Z) are correctly handled and converted to local time.

{
  type: 'date',
  label: 'Event Date',
  key: 'eventDate',
  order: 0,
  formatPattern: 'YYYY-MM-DD',
  defaultValue: new Date().toISOString() // Includes timezone
}
// Input: "2025-01-15T23:30:00Z" (UTC)
// Output: "2025-01-16" (if user is in UTC+10)

Date Field

On this page