Field Libraries Overview
Field libraries let you extend Atlas Forms with custom control types. Build a phone number input, a rich address picker, a color swatch selector, or any UI widget your forms need — then distribute it as a reusable library that any form can use via its type string.
What Is a Field Library?
A field library is an npm package that implements one or more custom control types using the ControlPlugin / ReactControlPlugin interface. Once registered, the control appears in the Form Studio palette and can be dragged onto any form canvas.
The Three Components
Every custom control has up to three React components — one for each rendering context:
EditComponent
Interactive control for data entry. Renders in edit mode. Receives value, fires onChange and onBlur.
ViewComponent
Read-only display. Renders in view and preview mode. Formats the value for human reading.
DesignComponent
Palette thumbnail shown in Form Studio. Provides a static visual preview of the control without real data.
ControlPlugin vs ReactControlPlugin
| Interface | Provides | Use When |
|---|---|---|
ControlPlugin | Metadata only (type, label, group, icon, schema) | Registering a non-React custom control |
ReactControlPlugin | ControlPlugin + EditComponent + ViewComponent + DesignComponent | Standard React custom controls (most cases) |
Quick Example
// src/PhoneInput/index.ts
import type { ReactControlPlugin } from '@atlas-forms/types-js';
import { PhoneEditComponent } from './PhoneEditComponent';
import { PhoneViewComponent } from './PhoneViewComponent';
import { PhoneDesignComponent } from './PhoneDesignComponent';
export const phoneInputPlugin: ReactControlPlugin = {
type: 'myorg:phone-input',
label: 'Phone Number',
group: 'input',
icon: 'phone',
description: 'International phone number with country code picker',
defaultConfig: {
defaultCountry: 'US',
showFlag: true
},
EditComponent: PhoneEditComponent,
ViewComponent: PhoneViewComponent,
DesignComponent: PhoneDesignComponent,
};Minimum Viable Plugin
Only type, label, and EditComponent are strictly required. ViewComponent defaults to showing the raw value. DesignComponent defaults to a generic control tile.
Built-In Controls as Examples
The best reference for building custom controls is the Atlas Forms built-in control library at packages/controls-builtin-js/src/. Every built-in control follows the same ReactControlPlugin pattern you will use for your custom controls.
@atlas-forms/types-js and @atlas-forms/control-registry-js as peer dependencies.