---
title: "Dynamic Fields Field Catalog"
slug: "dynamic-fields-field-catalog"
description: "Catalogo principal dos fields padrao registrados em @praxisui/dynamic-fields para formularios metadata-driven."
doc_type: "reference"
document_kind: "governance-reference"
component: "dynamic-fields"
category: "components"
audience:
  - "frontend"
  - "host"
  - "architect"
level: "intermediate"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-fields"
  - "catalog"
  - "controlType"
  - "forms"
order: 34
icon: "toc"
toc: true
sidebar: true
search_boost: 1.05
reading_time: 24
estimated_setup_time: 30
version: "1.0"
related_docs:
  - "dynamic-fields-inventory"
  - "dynamic-fields-field-selection-guide"
  - "dynamic-fields-host-custom-field-guide"
  - "dynamic-fields-inline-filter-catalog"
keywords:
  - "field catalog"
  - "which field to use"
  - "controlType"
  - "metadata snippet"
last_updated: "2026-03-26"
---

# Dynamic Fields Field Catalog

## Overview

Este catalogo cobre os fields padrao registrados por default para formularios dinamicos comuns.

Nao entram aqui:

- aliases de compatibilidade (`dateTime`, `treeView`);
- fields inline especializados de filtro.

Para auditoria completa do runtime, consulte [Dynamic Fields Inventory](./dynamic-fields-inventory.md). Para inline filter controls, consulte [Dynamic Fields Inline Filter Catalog](./dynamic-fields-inline-filter-catalog.md).

## Published surface for hosts

Este markdown continua sendo a referencia governada de narrativa, recomendacoes de uso e snippets curtos.

Para consumo operacional por hosts oficiais, a superficie canonica e o catalogo exportado pela lib em `src/lib/catalog/dynamic-fields-playground.catalog.ts`, reexportado pelo `public-api` de `@praxisui/dynamic-fields`.

Regra de uso:

- host, landing e playground consomem o catalogo exportado;
- este documento explica quando usar, quando evitar e para onde navegar;
- mudancas de runtime ou descoberta devem nascer primeiro na lib canonica, nao em listas locais do host.

## Canonical editorial source

Para os controls ja cobertos pela trilha editorial/i18n canonica, este catalogo nao e a fonte primaria de `friendlyName`, `description` ou `icon`.

Regra de governanca:

- descriptor em `src/lib/editorial/**`: fonte canonica da semantica editorial;
- `ComponentDocMeta`: artefato derivado da mesma semantica para builders/registry;
- catalogo playground/showcase: artefato derivado para discovery e narrativa de uso;
- `dynamic-form`: consumidor do resolver canonico, sem mapa editorial local.

Se um novo field precisar entrar neste catalogo com copy governada, ele deve primeiro entrar na trilha canonica da lib. Nao e aceitavel publicar copy nova apenas aqui.

## How to read this catalog

- `quando usar`: caso de uso preferencial;
- `quando evitar`: quando outro field entrega UX melhor;
- `valor esperado`: shape mental do valor no form;
- `snippet`: exemplo curto de metadata, focado no `controlType`.

## Published discovery semantics

O catalogo exportado por `@praxisui/dynamic-fields` agora publica semantica de descoberta para hosts oficiais:

- `track`: separa `primary-form` de `inline-filter`;
- `family`: agrupa a taxonomia funcional do field;
- `interactionPattern`: resume o padrao dominante de uso, como `single-value`, `lookup`, `range`, `visual` ou `trigger`;
- `icon.key` + `icon.tone`: entregam identidade visual canonica para menus, vitrines e playgrounds.

Regra editorial:

- este markdown continua explicando `quando usar` e `quando evitar`;
- landing, playground e outros hosts devem derivar navegacao, cues e mini-cards do catalogo exportado da lib;
- a documentacao nao deve manter uma tabela paralela de icones ou interaction patterns fora da fonte canonica.

## Texto

| Field          | controlType                                   | Quando usar                  | Quando evitar                        | Valor esperado | Snippet                                               | Detail doc                                |
| -------------- | --------------------------------------------- | ---------------------------- | ------------------------------------ | -------------- | ----------------------------------------------------- | ----------------------------------------- |
| Text input     | <span id="input"></span>`input`               | texto livre curto            | quando ha formato fechado            | `string`       | `{ name: 'fullName', controlType: 'input' }`          | `pdx-text-input.json-api.md`              |
| Email input    | <span id="email"></span>`email`               | email validado               | se o campo aceita qualquer texto     | `string`       | `{ name: 'email', controlType: 'email' }`             | `pdx-email-input.json-api.md`             |
| Password input | <span id="password"></span>`password`         | segredo/senha                | quando o valor precisa ficar legivel | `string`       | `{ name: 'password', controlType: 'password' }`       | `pdx-password-input.json-api.md`          |
| Textarea       | <span id="textarea"></span>`textarea`         | descricao longa, observacoes | conteudo curto de uma linha          | `string`       | `{ name: 'notes', controlType: 'textarea', rows: 4 }` | `pdx-material-textarea.json-api.md`       |
| Search input   | <span id="search"></span>`search`             | busca textual dedicada       | entrada comum sem semantica de busca | `string`       | `{ name: 'query', controlType: 'search' }`            | `pdx-search-input.json-api.md`            |
| Phone input    | <span id="phone"></span>`phone`               | telefone                     | se o dominio nao usa telefone        | `string`       | `{ name: 'phone', controlType: 'phone' }`             | `pdx-phone-input.json-api.md`             |
| URL input      | <span id="url"></span>`url`                   | links/URLs                   | strings livres sem validacao de URL  | `string`       | `{ name: 'website', controlType: 'url' }`             | `pdx-url-input.json-api.md`               |
| CPF/CNPJ input | <span id="cpfcnpjinput"></span>`cpfCnpjInput` | documento brasileiro         | dominio internacional/generalista    | `string`       | `{ name: 'document', controlType: 'cpfCnpjInput' }`   | `pdx-material-cpf-cnpj-input.json-api.md` |

## Numero, moeda e range

| Field          | controlType                                       | Quando usar                                                                           | Quando evitar                        | Valor esperado  | Snippet                                                                                            | Detail doc                              |
| -------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------ | --------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------- |
| Number input   | <span id="numerictextbox"></span>`numericTextBox` | numero simples                                                                        | intervalo guiado por slider          | `number`        | `{ name: 'age', controlType: 'numericTextBox' }`                                                   | `pdx-number-input.json-api.md`          |
| Currency input | <span id="currency"></span>`currency`             | valor monetario unico                                                                 | faixa monetaria                      | `number`        | `{ name: 'budget', controlType: 'currency' }`                                                      | `pdx-material-currency.json-api.md`     |
| Slider         | <span id="slider"></span>`slider`                 | valor unico em faixa continua, com marks, value label, bandas semanticas e histograma responsivo ao valor | campos financeiros complexos         | `number`        | `{ name: 'score', controlType: 'slider', min: 0, max: 10, valueLabelDisplay: 'on' }`               | `pdx-material-slider.json-api.md`       |
| Range slider   | <span id="rangeslider"></span>`rangeSlider`       | faixa numerica com marks, inputs opcionais, distancia min/max, bandas e distribuicao responsiva ao range  | datas/horarios                       | `{ start,end }` | `{ name: 'range', controlType: 'rangeSlider', mode: 'range', min: 0, max: 100, showInputs: true }` | `pdx-material-range-slider.json-api.md` |
| Price range    | <span id="pricerange"></span>`priceRange`         | faixa monetaria                                                                       | uma moeda unica                      | `{ min,max }`   | `{ name: 'priceBand', controlType: 'priceRange' }`                                                 | `pdx-material-price-range.json-api.md`  |
| Rating         | <span id="rating"></span>`rating`                 | nota/avaliacao visual                                                                 | quando precisao numerica e dominante | `number`        | `{ name: 'satisfaction', controlType: 'rating' }`                                                  | `pdx-material-rating.json-api.md`       |

### Contrato de preview do catalogo jogavel

`previewRecipe.presets[].initialValue` define a semente padrao do preset apos aplicar o metadata do estado ativo. Quando um preset precisa que um estado especifico tenha valor proprio, use `previewRecipe.presets[].stateInitialValues`.

Precedencia da semente no playground:

1. `preset.stateInitialValues[state]`
2. `state.initialValue`
3. `preset.initialValue`
4. `defaultState.initialValue`
5. fallback gerado pelo runtime do playground

Use `stateInitialValues` apenas quando o valor do preset precisa continuar coerente com a semantica daquele estado, como `Currency + Filled` em `rangeSlider`.

## Data e tempo

| Field          | controlType                                     | Quando usar                   | Quando evitar                                   | Valor esperado          | Snippet                                                 | Detail doc                             |
| -------------- | ----------------------------------------------- | ----------------------------- | ----------------------------------------------- | ----------------------- | ------------------------------------------------------- | -------------------------------------- |
| Date input     | <span id="dateinput"></span>`dateInput`         | integracao com input nativo   | quando o host precisa UX Material forte         | `string \| Date`        | `{ name: 'birthDate', controlType: 'dateInput' }`       | `pdx-date-input.json-api.md`           |
| Date picker    | <span id="date"></span>`date`                   | selecao de data no formulario | se o fluxo pede intervalo                       | `Date \| string`        | `{ name: 'startDate', controlType: 'date' }`            | `pdx-material-datepicker.json-api.md`  |
| Date range     | <span id="daterange"></span>`dateRange`         | intervalo de datas            | data unica                                      | `{ startDate,endDate }` | `{ name: 'period', controlType: 'dateRange' }`          | `pdx-material-date-range.json-api.md`  |
| Datetime local | <span id="datetimelocal"></span>`dateTimeLocal` | data + hora local em um campo | quando o fluxo precisa seletor dedicado de hora | `string`                | `{ name: 'appointment', controlType: 'dateTimeLocal' }` | `pdx-datetime-local-input.json-api.md` |
| Month input    | <span id="month"></span>`month`                 | mes/ano                       | datas completas                                 | `string`                | `{ name: 'competence', controlType: 'month' }`          | `pdx-month-input.json-api.md`          |
| Time input     | <span id="time"></span>`time`                   | hora simples                  | intervalo de horario                            | `string`                | `{ name: 'startAt', controlType: 'time' }`              | `pdx-time-input.json-api.md`           |
| Time picker    | <span id="timepicker"></span>`timePicker`       | seletor de horario Material   | campo simples sem picker                        | `string`                | `{ name: 'slot', controlType: 'timePicker' }`           | `pdx-material-timepicker.json-api.md`  |
| Time range     | <span id="timerange"></span>`timeRange`         | janela de horario             | apenas uma hora                                 | `{ start,end }`         | `{ name: 'window', controlType: 'timeRange' }`          | `pdx-material-time-range.json-api.md`  |
| Week input     | <span id="week"></span>`week`                   | semana ISO                    | quando o negocio trabalha por data convencional | `string`                | `{ name: 'weekRef', controlType: 'week' }`              | `pdx-week-input.json-api.md`           |
| Year input     | <span id="year"></span>`year`                   | ano isolado                   | mes/ano ou data completa                        | `number \| string`      | `{ name: 'fiscalYear', controlType: 'year' }`           | `pdx-year-input.json-api.md`           |

## Selecao

| Field             | controlType                                             | Quando usar                                                                    | Quando evitar                                              | Valor esperado               | Snippet                                                                                                            | Detail doc                                   |
| ----------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| Select            | <span id="select"></span>`select`                       | lista fechada simples                                                          | bases muito grandes sem busca                              | `string \| number \| object` | `{ name: 'status', controlType: 'select', options: [...] }`                                                        | `pdx-material-select.json-api.md`            |
| Searchable select | <span id="searchable-select"></span>`searchable-select` | lista maior com busca                                                          | consultas remotas pesadas                                  | `string \| number \| object` | `{ name: 'department', controlType: 'searchable-select' }`                                                         | `pdx-material-searchable-select.json-api.md` |
| Async select      | <span id="async-select"></span>`async-select`           | opcoes remotas                                                                 | lista pequena local                                        | `string \| number \| object` | `{ name: 'city', controlType: 'async-select', resourcePath: 'cities' }`                                            | `pdx-material-async-select.json-api.md`      |
| Entity lookup     | <span id="entitylookup"></span>`entityLookup`           | entidade corporativa com identidade, status, reidratacao e politica de selecao | opcoes simples sem semantica de entidade                   | `entity id \| EntityRef`     | `{ name: 'supplierId', controlType: 'entityLookup', optionSource: { key: 'suppliers', type: 'RESOURCE_ENTITY' } }` | `pdx-inline-entity-lookup.json-api.md`       |
| Autocomplete      | <span id="autocomplete"></span>`autoComplete`           | busca progressiva com sugestoes                                                | quando o usuario deve escolher so de lista fechada simples | `string \| number \| object` | `{ name: 'role', controlType: 'autoComplete' }`                                                                    | `pdx-material-autocomplete.json-api.md`      |
| Multi select      | <span id="multiselect"></span>`multiSelect`             | multiplas escolhas                                                             | se o usuario so pode escolher uma opcao                    | `unknown[]`                  | `{ name: 'tags', controlType: 'multiSelect' }`                                                                     | `pdx-material-multi-select.json-api.md`      |

## Arvores e listas

| Field               | controlType                                         | Quando usar                                              | Quando evitar                                   | Valor esperado                   | Snippet                                                                                | Detail doc                                   |
| ------------------- | --------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------- |
| Multi select tree   | <span id="multiselecttree"></span>`multiSelectTree` | hierarquia com multiplas selecoes                        | lista plana pequena                             | `unknown[]`                      | `{ name: 'permissions', controlType: 'multiSelectTree' }`                              | `pdx-material-multi-select-tree.json-api.md` |
| Tree select         | <span id="treeselect"></span>`treeSelect`           | hierarquia com selecao simples                           | multiplas selecoes                              | `string \| number \| object`     | `{ name: 'category', controlType: 'treeSelect' }`                                      | `pdx-material-tree-select.json-api.md`       |
| Editable collection | <span id="array"></span>`array`                     | lista repetivel de objetos com subcampos metadata-driven | uma entidade unica ou selecao simples de opcoes | `Array<Record<string, unknown>>` | `{ name: 'contacts', controlType: 'array', array: { itemSchema: { fields: [...] } } }` | `pdx-editable-collection`                    |
| Selection list      | <span id="selectionlist"></span>`selectionList`     | lista grande com affordance de lista                     | layouts que pedem dropdown compacto             | `unknown[]`                      | `{ name: 'channels', controlType: 'selectionList' }`                                   | `pdx-material-selection-list.json-api.md`    |
| Transfer list       | <span id="transferlist"></span>`transferList`       | mover itens entre disponivel/selecionado                 | selecoes simples                                | `unknown[]`                      | `{ name: 'members', controlType: 'transferList' }`                                     | `pdx-material-transfer-list.json-api.md`     |
| Chip input          | <span id="chipinput"></span>`chipInput`             | lista textual editavel                                   | se ordem/edicao nao importam                    | `string[]`                       | `{ name: 'emails', controlType: 'chipInput' }`                                         | `pdx-material-chips.json-api.md`             |
| Chip list           | <span id="chiplist"></span>`chipList`               | exibicao/edicao em chips                                 | entrada de valor unico                          | `string[]`                       | `{ name: 'labels', controlType: 'chipList' }`                                          | `pdx-material-chips.json-api.md`             |

## Toggle e choice

| Field         | controlType                                   | Quando usar                                                                                           | Quando evitar                                    | Valor esperado                | Snippet                                                                         | Detail doc                                |
| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------- |
| Checkbox      | <span id="checkbox"></span>`checkbox`         | booleano simples com `selectionMode: 'boolean'` ou múltiplas escolhas com `selectionMode: 'multiple'`; em migrações, flags `S`/`N` e `1`/`0` são normalizadas no modo booleano | contrato novo sem `selectionMode`; escolha única | `boolean \| unknown[]`        | `{ name: 'privacyConsent', controlType: 'checkbox', selectionMode: 'boolean' }` | `pdx-material-checkbox-group.json-api.md` |
| Radio group   | <span id="radio"></span>`radio`               | escolha unica explicita com `selectionMode: 'single'`                                                 | muitas opcoes/espaco restrito                    | `string \| number \| boolean` | `{ name: 'priority', controlType: 'radio', selectionMode: 'single' }`           | `pdx-material-radio-group.json-api.md`    |
| Toggle        | <span id="toggle"></span>`toggle`             | booleano binario                                                                                      | multiplos estados                                | `boolean`                     | `{ name: 'active', controlType: 'toggle' }`                                     | `pdx-material-slide-toggle.json-api.md`   |
| Button toggle | <span id="buttontoggle"></span>`buttonToggle` | escolha segmentada curta                                                                              | listas longas                                    | `string \| number`            | `{ name: 'mode', controlType: 'buttonToggle' }`                                 | `pdx-material-button-toggle.json-api.md`  |

## Upload

| Field       | controlType                       | Quando usar         | Quando evitar                    | Valor esperado               | Snippet                                         | Detail doc                             |
| ----------- | --------------------------------- | ------------------- | -------------------------------- | ---------------------------- | ----------------------------------------------- | -------------------------------------- |
| File upload | <span id="upload"></span>`upload` | anexos, documentos e escolha local de imagem com preview | quando o fluxo nao exige arquivo ou exige persistencia operacional completa sem `@praxisui/files-upload` | `File \| File[] \| metadata` | `{ name: 'attachment', controlType: 'upload', accept: 'image/*', imagePreview: true }` | `pdx-material-file-upload.json-api.md` |

## Cor

| Field        | controlType                                 | Quando usar                   | Quando evitar             | Valor esperado | Snippet                                          | Detail doc                     |
| ------------ | ------------------------------------------- | ----------------------------- | ------------------------- | -------------- | ------------------------------------------------ | ------------------------------ |
| Color input  | <span id="color"></span>`color`             | cor simples por valor textual | UX rica de paleta         | `string`       | `{ name: 'brandColor', controlType: 'color' }`   | `pdx-color-input.json-api.md`  |
| Color picker | <span id="colorpicker"></span>`colorPicker` | paleta, presets, selecao rica | entrada rapida sem picker | `string`       | `{ name: 'accent', controlType: 'colorPicker' }` | `pdx-color-picker.json-api.md` |

## Visual e acao

| Field        | controlType                                 | Quando usar                              | Quando evitar                  | Valor esperado     | Snippet                                                                          | Detail doc                        |
| ------------ | ------------------------------------------- | ---------------------------------------- | ------------------------------ | ------------------ | -------------------------------------------------------------------------------- | --------------------------------- |
| Avatar       | <span id="avatar"></span>`avatar`           | representacao visual de usuario/entidade | captura de dado textual        | `string \| object` | `{ name: 'ownerAvatar', controlType: 'avatar' }`                                 | `pdx-material-avatar.json-api.md` |
| Button       | <span id="button"></span>`button`           | acao auxiliar dentro do layout           | submit/cancel padrao do form   | n/a                | `{ name: 'validateBtn', controlType: 'button', action: 'validateCustomerData' }` | `pdx-material-button.json-api.md` |
| Cron builder | <span id="cronbuilder"></span>`cronBuilder` | agenda/expressao cron                    | datas simples ou ranges comuns | `string`           | `{ name: 'schedule', controlType: 'cronBuilder' }`                               | `@praxisui/cron-builder`          |

## Notes for enterprise use

- prefira `select`/`searchable-select`/`async-select` conforme o tamanho e a origem dos dados;
- prefira `entityLookup` quando o valor representa uma entidade real do dominio e precisa de `RESOURCE_ENTITY`, reidratacao por id, status, permissao de selecao ou dependencias;
- prefira `array` quando o usuario precisa editar uma colecao repetivel de objetos, como contatos, linhas de pedido ou itens de contrato;
- prefira `date` sobre `dateInput` quando o design system precisa consistencia Material;
- trate `button`, `avatar` e `cronBuilder` como controls especializados, nao como default;
- para trilha de filtros compactos, use o catalogo separado de inline filters;
- para vitrine jogavel e descoberta entre squads, prefira derivar categorias, tags, snippets, `interactionPattern` e `icon` a partir do catalogo exportado da lib.