Introducción

Una zona de arrastre y selector de archivos para elegir uno o más archivos, con arrastrar y soltar, validación del lado del cliente (tipo/tamaño/cantidad) y una lista de vista previa en vivo —todo compuesto a partir de partes equivalentes a Ark UI sobre un <input type="file"> nativo, de modo que el formulario sigue funcionando con JavaScript deshabilitado.

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"
    />
  );
}

Composición personalizada

La composición por defecto (props label + dropzoneText + triggerText) cubre el caso común. Pasa children explícitos para tener control total sobre el layout —sustituye cualquier subconjunto de las partes de abajo:

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>
  );
}

Constructor de páginas CMS

Este componente está disponible como un bloque file-upload (alias fileUpload) en el Constructor 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 y maxFileSize se convierten de cadenas a números por el renderizador; todos los demás campos se transfieren directamente a FileUpload. Siempre se renderiza como interactive en el Constructor de páginas.

Propiedades

Root

Composición por defecto

Estos props solo aplican cuando se omite children —entonces FileUpload renderiza Label + Dropzone + Trigger + List + HiddenInput por ti.

Subcomponentes

FileUpload es un componente compuesto —cada parte de abajo lee del contexto de FileUpload.Root, por lo que solo funcionan anidadas dentro de él (o dentro de un FileUpload.Item para las partes con alcance de elemento).

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

formatBytes(bytes, locale?) y los tipos FileAccept / FileError / FileRejection / FileChangeDetails / FileUploadTranslations también se exportan para quienes construyan una composición totalmente personalizada.

Validación

Cada archivo seleccionado se comprueba en orden y se rechaza en la primera regla fallida; validate se ejecuta al final, después de que pasen todas las comprobaciones integradas:

Con maxFiles={1} (por defecto), un nuevo archivo aceptado reemplaza la selección actual. Con maxFiles > 1, los nuevos archivos se añaden a la selección existente hasta el límite.

Accesibilidad

• Dropzone renderiza role="button" con aria-label de translations.dropzone, aria-disabled cuando está deshabilitado, y es operable con teclado (tabIndex={0}, Enter/Space abre el selector de archivos).
• Label y Trigger son elementos <label for> reales vinculados al id del input oculto, por lo que hacer clic en cualquiera de los dos abre el selector de archivos nativo incluso antes de la hidratación.
• ItemDeleteTrigger y ClearTrigger obtienen sus aria-label de translations.deleteFile(file) / translations.clearFiles, sobrescribibles mediante el prop translations.
• data-disabled / data-invalid / data-required / data-readonly / data-dragging se reflejan en cada parte para estilo y estado de tecnología de asistencia.