Pular para o conteúdo
UI

Tag Picker

Seletor de tags em popover: o usuário busca, marca e desmarca tags e, se o produto permitir, cria, renomeia, troca a cor e exclui tags sem sair do fluxo. As tags são exibidas com as cores do Tag.

O componente não busca nem salva dados. Ele recebe a lista em tags e avisa as ações pelas callbacks. Cada recurso de gestão aparece só quando a callback correspondente é passada.

Exemplos

Com gestão de tags

Passe onCreate, onRename, onChangeVariant e onDelete para liberar a gestão completa. As callbacks podem devolver uma Promise: o picker espera a resposta e, se ela rejeitar, mantém o estado (o texto digitado, a edição aberta, a confirmação de exclusão). O picker não mostra o erro nem o repassa adiante, então trate a falha dentro da callback (toast, log) e relance o erro para o picker saber que deu errado. Excluir pede confirmação, e tags com locked só podem ser marcadas.

O picker não guarda as tags: depois de cada ação, atualize tags (e tire de selectedIds a tag excluída). A renomeação é salva com Enter, ao sair do campo ou ao fechar o popover com clique fora.

Cardiologia

Só seleção

Sem as callbacks de gestão, o componente vira um filtro de tags com busca.

Trigger customizado

Para usar outro botão, passe-o como children. Ele é renderizado com asChild, então precisa ser um único elemento que aceite ref, como Button ou ChipFilter. O picker cuida de abrir, fechar e de aria-expanded.

Dentro de um modal

O conteúdo do picker é renderizado num portal no body. Dentro de um Dialog, passe modal para a lista continuar rolando com a roda do mouse; sem isso, o bloqueio de scroll do Dialog cancela o wheel fora do conteúdo dele.

<TagPicker modal tags={tags} selectedIds={selectedIds} onToggle={handleToggle} />

Acessibilidade

  • Cada tag é um checkbox cujo nome acessível é o nome da tag.
  • Os botões de ação anunciam a tag afetada ("Renomear tag Pediatria", "Excluir tag Pediatria"), e cada cor do seletor tem um nome em pt-BR ("Azul-marinho", "Verde suave", "Clínica médica").
  • Esc cancela primeiro a ação em andamento (renomear, trocar cor ou excluir) e só depois fecha o popover.
  • Enter confirma a criação e a renomeação (ignorado durante a composição de IME).
  • O foco não se perde: os campos continuam focados enquanto a ação roda, e quando um controle some (fim da edição, exclusão) o foco volta para a linha ou para a busca.
  • Em telas sem hover (touch), as ações da linha ficam sempre visíveis, e as cores têm área de toque de 24px.

API

PropriedadeTipoPadrãoDescrição
tagsTagPickerTag[]-Tags disponíveis: { id, name, variant?, locked? }.
selectedIdsstring[]-Ids das tags marcadas.
onToggle(id, selected) => void-Chamada ao marcar ou desmarcar uma tag.
onCreate({ name, variant }) => TagPickerTag | void | Promise-Cria uma tag. Se devolver a tag criada, ela já entra marcada (se já estiver marcada, onToggle não é chamado de novo). Sem esta prop, a área de criação não aparece.
onRename(tag, name) => void | Promise-Renomeia uma tag. Sem esta prop, o botão de renomear não aparece.
onChangeVariant(tag, variant) => void | Promise-Troca a cor de uma tag. Sem esta prop, o seletor de cor da linha não aparece.
onDelete(tag) => void | Promise-Exclui uma tag depois da confirmação. Tirar a tag de tags e de selectedIds fica com quem usa. Sem esta prop, o botão de excluir não aparece.
variantsreadonly TagVariant[]TAG_PICKER_PALETTECores oferecidas no seletor. A paleta padrão tem 16 cores em duas linhas de 8: sólidas, suaves e especialidades, nessa ordem.
defaultVariantTagVariant"gray-soft"Cor das tags sem variant e cor inicial de uma tag nova.
loadingbooleanfalseMostra o estado de carregamento no lugar da lista.
disabledbooleanfalseDesabilita o trigger padrão (sem efeito com children; desabilite o seu próprio elemento).
childrenReactNodeBotão "Adicionar tag"Trigger customizado. É renderizado com asChild, então precisa ser um único elemento que aceite ref (ex.: Button, ChipFilter).
labelsPartial<TagPickerLabels>Textos em pt-BRTextos da interface. Strings: trigger, searchPlaceholder, createPlaceholder, create, loading, empty, noResults, confirmDelete, cancelDelete e newTagColor. Funções que recebem o nome da tag: renameTag, changeTagColor, tagColor, deleteTag e confirmDeleteTag. E variantName(variant), o nome de cada cor no seletor.
open / defaultOpen / onOpenChange--Controle de abertura do popover, como no Popover do Radix. Fechar, por qualquer origem, limpa a busca e as ações em andamento.
modalbooleanfalseRepassado ao Popover. Use dentro de um Dialog para a lista rolar com a roda do mouse.
alignstring"start"Alinhamento do conteúdo em relação ao trigger.
contentClassNamestring-Classes adicionais aplicadas ao conteúdo do popover.