Transfer

Componente de transferência dual-list (`mk-transfer`) para mover itens entre dois painéis de origem e destino.

Componente Experimental

Este componente é experimental — não possui design aprovado no Figma. A API pode mudar entre versões.

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 (selecionados via checkbox) ou em massa. 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 de busca em cada painel. O filtro atua apenas na exibição — não move itens automaticamente.

<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 checkboxes e 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>

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` 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 de busca em cada painel. O filtro atua apenas na exibição — não move itens.
`disabled`	`boolean`	`false`	Desabilita todos os checkboxes 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.

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 usa role="listbox" e aria-multiselectable="true", comunicando ao leitor de tela que múltiplos itens podem ser selecionados.
A coluna de botões de ação usa role="group" com aria-label="Ações de transferência".
Cada botão de ação tem aria-label descritivo ("Mover selecionados para destino", "Mover todos para destino", etc.).
A seleção de itens é feita via mk-checkbox, que gerencia aria-checked automaticamente incluindo o estado mixed no "selecionar todos".
Itens com disabled: true recebem disabled no checkbox interno e não são alcançáveis por teclado.
O estado disabled global é refletido no atributo host, permitindo estilização via :host([disabled]).

Tecla	Comportamento
`Tab`	Move o foco sequencialmente entre checkboxes e botões de ação.
`Space`	Alterna a seleção do checkbox em foco.
`Enter`	Ativa o botão de ação em foco (equivalente ao clique).

Transfer

On this page