Dynamic Forms Module

The Dynamic Forms module steps the user through a multi-screen questionnaire whose screens, questions, and input types come from the backend per session. Use it for jurisdiction-specific questions that change without an SDK release.

This module follows the form-based pattern across multiple screens.

Tag

<incode-dynamic-forms> is a standard Web Component. Importing the UI subpath registers the custom element; importing the CSS applies the module's styles.

import '@incodetech/web/dynamic-forms';
import type { DynamicForms } from '@incodetech/web/dynamic-forms';
import type { ComponentProps } from 'preact';
import '@incodetech/web/dynamic-forms/styles.css';

This is the Web SDK 2.0 equivalent of Web SDK 1.x renderForms. SDK 2.0 uses the same Web Component integration pattern as the other standalone modules instead of an imperative render helper.

Properties

Standalone example

This example mirrors the SDK 1.x renderForms(container, options) use case with a locally supplied screen definition:

import { setup } from '@incodetech/web';
import '@incodetech/web/base.css';
import '@incodetech/web/themes/light.css';
import '@incodetech/web/dynamic-forms';
import type { DynamicForms } from '@incodetech/web/dynamic-forms';
import type { ComponentProps } from 'preact';
import '@incodetech/web/dynamic-forms/styles.css';

await setup({
  apiURL: 'https://demo-api.incodesmile.com',
  token: sessionToken,
  flow: false,
  theme: false,
});

const forms = document.createElement('incode-dynamic-forms') as HTMLElement & ComponentProps<typeof DynamicForms>;
forms.config = { screens };
forms.onFinish = () => showNextStep();
forms.onError = (error) => console.error(error);

document.querySelector('#forms-container')?.replaceChildren(forms);

Recoverable submission failures stay inside the component and show a retry screen. They do not call onError.

To use the Dashboard-configured module instead, omit forms.config. The standard standalone bootstrap loads the DYNAMIC_FORMS configuration for the active session. Inside <incode-flow>, the orchestrator continues to mount and configure the same component automatically.

Configuration

type DynamicFormsConfig = {
  flowId?: string;
  screens?: Screen[];
  prefillValue?: string;
};

When bypassing Dashboard Flow resolution, supply flowId or screens. If neither value is available after configuration resolution, the module enters misconfigured rather than failing at runtime.

Screens and questions

type Screen = {
  title?: string;
  hideTitle?: boolean;
  questions: Question[];
};

type Question = {
  questionId: string;
  question: string;
  inputType?: InputType;
  overrides?: InputType;
  isPredefined?: boolean;
  isOptional?: boolean;
  options?: string[];
  prefillSource?: string | null;
  editable?: boolean;
};

InputType is 'TEXT', 'DATE', 'COUNTRY', 'NATIONALITY', 'NUMBER', 'EMAIL', 'PHONE', 'CPF', 'NAME', 'YESNO', 'SELECT', or 'MULTISELECT'. Treat the union as open — an unrecognized value renders as text rather than breaking the screen.

Prefill from captured ID

Questions with prefillSource can receive values from the customer's captured ID. PHONE and MULTISELECT inputs are excluded. If a source does not resolve, the question stays blank and editable.

In inputting and submitting, prefilledQuestionIds: string[] identifies populated questions and nonEditableQuestionIds: string[] identifies read-only ones. Render the latter read-only with a “from ID” marker. Their values still submit; do not remove them from the payload. Resolve display text with your translations.

State machine

DynamicFormsState is a discriminated union over status:

attemptsExhausted stays inside this module rather than routing through the orchestrator's terminal error screen, because that screen's retry would reload the flow and fail against a single-use token. An invalid hint that still has attempts left keeps the user on the screen with an inline field error instead.

When status === 'inputting':

submitting carries the same screen, answers, and validity, frozen at submission time.

finished carries result: 'completed' when every screen was submitted, or 'skipped' when the screen configuration could not be loaded. Loading failures skip the module rather than blocking the flow.

The module treats the two kinds of submission failure differently. If the server fails (HTTP 5xx) or the request does not complete, the module enters submitFailed. Call retry() to send the answers again. If the backend refuses the content of one answer (HTTP 4xx), the module drops that answer, submits the remaining ones and continues to the next screen, because the same request would fail again. Blank optional answers are not sent at all.

canSubmit** is optimistic.** It starts true on an empty screen and only turns false after a submit attempt populates validationErrors. Binding a Continue button to canSubmit matches the SDK's own behavior; it does not mean every required answer is present.

API methods

Plus the universal lifecycle: subscribe, getState, stop.

Headless example

import { setup } from '@incodetech/core';
import { createDynamicFormsManager } from '@incodetech/core/dynamic-forms';

const manager = createDynamicFormsManager({ config: { flowId } });

manager.subscribe((state) => {
  if (state.status === 'inputting') {
    renderScreen({
      screen: state.currentScreen,
      progress: `${state.screenIndex + 1} of ${state.totalScreens}`,
      answers: state.answers,
      // validationErrors values are i18n keys — resolve them for display.
      errors: state.validationErrors,
      canSubmit: state.canSubmit,
    });
  }

  if (state.status === 'misconfigured') {
    console.error('Dynamic Forms needs either screens or a flowId');
  }

  if (state.status === 'finished') {
    console.log('Dynamic Forms', state.result);
  }
});

manager.load();

See also

• Module: Custom Fields: Dashboard-defined single-screen field schema
• Module: eKYC: identity-data form with a fixed field catalog
• Module Patterns → form-based
• Individual Modules