Form fields

Configuring form fields

OpenCRVS provides a selection of different kinds of form fields, which can be used on the declaration or action forms.

Note that some of the form fields are read-only fields intended to provide additional information on the form.

Field conditionals

Every form field accepts an optional conditionals array which gates whether the field is shown, enabled, or displayed on the review page. Each entry is a FieldConditional wrapping a conditional expression:

• ConditionalType.SHOW — Field is shown only when the conditional holds.

• ConditionalType.ENABLE — Field is editable only when the conditional holds.

• ConditionalType.DISPLAY_ON_REVIEW — Field appears on the review page only when both this conditional and the SHOW conditional hold.

When conditionals is omitted, the field is shown and enabled for everyone, and is displayed on review whenever it has a value.

For available conditional helper functions, see Conditionals

Example — hide a field on the review page using never():

import { ConditionalType, FieldType, never } from '@opencrvs/toolkit/events'

{
  id: 'recommender.none',
  type: FieldType.CHECKBOX,
  // ...
  conditionals: [
    {
      type: ConditionalType.DISPLAY_ON_REVIEW,
      conditional: never()
    }
  ]
}

FieldConditional schema

Available field types

TextField

A single-line text input.

TextAreaField

A multi-line text input.

EmailField

An email input.

PhoneField

A phone number input.

IdField

An input for identification numbers (e.g. national ID, passport).

NumberField

A numeric input.

NumberWithUnitField

A numeric input paired with a unit selector (the unit options come from the field config).

AgeField

An age input. Resolves to a date using today as the reference.

DateField

A date input in yyyy-MM-dd format.

TimeField

A time input in HH-mm format.

DateRangeField

A date range input ({ start: yyyy-MM-dd, end: yyyy-MM-dd }). Intended for search forms.

SelectDateRangeField

A select dropdown of predefined date ranges (e.g. "last 7 days"). Intended for search forms.

Checkbox

A boolean checkbox.

RadioGroup

A grouped set of radio buttons. The user picks one option.

Select

A dropdown select.

Country

A select dropdown of countries.

NameField

A composite input for capturing a person's name (firstname / middlename / surname).

AdministrativeAreaField

A field for selecting an administrative area from the country's location hierarchy.

LocationInput

A field for selecting a specific location (e.g. health facility, CRVS office). Filterable by location type.

Address

A composite address input combining country, administrative-area selectors, and free-text address lines.

File

A single-file upload field.

FileUploadWithOptions

A file upload field that lets the user attach files under a set of named document categories (e.g. "Proof of birth", "Photo ID").

SignatureField

Captures a handwritten signature.

PageHeader

A read-only page-header block.

Heading

A read-only heading. Supports a configurable HTML heading variant (h3, h4, ...).

Paragraph

A read-only HTML paragraph.

BulletList

A read-only bullet list.

Divider

A horizontal divider line.

ImageViewField

A read-only image block.

DataField

A read-only table that renders structured data from earlier in the form.

LoaderField

A non-interactive loading indicator. Typically paired with HttpField to surface request status.

ButtonField

A generic button that triggers an action.

LinkButtonField

A button styled as a hyperlink that opens a URL.

AlphaPrintButton

(Experimental.) A button for printing certificates during the declaration process.

HttpField

Issues a background HTTP request to an external service and stores the response so other fields can reference it. No visible UI — pair with LoaderField to surface request status.

AutocompleteField

An autocomplete input designed for large dictionary-style datasets (tens or hundreds of thousands of records). Options are fetched dynamically from a configured source.

SearchField

A search input. Extends HttpField to query an external service and surface the matches.

QrReaderField

A QR code reader, with optional JSON-Schema validation on the scanned value.

IdReaderField

A wrapper around nested QrReaderField and LinkButtonField sub-fields. Holds the value scanned by the inner reader.

QueryParamReaderField

Reads values from URL query parameters into form values, then clears them.

VerificationStatus

Displays a verification state (e.g. ID verified / pending). Often paired with IdReaderField — it can read its value off the reader rather than holding its own.

UserRoleField

A select dropdown automatically populated with the user roles configured in the country config.

FieldGroup

A wrapper that groups several fields together, supporting nested FieldConfig entries.

HiddenField

A non-interactive, hidden field that holds a value but is not rendered in the form.

CustomField

(Experimental.) A custom field implemented by a module path defined in the country config.