---
title: "Dynamic Fields Field Selection Guide"
slug: "dynamic-fields-field-selection-guide"
description: "Guia para escolher o field certo em @praxisui/dynamic-fields, considerando UX, contrato, origem dos dados e extensao no host."
doc_type: "guide"
document_kind: "governance-reference"
component: "dynamic-fields"
category: "components"
audience:
  - "frontend"
  - "host"
  - "architect"
level: "intermediate"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-fields"
  - "decision guide"
  - "controlType"
  - "ux"
order: 35
icon: "rule"
toc: true
sidebar: true
search_boost: 1.08
reading_time: 16
estimated_setup_time: 20
version: "1.0"
related_docs:
  - "dynamic-fields-field-catalog"
  - "dynamic-fields-inventory"
  - "dynamic-fields-host-custom-field-guide"
  - "dynamic-fields-inline-filter-catalog"
  - "dynamic-fields-inline-components-guide"
keywords:
  - "choose field"
  - "select vs autocomplete"
  - "custom host field"
  - "inline filter"
last_updated: "2026-06-25"
---

# Dynamic Fields Field Selection Guide

## Objective

Escolher o `controlType` certo nao e apenas um detalhe visual. A decisao afeta:

- clareza de UX;
- shape do valor no contrato;
- performance do runtime;
- chance de hot update funcionar sem refresh estrutural;
- custo de manutencao no host.

## Fonte canonica para descoberta

Para decisao humana, este guia e o field catalog continuam sendo a referencia editorial principal.

Para descoberta operacional em landing pages, playgrounds e outros hosts oficiais, use o catalogo exportado por `@praxisui/dynamic-fields`. Ele centraliza `controlType`, trilha (`primary-form` ou `inline-filter`), categorias, `interactionPattern`, semantica de `icon`, estados relevantes, snippets e links oficiais, com validacao de paridade contra o runtime.

Regra pratica para hosts:

- use `interactionPattern` para comunicar como o field decide ou captura valor;
- use `dataSourceKind` para deixar claro se o caso e local, remoto, misto ou especializado;
- use `icon.key` e `icon.tone` apenas como projecao visual do catalogo canonico, nunca como regra inventada no host.

## Politica visual para labels, icones e prefixos

Campos Material com `appearance: 'fill'` ou `'outline'` e conteudo em
`matPrefix`/`matSuffix` precisam de cuidado especial. Isso inclui `prefixIcon`,
`suffixIcon`, `clearButton`, datepicker toggle, seletor de cor, simbolo de moeda
e controles equivalentes.

Para esses casos, use a configuracao canonica:

```json
{
  "materialDesign": {
    "floatLabel": "always",
    "subscriptSizing": "dynamic"
  }
}
```

Essa configuracao deve vir da metadata ou da politica global do host que gera os
campos, nao de CSS local. O Angular Material documenta que, em campos
`fill`/`outline`, prefixos/sufixos nao se alinham bem com labels em repouso; por
isso a recomendacao oficial e manter o label sempre flutuante nesses cenarios.

## 1. Texto livre vs selecao

### Use `input` / `textarea` quando

- o usuario realmente precisa escrever;
- o dominio aceita grande variacao lexical;
- nao existe catalogo confiavel de opcoes.

### Use `select` / `searchable-select` / `async-select` / `autoComplete` quando

- o valor deve vir de um conjunto governado;
- o backend precisa consistencia sem normalizacao extra;
- a opcao precisa carregar label + id de forma previsivel.

### Sinal de erro de escolha

Se o schema usa `input` para algo que depois exige validacao pesada, busca semantica ou reconciliacao contra catalogo, provavelmente deveria ser selecao.

## 2. Local vs remoto

| Scenario | Prefer | Why |
| --- | --- | --- |
| poucas opcoes estaveis | `select` | simples, previsivel, barato |
| lista media/grande com busca local | `searchable-select` | reduz carga visual |
| lista remota/paginada | `async-select` | evita preload caro |
| entidade de negocio remota com status, permissao, reidratacao ou dependencias | `entityLookup` | preserva identidade de entidade e usa contrato `RESOURCE_ENTITY` em vez de tratar entidade como opcao simples |
| busca incremental com semantica de sugestao | `autoComplete` | boa UX para descoberta |

### Promocao oficial de exemplos `entityLookup`

Um recurso so deve ser promovido como exemplo oficial de `entityLookup` quando
provar a cadeia completa de plataforma, nao apenas um dropdown remoto no host.

Checklist minimo para promocao:

- o backend publica o recurso com identidade canonica e `@ApiResource(resourceKey=...)`;
- `/schemas/filtered` entrega `x-ui.controlType = entityLookup` com `optionSource.type = RESOURCE_ENTITY`;
- `optionSource.resourcePath`, `valuePropertyPath`, `labelPropertyPath`, `searchPropertyPaths` e `display` explicam a entidade sem regra hardcoded no frontend;
- o recurso oferece busca paginada e reidratacao por ids (`filter` e `byIds`) para valores salvos;
- `selectionPolicy` documenta status, elegibilidade e preservacao de valor historico quando aplicavel;
- dependencias entre entidades usam `dependsOn` e `dependencyFilterMap`, sem inferencia por nome de campo no Angular;
- surfaces de detalhe sao publicadas pelo recurso quando `navigateToDetail` estiver habilitado;
- existe demo jogavel cobrindo campo de formulario e, quando o uso for filtro, `inlineEntityLookup`;
- existe teste focal ou e2e cobrindo busca, selecao, reidratacao e estado bloqueado/historico;
- a landing publica o exemplo como derivado da documentacao canonica, sem redefinir o contrato.

Exemplos oficiais atuais:

| Exemplo | Papel na plataforma | Status |
| --- | --- | --- |
| `human-resources.funcionarios` | referencia base de entidade humana reutilizavel em formularios, filtros e detalhes por surface | oficial para demonstrar `entityLookup` simples e `inlineEntityLookup` |
| `procurement.*` | demo enterprise com fornecedor, empresa, contrato, produto e pedido de compra dependentes | oficial como prova corporativa de dependencias e reidratacao |

Novos candidatos, como centros de custo, contratos, projetos ou ativos, devem
entrar por esse mesmo funil. Se o recurso ainda nao publica `byIds`,
`selectionPolicy` ou surface de detalhe, ele pode ser documentado como candidato,
mas nao como exemplo canonico completo.

## 3. Simples vs range

| Need | Prefer | Avoid |
| --- | --- | --- |
| um numero | `numericTextBox` | `rangeSlider` |
| um valor monetario | `currency` | `priceRange` |
| uma data | `date` | `dateRange` |
| uma hora | `time` ou `timePicker` | `timeRange` |
| faixa numerica | `rangeSlider` | dois `numericTextBox` desconectados |
| faixa monetaria | `priceRange` | dois `currency` soltos |
| faixa temporal | `dateRange` ou `timeRange` | dois campos sem semantica de range |
| lista repetivel de objetos | `array` | varios grupos duplicados manualmente |

## 4. Padrao vs custom host

### Fique no catalogo padrao quando

- o field ja esta registrado por default;
- a diferenca e apenas visual ou de metadata;
- o comportamento cabe em inputs/props do componente existente;
- o runtime ja cobre CVA, hot update e editor metadata.

### Crie field custom no host quando

- o dominio pede interacao especializada que nao cabe no catalogo;
- o componente precisa de semantica propria no editor;
- o contrato precisa de `controlType` exclusivo e governado pelo host.

Antes de criar, consulte [Dynamic Fields Host Custom Field Guide](./dynamic-fields-host-custom-field-guide.md).

## 5. Form field vs inline filter field

Nao misture as duas narrativas:

- formulario comum: use `input`, `select`, `date`, `upload`, `toggle`, etc.;
- filtro inline compacto: use `inline*` apenas em trilhas de filtro.

Se o caso e filtro corporativo compacto, consulte:

- [Dynamic Fields Inline Filter Catalog](./dynamic-fields-inline-filter-catalog.md)
- [Dynamic Fields Inline Components Guide](./dynamic-fields-inline-components-guide.md)

## 6. Presentation mode vs chart widget

`presentation.presenter = 'microVisualization'` nao e um `controlType`. Use esse presenter quando o campo ja tem valor no `FormControl`, mas a surface readonly precisa mostrar um indicador compacto e escaneavel.

Use `microVisualization` quando:

- a surface e `form-presentation`, `table-cell`, `list-item`, `object-header` ou `card-summary`;
- a leitura precisa caber em celula, linha, drawer ou detalhe compacto;
- o indicador e pequeno, como `comparison`, `stackedBar`, `bullet` ou `delta`;
- a mesma semantica deve ser dirigida por `presentationRules` e Json Logic sem mutar o valor do campo.

Use `@praxisui/charts` quando:

- o usuario precisa interagir com grafico, legenda, tooltip analitico ou drilldown;
- o grafico ocupa card, dashboard, cockpit ou modal dedicado;
- a visualizacao depende de series maiores, eixos, zoom ou agregacoes vindas de endpoint analitico.

Use `rich-content` quando:

- o bloco mistura timeline, record summary, property sheet, progresso, badges e textos;
- a surface de detalhe precisa composicao editorial, nao apenas um valor de campo.

## 7. Decision table

| Question | Prefer |
| --- | --- |
| o usuario escreve texto curto? | `input` |
| o usuario escreve texto longo? | `textarea` |
| o usuario escolhe 1 opcao de lista pequena? | `select` |
| o usuario escolhe 1 opcao de lista grande? | `searchable-select` |
| a lista vem do backend sob demanda? | `async-select` |
| o usuario escolhe entidade real do dominio? | `entityLookup` |
| a UX parece busca com sugestoes? | `autoComplete` |
| o valor e monetario? | `currency` / `priceRange` |
| o valor e data? | `date` / `dateRange` |
| o valor e horario? | `time` / `timePicker` / `timeRange` |
| o padrao e lookup governado com busca? | `entityLookup` quando houver identidade/status/politica; `searchable-select` / `async-select` / `autoComplete` para opcoes simples |
| o padrao e range com semantica propria? | `priceRange` / `dateRange` / `timeRange` / `inlineDateRange` |
| o padrao e visual semantico? | `rating` / `inlinePipelineStatus` / `inlineSentiment` / `inlineColorLabel` |
| o valor e booleano? | `toggle` |
| a escolha unica precisa ser muito explicita? | `radio` ou `buttonToggle` |
| ha multiplas escolhas discretas? | `checkbox` ou `multiSelect` |
| ha hierarquia? | `treeSelect` / `multiSelectTree` |
| ha uma colecao repetivel de objetos? | `array` |
| ha anexos? | `upload` |
| o controle e acao, nao dado? | `button` |
| o valor readonly precisa de indicador compacto em celula/lista/formulario? | `presentation.presenter = "microVisualization"` |
| nada do catalogo resolve sem gambiarra? | field custom do host |

## 8. Enterprise recommendations

- prefira nomes canonicos de `controlType`; deixe aliases apenas para compatibilidade;
- nao use inline filter controls em formularios normais para “economizar espaco”;
- nao crie `controlType` local para indicadores readonly; use `presentation.presenter` e `presentation.visualization` quando a semantica for de apresentacao;
- para campos remotos, explicite origem de dados e comportamento de busca;
- para entidades de negocio, use `entityLookup` com `optionSource.type = RESOURCE_ENTITY`, `byIds`, `dependsOn`, `dependencyFilterMap` e `selectionPolicy` quando a selecao depender de status, permissao ou contexto;
- para colecoes repetiveis, use `array` com `array.itemSchema.fields` em vez de criar campos numerados como `item1`, `item2`, `item3`;
- para custom fields, alinhe runtime registry + metadata registry + hot update desde o inicio.

## Nota de governanca para hosts

Se um host precisar montar vitrine, filtros ou snippets jogaveis, derive isso do catalogo exportado da lib em vez de manter listas autorais locais.

Isso inclui explicitamente:

- cues de decisao;
- navegacao por tipo de interacao;
- iconografia de cards e menus;
- agrupamentos por track/family para descoberta operacional.