Envio de arquivos
Área de arrastar-e-soltar com lista de arquivos, limite por tamanho e erro. `error` (mensagem) equivale a `invalid` + mensagem; `invalid` sozinho marca o campo sem texto próprio. Com `name`/`required`, funciona em `<form>` nativo: o `input.files` acompanha a lista mostrada (escolha, soltar e `value` do pai). Cada escolha substitui a seleção anterior, como no input nativo; para juntar arquivos de várias escolhas, controle `value` no pai. No Safari anterior à 16.4 (sem o evento `cancel`), cancelar o seletor depois de já haver arquivo esvazia o `input.files`, embora a lista continue mostrando o arquivo, e ele não vai no envio.
Quando usar
Sempre que o usuário precisar enviar um ou mais arquivos: currículo, comprovante de residência, imagem de perfil, documento escaneado. O componente valida tipo e tamanho antes do envio, evitando idas e voltas ao servidor.
Quando não usar
Para upload de imagem apenas para visualização (crop, avatar), use um componente dedicado de upload de imagem. Para upload de vários arquivos com progresso individual e fila, considere um componente mais especializado.
Acessibilidade
- O input nativo está acessível via sr-only e pode ser acionado por Enter ou Espaço quando o invólucro recebe foco.
- A mensagem de erro usa role="alert" para ser anunciada imediatamente pelo leitor de tela.
- O estado de arraste é sinalizado visualmente, mas a ação de clique sempre está disponível como alternativa.
- Cada arquivo na lista exibe nome e tamanho em texto, sem depender de ícones.
Props
| Prop | Tipo | Descrição |
|---|---|---|
accept | string | Tipos aceitos (ex.: .pdf,image/*). |
maxSize | number | Limite em bytes. Excede → erro. |
label | string | Rótulo acima da área de arraste. |
hint | string | Texto auxiliar abaixo da área. |
error | string | Mensagem de erro controlada externamente. |
onChange | (files: File[]) => void | Callback quando os arquivos mudam. |
Preview
Variantes e composição
| Prop / grupo | Valores |
|---|---|
props | accept · maxSize · label · hint · error · invalid · onValueChange(files) · value · multiple · id · name · required · disabled · inputProps · labels |
removidas na 4.0 | onChange(files) → use onValueChange |