---
title: "Dynamic Fields Inline Filter Catalog"
slug: "dynamic-fields-inline-filter-catalog"
description: "Catalogo especializado dos inline filter components do dynamic-fields, com criterios de uso, shape de valor e notas de UX para a trilha de filtro em table."
doc_type: "reference"
document_kind: "host-guide"
component: "dynamic-fields"
category: "components"
audience:
  - "frontend"
  - "host"
  - "designer"
  - "architect"
level: "advanced"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-fields"
  - "dynamic-filter"
  - "inline"
  - "catalog"
order: 42
icon: "view_compact_alt"
toc: true
sidebar: true
search_boost: 1.2
reading_time: 24
estimated_setup_time: 25
version: "1.0"
related_docs:
  - "dynamic-fields-inline-filter-selection-guide"
  - "dynamic-fields-inline-filter-runtime-contract"
  - "dynamic-fields-inline-filter-custom-component-guide"
  - "dynamic-inline-filter-catalog"
  - "dynamic-filter-range-filters-guide"
keywords:
  - "inlineSelect"
  - "inlinePhone"
  - "inlineDateRange"
  - "inlineTreeSelect"
  - "inlineRelativePeriod"
last_updated: "2026-05-26"
---

# Dynamic Fields Inline Filter Catalog

## Objetivo

Catalogar os inline components reais usados pela trilha de filtro em `praxis-table`, sem misturar com o catalogo geral de fields do formulario.

## Superficie publicada para hosts

Este documento continua sendo a referencia editorial da trilha inline.

Para consumo operacional por hosts oficiais, landing page e playground, a superficie canonica e o catalogo exportado pela lib de dynamic-fields. Nele, os inline filters aparecem em `track: inline-filter`, separados dos fields de formulario comuns e validados contra o registry default.

Nesse catalogo exportado, a trilha inline tambem publica:

- `family`, para agrupar a natureza funcional do filtro;
- `interactionPattern`, para resumir se o caso e `lookup`, `range`, `single-choice`, `multi-choice`, `visual` ou outro padrao dominante;
- `icon.key` + `icon.tone`, para identidade visual canonica em menus, playgrounds e vitrines derivadas;
- `dataSourceKind`, para explicitar o custo de integracao do filtro.

## Pre-requisitos

- Entendimento basico de toolbar compacta vs filtro avancado
- Leitura recomendada do inventario runtime e do guia de payload do filtro

## Como usar este catalogo

Para cada item, leia em conjunto:

- **quando usar**: cenarios em que a variante inline agrega produtividade
- **quando evitar**: quando a compactacao piora a UX
- **shape do valor**: valor do componente dentro do form do filtro
- **UX note**: restricoes de densidade, acessibilidade e leitura na toolbar

Para hosts oficiais:

- a narrativa continua vindo deste markdown;
- a navegacao, os cues e a iconografia devem ser derivados do catalogo exportado da lib;
- nao mantenha uma tabela paralela de `interactionPattern` ou `icon` dentro do host.

## Tiers editoriais

- `core compact`: controles universais, previsiveis e de alta recorrencia
- `advanced compact`: controles validos em toolbar, mas que exigem criterio adicional de densidade
- `graphic specialized`: controles semanticos ou visuais que entram apenas por decisao explicita de produto

## 1. Texto

### <span id="inline-input"></span>`inlineInput`

- Quando usar: busca textual curta, identificador, nome, codigo, termo livre
- Quando evitar: texto longo, mascara pesada, validacao complexa que exija componente dedicado
- Shape do valor: `string`
- Mascara de display: quando houver semantica explicita em metadata (`mask`, `displayMask`,
  `inputMask`, `format` com tokens de mascara) o campo renderiza o valor mascarado e preserva
  o valor cru no form. Para compatibilidade com filtros metadata-driven, `inlineInput` tambem
  reconhece sinais explicitos de CPF/CNPJ, telefone BR/E.164 e CEP; numeros sem essa semantica
  permanecem texto cru.
- Snippet:

```json
{ "name": "name", "controlType": "inlineInput", "label": "Nome" }
```

- UX note: mantenha placeholder curto e `clearButton` habilitado
- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`, `dynamic-filter-payload-contract`

### <span id="inline-phone"></span>`inlinePhone`

- Quando usar: busca compacta por telefone em listas de contatos, pessoas, clientes ou funcionarios
- Quando evitar: edicao completa de telefone, seletor de pais, validacao internacional rica ou cadastro de multiplos telefones
- Shape do valor: `string` com digitos preservados no form
- Mascara de display: usa semantica telefonica do `inlineInput`, com `type="tel"` no input nativo e mascara visual quando `phoneFormat`, `mask`, `displayMask`, `inputMask` ou `format` indicarem telefone.
- Snippet:

```json
{ "name": "telefone", "controlType": "inlinePhone", "label": "Telefone", "prefixIcon": "phone" }
```

- UX note: use placeholder curto e nao exponha texto de ajuda permanente na toolbar; detalhes de formato devem ficar em hint acessivel ou filtro avancado
- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`, `dynamic-filter-payload-contract`

## 2. Selecao simples e multipla

### <span id="inline-select"></span>`inlineSelect`

- Quando usar: lista local pequena ou media
- Quando evitar: catalogo remoto grande ou lookup rico
- Shape do valor: valor simples
- Snippet:

```json
{ "name": "status", "controlType": "inlineSelect", "options": [{ "label": "Ativo", "value": "ACTIVE" }] }
```

- UX note: o valor precisa continuar legivel dentro da pill
- Docs relacionadas: `dynamic-fields-inline-filter-selection-guide`, `dynamic-inline-filter-catalog`

### <span id="inline-multiselect"></span>`inlineMultiSelect`

- Quando usar: poucas selecoes simultaneas que precisam permanecer visiveis como tokens compactos na pill
- Quando evitar: selecao grande ou dependencia de leitura integral permanente fora do painel
- Shape do valor: `unknown[]`
- Snippet:

```json
{ "name": "status", "controlType": "inlineMultiSelect", "multiple": true }
```

- UX note: o trigger mostra tokens selecionados com overflow `+N`; o painel deve manter uma secao de selecionados para leitura e remocao rapida
- Docs relacionadas: `dynamic-fields-inline-filter-selection-guide`

### <span id="inline-searchable-select"></span>`inlineSearchableSelect`

- Quando usar: lista media/grande com busca
- Quando evitar: se `select` simples ja resolve
- Shape do valor: valor simples ou option object, conforme metadata
- Snippet:

```json
{ "name": "departmentId", "controlType": "inlineSearchableSelect", "resourcePath": "/departments/options" }
```

- UX note: so use quando a busca realmente reduz friccao
- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`, `dynamic-filter-backend-contract-cheatsheet`

### <span id="inline-async-select"></span>`inlineAsyncSelect`

- Quando usar: fonte remota com busca sob demanda ou paginacao
- Quando evitar: se o custo cognitivo de abrir painel remoto na toolbar for alto
- Shape do valor: valor simples ou option object
- Snippet:

```json
{ "name": "ownerId", "controlType": "inlineAsyncSelect", "resourcePath": "/users/options" }
```

- UX note: valide loading, empty state e reset de termo na reabertura
- Docs relacionadas: `dynamic-fields-inline-filter-troubleshooting`

## 3. Lookup e autocomplete

### <span id="inline-entity-lookup"></span>`inlineEntityLookup`

- Quando usar: entidade com `id + descricao`, busca operacional, confirmacao de identidade
- Quando evitar: simples select local
- Shape do valor: objeto ou id final, conforme `optionValueKey`
- Snippet:

```json
{ "name": "customerId", "controlType": "inlineEntityLookup", "resourcePath": "/customers/options" }
```

- UX note: sempre explicite `optionLabelKey` e `optionValueKey`
- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`, `dynamic-filter-payload-contract`

### <span id="inline-autocomplete"></span>`inlineAutocomplete`

- Quando usar: sugestao incremental com escolha unica
- Quando evitar: lookup rico com mais de um identificador
- Shape do valor: valor simples ou option object
- Snippet:

```json
{ "name": "city", "controlType": "inlineAutocomplete", "resourcePath": "/cities/options" }
```

- UX note: autocomplete inline exige placeholder claro e feedback de carregamento
- Docs relacionadas: `dynamic-fields-inline-filter-selection-guide`

## 4. Numero e moeda

### <span id="inline-number"></span>`inlineNumber`

- Quando usar: valor numerico unico, score absoluto, quantidade
- Quando evitar: quando o dominio e intervalo, nao valor pontual
- Shape do valor: `number`
- Snippet:

```json
{ "name": "attempts", "controlType": "inlineNumber", "min": 0, "max": 100 }
```

- UX note: use `suffix` ou `%` quando o numero isolado puder ser ambiguo
- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`

### <span id="inline-currency"></span>`inlineCurrency`

- Quando usar: valor monetario unico
- Quando evitar: faixa monetaria
- Shape do valor: `number`
- Snippet:

```json
{ "name": "ticket", "controlType": "inlineCurrency", "currency": "BRL", "locale": "pt-BR" }
```

- UX note: compacte moeda, mas nao esconda contexto de locale
- Docs relacionadas: `dynamic-filter-backend-contract-cheatsheet`

## 5. Range

### <span id="inline-currency-range"></span>`inlineCurrencyRange`

- Quando usar: preco, budget, ticket medio, contrato
- Quando evitar: valor pontual
- Shape do valor: `{ minPrice?, maxPrice?, currency? }`
- Snippet:

```json
{ "name": "salaryRange", "controlType": "inlineCurrencyRange", "currency": "BRL" }
```

- UX note: resumo na pill deve deixar claro lower/upper bound
- Docs relacionadas: `dynamic-filter-range-filters-guide`

### <span id="inline-range"></span>`inlineRange`

- Quando usar: range numerico generico, slider simples ou duplo
- Quando evitar: data, hora ou semantica monetaria
- Shape do valor: `number` em modo simples; `{ start?, end? }` em `mode: "range"`
- Snippet:

```json
{ "name": "scoreRange", "controlType": "inlineRange", "min": 0, "max": 10, "mode": "range" }
```

- UX note: use presets apenas quando houver ganho real de velocidade
- Docs relacionadas: `dynamic-filter-range-filters-guide`

### <span id="inline-rating"></span>`inlineRating`

- Tier editorial: `graphic specialized`
- Quando usar: score visual, rating, classificacao por estrelas
- Quando evitar: se o backend so entende numero bruto sem ganho semantico ou se o usuario pensa em faixa numerica simples
- Shape do valor: `{ start?, end? }`
- Snippet:

```json
{ "name": "rating", "controlType": "inlineRating", "max": 5 }
```

- UX note: explicite se a leitura eh valor unico ou faixa e mantenha fallback textual claro na pill
- Docs relacionadas: `dynamic-filter-range-filters-guide`

### <span id="inline-distance-radius"></span>`inlineDistanceRadius`

- Tier editorial: `graphic specialized`
- Quando usar: raio de busca, distancia operacional, proximidade
- Quando evitar: range numerico generico sem semantica espacial ou quando a unidade varia por contexto
- Shape do valor: `number` em modo simples; `{ start?, end? }` em `mode: "range"`
- Snippet:

```json
{ "name": "radius", "controlType": "inlineDistanceRadius", "unit": "km" }
```

- UX note: sempre mostre unidade e evite esse inline quando o usuario precisar comparar varios sistemas de medida
- Docs relacionadas: `dynamic-filter-range-filters-guide`

### <span id="inline-score-priority"></span>`inlineScorePriority`

- Tier editorial: `graphic specialized`
- Quando usar: score com bandas, prioridade, criticidade
- Quando evitar: numero simples sem valor visual
- Shape do valor: `number` em modo simples; `{ start?, end? }` em `mode: "range"`
- Snippet:

```json
{ "name": "priority", "controlType": "inlineScorePriority", "min": 1, "max": 10 }
```

- UX note: a legenda visual precisa bater com a semantica do dominio; sem legenda confiavel, prefira `inlineRange`
- Docs relacionadas: `dynamic-fields-inline-filter-selection-guide`

## 6. Data e tempo

### <span id="inline-date"></span>`inlineDate`

- Quando usar: data unica
- Quando evitar: periodo completo
- Shape do valor: `Date`
- Snippet:

```json
{ "name": "createdAt", "controlType": "inlineDate", "label": "Criado em" }
```

- UX note: o host precisa serializar e alinhar timezone com backend
- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`, `dynamic-filter-payload-contract`

### <span id="inline-date-range"></span>`inlineDateRange`

- Quando usar: janela temporal, periodo de analise, atalhos como hoje/7 dias
- Quando evitar: quando a toolbar ja esta saturada
- Shape do valor: `{ startDate?, endDate? }`
- Snippet:

```json
{ "name": "period", "controlType": "inlineDateRange", "showShortcuts": true }
```

- UX note: shortcuts nao podem mascarar o shape final enviado ao backend
- Docs relacionadas: `dynamic-filter-range-filters-guide`

### <span id="inline-time"></span>`inlineTime`

- Quando usar: horario unico
- Quando evitar: se o usuario pensa em data ou periodo relativo
- Shape do valor: string `HH:mm`
- Snippet:

```json
{ "name": "hour", "controlType": "inlineTime" }
```

- UX note: sempre mantenha estado vazio claramente distinguivel
- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`

### <span id="inline-time-range"></span>`inlineTimeRange`

- Quando usar: turno, janela operacional, horario de atendimento
- Quando evitar: quando o backend espera `LocalDateTime`
- Shape do valor: `{ start?, end? }` com strings `HH:mm`
- Snippet:

```json
{ "name": "workHour", "controlType": "inlineTimeRange" }
```

- UX note: valide bound invertido e fallback de clear
- Docs relacionadas: `dynamic-filter-range-filters-guide`

## 7. Arvore

### <span id="inline-tree-select"></span>`inlineTreeSelect`

- Tier editorial: `advanced compact`
- Quando usar: taxonomia, estrutura hierarquica ou unidade organizacional com selecao de no unico e profundidade curta
- Quando evitar: arvore profunda demais para toolbar, necessidade de expandir varios ramos ou revisao visual da estrutura completa
- Shape do valor: valor simples do no
- Snippet:

```json
{ "name": "orgUnit", "controlType": "inlineTreeSelect", "nodes": [] }
```

- UX note: preserve contraste, foco e navegacao por teclado no popover; se o usuario precisar "navegar a arvore para pensar", mova o caso para o filtro avancado
- Docs relacionadas: `dynamic-fields-inline-filter-troubleshooting`

## 8. Semanticos especializados

### <span id="inline-pipeline-status"></span>`inlinePipelineStatus`

- Tier editorial: `graphic specialized`
- Quando usar: pipeline comercial, esteira, estado operacional
- Quando evitar: status simples de enum
- Shape do valor: valor simples ou `unknown[]`
- Snippet:

```json
{ "name": "pipelineStatus", "controlType": "inlinePipelineStatus", "options": [] }
```

- UX note: nao use se o desenho visual nao agrega mais do que um select; esse componente precisa representar uma jornada operacional reconhecivel
- Docs relacionadas: `dynamic-fields-inline-filter-selection-guide`

### <span id="inline-relative-period"></span>`inlineRelativePeriod`

- Tier editorial: `graphic specialized`
- Quando usar: hoje, ontem, ultimos 7 dias, este mes
- Quando evitar: quando a API nao usa a trilha canonica de filtros da plataforma, nao normaliza presets relativos ou quando o time precisa de rastreabilidade exata por data
- Shape do valor: `string`
- Snippet:

```json
{ "name": "periodPreset", "controlType": "inlineRelativePeriod" }
```

- UX note: com `praxis-metadata-starter`, presets suportados sao normalizados automaticamente para `onDate`, `lastDays` ou `between`; fora dessa trilha, documente a semantica HTTP equivalente e prefira `inlineDateRange`
- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`

### <span id="inline-sentiment"></span>`inlineSentiment`

- Tier editorial: `graphic specialized`
- Quando usar: sentimento, humor, polaridade
- Quando evitar: quando o backend ja usa enum simples sem ganho visual
- Shape do valor: `string`
- Snippet:

```json
{ "name": "sentiment", "controlType": "inlineSentiment" }
```

- UX note: contraste e rotulagem textual continuam obrigatorios; se a leitura final depender de cor ou emoji, o componente esta mal curado
- Docs relacionadas: `dynamic-fields-inline-filter-troubleshooting`

### <span id="inline-color-label"></span>`inlineColorLabel`

- Tier editorial: `graphic specialized`
- Quando usar: tags coloridas, labels semanticas, squads, categorias visuais
- Quando evitar: quando a cor eh o unico canal de significado
- Shape do valor: valor simples ou `unknown[]`
- Snippet:

```json
{ "name": "labels", "controlType": "inlineColorLabel", "options": [] }
```

- UX note: siga WCAG AA e nao dependa apenas de cor; sem texto curto e consistente, prefira `inlineMultiSelect`
- Docs relacionadas: `dynamic-fields-inline-filter-troubleshooting`

## 9. Toggle

### <span id="inline-toggle"></span>`inlineToggle`

- Quando usar: booleano com estado neutro
- Quando evitar: quando `false` e `null` significam coisas diferentes e nao estao documentadas
- Shape do valor: `boolean | null`
- Snippet:

```json
{ "name": "active", "controlType": "inlineToggle" }
```

- UX note: `clear` deve voltar para neutro, nao para `false`
- Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`

## Nota editorial importante

`praxis-table/docs/dynamic-inline-filter-catalog.md` continua sendo a visao de feature e jornada.

Este documento eh a visao de componente e implementacao.

Regra de governanca:

- `praxis-table`: documenta jornada, payload e operacao da feature de filtro;
- `@praxisui/dynamic-fields`: documenta e publica os componentes inline reutilizaveis;
- hosts oficiais devem consumir o catalogo exportado da lib, nao reconstruir uma lista inline paralela.

Regra para ranges Java:

- quando o backend usar operacoes `BETWEEN`, `BETWEEN_EXCLUSIVE`, `NOT_BETWEEN` ou `OUTSIDE_RANGE`, o valor simples `number` nao e payload HTTP valido; configure o inline em `mode: "range"` ou use um controle de range dedicado.

## Comparativos rapidos de curadoria

### Prefira `inlineSelect` em vez de `inlinePipelineStatus` quando

- o valor final for um enum simples
- nao houver jornada operacional clara por etapas
- a pill precisar permanecer discreta na toolbar

### Prefira `inlineDateRange` em vez de `inlineRelativePeriod` quando

- o time precisa de rastreabilidade exata por data
- o backend nao normaliza presets relativos de forma canonica
- usuarios auditam o filtro pelo valor final, nao pelo atalho semantico

### Prefira `inlineRange` em vez de `inlineRating` ou `inlineScorePriority` quando

- a pessoa usuaria pensa em numero bruto
- nao existe legenda de dominio forte
- o valor precisa ser comparado com facilidade entre telas

### Prefira `inlineMultiSelect` em vez de `inlineColorLabel` quando

- a cor nao for semanticamente confiavel
- o estado final precisar continuar claro em acessibilidade
- o usuario reconhecer a categoria pelo texto, nao pelo badge

### Prefira filtro avancado em vez de `inlineTreeSelect` quando

- a arvore tiver muitos niveis
- a decisao depender de explorar varios ramos
- a pessoa usuaria precisar revisar a estrutura para confiar no filtro ativo