Introdução

Uma zona de soltar e seletor de arquivos para escolher um ou mais arquivos, com arrastar e soltar, validação do lado do cliente (tipo/tamanho/quantidade) e uma lista de preview ao vivo — tudo composto a partir de partes equivalentes ao Ark UI sobre um <input type="file"> nativo, de modo que o formulário continua funcionando com JavaScript desabilitado.

Uso

import { FileUpload } from "../components/ui";

export default function MyPage() {
  return (
    <FileUpload
      label="Upload Images"
      name="images"
      accept="image/*"
      maxFiles={2}
      dropzoneText="Drag and drop or browse files"
    />
  );
}

Composição personalizada

A composição padrão (props label + dropzoneText + triggerText) cobre o caso comum. Passe children explícitos para ter controle total sobre o layout — substitua qualquer subconjunto das partes abaixo:

import { FileUpload } from "../components/ui";

export default function MyPage() {
  return (
    <FileUpload name="attachments" maxFiles={5} accept="image/*,.pdf">
      <FileUpload.Label>Attachments</FileUpload.Label>
      <FileUpload.Dropzone>
        <span>Drop files here, or</span>
        <FileUpload.Trigger>browse</FileUpload.Trigger>
      </FileUpload.Dropzone>
      <FileUpload.List showSize clearable />
      <FileUpload.ClearTrigger>Clear all</FileUpload.ClearTrigger>
      <FileUpload.HiddenInput />
    </FileUpload>
  );
}

Construtor de páginas CMS

Este componente está disponível como um bloco file-upload (aliás fileUpload) no Construtor de páginas (content/pages/*.json):

{
  "type": "file-upload",
  "label": "Resume",
  "name": "resume",
  "accept": ".pdf,.docx",
  "maxFiles": 1,
  "maxFileSize": 5242880,
  "dropzoneText": "Drag your file(s) here",
  "triggerText": "Open file picker",
  "showSize": true,
  "clearable": true
}

maxFiles e maxFileSize são convertidos de strings para números pelo renderizador; todos os outros campos são repassados diretamente para FileUpload. Ele sempre renderiza interactive no Construtor de páginas.

Propriedades

Root

Composição padrão

Esses props só se aplicam quando children é omitido — então FileUpload renderiza Label + Dropzone + Trigger + List + HiddenInput para você.

Subcomponentes

FileUpload é um componente composto — cada parte abaixo lê do contexto de FileUpload.Root, então elas só funcionam aninhadas dentro dele (ou dentro de um FileUpload.Item para as partes com escopo de item).

import { FileUpload, formatBytes } from "../components/ui";

formatBytes(bytes, locale?) e os tipos FileAccept / FileError / FileRejection / FileChangeDetails / FileUploadTranslations também são exportados para quem estiver construindo uma composição totalmente personalizada.

Validação

Cada arquivo selecionado é verificado em ordem e rejeitado na primeira regra que falhar; validate é executado por último, depois que todas as verificações integradas passarem:

Com maxFiles={1} (padrão), um novo arquivo aceito substitui a seleção atual. Com maxFiles > 1, os novos arquivos são anexados à seleção existente até o limite.

Acessibilidade

• Dropzone renderiza role="button" com aria-label de translations.dropzone, aria-disabled quando desabilitado, e é operável por teclado (tabIndex={0}, Enter/Space abre o seletor de arquivos).
• Label e Trigger são elementos <label for> reais vinculados ao id do input oculto, então clicar em qualquer um deles abre o seletor de arquivos nativo mesmo antes da hidratação.
• ItemDeleteTrigger e ClearTrigger obtêm seus aria-label de translations.deleteFile(file) / translations.clearFiles, sobrescritíveis por meio do prop translations.
• data-disabled / data-invalid / data-required / data-readonly / data-dragging são espelhados em cada parte para estilo e estado de tecnologia assistiva.