@dynamic-widget/react

React component for schema-driven forms and dashboards, built on @dynamic-widget/core. Validation, editable tabs, enterprise charts, rules engine, widgetEvent callbacks, and visual schema designer (SchemaDesigner).

Current release: 1.2.0 — Depends on @dynamic-widget/core ^1.2.0. See monorepo CHANGELOG.

Live demo & docs: https://dynamic-widget-app.vercel.app/ — try the interactive demo, /designer, or read the React API guide.

What's new in 1.2.0

• SchemaDesigner — templates, undo/redo, import modal, field-type modal, validation jump-to-field (parity with Angular).
• locale, dataProvider, enterpriseLicenseKey on schema designer preview.
• Controlled schema + onSchemaChange keeps undo history when parent echoes updates back.

Adds @dynamic-widget/core automatically. Peer deps: React 18 or 19 (react, react-dom). Optional peer: @dynamic-widget/enterprise.

Keywords: dynamic-widget react component schema-driven forms dashboard hooks i18n data-binding

Install

npm install @dynamic-widget/react @dynamic-widget/themes
# Adds @dynamic-widget/core automatically.
# Peer deps: react ^18 || ^19, react-dom ^18 || ^19.
# Optional enterprise:
npm install @dynamic-widget/enterprise

Usage

Component

import { DynamicWidget } from "@dynamic-widget/react";
import type { WidgetSchema } from "@dynamic-widget/core";
import "@dynamic-widget/themes/dynamic-widget.css";

const schema: WidgetSchema = {
  widgets: [{ id: "title", type: "heading", label: "Hello" }],
};

export default function App() {
  return (
    <DynamicWidget
      schema={schema}
      onWidgetEvent={(event) => console.log(event)}
      enterpriseLicenseKey=""
    />
  );
}

Controlled values

import { useState } from "react";
import { DynamicWidget } from "@dynamic-widget/react";

export default function Form() {
  const [values, setValues] = useState<Record<string, unknown>>({});

  return (
    <DynamicWidget
      schema={schema}
      values={values}
      onValuesChange={setValues}
    />
  );
}

i18n (language dropdown)

Your app provides the language picker; pass the active tag as locale:

const [locale, setLocale] = useState("en");

<select value={locale} onChange={(e) => setLocale(e.target.value)} aria-label="Language">
  <option value="en">English</option>
  <option value="fr">Français</option>
  <option value="ar">العربية</option>
</select>

<DynamicWidget schema={i18nSchema} locale={locale} values={values} onValuesChange={setValues} />;

Use labelKey and schema.locales on the schema (see @dynamic-widget/core README). Docs: i18n guide.

Async binding

import { createFetchDataProvider } from "@dynamic-widget/core";

const dataProvider = createFetchDataProvider();

<DynamicWidget schema={schema} dataProvider={dataProvider} values={values} onValuesChange={setValues} />;

Use optionsFrom on select/radio nodes in the schema. Demo: Async binding scenario (requires npm run docs:dev for /api/options/*).

Markdown & file upload

Community widgets markdown and fileUpload work with no extra props. Virtual tables need enterpriseLicenseKey — see core README.

Visual schema designer (SchemaDesigner)

import { useState } from "react";
import { SchemaDesigner } from "@dynamic-widget/react";
import { createEmptySchema, type WidgetSchema, type WidgetValues } from "@dynamic-widget/core";
import "@dynamic-widget/themes/dynamic-widget.css";

export default function FormBuilderPage() {
  const [schema, setSchema] = useState<WidgetSchema>(createEmptySchema("My form"));
  const [values, setValues] = useState<WidgetValues>({});

  return (
    <SchemaDesigner
      schema={schema}
      onSchemaChange={setSchema}
      values={values}
      onValuesChange={setValues}
      previewTitle="Form preview"
      showJsonPanel
      enterpriseLicenseKey=""
    />
  );
}

| Prop | Type | Description | | --- | --- | --- | | schema | WidgetSchema | Required. Controlled form schema. | | onSchemaChange | (schema) => void | After add/edit, templates, import, undo/redo. | | values / onValuesChange | WidgetValues | Live preview values. | | palette | SchemaDesignerPaletteGroup[] | Custom field/dashboard palette. | | readonly | boolean | Disable editing. | | embedded | boolean | Compact chrome for embeds. | | dark | boolean | Dark theme for designer shell and preview. | | previewTitle | string | Preview heading (default "Form preview"). | | showJsonPanel | boolean | Collapsible JSON (default true). | | locale | string | Preview locale for labelKey resolution. | | dataProvider | DataProvider | optionsFrom in preview. | | enterpriseLicenseKey | string | Charts/plugins in preview when licensed. |

Guide: Schema designer · Live: /designer

React vs Angular naming

| React | Angular | | --- | --- | | SchemaDesigner | SchemaDesignerComponent / dw-schema-designer | | onSchemaChange | (schemaChange) |

Re-exports all public symbols from @dynamic-widget/core (createWidgetApi, createFetchDataProvider, createSchemaDesignerController, applyEditableTabsAction, types, etc.).

API

DynamicWidget props

Extends WidgetHostOptions from core.

| Prop | Type | Description | | --- | --- | --- | | schema | WidgetSchema | Required. Root widget tree. | | locale | string | Resolves labelKey strings from schema.locales (e.g. en, fr, ar for RTL). | | dataProvider | DataProvider | Loads optionsFrom URLs (e.g. createFetchDataProvider()). | | values | WidgetValues | Controlled field values. | | onValuesChange | (values) => void | Called when bound fields change. | | dark | boolean | Dark theme on host. | | enterpriseLicenseKey | string | Registers enterprise license when valid. | | rules | WidgetRule[] | Rules engine input. | | aiInsightProvider | AiInsightProvider | Custom AI insight hook. | | tabsContentOnly | boolean | Preview: hide insert bar and edit chrome. | | onWidgetEvent | (event) => void | Tab designer and widget actions. | | onEnterpriseStatusChange | (status) => void | { licensed, flags } after license changes. | | onToast | (message) => void | Toast messages from the renderer. |

The component owns an internal WidgetApi and re-renders the DOM tree on each React commit.

Browser support

Requires a modern browser (see @dynamic-widget/core). Mount only on the client in Next.js / Remix — wrap with "use client" or dynamic ssr: false because rendering uses DOM APIs.

Related packages

• @dynamic-widget/core — framework-agnostic engine (auto-installed as a dependency).
• @dynamic-widget/themes — shared CSS.
• @dynamic-widget/enterprise — optional licensing and gated APIs.
• @dynamic-widget/angular — Angular standalone component on the same core.
• @dynamic-widget/js — vanilla createDynamicWidget host.

License

MIT