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

O componente br-upload é o elemento oficial do GovBR-DS para seleção, anexação e envio de arquivos em formulários, com suporte a seleção múltipla, área de arrastar-e-soltar (drag-and-drop) e acompanhamento de progresso.

Para que serve

• Seleção e anexação de arquivos: Permite anexar documentos, planilhas, imagens ou outros formatos através do seletor nativo do sistema operacional ou por arrastar e soltar.
• Validação de tipos e tamanhos: Valida extensões permitidas (accept) e tamanho máximo por arquivo (max-file-size), informando erros de validação de forma acessível.
• Listagem visual e remoção: Exibe a lista de arquivos selecionados com nome, tamanho formatado (KB/MB), barra de progresso individual e botão de exclusão.
• Integração com formulários: Integrado nativamente via formAssociated, permitindo submissão tradicional de formulários ou upload assíncrono programático.

Quando utilizar

• Utilize quando:
  • A pessoa usuária precisar enviar comprovantes, relatórios, fotografias ou documentos digitais.
  • For necessário limitar e validar os tipos de arquivo e o tamanho máximo antes do envio ao servidor.
• Evite e prefira outro componente quando:
  • A captura for exclusivamente de texto ou URLs externas (prefira br-input).

Estrutura e Slots

O br-upload possui estrutura rica com múltiplos slots:

• default: Slot para texto personalizado do botão de upload (padrão: "Selecione o arquivo").
• upload-list: Slot opcional para substituição da área padrão de listagem de arquivos.
• label: Slot para personalização do rótulo do campo.
• helper: Slot para instruções ou restrições de formato/tamanho exibidas abaixo do campo.
• feedback: Slot para mensagens de validação e erro (como br-message).
• loading: Slot para indicador exibido durante o envio assíncrono dos arquivos.

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

PadrãoMúltiplos arquivosHandler da aplicação

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

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. Valores inválidos são ignorados. 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. Cada item deve ter name não vazio e size numérico não negativo opcional. Use JSON no atributo HTML ou um array por property binding.
Exemplo de uso	<br-upload existing-files='[{"name":"relatorio.pdf","size":204800}]'></br-upload> const upload = document.querySelector('br-upload'); upload.existingFiles = [{ name: 'relatorio.pdf', size: 204800 }];
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. Deve ser um inteiro não negativo; valores inválidos usam 0.
Tipo	number
Valor padrão	0

maxFiles

Atributo	max-files
Descrição	Quantidade máxima de arquivos. Zero significa sem limite. Deve ser um inteiro não negativo; valores inválidos usam 0.
Tipo	number
Valor padrão	0

minFiles

Atributo	min-files
Descrição	Quantidade mínima de arquivos, incluindo arquivos já enviados. Deve ser um inteiro não negativo; valores inválidos usam 0.
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'. Valores inválidos não aplicam estado.
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	Lista de arquivos já enviados (para edição ou pré-visualização). Pode ser uma string JSON ou um array de objetos IUploadFile. Cada item deve ter name não vazio e size numérico não negativo opcional; itens inválidos são ignorados.
Exemplo de uso	<!-- Compatibilidade legada; prefira existing-files. --> <br-upload upload-files='[{"name":"relatorio.pdf","size":204800}]'></br-upload>
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.
Exemplo de uso	const upload = document.querySelector('br-upload'); upload.uploadHandler = ({ file, signal, onProgress }) => enviarArquivo({ file, signal, onProgress });
Tipo	(context: UploadHandlerContext) => Promise<void>
Valor padrão	---

validator Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

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.
Exemplo de uso	const upload = document.querySelector('br-upload'); upload.validator = (files) => files.every((file) => file.size <= 5_000_000) ? null : 'Cada arquivo deve ter até 5 MB';
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 Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	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 Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

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.

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/contracts/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.

Atributos nativos

O host FACE aceita name, form, required e disabled. accept, multiple e capture são encaminhados ao <input type="file">; capture aceita "", "user" ou "environment".

form funciona como atributo nativo do host e não é uma prop Stencil. showPicker() não é exposto: a seleção de arquivos continua pela ativação do botão, respeitando a user activation do navegador.

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.

Dependências

Depende de

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

Gráfico