Pular para o conteúdo principal

SchemaForms

Criador e renderizador de formulários orientado a schema para React.

Crie formulários complexos com múltiplos passos sem escrever JSX repetitivo. Defina seu formulário como um schema JSON, renderize com <FormRenderer> e deixe os usuários criarem schemas visualmente com <BuilderProvider>.

O que é o SchemaForms?​

O SchemaForms separa o design do formulário da sua renderização:

  • Defina seu formulário como um objeto JSON (FormSchema)
  • Renderize com <FormRenderer /> — navegação multi-step, 30+ tipos de campo, validação, condicionais, upload de arquivo, busca de CEP e muito mais
  • Edite schemas visualmente com <BuilderProvider /> — editor drag-and-drop que gera o mesmo JSON

Pacotes​

PacoteDescrição
@schema-forms-data/coreTipos TypeScript e enums — zero dependências
@schema-forms-data/templatesTemas visuais (CSS vars) e blocos de campos pré-prontos
@schema-forms-data/renderer<FormRenderer> — renderiza um schema como formulário
@schema-forms-data/builder<BuilderProvider> — editor drag-and-drop de schemas
@schema-forms-data/reactMeta-pacote que re-exporta todos os anteriores
@schema-forms-data/createCLI scaffold — app Studio via npx @schema-forms-data/create

Início Rápido​

Opção A — Experimente instantaneamente (sem configuração)​

Crie um SchemaForms Studio local — builder + visualizador JSON + preview ao vivo:

npx @schema-forms-data/create meu-app
cd meu-app
npm install
npm run dev

Abra http://localhost:5173, arraste campos para o canvas e copie o JSON gerado. Veja o guia do Studio para mais detalhes.

Opção B — Adicionar a um projeto existente​

# Tudo em um (recomendado)
npm install @schema-forms-data/react react-hook-form lucide-react

# Ou somente o que precisar
npm install @schema-forms-data/renderer react-hook-form lucide-react
npm install @schema-forms-data/builder react-hook-form lucide-react

Conceitos-chave​

ConceitoDescrição
FormSchemaDocumento JSON que define o formulário inteiro (steps → containers → fields)
FieldTypeEnum com 30+ tipos de campo (texto, select, file, field_array, sub_form, …)
RendererContextContexto injetável para integrações (uploadFile, cepLookup, validatorMapper, componentMapper, …)
componentMapperMapa de componentes React personalizado por FieldType — substitui qualquer campo built-in
validatorMapperMapa de funções validadoras assíncrona por type — usado em validate[] e warn[]
FormSpy / hooksuseFormApi(), useFormState(), useField(), useFieldApi() — acessa o estado do formulário em qualquer filho
TemplatesConjuntos de variáveis CSS que controlam cores, fontes e layout

O que vem incluído​

  • ✅ 30+ tipos de campo — texto, email, senha, número, data, hora, intervalo de datas, select, autocomplete, radio, checkbox, switch, slider, avaliação, color picker, CEP, CPF, arquivo, termos, array de campos, sub-formulário e mais
  • ✅ Navegação multi-step com indicador de progresso animado
  • ✅ Visibilidade condicional — por campo e por container, com grupos AND/OR
  • ✅ Validators customizados — síncronos e assíncronos, cross-field, registrados via validatorMapper
  • ✅ Avisos (warn[]) — mensagens informativas que não bloqueiam o envio
  • ✅ Component Mapper — substitui o componente built-in de qualquer tipo de campo
  • ✅ Hooks públicos — useFormApi, useFormState, useField, useFieldApi, <FormSpy>
  • ✅ Template vars — {{evento.nome}} em qualquer label, título ou hint
  • ✅ Builder visual — drag-and-drop, undo/redo, grade de 12 colunas, blocos pré-prontos