MultiSelect

Um seletor com suporte a múltiplas opções, busca, criação personalizada, scroll infinito e renderização de badges.

Utilização

index.tsx
import { MultiSelect } from "@convertcompany/ui";

Exemplos

Com badges customizadas

Com a opção renderValues, você pode personalizar a renderização das badges exibidas no campo.

Com opções selecionadas fora do campo

Com a opção renderOutside, você pode renderizar as opções selecionadas fora do campo principal.

Com criação de opção

O MultiSelect permite criar novas opções com base na busca. Para isso, utilize a prop canCreate e onCreate. O texto exibido ao criar uma nova opção pode ser customizado com a prop createItemText, onde {search} será substituído pelo termo buscado. Além disso é possível customizar o ícone ao lado do texto de criação de item com a prop createItemIcon.

Pressione Enter para criar uma nova opção

Com filtro customizado

Você pode personalizar o filtro de opções utilizando a prop filterBy. Essa função recebe o valor da opção, o termo buscado e as palavras-chave. O retorno deve ser um número que indica a relevância da opção (quanto maior, mais relevante). Você também pode usar a prop canFilter para habilitar o campo de busca dentro do menu.

Com trigger customizado

Você pode personalizar o gatilho do MultiSelect utilizando a prop children. Isso permite que você use qualquer componente como gatilho, mantendo a funcionalidade do MultiSelect.

Use qualquer componente como gatilho

Com scroll infinito

O MultiSelect permite carregar opções de forma assíncrona com scroll infinito. Para isso, utilize a prop onEndReached para carregar mais opções quando o usuário chegar ao final da lista. Você pode usar a prop loading para indicar que as opções estão sendo carregadas.

Realize scroll até o final

Com contador e limite

A opção maxCount define o número máximo de badges exibidas antes de resumir as opções selecionadas. A prop maxSelections define o número máximo de seleções permitidas. Quando o número de seleções atinge o limite, as opções adicionais são desabilitadas.

Máximo de 3 seleções, exibindo até 2 badges

Com botão de selecionar tudo

A opção canSelectAll habilita a seleção de todas as opções. O texto exibido para essa opção pode ser customizado com a prop selectAllText.

Habilita a opção de selecionar todas as opções

Com campo de busca desativado

A opção canFilter desabilita o campo de busca dentro do menu. Isso pode ser útil quando você não precisa de busca entre as opções disponíveis.

Desabilita o campo de busca dentro do menu

Com botão de limpar e fechar no rodapé

A opção showActionFooter exibe um rodapé com ações de limpar e fechar. Isso pode ser útil para fornecer uma maneira rápida de limpar as seleções ou fechar o menu.

Exibe o rodapé com ações de limpar e fechar

Props

PropriedadeTipo
optionsLista de opções com label e value.
Option[]
valueValores selecionados.
string[]
onChangeCallback ao alterar os valores.
(options: string[]) => void
placeholderTexto exibido quando não houver seleções.
string
canClearPermite limpar as opções. Padrão é true.
boolean
canCreatePermite criar uma nova opção digitando.
boolean
onCreateCallback ao criar nova opção.
(value: string) => void
createItemTextTexto para criar item. Use {search} no texto.
string
createItemIconÍcone ao lado da opção de criar.
ReactNode
canFilterHabilita busca entre as opções.
boolean
filterByFunção de filtro customizada. Se retornar false, o filtro será desabilitado.
(value: string, search: string, keywords?: string[]) => number | false
onSearchCallback ao digitar no campo de busca.
(value: string) => void
canSelectAllHabilita opção de selecionar todas.
boolean
selectAllTextTexto exibido para a opção de selecionar tudo.
string
maxSelectionsDefine o número máximo de seleções permitidas.
number
maxCountDefine o número de badges exibidas antes de resumir.
number
renderItemRenderização customizada do item.
(option: Option) => ReactNode
renderValuesRenderização customizada das badges.
(values: Option[]) => ReactNode
renderOutsideRenderiza badges fora do campo principal.
boolean
classNameClasse CSS adicional.
string
modalPopoverUsa o popover em modo modal (Radix).
boolean
loopPermite navegação com teclado em loop.
boolean
onEndReachedCallback ao chegar ao final da lista.
() => void
loadingExibe estado de carregamento.
boolean
passiveLoadingExibe carregando mesmo com dados visíveis.
boolean
loadingStateTextTexto exibido durante o carregamento.
string
emptyStateTextTexto exibido quando nenhuma opção é encontrada.
string
showSelectedOptionsExibe opções já selecionadas no menu.
boolean
showActionFooterExibe rodapé com ações de limpar e fechar.
boolean
childrenGatilho customizado para o MultiSelect.
ReactNode