Upload

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Visão Geral

Design System

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

HTML

Controles

JS

CSS

Console

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Formatar código

Resetar código para o estado inicial

Copiar para a área de transferência

Handler fornecido pela aplicação

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

HTML

Controles

JS

CSS

Console

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Expandir controles e código

Propriedades

accept

Atributo	accept
Descrição	Tipos de arquivo permitidos (ex.: 'image/*').
Tipo	string
Valor padrão	''

capture

Atributo	capture
Descrição	Sugere a câmera usada na captura de imagem ou vídeo. O navegador pode ignorar a preferência conforme dispositivo e permissões.
Tipo	"" | "environment" | "user"
Valor padrão	---

customId

Atributo	custom-id
Descrição	Identificador único do componente. Quando omitido, um valor é gerado automaticamente. > Padrão: valor único gerado por generateUniqueId().
Tipo	string
Valor padrão	generateUniqueId()

disabled

Atributo	disabled
Descrição	Desabilita a interação com o componente.
Tipo	boolean
Valor padrão	false

existingFiles

Atributo	existing-files
Descrição	Arquivos já existentes. Quando informada, tem precedência sobre uploadFiles.
Tipo	IUploadFile[] | string
Valor padrão	---

feedbackState

Atributo	feedback-state
Descrição	Estado de feedback canônico. Quando informado, tem precedência sobre state.
Tipo	"danger" | "info" | "success" | "warning"
Valor padrão	---

files

Atributo	---
Descrição	Lista de arquivos selecionados, equivalente a HTMLInputElement.files.
Tipo	FileList
Valor padrão	null

label

Atributo	label
Descrição	Rótulo exibido acima do botão de upload.
Tipo	string
Valor padrão	'Envio de arquivo'

maxFileSize

Atributo	max-file-size
Descrição	Tamanho máximo permitido para cada arquivo, em bytes. Zero significa sem limite.
Tipo	number
Valor padrão	0

maxFiles

Atributo	max-files
Descrição	Quantidade máxima de arquivos. Zero significa sem limite.
Tipo	number
Valor padrão	0

minFiles

Atributo	min-files
Descrição	Quantidade mínima de arquivos, incluindo arquivos já enviados.
Tipo	number
Valor padrão	0

multiple

Atributo	multiple
Descrição	Indica se o componente permite a seleção de múltiplos arquivos. Quando definido como true, o usuário pode selecionar mais de um arquivo para upload.
Tipo	boolean
Valor padrão	false

name

Atributo	name
Descrição	Nome do campo enviado no formulário.
Tipo	string
Valor padrão	---

required

Atributo	required
Descrição	Se verdadeiro, o input de upload é obrigatório antes que o formulário possa ser enviado.
Tipo	boolean
Valor padrão	false

state

Atributo	state
Descrição	Estado visual: 'info', 'warning', 'danger' ou 'success'.
Tipo	"danger" | "info" | "success" | "warning"
Valor padrão	---

uploadFiles Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	upload-files
Depreciação	Use existingFiles.
Descrição
Tipo	IUploadFile[] | string
Valor padrão	[]

uploadHandler

Atributo	---
Descrição	Função assíncrona opcional fornecida pela aplicação para enviar cada arquivo. O componente fornece o arquivo, um AbortSignal e uma função de progresso, mas não conhece endpoint, autenticação nem formato de resposta.
Tipo	(context: UploadHandlerContext) => Promise<void>
Valor padrão	---

validator

Atributo	---
Descrição	Regra síncrona ou assíncrona aplicada à lista de arquivos selecionados. O componente valida File[], mas não envia arquivos nem interpreta a resposta do servidor.
Tipo	(value: File[]) => string | Promise<string>
Valor padrão	---

Slots

Nome	Descrição
"default"	Texto personalizado para o botão de upload. Se não fornecido, será exibido "Selecione o arquivo" como texto padrão. Use este slot para personalizar o texto do botão de acordo com o contexto do upload, por exemplo: "Anexar documentos", "Enviar imagens", etc.
"feedback"	Mensagem de validação, normalmente um br-message.
"helper"	Texto auxiliar exibido abaixo da superfície de seleção.
"label"	Rótulo customizado do upload. Quando utilizado, a prop label é ignorada.
"loading"	Conteúdo exibido enquanto o handler fornecido pela aplicação envia um arquivo.
"upload-list"	Permite customizar a área de listagem de arquivos. Se utilizado, substitui a lista padrão gerada pelo componente.

Eventos

Evento	Descrição	Depreciação	Propagação
brRemove Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Evento emitido quando um arquivo da lista uploadFiles (externos) é removido pelo usuário. O objeto emitido contém os dados do arquivo removido.	Use brUploadRemove.	true
brUploadCancel	Emitido quando o usuário fecha a caixa de seleção de arquivos sem escolher nada.	---	true
brUploadError	Emitido quando o uploadHandler falha ao enviar um arquivo.	---	true
brUploadProgress	Emitido quando o uploadHandler informa o progresso de um arquivo.	---	true
brUploadRemove	Evento canônico emitido quando um arquivo existente é removido.	---	true
brUploadStart	Emitido antes de o uploadHandler processar um arquivo.	---	true
brUploadSuccess	Emitido quando o uploadHandler conclui um arquivo.	---	true
brUploadValidationChange	Emitido ao iniciar e concluir a validação customizada. O detail contém validating, valid e message.	---	true
selectedFilesChange Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Emitido quando a lista de arquivos selecionados muda.	Use input/change e leia event.target.files.	true

Métodos

cancelUpload

Descrição	Cancela o envio atual iniciado pelo uploadHandler.
Assinatura	cancelUpload() => Promise<void>
Parâmetros	---

checkValidity

Descrição	Retorna true se o valor do componente for válido, caso contrário false. Se o componente for inválido, dispara um evento 'invalid'.
Assinatura	checkValidity() => Promise<boolean>
Parâmetros	---

getValidationState

Descrição	Retorna um snapshot serializável da Constraint Validation API.
Assinatura	getValidationState() => Promise<FormValidationState>
Parâmetros	---

reportValidity

Descrição	Retorna true se o valor do componente for válido, caso contrário false. Se for inválido, exibe a mensagem de erro padrão do navegador.
Assinatura	reportValidity() => Promise<boolean>
Parâmetros	---

setCustomValidity

Descrição	Define uma mensagem de validação customizada para o upload. Se a mensagem for uma string vazia, o erro customizado é limpo.
Assinatura	setCustomValidity(message: string) => Promise<void>
Parâmetros	message:

validate

Descrição	Executa o validator do upload e retorna se a lista atual é válida.
Assinatura	validate() => Promise<boolean>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"button"	Botão de seleção de arquivo.
"container"	Wrapper principal do upload.
"feedback"	Contêiner da mensagem de validação.
"file-list"	Lista de arquivos selecionados.
"helper"	Texto auxiliar do upload.
"input"	Elemento input de arquivo.
"label"	Rótulo do campo de upload.
"loading"	Estado e progresso do envio assíncrono.
"remove-button"	Botão de remoção de arquivo.

Dependências

Depende de

• br-item
• br-button
• br-icon
• br-loading
• br-message
• br-list

Gráfico

Validação

Para o contrato geral e a matriz de componentes, consulte o guia de formulários. Esta seção documenta o contrato específico do br-upload.

Use required, min-files, max-files, accept e max-file-size conforme a regra do campo. O estado é exposto em files e enviado por FormData; navegadores não permitem atribuir programaticamente um FileList.

Para rejeições de domínio, use setCustomValidity() e limpe a mensagem após uma nova seleção válida. input e change são emitidos quando a lista muda.

A mensagem é renderizada como br-message quando não existe feedback. Use o slot feedback para fornecer o conteúdo e manter a referência ARIA.

Para regras de domínio síncronas ou assíncronas, use a propriedade JavaScript validator. Ela recebe File[] e retorna uma mensagem ou null. A validação também ocorre no change, pode ser acionada por await upload.validate() e emite brUploadValidationChange.

Acessibilidade

Forneça label visível, instruções de formatos/tamanho e uma mensagem textual de erro. O botão de escolher arquivo deve ter nome acessível e ser alcançável por teclado; ofereça também remoção individual sem depender de arrastar.

Associe mensagens com aria-describedby/aria-errormessage e mantenha aria-invalid sincronizado ao mostrar erro.

Eventos nativos

Elemento HTML de referência

br-upload combina <input type="file">, botão, drop zone e lista. O host representa o campo de arquivos.

Como ouvir os eventos

const upload = document.querySelector('br-upload');
upload.addEventListener('change', () => console.log(upload.files));

Eventos nativos suportados

Evento	Quando ocorre	Bubbles	Composed	Cancelable	Host	Observações
cancel	seletor de arquivos é fechado sem nova seleção	conforme o browser	conforme o browser	Não	Sim	Redisparado uma vez no host quando encapsulado pelo Shadow DOM.
change	seleção/drop/remoção é confirmada	Sim	Sim	Não	Sim	Após input.
input	lista de arquivos muda	Sim	Sim	Não	Sim	Sintético após atualizar files; uma ocorrência.
click e foco	botão/input são ativados	conforme o tipo	Sim	conforme o tipo	Sim	Botão encaminha a seleção ao file input.
drag/drop	arquivo cruza ou é solto na drop zone	conforme o tipo	conforme o tipo	conforme o tipo	Parcial	Drop atual é tratado pelo botão interno.

Eventos não suportados ou ainda não caracterizados

Drag and drop real e cancel em Firefox/WebKit aguardam caracterização. Escrita em files, reset e inicialização são silenciosos. Eventos redisparados são sintéticos e não prometem isTrusted.

Eventos customizados

selectedFilesChange e brRemove são aliases depreciados. brUploadRemove representa remoção de arquivo já existente.

Valor, frameworks e acessibilidade

Leia event.target.files; FormData recebe cada arquivo pelo name. React usa ref, Angular usa file value accessor e Vue usa o model de arquivos. Label, botão e input compartilham o nome acessível.

Evidência de teste

src/shared/platform-contract.e2e.tsx usa userEvent.upload e cobre ordem, ausência de duplicação, target, caminho e FormData em Chromium headless. _tests/upload.e2e.tsx cobre lista, remoção, capture, cancel e handler de drop.

Documentações relacionadas

Consulte o guia geral de dados remotos para integrar uploadHandler, progresso, cancelamento, validação e tratamento de erros sem colocar endpoint ou autenticação dentro do componente.

Também são relacionados:

• Input e Textarea, para validação assíncrona de campos de formulário;
• Formulários, para validade nativa e submissão;
• Eventos, para escolher entre eventos nativos e eventos específicos do upload.