Upload

Campo de upload de arquivos com drag-and-drop e validação nativa de formulário (`mk-upload`).

Componente Experimental

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

O mk-upload é um campo de upload de arquivos form-associated que suporta drag-and-drop, clique para selecionar e validação integrada (accept, tamanho máximo, quantidade máxima). Participa nativamente de <form> via ElementInternals — sem configuração adicional.

Padrão

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

<MkUpload label="Anexo" supportText="Formatos aceitos: qualquer arquivo" />

<mk-upload label="Anexo" helper-text="Formatos aceitos: qualquer arquivo"></mk-upload>

Múltiplos arquivos

Ative multiple para permitir seleção de vários arquivos. Use maxFiles para limitar a quantidade.

<MkUpload label="Imagens" multiple maxFiles={5} supportText="Até 5 imagens" />

<mk-upload label="Imagens" multiple max-files="5" helper-text="Até 5 imagens"></mk-upload>

Tipos aceitos

Use accept com a mesma sintaxe do atributo nativo <input accept>.

<MkUpload label="Documentos" accept="application/pdf,.docx" supportText="Apenas PDF e DOCX" />

<mk-upload label="Documentos" accept="application/pdf,.docx" helper-text="Apenas PDF e DOCX"></mk-upload>

Validação de tamanho

Use maxSize (em bytes) para rejeitar arquivos grandes. Arquivos rejeitados disparam mkError.

<MkUpload
  label="Imagem de perfil"
  accept="image/*"
  maxSize={2 * 1024 * 1024}
  supportText="Máximo 2 MB · Apenas imagens"
  onMkError={(e) => console.warn('Rejeitado:', e.detail)}
/>

<mk-upload
  label="Imagem de perfil"
  accept="image/*"
  max-size="2097152"
  helper-text="Máximo 2 MB · Apenas imagens"
  (mkError)="onError($event)"
></mk-upload>

Estado desabilitado

<MkUpload label="Arquivo" disabled supportText="Upload indisponível" />

<mk-upload label="Arquivo" disabled helper-text="Upload indisponível"></mk-upload>

Dropzone customizada

Use o slot padrão para substituir o conteúdo interno da zona de drop.

<MkUpload label="Foto">
  <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '8px' }}>
    <strong>Arraste sua foto aqui</strong>
    <span style={{ fontSize: '12px' }}>ou clique para escolher</span>
  </div>
</MkUpload>

<mk-upload label="Foto">
  <div style="display:flex; flex-direction:column; align-items:center; gap:8px">
    <strong>Arraste sua foto aqui</strong>
    <span style="font-size:12px">ou clique para escolher</span>
  </div>
</mk-upload>

Formulários

mk-upload é form-associated — participa nativamente de <form> sem necessidade de JavaScript adicional.

<form id="meu-form">
  <mk-upload name="arquivo" required label="Comprovante"></mk-upload>
  <button type="submit">Enviar</button>
</form>

O valor é submetido como FormData com uma entrada por arquivo, usando a prop name.
required aciona a validação nativa: o formulário não submete enquanto nenhum arquivo estiver selecionado.
form.reset() limpa a lista de arquivos automaticamente.
mk-upload reporta erros via setValidity() — compatível com APIs nativas (checkValidity(), reportValidity()).

Props — mk-upload

Prop	Tipo	Padrão	Descrição
`name`	`string`	—	Nome do campo na submissão do formulário.
`accept`	`string`	—	Tipos aceitos. Mesma sintaxe de `<input accept>` (ex: `"image/*, .pdf"`).
`multiple`	`boolean`	`false`	Permite selecionar múltiplos arquivos.
`maxSize`	`number`	`0`	Tamanho máximo por arquivo em bytes. `0` = sem limite.
`maxFiles`	`number`	`0`	Quantidade máxima de arquivos (quando `multiple`). `0` = sem limite.
`required`	`boolean`	`false`	Torna o campo obrigatório na validação do formulário.
`disabled`	`boolean`	`false`	Desabilita toda interação com o campo.
`label`	`string`	—	Rótulo exibido acima da zona de drop.
`supportText`	`string`	—	Texto auxiliar exibido abaixo do campo quando não há erro.
`errorMessage`	`string`	—	Mensagem de erro externa (da aplicação). Sobrepõe o erro interno.
`locale`	`string`	—	Tag BCP 47 para i18n.

Eventos

Evento	Componente	Payload	Descrição
`mkChange`	`mk-upload`	`File[]`	Emitido sempre que a lista de arquivos muda (adição ou remoção).
`mkAdd`	`mk-upload`	`File[]`	Emitido ao adicionar novos arquivos aceitos.
`mkRemove`	`mk-upload`	`File`	Emitido ao remover um arquivo da lista.
`mkError`	`mk-upload`	`{ type: "maxSize" \| "maxFiles" \| "accept", files: File[] }`	Emitido quando arquivos são rejeitados pela validação.

Slots

Componente	Slot	Descrição
`mk-upload`	(default)	Conteúdo customizado da zona de drop. Substitui o ícone e texto padrão quando fornecido.

Acessibilidade

A zona de drop tem role="button", tabindex="0" e aria-label descritivo.
aria-dropeffect="copy" é aplicado enquanto o campo estiver habilitado.
aria-disabled="true" é aplicado quando disabled.
Enter e Space abrem o seletor de arquivos nativo.
O <input type="file"> interno é oculto com aria-hidden="true" — o controle de acessibilidade é a zona de drop.
Cada botão de remover tem aria-label="Remover {nome do arquivo}".
Mensagens de erro usam role="alert" para leitura imediata por leitores de tela.

Upload

On this page