Select

Campo de seleção com suporte a seleção simples ou múltipla, opções agrupadas, modo árvore e integração nativa com formulários.

O mk-select é o componente de seleção do Makuco UI. Suporta os modos single e multiple, busca de opções, agrupamento e hierarquia em modo árvore, e integração nativa com formulários via ElementInternals.

Integração com Angular Forms

Para usar com ngModel ou FormControl, importe MkSelectModule em vez de MkSelectComponent. Veja Formulários com Angular.

Seleção simples

import { MkSelect } from '@db1/makuco-ui-react';

const options = [
  { value: 'sp', label: 'São Paulo' },
  { value: 'rj', label: 'Rio de Janeiro' },
  { value: 'mg', label: 'Minas Gerais' },
];

<MkSelect label="Estado" options={options} placeholder="Selecione um estado" />

// component.ts
options = [
  { value: 'sp', label: 'São Paulo' },
  { value: 'rj', label: 'Rio de Janeiro' },
  { value: 'mg', label: 'Minas Gerais' },
];

<mk-select label="Estado" [options]="options" placeholder="Selecione um estado"></mk-select>

Seleção múltipla

Use kind="multiple" para permitir mais de uma seleção. O trigger exibe chips com os valores selecionados e um contador de excedentes.

<MkSelect label="Estados" kind="multiple" options={options} placeholder="Selecione os estados" />

<mk-select label="Estados" kind="multiple" [options]="options"></mk-select>

Com busca

Use searchable para exibir um campo de busca dentro do dropdown que filtra as opções pelo rótulo.

<MkSelect label="Estado" options={options} searchable />

<mk-select label="Estado" [options]="options" searchable></mk-select>

Opções agrupadas

Quando uma opção possui a propriedade items, ela é renderizada como um cabeçalho de grupo — não-selecionável — com seus filhos indentados abaixo. Use para organizar visualmente opções relacionadas sem hierarquia de seleção.

const options = [
  {
    value: 'sudeste',
    label: 'Sudeste',
    items: [
      { value: 'sp', label: 'São Paulo' },
      { value: 'rj', label: 'Rio de Janeiro' },
    ],
  },
  {
    value: 'sul',
    label: 'Sul',
    items: [
      { value: 'rs', label: 'Rio Grande do Sul' },
      { value: 'sc', label: 'Santa Catarina' },
    ],
  },
];

<MkSelect label="Estado" options={options} />

<mk-select label="Estado" [options]="options"></mk-select>

Modo árvore

Com tree, opções que possuem items tornam-se pais selecionáveis com filhos indentados. Em kind="multiple", clicar em um pai seleciona ou desmarca todos os filhos habilitados de uma só vez.

Cada pai exibe um chevron à esquerda: aponta para cima com os filhos visíveis e para baixo com os filhos ocultos. Clicar no chevron, ou pressionar ArrowLeft / ArrowRight no pai focado, fecha ou abre o pai sem alterar a seleção. Todos os pais começam abertos. Durante a busca, os pais ficam abertos e o chevron não é exibido.

const options = [
  {
    value: 'sudeste',
    label: 'Sudeste',
    items: [
      { value: 'sp', label: 'São Paulo' },
      { value: 'rj', label: 'Rio de Janeiro' },
    ],
  },
  {
    value: 'sul',
    label: 'Sul',
    items: [
      { value: 'rs', label: 'Rio Grande do Sul' },
      { value: 'sc', label: 'Santa Catarina' },
    ],
  },
];

<MkSelect label="Estados" kind="multiple" options={options} tree />

<mk-select label="Estados" kind="multiple" [options]="options" tree></mk-select>

Aninhamento profundo

Quando a hierarquia tem 3 ou mais níveis, combine tree com searchable para facilitar a navegação. O componente aplica indentação automática a cada nível e gerencia aria-level em cada opção.

const options = [
  {
    value: 'brasil',
    label: 'Brasil',
    items: [
      {
        value: 'br-sudeste',
        label: 'Sudeste',
        items: [
          { value: 'sp', label: 'São Paulo' },
          { value: 'rj', label: 'Rio de Janeiro' },
        ],
      },
      {
        value: 'br-sul',
        label: 'Sul',
        items: [
          { value: 'rs', label: 'Rio Grande do Sul' },
          { value: 'pr', label: 'Paraná' },
        ],
      },
    ],
  },
];

<MkSelect
  label="Local"
  options={options}
  tree
  searchable
  kind="multiple"
  allowSelectAll
  placeholder="Selecione locais"
/>

options = [
  {
    value: 'brasil',
    label: 'Brasil',
    items: [
      {
        value: 'br-sudeste',
        label: 'Sudeste',
        items: [
          { value: 'sp', label: 'São Paulo' },
          { value: 'rj', label: 'Rio de Janeiro' },
        ],
      },
    ],
  },
];

<mk-select
  label="Local"
  [options]="options"
  tree
  searchable
  kind="multiple"
  [allow-select-all]="true"
  placeholder="Selecione locais"
></mk-select>

Selecionar tudo

Use allowSelectAll junto com kind="multiple" para exibir a opção "Selecionar tudo" no topo da lista. Ao clicar, todas as opções habilitadas são selecionadas ou desmarcadas.

<MkSelect label="Estados" kind="multiple" options={options} allowSelectAll />

<mk-select label="Estados" kind="multiple" [options]="options" allow-select-all></mk-select>

Texto de ajuda

<MkSelect label="Estado" options={options} supportText="Escolha o estado de entrega" />

<mk-select label="Estado" [options]="options" helper-text="Escolha o estado de entrega"></mk-select>

Rótulo oculto

Use hideLabel para ocultar o rótulo visualmente. O label continua nomeando o combobox para tecnologias assistivas.

<MkSelect label="Estado" options={options} hideLabel />

<mk-select label="Estado" [options]="options" hide-label></mk-select>

Estado vazio

Quando options está vazio, o dropdown exibe uma mensagem no lugar da lista. Use emptyText para customizá-la — caso contrário, o componente recai para a mensagem localizada padrão.

<MkSelect label="Estado" options={[]} emptyText="Nenhum estado encontrado" />

<mk-select label="Estado" [options]="[]" empty-text="Nenhum estado encontrado"></mk-select>

Estado de erro

Use errorMessage para ativar o estado de erro com uma mensagem exibida abaixo do campo.

<MkSelect label="Estado" options={options} errorMessage="Selecione uma opção" />

<mk-select label="Estado" [options]="options" error-message="Selecione uma opção"></mk-select>

Desabilitado e somente leitura

<MkSelect label="Estado" options={options} disabled />
<MkSelect label="Estado" options={options} readonly />

<mk-select label="Estado" [options]="options" [disabled]="true"></mk-select>
<mk-select label="Estado" [options]="options" [readonly]="true"></mk-select>

Formulários

O mk-select é form-associated. Para seleção múltipla, cada valor selecionado é registrado individualmente no FormData.

<form onSubmit={handleSubmit}>
  <MkSelect label="Estado" name="estado" options={options} required />
  <MkButton type="submit">Enviar</MkButton>
</form>

<form (ngSubmit)="handleSubmit()">
  <mk-select label="Estado" name="estado" [options]="options" required></mk-select>
  <mk-button type="submit">Enviar</mk-button>
</form>

Props

Prop	Tipo	Padrão	Descrição
`label`	`string`	—	Texto do rótulo exibido acima do campo. Obrigatório.
`options`	`SelectOption[]`	`[]`	Lista de opções. Veja a tabela `SelectOption` abaixo.
`kind`	`"single" \\| "multiple"`	`"single"`	Modo de seleção — única ou múltipla.
`value`	`unknown \\| unknown[]`	—	Valor(es) selecionado(s). Use array para `kind="multiple"`. Comparação por referência (`===`).
`placeholder`	`string`	—	Texto exibido quando nenhuma opção está selecionada.
`tree`	`boolean`	`false`	Ativa o modo hierárquico. Opções com `items` tornam-se pais selecionáveis com filhos indentados. Em `kind="multiple"`, clicar no pai seleciona/desmarca todos os filhos habilitados.
`searchable`	`boolean`	`false`	Exibe campo de busca dentro do dropdown para filtrar opções pelo rótulo.
`allowSelectAll`	`boolean`	`false`	Exibe a opção "Selecionar tudo" no topo da lista. Apenas para `kind="multiple"`.
`clearable`	`boolean`	`true`	Exibe um botão para limpar a seleção quando há valor. Defina `false` para remover essa opção.
`required`	`boolean`	`false`	Marca o campo como obrigatório com asterisco no rótulo.
`disabled`	`boolean`	`false`	Desabilita o campo, impedindo qualquer interação.
`readonly`	`boolean`	`false`	Exibe o valor mas impede abertura do dropdown.
`errorMessage`	`string`	—	Mensagem de erro exibida abaixo do campo. Ativa o estado inválido quando definida.
`supportText`	`string`	—	Texto auxiliar exibido abaixo do campo quando não há erro.
`hideLabel`	`boolean`	`false`	Oculta o rótulo visualmente. O `label` continua nomeando o combobox para tecnologias assistivas.
`emptyText`	`string`	—	Texto exibido no dropdown quando `options` está vazio. Quando omitido, recai para a mensagem localizada padrão.
`helperText`	`string`	—	Texto exibido no ícone de ajuda ao lado do rótulo. Quando omitido, o ícone não é exibido.
`optionValue`	`string`	`"value"`	Chave do objeto de opção usada como valor selecionado.
`optionLabel`	`string`	`"label"`	Chave do objeto de opção usada como rótulo exibido.
`name`	`string`	—	Atributo `name` para envio em formulários.
`requiredMessage`	`string`	`"Please select an option"`	Mensagem de validação nativa exibida quando o campo é obrigatório e está vazio.
`open`	`boolean`	`false`	Estado do dropdown. Pode ser definido externamente para abrir/fechar programaticamente.
`locale`	`string`	—	Tag BCP 47 para resolver mensagens i18n. Recai para `lang` do ancestral e depois `pt-BR`.

SelectOption

Campo	Tipo	Descrição
`value`	`unknown`	Valor da opção. Obrigatório.
`label`	`string`	Rótulo exibido na lista. Obrigatório.
`disabled`	`boolean`	Desabilita a opção individualmente.
`description`	`string`	Texto secundário exibido abaixo do rótulo.
`avatar`	`\{ label?: string; src?: string \}`	Exibe um avatar à esquerda da opção.
`items`	`SelectOption[]`	Sub-itens. Sem `tree`: a opção pai vira cabeçalho de grupo (não-selecionável). Com `tree`: a opção pai é selecionável e os filhos ficam indentados.

Eventos

Evento	Payload	Descrição
`mkChange`	`{ value: unknown \\| unknown[] }`	Emitido sempre que a seleção muda.
`mkOpen`	`void`	Emitido quando o dropdown abre.
`mkClose`	`void`	Emitido quando o dropdown fecha.

Acessibilidade

O trigger usa role="combobox" com aria-expanded, aria-haspopup="listbox" e aria-controls apontando para o listbox.
O dropdown usa role="listbox" com aria-multiselectable para o modo multiple.
Cada opção usa role="option" com aria-selected e aria-disabled.
No modo árvore, filhos recebem aria-level="2".
Com valor escolhido, a lista abre com o destaque na opção escolhida (em kind="multiple", a primeira escolhida na ordem da lista), que entra na vista; as setas partem dela. Confirmar com Enter a opção que já está escolhida fecha a lista sem emitir mkChange.
Navegação por teclado: ArrowUp / ArrowDown movem o foco entre opções; ArrowLeft / ArrowRight fecham e abrem o pai focado no modo árvore; Enter ou Space selecionam; Escape fecha.
delegatesFocus: true garante que o foco seja delegado ao trigger ao clicar no host.
Com hideLabel, o label permanece como nome acessível do combobox.

Select

On this page