Skip to main content

Form Field Component

Purpose​

Form Field is a component that wraps a form field and provides a label, description, and error message.

Field Component​

Field Component is using Formik for form management. It is a wrapper for Formik's field component. More information about Formik's field component can be found here.

Field Definition​

Field definition is used to define the field component. It is used to define the field component in the form.

component: field
name: firstName # component / field name is required
props:
  label: First Name # label of the field
  type: text # type of the field

Props​

  • label (string): The label of the field. (localized)
  • description (string): The description of the field. (localized)
  • error (string): The error message of the field. (localized)
  • type (string): The type of the field. It accepts text, number, password, email, checkbox, radio, select, select-async, textarea, date, time, datetime, rangedatetime, url, tel, file, hidden, image, range.
  • placeholder (string): The placeholder of the field.
  • defaultValue (string): The default value of the field.
  • items (array): The items of the field. It is used for radio and select types.
  • options (object): The options of the field. Options for Formik field component.

Yaml Example​

component: field
name: firstName
props:
  label: First Name
  type: text
  placeholder: Enter your first name
  defaultValue: John

Field Types​

The following types are supported:

  • text
  • number
  • password
  • email
  • checkbox
  • radio
  • select
  • select-async
  • textarea
  • date
  • time
  • datetime
  • rangedatetime
  • url
  • tel
  • secret
  • hidden
  • file
  • image
  • range

Text​

The text type is used for single-line text input.

component: field
name: firstName
props:
  label: First Name
  type: text
  placeholder: Enter your first name

Text field with edit action​

Text fields support an onEditClick prop that renders an edit icon button. When clicked, it triggers the specified action with the current form values passed as context (including the field's current value).

component: field
name: customerName
props:
  label: Customer Name
  type: text
  onEditClick:
    action: openEditDialog
  options:
    valueFieldName: customerName  # includes this field's value explicitly in the action context

Number​

The number type is used for input fields that should contain a numeric value.

Options: https://s-yadav.github.io/react-number-format/docs/numeric_format for more details.

component: field
name: age
props:
  label: Age
  type: number
  placeholder: Enter your age
  options:
    decimalScale: 3

Password​

The password type is used for password input fields.

component: field
name: password
props:
  label: Password
  type: password
  placeholder: Enter your password

Email​

The email type is used for email input fields.

component: field
name: email
props:
  label: Email
  type: email
  placeholder: Enter your email

Checkbox​

The checkbox type is used for checkboxes.

component: field
name: terms
props:
  label: Terms
  type: checkbox
  onChange:
    - if: "{{ value }}"
      then: # if checked
        - setStore:
            terms: "T"
      else: # if unchecked
        - setStore:
            terms: "N"
  onKeyPress: # on key press event for the field
    - if: "{{ eval keyCode === 13 }}"
      then: # if enter key is pressed
        - consoleLog: "Enter key pressed"

Radio​

The radio type is used for radio buttons.

component: field
name: PaymentMethod
props:
  label: Payment Method
  type: radio
  items:
    - label: Credit Card
      value: creditCard
    - label: PayPal
      value: payPal

Select​

The select type is used for select dropdowns.

component: field
name: country
props:
  label: Country
  type: select
  options:
    allowSearch: true
    allowClear: true
    allowMultiple: true
    allowCreate: true
  items:
    - label: United States
      value: us
    - label: Canada
      value: ca

Select Async​

Select with query is used to load options from a GraphQL query.

component: field
name: country
props:
  label: Country
  type: select-async
  options:
    valueFieldName: "countryCode" # if name is different than value field
    itemLabelTemplate: "{{value}}"
    itemValueTemplate: "{{id}}"
    searchQuery:
      name: getCountries
      path: countries
      totalCountPath: totalCount
    valueQuery:
      name: getCountry
      path: country
    allowSearch: true
    allowClear: true
    allowMultiple: false
    allowCreate: true
    queries:
      - name: getCountries
        query:
          command: "query { countries { id name } }"
          variables: { search: "{{search}}" }
      - name: getCountry
        query:
          command: "query { country(id: {{id}}) { id name } }"
        variables: { id: "{{id}}" }
    dropDownToolbar:
      - component: button
        name: createCountryBtn
        props:
          label:
            en-US: Create Country
          icon: plus
          options:
            variant: primary
          onClick:
            - dialog:
                component: Countries/CreateCountry
                onClose:
                  - selectValue: "{{ result.countryCode }}"
    onSelectValue:
      - setStore:
          selectedCountry: "{{ selectedItem }}"
    onCreateValue:
      - mutation:
          command: "mutation { createCountry(input: { countryCode: '{{ value }}' }) { countryCode } }"
          variables: { value: "{{ value }}" }

Select Async Options​

  • itemLabelTemplate (string): The template for the label of the item.
  • itemValueTemplate (string): The template for the value of the item.
  • searchQuery (object): The search query for the select dropdown.
  • valueQuery (object): The value query for the select dropdown.
  • allowSearch (boolean): Allow search in the select dropdown.
  • allowClear (boolean): Allow clear in the select dropdown.
  • allowMultiple (boolean): Allow multiple selection in the select dropdown.
  • allowCreate (boolean): Allow create in the select dropdown.
  • queries (array): The queries for the select dropdown.
  • dropDownToolbar (components): The toolbar component to be displayed in the dropdown.
  • onSelectValue (array): The actions to be executed when a value is selected.
  • onCreateValue (array): The actions to be executed when a value is created.

Select Async Additional Actions​

  • 'refreshSelect': Reload the selected value from the server.

Textarea​

The textarea type is used for multi-line text input.

component: field
name: description
props:
  label: Description
  type: textarea
  placeholder: Enter your description
  options:
    rows: 3

Date​

The date type is used for date input fields.

component: field
name: date
props:
  label: Date
  type: date
  options:
    format: "MM/dd/yyyy"

Time​

The time type is used for time input fields.

component: field
name: time
props:
  label: Time
  type: time
  options:
    format: "hh:mm a"

Datetime​

DateTime and DateTimeRange Options Reference​

Overview​

This document describes all available options for datetime and rangedatetime field types in the TMS Frontend Web application.

DateTime Options​

The datetime field type supports the following options:

Core Options​

OptionTypeDefaultDescription
dateFormatstring"MM/dd/yyyy"Display format for the date picker. Uses moment.js format tokens.
showTimeSelectbooleanfalseWhether to show time selection in addition to date.
showTimeSelectOnlybooleanfalseShow only time picker without date selection.
timeIntervalsnumber15Time selection intervals in minutes (e.g., 15, 30, 60).
timeCaptionstring"Time"Label displayed for the time selection section.

Timezone Options​

OptionTypeDefaultDescription
useTimezonebooleanfalseEnable timezone-aware date handling. When false, dates are stored as simple strings.
storeAsUTCbooleanfalseWhen used with useTimezone: true, converts and stores dates in UTC format.
timezonestringundefinedFixed timezone for display (requires moment-timezone library).

Storage Format​

OptionTypeDefaultDescription
formatstringundefinedCustom storage format. If not specified, format is determined by other options.

DateTime Range Options​

The rangedatetime field type supports all datetime options plus:

OptionTypeDefaultDescription
isClearablebooleantrueWhether to show a clear button to reset the date range.

Storage Formats by Configuration​

Default (Simple Date)​

type: datetime
# Stores as: "2024-03-15"

Date with Time​

type: datetime
options:
  showTimeSelect: true
# Stores as: "2024-03-15 14:30:00"

Timezone-Aware with UTC Storage​

type: datetime
options:
  showTimeSelect: true
  useTimezone: true
  storeAsUTC: true
# Stores as: "2024-03-15T19:30:00.000Z"

Timezone-Aware with Local Offset​

type: datetime
options:
  showTimeSelect: true
  useTimezone: true
# Stores as: "2024-03-15T14:30:00-05:00"

Common Use Cases​

1. Birth Date (Date Only)​

- name: birthDate
  component: field
  componentProps:
    props:
      type: datetime
      label: Birth Date
      options:
        dateFormat: "MM/dd/yyyy"

2. Appointment Time (Local Time)​

- name: appointmentTime
  component: field
  componentProps:
    props:
      type: datetime
      label: Appointment Time
      options:
        showTimeSelect: true
        timeIntervals: 30
        dateFormat: "MM/dd/yyyy h:mm aa"

3. International Meeting (UTC Storage)​

- name: meetingTime
  component: field
  componentProps:
    props:
      type: datetime
      label: Meeting Time (UTC)
      options:
        showTimeSelect: true
        useTimezone: true
        storeAsUTC: true
        dateFormat: "MM/dd/yyyy HH:mm"
        timeCaption: "Time (UTC)"

4. Date Range Filter​

- name: dateRange
  component: field
  componentProps:
    props:
      type: rangedatetime
      label: Date Range
      placeholder: "Select date range"
      options:
        dateFormat: "MM/dd/yyyy"
        isClearable: true

5. Delivery Window (Date Range with Time)​

- name: deliveryWindow
  component: field
  componentProps:
    props:
      type: rangedatetime
      label: Delivery Window
      options:
        showTimeSelect: true
        timeIntervals: 60
        dateFormat: "MM/dd/yyyy h:mm aa"

6. Time-Only Selection​

- name: dailyReminder
  component: field
  componentProps:
    props:
      type: datetime
      label: Daily Reminder Time
      options:
        showTimeSelectOnly: true
        timeIntervals: 15
        dateFormat: "h:mm aa"
        timeCaption: "Reminder Time"

Enhanced Range DateTime Filter Modes​

When used as a DataGrid filter (via enhanced-rangedatetime), the range date picker supports these filter modes:

ModeDescriptionAuto-applies?
todayFilters to today's date onlyYes
withinWithin the last N unitsYes
more_thanMore than N units agoYes
betweenBetween two specific datesNo (requires Apply)
emptyRecords with no date value (NULL)Yes
not_emptyRecords that have a date valueYes

The Today mode generates a Lucene range query for the current date (e.g., field:["2026-04-05" TO "2026-04-05"]) and auto-applies immediately.

DatePicker and DataGrid Filter Behavior​

DatePicker components support two modes:

  1. Simple Date Format (default): Returns dates as YYYY-MM-DD without timezone
  2. Timezone-Aware Format: Returns ISO 8601 dates with timezone when useTimezone: true

By default, date filters produce clean range queries: customValues.pickUpDate:["2025-08-03" TO "2025-08-13"] instead of timezone-padded ISO strings.

Year Correction for Typed Partial Dates​

When users type partial dates like 4/1 (without a year), the component corrects the year to the current year (e.g., 04/01/2026 instead of 04/01/2001). Detection checks for typed input where the parsed year is unreasonably far from the current year.

Select Component Filter Support​

The select field type used inside filter columns supports InputProps (e.g., endAdornment) passed from YAML configuration, enabling custom adornments alongside the default dropdown arrow and clear button.

Display Format Tokens​

Common moment.js format tokens used in dateFormat:

TokenOutputDescription
MM01-12Month (2 digits)
M1-12Month (1-2 digits)
DD01-31Day of month (2 digits)
D1-31Day of month (1-2 digits)
YYYY20244-digit year
YY242-digit year
HH00-23Hours (24-hour, 2 digits)
H0-23Hours (24-hour, 1-2 digits)
hh01-12Hours (12-hour, 2 digits)
h1-12Hours (12-hour, 1-2 digits)
mm00-59Minutes (2 digits)
m0-59Minutes (1-2 digits)
ss00-59Seconds (2 digits)
s0-59Seconds (1-2 digits)
aam/pmLowercase meridiem
AAM/PMUppercase meridiem

Migration Guide​

From Individual Props to Options Object​

Before (Deprecated):

<ReactDatepickerComponent
  id="eventDate"
  showTimeSelect={true}
  timeIntervals={30}
  dateFormat="MM/dd/yyyy h:mm aa"
/>

After (Recommended):

<ReactDatepickerComponent
  id="eventDate"
  options={{
    showTimeSelect: true,
    timeIntervals: 30,
    dateFormat: "MM/dd/yyyy h:mm aa",
  }}
/>

From Timezone-by-Default to Simple Dates​

Before: Dates were often stored with timezone information by default.

After: Dates are stored as simple strings by default. To enable timezone handling:

options:
  useTimezone: true # Must be explicitly enabled

Best Practices​

  1. Use Simple Dates by Default: Unless you specifically need timezone handling, use the default simple date format.
  2. Be Explicit About Time: If you need time selection, always set showTimeSelect: true.
  3. Consider User Experience:
    • Use appropriate time intervals (15 min for appointments, 60 min for deliveries)
    • Provide clear labels with timeCaption
    • Use familiar date formats for your locale
  4. DataGrid Filters: For date range filters in grids, use rangedatetime with clear labels.
  5. International Applications: Only use useTimezone: true with storeAsUTC: true for truly international applications where timezone accuracy is critical.

Troubleshooting​

Dates showing unexpected timezone​

  • Check if useTimezone is set to true unintentionally
  • Verify the stored format matches your expectations

Time not appearing in picker​

  • Ensure showTimeSelect is set to true
  • Check that dateFormat includes time tokens

Range picker not clearing​

  • Verify isClearable is not set to false
  • Check for any custom validation preventing null values

Format not applying​

  • Ensure format tokens are valid moment.js tokens
  • Check for typos in the dateFormat string

URL​

The url type is used for URL input fields.

component: field
name: url
props:
  label: URL
  type: url
  placeholder: Enter your URL

Tel​

The tel type is used for telephone input fields.

component: field
name: phone
props:
  label: Phone
  type: tel
  placeholder: Enter your phone number

Attachment​

Attachment type is used for attachment input fields. It will create a new attachment record in the database and return the attachment id.

component: field
name: attachment
props:
  label: Attachment
  type: attachment
  options:
    allowMultiple: false
    allowClear: true
    displayAs: "image" # image, file
    previewWidth: 100 # optional
    previewHeight: 100 # optional
    maxSize: 10485760 # 10MB
    allowedExtensions:
      - "image/*"
      - "application/pdf"
    onUploaded:
      - consoleLog: "{{ result.attachmentId }}"

Attachment Options​

OptionTypeDefaultDescription
allowMultiplebooleanfalseAllow uploading multiple files
allowClearbooleanfalseShow clear/remove button for attachments
allowCamerabooleantrueShow camera capture button
cameraQualitystring'high'Camera quality: 'low', 'medium', 'high', 'maximum'
captureFormatstring'jpeg'Camera capture format: 'jpeg', 'png'
instantCamerabooleanfalseInstant capture mode (auto-upload after capture)
displayAsstring'image'Display mode: 'image' or 'file'
maxSizenumber10485760Maximum file size in bytes (default 10MB)
allowedExtensionsarray['image/*', 'application/pdf']Allowed file extensions/MIME types
previewWidthnumber/string'100%'Preview width
previewHeightnumber/string'150px'Preview height
parentIdstring/number-Parent entity ID for linking attachment
parentTypestring-Parent entity type (e.g., 'Order', 'Shipment')
onUploadedstring/array-Actions to execute after successful upload
clearAfterUploadbooleanfalseClear field after upload, showing success message briefly

Drop Zone Mode (clearAfterUpload)​

Use clearAfterUpload: true to create a drop zone for uploading files to a parent entity. After upload, a success message displays for 3 seconds, then the field clears automatically, ready for more uploads.

component: field
name: orderAttachment
props:
  label: "Upload to Order"
  type: attachment
  options:
    allowMultiple: true
    allowCamera: true
    clearAfterUpload: true
    parentId: "{{ orderId }}"
    parentType: "Order"
    onUploaded:
      - refetch: getOrderAttachments

Behavior:

  1. User drops/selects files or captures from camera
  2. Files upload to the parent entity (via parentId/parentType)
  3. Success message shows: "Uploaded: document.pdf, photo.jpg"
  4. After 3 seconds, field clears back to empty drop zone
  5. onUploaded action triggers to refresh attachments elsewhere

File​

The file type is used for file input fields. File type will upload the file to the temp storage and return the file ur

component: field
name: file
props:
  label: File
  type: file

Secret​

The secret type is used for fields that store sensitive values (API keys, tokens, credentials). Instead of storing the actual value in the form field, it encrypts the value server-side using the Secrets API and stores a reference in the format ${secret:org/{orgId}/{secretName}}.

Props:

PropTypeDescription
secretPathstringTemplate expression for the secret name (e.g., "integrations/{{id}}/apiKey"). Resolved against form variables and store context.
placeholderstringPlaceholder text for the input
disabledbooleanDisable the input

Behavior:

  • When a secret is already set, the field displays a chip showing the secret reference (masked) instead of the raw value
  • Clicking the edit button reveals a text input to set a new secret value
  • On save, the value is encrypted via the setSecret GraphQL mutation and the field value is updated to the secret reference string
  • Clearing the secret calls the deleteSecret mutation and removes the reference
component: field
name: apiKey
props:
  label: API Key
  type: secret
  secretPath: "integrations/{{ id }}/apiKey"
  placeholder: Enter API key
info

Secret fields require the Secrets API to be configured on the backend. The stored form value will be a reference string like ${secret:org/42/integrations/1/apiKey}, which is automatically resolved at runtime when the configuration is read.

Hidden​

The hidden type is used for hidden input fields.

component: field
name: id
props:
  label: ID
  type: hidden
  defaultValue: 1

Image​

The image type is used for image input fields.

component: field
name: image
props:
  label: Image
  type: image

Range​

The range type is used for range input fields.

component: field
name: range
props:
  label: Range
  type: range
  options:
    min: 0
    max: 100
    step: 1

Field Actions​

The following actions are supported:

  • setValue - Set value for a field. Available for form fields only.

Autocomplete​

The autocomplete type is used for autocomplete input fields.

component: field
name: country
props:
  label: Country
  type: autocomplete
  options:
    allowSearch: true
    allowClear: true
    allowMultiple: true
    allowCreate: true
  items:
    - label: United States
      value: us
    - label: Canada
      value: ca

Autocomplete (Draft)​

Autocomplete with query is used to load options from a GraphQL query.

component: field
name: country
props:
  label: Country
  type: autocomplete
  options:
    searchQuery:
      name: getCountries
      path: countries
    queries:
      - name: getCountries
        query:
          command: "query { countries { id name } }"
          variables: { search: "{{search}}" }
    onSelectValue:
      - setStore:
          selectedCountry: "{{ selectedItem }}"

Autocomplete Async With Google Places (Draft)​

Autocomplete with Google Places is used to load options from Google Places API.

component: field
name: location
props:
  label: Location
  type: autocomplete
  options:
    searchQuery:
      type: googlePlaces
      options:
        apiKey: '{{ YOUR_GOOGLE_PLACES_API_KEY }}'
        locationRestriction: { country: 'us' }
        origin: { lat: 37.7749, lng: -122.4194 }
        includedPrimaryTypes: ['locality', 'administrative_area_level_1', 'country']
        language: "en-US",
        region: "us",
        fields: ['address_components', 'geometry', 'icon', 'name', 'place_id', 'types']
    onSelectValue:
      - setStore:
          selectedLocation: '{{ selectedItem }}'