Transfer

Componente de transferência dual-list (`mk-transfer`) para mover itens entre dois painéis de origem e destino, com seleção via listbox multi-selecionável.

O mk-transfer exibe dois painéis lado a lado — origem à esquerda e destino à direita — com botões de ação centrais para mover itens individualmente ou em massa. Cada painel é um grupo de mk-checkbox, um por item, com navegação e ativação seguindo o comportamento nativo de checkbox. Indicado para seleção múltipla avançada em UIs de configuração, permissões e agrupamento de recursos.

Padrão

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

const options = [
  { value: 'ts', label: 'TypeScript' },
  { value: 'js', label: 'JavaScript' },
  { value: 'py', label: 'Python' },
];

<MkTransfer options={options} value={[]} />

<mk-transfer [options]="options" [value]="selected"></mk-transfer>

Com valor inicial

Passe um array de valores na prop value para pré-popular o painel de destino na carga inicial.

<MkTransfer
  options={options}
  value={['ts', 'go', 'rs']}
  onMkChange={(e) => setSelected(e.detail.value)}
/>

<mk-transfer
  [options]="options"
  [value]="selected"
  (mkChange)="onTransferChange($event)"
></mk-transfer>

Com busca

Ative searchable para exibir um campo mk-search em cada painel. O filtro atua apenas na exibição — não move nem desmarca itens.

<MkTransfer options={options} value={selected} searchable />

<mk-transfer [options]="options" [value]="selected" searchable></mk-transfer>

Títulos customizados

Use sourceTitle e targetTitle para adaptar os rótulos dos painéis ao contexto da sua UI.

<MkTransfer
  options={options}
  value={selected}
  sourceTitle="Linguagens disponíveis"
  targetTitle="Linguagens do projeto"
/>

<mk-transfer
  [options]="options"
  [value]="selected"
  source-title="Linguagens disponíveis"
  target-title="Linguagens do projeto"
></mk-transfer>

Desabilitado

Com disabled, todos os itens e os 4 botões de ação ficam inoperantes. O estado é refletido no atributo host [disabled] para estilização via CSS.

<MkTransfer options={options} value={selected} disabled />

<mk-transfer [options]="options" [value]="selected" [disabled]="true"></mk-transfer>

Vazio

Quando um painel não tem itens visíveis, exibe uma mensagem de empty state (sem ícone). A mensagem é resolvida via locale — ou pelo lang mais próximo na árvore, com fallback em pt-BR.

<MkTransfer options={options} value={options.map((o) => o.value)} locale="en" />

<mk-transfer [options]="options" [value]="allValues" locale="en"></mk-transfer>

Props — mk-transfer

Prop	Tipo	Padrão	Descrição
`options`	`TransferOption[]`	`[]`	Lista completa de opções disponíveis. Cada item deve ter as chaves definidas por `optionValue` e `optionLabel`. Itens com `disabled: true` renderizam o `mk-checkbox` desabilitado e não participam das operações "mover tudo".
`value`	`unknown[]`	`[]`	Valores dos itens presentes no painel de destino. Prop mutable — o componente a atualiza ao mover itens e emite `mkChange`.
`sourceTitle`	`string`	`"Disponíveis"`	Título exibido acima do painel de origem.
`targetTitle`	`string`	`"Selecionados"`	Título exibido acima do painel de destino.
`searchable`	`boolean`	`false`	Exibe um campo `mk-search` em cada painel. O filtro atua apenas na exibição — não move nem desmarca itens.
`disabled`	`boolean`	`false`	Desabilita todos os itens e botões de ação, impedindo qualquer interação.
`optionValue`	`string`	`"value"`	Chave do objeto de opção usada como valor identificador para comparação e envio.
`optionLabel`	`string`	`"label"`	Chave do objeto de opção usada como rótulo de exibição nos painéis.
`locale`	`string`	`undefined`	BCP 47 (ex.: `"en"`, `"es"`, `"pt-BR"`) usado para resolver a mensagem de empty state. Sem valor, resolve pelo `lang` mais próximo na árvore, depois `<html lang>`, com fallback `"pt-BR"`.

Eventos

Evento	Componente	Payload	Descrição
`mkChange`	`mk-transfer`	`{"{ value: unknown[] }"}`	Emitido sempre que a lista do painel de destino muda — ao mover selecionados, mover todos, remover selecionados ou remover todos.

Acessibilidade

Cada painel é um <ul role="group" aria-label="{título do painel}"> contendo um mk-checkbox por item — o checkbox é o elemento focável/interativo real, não um indicador visual aninhado dentro de um item clicável.
Não há padrão de listbox nem roving tabindex: a navegação segue o comportamento nativo de checkbox, um tabindex por item.
Itens com option.disabled: true renderizam o mk-checkbox com disabled, ficando fora da navegação por teclado e não participando das operações "mover tudo".
A coluna de ações usa role="group" com aria-label="Ações de transferência"; cada botão tem aria-label descritivo.

Tecla	Comportamento
`Tab` / `Shift+Tab`	Percorre os checkboxes um a um dentro do painel — busca (se `searchable`), depois cada item, depois os botões de ação, depois o painel seguinte.
`Space`	Alterna a seleção do checkbox com foco.

Transfer

On this page