Atlas Forms
Custom Players Overview
A custom player is a React component that wraps FormStateProvider and uses ControlRenderer to render individual controls inside a custom layout. Build one when the default FormRenderer two-column grid is not the right structure for your use case.
When to Build a Custom Player
| Scenario | Solution |
|---|---|
| Standard data entry form | Use FormRenderer — don't build a custom player |
| One card per section layout | Custom player — CardSectionPlayer pattern |
| Single-column mobile layout | Custom player — MobilePlayer |
| Multi-step chat-style form | Custom player — ChatPlayer (one field at a time) |
| Form embedded in a sidebar panel | Custom player — CompactPlayer (minimal chrome) |
| React Native app | Custom player using native controls + FormEngine directly |
The Three Building Blocks
FormStateProvider
Context provider that owns the FormEngine instance. All hooks and ControlRenderer must be within this provider.
ControlRenderer
Renders a single control by dispatching to the registered component for its type. Takes a FormControl object as its prop.
useAtlasForm
Hook that provides access to values, errors, setFieldValue, submitForm, and the raw FormEngine instance.
Custom Player vs FormRenderer Comparison
| Feature | FormRenderer | Custom Player |
|---|---|---|
| Layout control | Fixed 12-column grid | Fully custom |
| Section rendering | Automatic (from schema) | Explicit (you decide which sections appear where) |
| Validation | Built-in | Must call submitForm() from the hook — validation runs automatically |
| Draft auto-save | Built-in | Must implement manually using StorageManager and useAtlasForm |
| Theme support | Built-in | Pass ThemeProvider above FormStateProvider |
| Studio selectable | Always available | Register with registerFormPlayer() |