SchemaForms Data
React library for schema-driven dynamic forms.
Build complex multi-step forms without repeating JSX. Define the form as a JSON object (FormSchema), render it with <FormRenderer>, and let users create schemas visually with the drag-and-drop builder.
What is SchemaForms Data?
SchemaForms Data separates form design from form rendering:
- Define the form as plain JSON (
FormSchema) - Render it with
<FormRenderer />— multi-step navigation, 30+ field types, validation, conditionals, file upload, ZIP-code lookup and much more - Edit schemas visually with
<BuilderWrapper />— drag-and-drop builder that generates the same JSON
A schema always follows the same hierarchy:
FormSchema
└── FormStep[]
└── FormContainer[]
└── FormField[]
Packages
| Package | Description |
|---|---|
@schema-forms-data/core | TypeScript types and enums — zero runtime dependencies |
@schema-forms-data/ui | Internal UI components (Radix UI + Tailwind) |
@schema-forms-data/templates | Visual templates (CSS vars) and preset blocks |
@schema-forms-data/renderer | <FormRenderer> — renders a schema as a form |
@schema-forms-data/builder | Drag-and-drop builder for visual schema creation |
@schema-forms-data/react | Meta-package re-exporting everything above |
Quick Start
Option A — Try without any setup (recommended)
Create a local Studio with builder + live preview in one command:
npx @schema-forms-data/create my-app
cd my-app
npm install
npm run dev
Open http://localhost:5173, drag fields to the canvas and copy the generated JSON. See the Studio guide.
Option B — Add to an existing project
# Everything at once (recommended)
npm install @schema-forms-data/react react-hook-form lucide-react
# Or only what you need
npm install @schema-forms-data/renderer react-hook-form lucide-react
npm install @schema-forms-data/builder @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
Key concepts
| Concept | Description |
|---|---|
FormSchema | JSON object that defines the entire form structure (steps → containers → fields) |
FieldType | Enum with 30+ field types (texto, select, file, field_array, sub_form, …) |
componentMapper | Map of custom React components per FieldType — replaces any default field |
validatorMapper | Map of async validation functions registered by type — referenced in the schema |
fieldResolvers | Dynamic props per field loaded at render time |
FormSpy / hooks | useFormApi(), useFormState(), useField(), useFieldApi() — form state access |
| Templates | Sets of CSS variables controlling colours, fonts and layout |
What comes out of the box
- ✅ 30+ field types — text, email, password, number, date, time, date range, select, autocomplete, radio, checkbox, switch, slider, rating, color picker, ZIP code, CPF, file, terms, field array, sub-form and more
- ✅ Multi-step navigation with animated progress indicator (wizard, tabs, vertical)
- ✅ Conditional visibility — per field and per container, with nested AND / OR groups
- ✅ Custom validators — sync and async, cross-field, via
validatorMapper - ✅ Non-blocking warnings (
warn[]) — messages that don’t block submission - ✅ Component Mapper — swap the default component for any field type
- ✅ Public hooks —
useFormApi,useFormState,useField,useFieldApi,<FormSpy> - ✅ Variable interpolation —
{{evento.nome}}in any label, title or hint - ✅ 20+ visual templates — ready-made styles: modern, minimalist, glassmorphism, corporate, etc.
- ✅ Visual builder — drag-and-drop, undo/redo, 12-column grid, field preset blocks
Peer dependencies
| Package | Usage |
|---|---|
react ^18 | Renderer and builder |
react-hook-form ^7 | Form engine for the renderer |
lucide-react | Icons in fields and builder |
@dnd-kit/core >=6 | Drag-and-drop in the builder |
@dnd-kit/sortable >=9 | Reordering in the builder |
@dnd-kit/utilities >=3 | DnD utilities in the builder |
Biblioteca React para formulários dinâmicos baseados em schema JSON.
Crie formulários complexos de múltiplos steps sem repetir JSX. Defina o formulário como um objeto JSON (FormSchema), renderize com <FormRenderer> e deixe usuários criarem schemas visualmente com o builder drag-and-drop.
O que é o SchemaForms?
O SchemaForms separa design do formulário de renderização do formulário:
- Defina o formulário como um JSON puro (
FormSchema) - Renderize com
<FormRenderer />— navegação multi-step, 30+ tipos de campo, validação, condicionais, upload de arquivos, busca de CEP e muito mais - Edite schemas visualmente com
<BuilderWrapper />— builder drag-and-drop que gera o mesmo JSON
A estrutura de um schema segue sempre a mesma hierarquia:
FormSchema
└── FormStep[]
└── FormContainer[]
└── FormField[]
Pacotes
| Pacote | Descrição |
|---|---|
@schema-forms-data/core | Tipos TypeScript e enums — zero dependências de runtime |
@schema-forms-data/ui | Componentes UI internos (Radix UI + Tailwind) |
@schema-forms-data/templates | Templates visuais (CSS vars) e preset blocks |
@schema-forms-data/renderer | <FormRenderer> — renderiza um schema como formulário |
@schema-forms-data/builder | Builder drag-and-drop para criação visual de schemas |
@schema-forms-data/react | Meta-pacote que re-exporta tudo acima |
Quick Start
Opção A — Testar sem configuração (recomendado para início)
Crie um Studio local com builder + preview em um comando:
npx @schema-forms-data/create my-app
cd my-app
npm install
npm run dev
Acesse http://localhost:5173, arraste campos para o canvas e copie o JSON gerado. Veja o guia do Studio.
Opção B — Adicionar a um projeto existente
# Tudo em um (recomendado)
npm install @schema-forms-data/react react-hook-form lucide-react
# Ou apenas o que você precisa
npm install @schema-forms-data/renderer react-hook-form lucide-react
npm install @schema-forms-data/builder @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
Conceitos principais
| Conceito | Descrição |
|---|---|
FormSchema | Objeto JSON que define toda a estrutura do formulário (steps → containers → fields) |
FieldType | Enum com 30+ tipos de campo (texto, select, file, field_array, sub_form, …) |
componentMapper | Mapa de componentes React customizados por FieldType — substitui qualquer campo padrão |
validatorMapper | Mapa de funções de validação async registradas por type — referenciadas no schema |
fieldResolvers | Props dinâmicas por campo carregadas em tempo de render |
FormSpy / hooks | useFormApi(), useFormState(), useField(), useFieldApi() — acesso ao estado do form |
| Templates | Conjuntos de CSS vars que controlam cores, fontes e layout |
O que vem pronto
- ✅ 30+ tipos de campo — texto, email, senha, número, data, hora, faixa de datas, select, autocomplete, radio, checkbox, switch, slider, rating, color picker, CEP, CPF, arquivo, termos, field array, sub-form e mais
- ✅ Navegação multi-step com indicador de progresso animado (wizard, tabs, vertical)
- ✅ Visibilidade condicional — por campo e por container, com grupos AND / OR aninhados
- ✅ Validadores customizados — síncronos e assíncronos, cross-field, via
validatorMapper - ✅ Avisos não-bloqueantes (
warn[]) — mensagens que não impedem o submit - ✅ Component Mapper — substitua o componente padrão de qualquer tipo de campo
- ✅ Hooks públicos —
useFormApi,useFormState,useField,useFieldApi,<FormSpy> - ✅ Interpolação de variáveis —
{{evento.nome}}em qualquer label, título ou hint - ✅ 20+ templates visuais — estilos prontos: moderno, minimalista, glassmorphism, corporativo, etc.
- ✅ Builder visual — drag-and-drop, undo/redo, grid de 12 colunas, preset blocks de campos
Dependências peer
| Pacote | Uso |
|---|---|
react ^18 | Renderer e builder |
react-hook-form ^7 | Engine de formulário do renderer |
lucide-react | Ícones nos campos e builder |
@dnd-kit/core >=6 | Drag-and-drop no builder |
@dnd-kit/sortable >=9 | Reordenação no builder |
@dnd-kit/utilities >=3 | Utilitários do DnD no builder |