FormRenderer Props — Form Players

Props Reference

Prop	Type	Default	Required	Description
`schema`	`FormSchema`	—	Yes	The parsed form schema object. Do not pass raw JSON strings — parse first with `parseSchema()`.
`initialValues`	`Record<string, any>`	`{}`	No	Pre-populated field values for edit mode, or record data for view mode.
`mode`	`FormMode`	`"edit"`	No	Operating mode: `edit`, `view`, `design`, `admin`, `preview`.
`onSubmit`	`(values, context) => Promise<void>`	—	Yes	Called after all validation passes. Receives the complete form values and execution context.
`onError`	`(errors) => void`	—	No	Called when submit validation fails. Receives a map of `{ fieldId: errorMessage }`.
`autoValidate`	`boolean`	`false`	No	Validate on every field change, not just on submit.
`readOnly`	`boolean`	`false`	No	Force all controls into read-only display regardless of mode.
`theme`	`ThemeConfig`	system default	No	Override the active theme. See Theming.
`context`	`Record<string, any>`	`{}`	No	External execution context — available as `$context` in bindings and visibility rules.
`draftKey`	`string`	auto from formId	No	Override the storage key used for draft auto-save.
`draftEnabled`	`boolean`	`true`	No	Enable or disable draft auto-save.
`validateOn`	`"change" \| "blur" \| "submit"`	`"blur"`	No	Controls when field-level validation fires.
`className`	`string`	—	No	Additional CSS class applied to the root element.
`onFieldChange`	`(fieldId, value) => void`	—	No	Callback fired on every field change — use for external state sync.

TypeScript Interface

// packages/player-components-react/src/components/FormRenderer.tsx

interface FormRendererProps {
  schema:          FormSchema;
  initialValues?:  Record<string, any>;
  mode?:           FormMode;
  onSubmit:        (values: Record<string, any>, context: Record<string, any>) => Promise<void>;
  onError?:        (errors: Record<string, string>) => void;
  autoValidate?:   boolean;
  readOnly?:       boolean;
  theme?:          ThemeConfig;
  context?:        Record<string, any>;
  draftKey?:       string;
  draftEnabled?:   boolean;
  validateOn?:     'change' | 'blur' | 'submit';
  className?:      string;
  onFieldChange?:  (fieldId: string, value: any) => void;
}

Minimal Usage

import { FormRenderer } from '@atlas-forms/player-components-react';
import { parseSchema }  from '@atlas-forms/schema-js';
import rawSchema        from './my-form.schema.json';

const schema = parseSchema(rawSchema);

<FormRenderer
  schema={schema}
  onSubmit={async (values) => {
    await api.save(values);
  }}
/>

Full Usage with All Key Props

<FormRenderer
  schema={schema}
  initialValues={existingRecord}
  mode="edit"
  autoValidate={true}
  validateOn="blur"
  context={{ currentUser, tenantSettings }}
  draftEnabled={true}
  draftKey={`form-${formId}-${recordId}`}
  theme={darkTheme}
  onSubmit={async (values, context) => {
    await api.updateRecord(recordId, values);
    navigate('/records');
  }}
  onError={(errors) => {
    toast.error(`${Object.keys(errors).length} validation errors — please correct them`);
  }}
  onFieldChange={(fieldId, value) => {
    analytics.track('field_changed', { fieldId, formId });
  }}
/>

Parse Schema Before Passing Always pass a parsed FormSchema object via parseSchema(rawJson) — not the raw JSON string or object. parseSchema() validates the schema structure, normalises defaults, and throws descriptive errors on schema errors before rendering begins.

← Overview Next: Operating Modes →