Render dynamic forms in your application

This page provides implementation guidance for rendering dynamic forms in your application.

Getting started

To render a dynamic form, you need:

A schema — the JSON Schema defining data types and validation
A uiSchema — the UI Schema defining layout and controls
A data — (optional) existing data to prefill the form
A renderer — either a JSON Forms library or your own implementation

Using JSON Forms libraries

The fastest way to get started is using an official JSON Forms renderer:

These libraries handle schema interpretation, validation, and rendering out of the box.

Schema-level hints

The JSON Schema includes a format keyword that indicates how a field should be rendered. Use it to select the appropriate input component:

Format	Implementation
`format: "date"`	Render a date picker input

Custom renderers for Enterprise API Suite

The UI Schema extends JSON Forms with custom options that require additional rendering logic:

Option	Implementation
`data.source`	Populate options from any data source (API, database, etc.) based on the source identifier. The Enterprise API Suite provides endpoints for available sources.
`data.exclude`	Filter the data source based on the specified restriction
`format: "postal-code"`	Render a postal code input with country-aware formatting
`rules`	Apply client-side validation rules (e.g., age thresholds)
`dependsOn`	Re-fetch or update the control when a dependency value changes

Building a custom renderer

If you need full control over the user experience, you can build your own form renderer. Your implementation must:

Parse the schema — Extract property definitions, types, and validation rules
Parse the uiSchema — Build the layout tree from elements
Render controls — Map schema types to appropriate input components
Apply rules — Evaluate conditions and show/hide/enable/disable elements
Validate input — Enforce schema constraints before submission
Handle progressive disclosure — Re-render when the API returns updated schemas

Handling progressive disclosure

When implementing progressive disclosure:

Render the form from schema, uiSchema, and any existing data
Collect user input for the current step (Category)
Submit the answers to the API
Compare the new response with the previous one:
- If there’s a new root property in the schema, or a new Category in the uiSchema, re-render the form to show the new questions
- If the schema and uiSchema are unchanged, the form is complete

Examples: React custom renderers

The examples below show how to implement custom renderers using JSON Forms for React and Material UI. Each renderer follows the same pattern: a tester that matches specific UI Schema options, and a control component that renders the appropriate input.

Country renderer (`data.source: "countries"`)

Fetches the country list and applies data.exclude filters. In this example, the data is fetched from List countries endpoint.

import { withJsonFormsControlProps } from '@jsonforms/react';
import { rankWith } from '@jsonforms/core';
import { Autocomplete, TextField } from '@mui/material';
import { useEffect, useState } from 'react';

// Custom renderer that fetches data for the data.source option
const DataSourceControl = (props) => {
  const { data, path, handleChange, uischema, label } = props;
  const [options, setOptions] = useState([]);
  const { data: dataOptions } = uischema.options || {};

  useEffect(() => {
    if (dataOptions?.source === 'countries') {
      // Fetch countries and apply exclude filters
      fetch('https://api.enterprise.uphold.com/core/countries', {
        headers: {
          'Authorization': `Bearer ${accessToken}` // Your OAuth2 access token
        }
      })
        .then((res) => res.json())
        .then((countries) => {
          // Apply exclude filter if specified
          const filtered = dataOptions.exclude?.restrictions
            ? countries.filter((country) =>
                !dataOptions.exclude.restrictions.some((r) =>
                  country.restrictions?.some((cr) => cr.scope === r.scope)
                )
              )
            : countries;
          setOptions(filtered.map((c) => ({ value: c.code, label: c.name })));
        });
    }
  }, [dataOptions]);

  return (
    <Autocomplete
      options={options}
      value={options.find((o) => o.value === data) || null}
      onChange={(_, selected) => handleChange(path, selected?.value)}
      getOptionLabel={(option) => option.label}
      renderInput={(params) => <TextField {...params} label={label} />}
    />
  );
};

// Tester: use this renderer when data.source is present
const dataSourceTester = rankWith(10, (uischema) =>
  uischema.options?.data?.source ? true : false
);

// Export for use with JsonForms
export const dataSourceRenderer = {
  tester: dataSourceTester,
  renderer: withJsonFormsControlProps(DataSourceControl),
};

This example demonstrates:

Detecting the data.source option with a custom tester
Fetching options from the API and applying data.exclude filters
Using Material UI’s Autocomplete for consistent styling
Passing existing data to prefill the form

Subdivision renderer (`data.source: "subdivisions"` + `dependsOn`)

Fetches subdivisions based on the selected country. Uses dependsOn to read the current country value and re-fetch when it changes. In this example, the data is fetched from Get country endpoint.

import { withJsonFormsControlProps } from '@jsonforms/react';
import { rankWith, Resolve, toDataPath } from '@jsonforms/core';
import { useJsonForms } from '@jsonforms/react';
import { Autocomplete, TextField } from '@mui/material';
import { useEffect, useRef, useState } from 'react';

// Custom renderer that fetches subdivisions based on the selected country
const SubdivisionControl = (props) => {
  const { data, path, handleChange, uischema, label } = props;
  const { core } = useJsonForms();
  const [options, setOptions] = useState([]);
  const isFirstRender = useRef(true);
  const { data: dataOptions } = uischema.options || {};

  // Read the country value from the dependency declared in dependsOn
  const dependsOn = uischema.options?.dependsOn;
  const countryScope = dependsOn?.find(({ name }) => name === 'country')?.scope;
  const country = countryScope ? Resolve.data(core?.data, toDataPath(countryScope)) : undefined;

  useEffect(() => {
    if (dataOptions?.source === 'subdivisions' && country) {
      // Clear the subdivision value when the country changes (except on initial render)
      if (!isFirstRender.current) {
        handleChange(path, undefined);
      }
      isFirstRender.current = false;

      // Fetch subdivisions from GET /countries/{country}
      fetch(`https://api.enterprise.uphold.com/core/countries/${country}`, {
        headers: {
          'Authorization': `Bearer ${accessToken}` // Your OAuth2 access token
        }
      })
        .then((res) => res.json())
        .then((data) => {
          const subdivisions = data.country?.subdivisions ?? [];
          setOptions(subdivisions.map((s) => ({ value: s.code, label: s.name })));
        });
    } else {
      setOptions([]);
    }
  }, [dataOptions, country]);

  return (
    <Autocomplete
      options={options}
      value={options.find((o) => o.value === data) || null}
      onChange={(_, selected) => handleChange(path, selected?.value)}
      getOptionLabel={(option) => option.label}
      disabled={!country}
      renderInput={(params) => <TextField {...params} label={label} />}
    />
  );
};

// Tester: use this renderer when data.source is "subdivisions"
const subdivisionTester = rankWith(10, (uischema) =>
  uischema.options?.data?.source === 'subdivisions'
);

// Export for use with JsonForms
export const subdivisionRenderer = {
  tester: subdivisionTester,
  renderer: withJsonFormsControlProps(SubdivisionControl),
};

This example demonstrates:

Reading dependency values from dependsOn using Resolve.data and toDataPath
Re-fetching subdivisions from Get country when the country changes
Clearing the selected value when the dependency changes (except on initial render)
Disabling the control until a country is selected

Date renderer (`format: "date"` + `rules`)

Renders a date picker and converts rules (e.g., difference-greater-than-or-equal-to-threshold, difference-less-than-or-equal-to-threshold) into min/max date constraints. The format: "date" is defined in the JSON Schema; this renderer adds support for the rules option from the UI Schema.

import { withJsonFormsControlProps } from '@jsonforms/react';
import { rankWith } from '@jsonforms/core';
import { TextField } from '@mui/material';

// Custom renderer that handles the format: "date" schema with validation rules
const DateControl = (props) => {
  const { data, path, handleChange, uischema, label } = props;

  const rules = uischema.options?.rules ?? [];

  // Your own function that converts rules into date picker constraints.
  // This must be implemented by the partner (e.g., evaluating threshold rules against the current date).
  const { min, max } = RulesEvaluator.datepicker.evaluate(rules);

  return (
    <TextField
      fullWidth
      margin="normal"
      label={label}
      type="date"
      value={data ?? ''}
      slotProps={{
        inputLabel: { shrink: true },
        htmlInput: { min, max },
      }}
      onChange={(e) => handleChange(path, e.target.value || undefined)}
    />
  );
};

// Tester: use this renderer when schema.format is "date"
const dateTester = rankWith(10, (schema) =>
  schema?.format === 'date'
);

// Export for use with JsonForms
export const dateRenderer = {
  tester: dateTester,
  renderer: withJsonFormsControlProps(DateControl),
};

This example demonstrates:

Detecting format: "date" in the JSON Schema with a custom tester
Delegating rule evaluation to a partner-implemented function
Applying min/max constraints to the native date input

Postal code renderer (`format: "postal-code"` + `dependsOn`)

Renders a text input for postal codes. Uses dependsOn to read the current country and subdivision values, then applies country-specific validation patterns.

import { withJsonFormsControlProps } from '@jsonforms/react';
import { rankWith, Resolve, toDataPath } from '@jsonforms/core';
import { useJsonForms } from '@jsonforms/react';
import { Autocomplete, TextField } from '@mui/material';
import { useEffect, useState } from 'react';

// Custom renderer that validates postal codes based on the selected country
const PostalCodeControl = (props) => {
  const { data, path, handleChange, uischema, label } = props;
  const { core } = useJsonForms();
  const [pattern, setPattern] = useState(null);

  // Read dependency values declared in dependsOn
  const dependsOn = uischema.options?.dependsOn;
  const countryScope = dependsOn?.find(({ name }) => name === 'country')?.scope;
  const subdivisionScope = dependsOn?.find(({ name }) => name === 'subdivision')?.scope;

  const country = countryScope ? Resolve.data(core?.data, toDataPath(countryScope)) : undefined;
  const subdivision = subdivisionScope ? Resolve.data(core?.data, toDataPath(subdivisionScope)) : undefined;

  useEffect(() => {
    if (uischema.options?.format === 'postal-code' && country) {
      // Your own service/function that returns a regex pattern for the given country.
      // This must be implemented by the partner (e.g., from a local mapping or an API).
      PostalCodeService.getPattern(country, subdivision).then(setPattern);
    } else {
      setPattern(null);
    }
  }, [uischema.options?.format, country, subdivision]);

  const validationError = data && pattern && !new RegExp(pattern).test(data) ? 'Invalid postal code format' : undefined;

  return (
    <TextField
      fullWidth
      margin="normal"
      label={label}
      value={data ?? ''}
      disabled={!country}
      error={!!validationError}
      helperText={validationError}
      onChange={(e) => handleChange(path, e.target.value)}
    />
  );
};

// Tester: use this renderer when options.format is "postal-code"
const postalCodeTester = rankWith(10, (uischema) =>
  uischema.options?.format === 'postal-code'
);

// Export for use with JsonForms
export const postalCodeRenderer = {
  tester: postalCodeTester,
  renderer: withJsonFormsControlProps(PostalCodeControl),
};

This example demonstrates:

Reading multiple dependency values (country, subdivision) from dependsOn
Delegating pattern resolution to a partner-implemented service
Applying regex validation against the resolved pattern
Disabling the control until a country is selected

Registering all custom renderers

import { JsonForms } from '@jsonforms/react';
import { materialRenderers, materialCells } from '@jsonforms/material-renderers';
import { dataSourceRenderer } from './DataSourceControl';
import { subdivisionRenderer } from './SubdivisionControl';
import { dateRenderer } from './DateControl';
import { postalCodeRenderer } from './PostalCodeControl';

const customRenderers = [
  dataSourceRenderer,
  subdivisionRenderer,
  dateRenderer,
  postalCodeRenderer,
  ...materialRenderers,
];

const DynamicForm = ({ schema, uiSchema, data }) => (
  <JsonForms
    schema={schema}
    uischema={uiSchema}
    data={data}
    renderers={customRenderers}
    cells={materialCells}
  />
);

See it in action

To see dynamic forms in practice, explore the KYC processes that use them:

KYC Processes

Learn how dynamic forms power KYC data collection.

User onboarding

Bank transfers

Card transfers

APM transfers

Buy and Sell

Crypto transfers

Travel Rule

Trade & Send

Statements

Resources

Render dynamic forms in your application

Getting started

Using JSON Forms libraries

Schema-level hints

Custom renderers for Enterprise API Suite

Building a custom renderer

Handling progressive disclosure

Examples: React custom renderers

Country renderer (`data.source: "countries"`)

Subdivision renderer (`data.source: "subdivisions"` + `dependsOn`)

Date renderer (`format: "date"` + `rules`)

Postal code renderer (`format: "postal-code"` + `dependsOn`)

Registering all custom renderers

See it in action

KYC Processes

​Getting started

​Using JSON Forms libraries

​Schema-level hints

​Custom renderers for Enterprise API Suite

​Building a custom renderer

​Handling progressive disclosure

​Examples: React custom renderers

​Country renderer (data.source: "countries")

​Subdivision renderer (data.source: "subdivisions" + dependsOn)

​Date renderer (format: "date" + rules)

​Postal code renderer (format: "postal-code" + dependsOn)

​Registering all custom renderers

​See it in action

KYC Processes

Getting started

Using JSON Forms libraries

Schema-level hints

Custom renderers for Enterprise API Suite

Building a custom renderer

Handling progressive disclosure

Examples: React custom renderers

Country renderer (`data.source: "countries"`)

Subdivision renderer (`data.source: "subdivisions"` + `dependsOn`)

Date renderer (`format: "date"` + `rules`)

Postal code renderer (`format: "postal-code"` + `dependsOn`)

Registering all custom renderers

See it in action