---
title: "Dynamic Fields Inline Filter Selection Guide"
slug: "dynamic-fields-inline-filter-selection-guide"
description: "Guia de decisao para escolher o inline correto na trilha de filtro, equilibrando densidade, semantica, payload e custo de integracao."
doc_type: "guide"
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"
  - "selection"
  - "ux"
order: 43
icon: "rule"
toc: true
sidebar: true
search_boost: 1.16
reading_time: 16
estimated_setup_time: 15
version: "1.0"
related_docs:
  - "dynamic-fields-inline-filter-catalog"
  - "dynamic-fields-inline-filter-runtime-contract"
  - "dynamic-inline-filter-catalog"
  - "dynamic-filter-range-filters-guide"
keywords:
  - "quando usar inline"
  - "single value vs range"
  - "local vs remoto"
  - "compact toolbar"
last_updated: "2026-03-26"
---

# Dynamic Fields Inline Filter Selection Guide

## Objetivo

Ajudar times host a escolher o inline correto sem transformar a toolbar do filtro em um formulario comprimido e confuso.

## Pre-requisitos

- Conhecer a feature de filtro dinamico em `praxis-table`
- Saber o tipo de dado e a expectativa de payload do backend

## Fonte canonica para descoberta

Para landing pages, playgrounds e outros hosts oficiais, a descoberta da trilha inline deve partir do catalogo exportado por `@praxisui/dynamic-fields`.

Esse catalogo centraliza os mesmos `controlType` desta trilha com semantica pronta para descoberta:

- `track`, para separar `inline-filter` de outras trilhas;
- `family`, para agrupar a natureza funcional do filtro;
- `interactionPattern`, para resumir se o caso dominante e `lookup`, `range`, `single-choice`, `multi-choice`, `visual` ou `trigger`;
- `dataSourceKind`, para deixar claro se o caso e local, remoto, misto ou especializado;
- `icon.key` e `icon.tone`, para projetar identidade visual canonica sem inventar outra taxonomia no host.

Regra de uso:

- este guia continua sendo a narrativa de decisao;
- o inventario continua provando suporte runtime real;
- cues de navegacao, mini-cards e vitrines devem ser derivados do catalogo exportado da lib.

## Principio central

Um inline filter component so vale a pena quando melhora a velocidade de decisao na barra compacta.

Se ele exige muita exploracao, muita leitura ou muito backend roundtrip, prefira deixar a experiencia no filtro avancado.

```mermaid
flowchart TD
  field["Filter field candidate"] --> freq{"High frequency?"}
  freq -- no --> advanced["Keep in advanced filter"]
  freq -- yes --> legible{"Readable active state?"}
  legible -- no --> advanced
  legible -- yes --> payload{"Payload fits backend DTO?"}
  payload -- no --> advanced
  payload -- yes --> density{"Compact enough for toolbar?"}
  density -- yes --> inline["Promote to inline control"]
  density -- no --> advanced
```

## Perguntas de decisao

1. O usuario usa esse filtro com frequencia alta?
2. O valor final continua legivel na pill?
3. O shape do valor ja conversa bem com o DTO do backend?
4. O filtro depende de lista remota pesada ou hierarquia profunda?
5. O controle expressa uma semantica especifica do dominio ou eh so um field generico?

Antes de transformar essas respostas em navegacao publicada, projete o resultado usando `interactionPattern`, `dataSourceKind` e `icon` vindos do catalogo exportado em vez de montar uma tabela paralela no host.

## Simples vs multipla

### Escolha simples

Prefira:

- `inlineSelect`
- `inlineSearchableSelect`
- `inlineAsyncSelect`
- `inlineEntityLookup`
- `inlineAutocomplete`

Pergunta chave:

- o usuario escolhe um item ou procura por uma entidade?

Use `entity-lookup` quando a identidade do item importa.
Use `select`/`searchable` quando o label por si so basta.

### Escolha multipla

Prefira:

- `inlineMultiSelect`
- `inlinePipelineStatus`
- `inlineColorLabel`

Evite inline multiplo quando:

- a selecao tipica passa de 3 ou 4 itens;
- a pill perde poder explicativo;
- o usuario precisa revisar a lista completa para confiar no estado.

## Local vs remoto

### Local

Use variantes locais quando:

- o conjunto de opcoes eh estavel;
- a lista cabe em memoria sem custo operacional;
- a toolbar precisa abrir rapido.

### Remoto

Use variantes remotas quando:

- o conjunto eh grande ou dependente de tenant;
- ha busca paginada;
- o filtro faz parte de operacao enterprise real.

Prefira:

- `inlineAsyncSelect`
- `inlineEntityLookup`
- `inlineAutocomplete`

Risco:

- backend lento degrada a UX da toolbar mais rapido do que degrada um modal de filtro avancado.

## Single value vs range

### Single value

Prefira:

- `inlineInput`
- `inlineNumber`
- `inlineCurrency`
- `inlineDate`
- `inlineTime`
- `inlineToggle`

### Range

Prefira:

- `inlineRange`
- `inlineCurrencyRange`
- `inlineDateRange`
- `inlineTimeRange`
- `inlineRating`
- `inlineDistanceRadius`
- `inlineScorePriority`

Regra:

- se o backend opera com lower/upper bound, documente o shape canonicamente como range
- nao disfarce um range como numero simples apenas para caber na toolbar

## Inline compacto vs advanced filter

### Fica bem na toolbar

- valor curto e recorrente
- uma ou duas interacoes para definir
- leitura rapida do estado ativo
- clear facil

### Melhor no painel avancado

- lista profunda
- arvore grande
- validacao pesada
- combinacao de muitos subcampos
- dependencia forte de contexto adicional

## Especializado semantico vs controle generico

Use controles especializados quando a semantica visual reduz ambiguidade:

- `inlineRating`
- `inlineDistanceRadius`
- `inlinePipelineStatus`
- `inlineScorePriority`
- `inlineRelativePeriod`
- `inlineSentiment`
- `inlineColorLabel`

Evite especializados quando:

- o backend e o usuario so precisam de um enum simples;
- a visualizacao rica nao muda a decisao.

Regra de produto obrigatoria:

- componentes `graphic specialized` entram na toolbar somente por `controlType` explicito no schema
- eles nao devem ser promovidos automaticamente a partir de um controle generico
- se houver duvida entre `inlineSelect` e um especializado visual, prefira o controle generico

Familia `graphic specialized`:

- `inlinePipelineStatus`
- `inlineRelativePeriod`
- `inlineRating`
- `inlineDistanceRadius`
- `inlineScorePriority`
- `inlineSentiment`
- `inlineColorLabel`

## Tiers de densidade

### Core compact

Use como primeira opcao na toolbar:

- `inlineInput`
- `inlineSelect`
- `inlineSearchableSelect`
- `inlineAsyncSelect`
- `inlineEntityLookup`
- `inlineAutocomplete`
- `inlineNumber`
- `inlineCurrency`
- `inlineRange`
- `inlineCurrencyRange`
- `inlineDate`
- `inlineDateRange`
- `inlineTime`
- `inlineTimeRange`
- `inlineToggle`
- `inlinePeriodRange`

Heuristica:

- uma interacao principal
- estado preenchido facil de ler
- baixo custo de explicacao para usuario novo

### Advanced compact

Use quando houver ganho claro e frequente:

- `inlineMultiSelect`
- `inlineTreeSelect`

Regra:

- `inlineTreeSelect` so vale a pena para hierarquias rasas, com rotulo final curto e selecao de no unico
- se a arvore exigir exploracao profunda, varios niveis expandidos ou revisao estrutural para confiar no estado, prefira filtro avancado ou desative a promocao inline

### Graphic specialized

Use apenas por opt-in explicito:

- `inlinePipelineStatus`
- `inlineRelativePeriod`
- `inlineRating`
- `inlineDistanceRadius`
- `inlineScorePriority`
- `inlineSentiment`
- `inlineColorLabel`

Regra:

- esses componentes nunca devem ser o primeiro default editorial quando um controle generico resolve
- so use quando a linguagem visual reduz ambiguidade ou acelera decisao de forma mensuravel
- se a principal vantagem for "ficar mais bonito", nao use na toolbar compacta

## Anti-padroes comuns

- promover `inlineTreeSelect` para qualquer taxonomia so porque existe arvore no backend
- usar `inlineRelativePeriod` quando a API nao normaliza presets relativos de forma canonica
- usar `inlinePipelineStatus` para enum simples de status administrativo
- usar `inlineColorLabel` quando a cor eh o unico canal sem texto de apoio
- usar `inlineRating` ou `inlineScorePriority` quando o usuario pensa em numero bruto, nao em banda visual

## Matriz de decisao

| Pergunta | Melhor opcao |
| --- | --- |
| Lista pequena, selecao unica | `inlineSelect` |
| Lista grande com busca | `inlineSearchableSelect` |
| Lista remota paginada | `inlineAsyncSelect` |
| Entidade com id + descricao | `inlineEntityLookup` |
| Sugestao incremental | `inlineAutocomplete` |
| Texto curto | `inlineInput` |
| Numero unico | `inlineNumber` |
| Valor monetario unico | `inlineCurrency` |
| Faixa monetaria | `inlineCurrencyRange` |
| Range numerico generico | `inlineRange` |
| Data unica | `inlineDate` |
| Periodo | `inlineDateRange` |
| Horario unico | `inlineTime` |
| Faixa horaria | `inlineTimeRange` |
| Hierarquia rasa, no unico e leitura curta | `inlineTreeSelect` |
| Booleano com neutro | `inlineToggle` |
| Score visual com ganho semantico real | `inlineRating` |
| Distancia / raio com unidade explicita | `inlineDistanceRadius` |
| Status visual de pipeline com semantica operacional | `inlinePipelineStatus` |
| Score / prioridade por banda com legenda clara | `inlineScorePriority` |
| Preset temporal em API com normalizacao canonica | `inlineRelativePeriod` |
| Polaridade / sentimento com leitura textual clara | `inlineSentiment` |
| Tags com cor e rotulo textual forte | `inlineColorLabel` |

## Recipes comparativos

### Use isto / evite isto

#### Enum simples de status administrativo

Use isto:

- `inlineSelect`

Evite isto:

- `inlinePipelineStatus`

Motivo:

- se o usuario so precisa escolher `Ativo`, `Inativo` ou `Pendente`, a metafora de pipeline adiciona peso visual sem acelerar decisao

#### Periodo analitico com rastreabilidade

Use isto:

- `inlineDateRange`
- `inlinePeriodRange`

Evite isto:

- `inlineRelativePeriod` quando o backend nao normaliza presets

Motivo:

- filtros analiticos precisam deixar claro o recorte final enviado ao backend; se a plataforma nao fecha essa traducao canonicamente, o preset relativo cria opacidade

#### Hierarquia organizacional

Use isto:

- `inlineTreeSelect` para arvore rasa, selecao unica e rotulo final curto

Evite isto:

- `inlineTreeSelect` para navegacao exploratoria ou estruturas profundas

Motivo:

- quando a pessoa precisa abrir muitos ramos para decidir, a toolbar vira um mini navegador de arvore e perde sua funcao compacta

#### Faixa numerica sem semantica visual forte

Use isto:

- `inlineRange`

Evite isto:

- `inlineRating`
- `inlineScorePriority`

Motivo:

- se o dominio pensa em numero ou intervalo bruto, o componente especializado so troca clareza por ornamento

#### Tags ou categorias

Use isto:

- `inlineMultiSelect`

Evite isto:

- `inlineColorLabel` quando a cor for o principal canal

Motivo:

- cor pode ajudar, mas nao pode carregar sozinha a semantica de um filtro enterprise

## Recomendacoes enterprise

- use `controlType` canonico `inline*`
- valide sempre o shape do valor com o DTO da tabela
- nao promova um controle para inline so porque existe componente pronto
- trate `inlineTreeSelect` como excecao operacional, nao como default para qualquer hierarquia
- trate a familia `graphic specialized` como opt-in de produto, nunca como decoracao padrao