> For the complete documentation index, see [llms.txt](https://docs.hablla.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hablla.com/hablla/marketing/formulario.md).

# Formulário

Os **Formulários da Hablla** permitem criar interfaces de captura de dados por **arrastar e soltar** (drag-and-drop).\
Você monta o layout, configura cada campo e publica para uso em páginas, fluxos e integrações.

> **Como funciona:** escolha os componentes, arraste para a área de edição e ajuste as propriedades nas abas de configuração de cada campo.

<figure><img src="/files/JkYDOsljgHXyWjX8JtMP" alt=""><figcaption></figcaption></figure>

### Biblioteca de componentes

#### Basic

* **Text Field**: campo de texto curto (ex.: nome).
* **Text Area**: texto longo (observações).
* **Number**: números inteiros/decimais.
* **Password**: senha (oculta).
* **Checkbox**: verdadeiro/falso.
* **Select Boxes**: múltipla seleção por checkboxes.
* **Select**: lista suspensa (uma opção).
* **Radio**: seleção única por botões de rádio.
* **Button**: botões de ação (Enviar, Voltar etc.).

<figure><img src="/files/Cv4zom9scsMfgkd3AARs" alt=""><figcaption></figcaption></figure>

#### Advanced

* **Email** • **Url** • **Phone Number**
* **Tags**: múltiplos valores com chips.
* **Address**: endereço estruturado.
* **Date/Time** • **Day** • **Time**
* **Currency**: valores monetários.
* **Survey**: matriz de perguntas.
* **Signature**: assinatura digital.

<figure><img src="/files/vt1uTcvaogfIjsXeipJH" alt=""><figcaption></figcaption></figure>

#### Layout

* **HTML Element**: bloco HTML livre.
* **Content**: texto estático/MD.
* **Columns**: colunas responsivas.
* **Field Set** • **Panel**: agrupar campos.
* **Table**: grade tabular simples.
* **Tabs**: navegação por abas.
* **Well**: caixa de destaque.

<figure><img src="/files/I5yGTjwa2qfRilAL5w99" alt=""><figcaption></figcaption></figure>

#### Data

* **Hidden**: valor oculto (ex.: UTM).
* **Container**: objeto com subcampos.
* **Data Map**: pares chave/valor dinâmicos.
* **Data Grid / Edit Grid**: listas editáveis (linhas repetíveis).

<figure><img src="/files/v7F3sAzDUcM7W7jvezem" alt=""><figcaption></figcaption></figure>

#### Premium

* **File**: upload de arquivos.
* **Nested Form**: reaproveitar outro formulário.
* **Custom**: componente de lógica própria.

<figure><img src="/files/cOCU3LzmyhZ332wI393k" alt=""><figcaption></figcaption></figure>

***

### Configuração de cada campo

Cada componente possui abas de configuração. As mais usadas:

* **Display (Exibição)**\
  Rótulo, placeholder, ajuda (tooltip), posição do rótulo, máscara de entrada e de exibição, CSS de classe, visibilidade.
* **Data (Dados)**\
  Chave interna (`key`), valor padrão, fonte de dados (estático, remoto), mapa de valor/rótulo, persistência.
* **Validation (Validação)**\
  Obrigatoriedade, tamanho mínimo/máximo, regex, limites numéricos, mensagens de erro personalizadas.
* **API**\
  Nome de propriedade, referência para integrações e webhooks.
* **Conditional (Condição)**\
  Mostrar/ocultar baseado em regras (ex.: “mostrar *Telefone* se *Receber contato por WhatsApp* = Sim”).
* **Logic (Lógica)**\
  Ações ao mudar o valor (preencher automático, copiar de outro campo, executar expressão).
* **Layout**\
  Colunas, largura, responsividade e agrupamentos.

> **Dica:** defina `Label` (o que o usuário vê) e `Key` (o identificador técnico) com nomes claros. Ex.: `Label: Nome`, `Key: nome`.

***

### Exemplo: campo **Nome** (JSON)

Abaixo um exemplo minimalista de um **Text Field** para capturar o nome do contato.\
Você pode copiar, adaptar e reutilizar.

```json
{
  "label": "Nome",
  "placeholder": "Digite seu nome completo",
  "description": "Informe como deseja ser chamado.",
  "tooltip": "Use apenas letras e espaços.",
  "type": "textfield",
  "key": "nome",
  "autocomplete": "name",
  "input": true,
  "validate": {
    "required": true,
    "minLength": 2,
    "maxLength": 120,
    "pattern": "^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$",
    "customMessage": "Digite um nome válido (apenas letras)."
  },
  "widget": {
    "type": "input"
  },
  "persistent": true,
  "clearOnHide": true,
  "hidden": false
}
```

### Melhores práticas

1. **Padronize chaves (`key`)**\
   Use `camelCase` ou `snake_case` e evite espaços (ex.: `telefoneWhatsApp`, `aceiteTermos`).
2. **Valide na borda**\
   Aplique validações (regex, min/max, required) para reduzir dados inválidos e retrabalho.
3. **Use máscaras quando fizer sentido**\
   Ex.: telefone, CPF/CNPJ, CEP. Máscara orienta o preenchimento e reduz erros.
4. **Agrupe o que pertence junto**\
   Use **Panels**, **Field Sets** ou **Tabs** para tornar o formulário escaneável.
5. **Condições deixam o fluxo inteligente**\
   Exiba campos apenas quando forem relevantes para reduzir atrito.
6. **Teste em dispositivos reais**\
   Verifique responsividade e acessibilidade (teclado, leitores de tela, contraste).

***

### Publicação e uso

* **Salvar e pré-visualizar:** confira erros de validação e responsividade.
* **Integrar em fluxos:** use o formulário para capturar leads, abrir tickets, alimentar Pessoas/Organizações ou disparar automações.
* **Exportar envios:** combine com relatórios para analisar conversões e qualidade de dados.

***

### Resumo

* Monte formulários por **arrastar e soltar**.
* Configure cada campo pelas abas **Display, Data, Validation, API, Conditional, Logic, Layout**.
* Padronize chaves, valide entradas e use condições para **experiências mais rápidas e assertivas**.

📌 **Dica prática:** comece pequeno (Nome, Email, WhatsApp), valide os campos, publique, e só então evolua o formulário com grupos, lógicas e grids conforme o caso de uso.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hablla.com/hablla/marketing/formulario.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.