FileUpload

Tier: own

ImportCopy Anchor Link

import { FileUpload } from '@nizivo/react/file-upload';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/button.css and @nizivo/react/css/icon-button.css and @nizivo/react/css/inline-error.css and @nizivo/react/css/progress-bar.css
import '@nizivo/react/css/file-upload.css';

Static or interactiveCopy Anchor Link

Client. FileUpload is a client component that reads its Field through FieldScope, so a page with one also loads FieldScope and React Aria's drop hook. Its server HTML is complete and works before hydration: a native <input type="file"> covers the dropzone, so a click opens the picker and a file dropped on it is chosen natively, and a form submits the chosen files under name. How to choose.

In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.

The form submits the filesCopy Anchor Link

FileUpload never uploads anything. The native input holds the chosen files, and the component writes the list back into it after every pick, drop and remove, so a form (a Server Action, or method="post" with encType="multipart/form-data") submits exactly the files you see. With multiple, each pick or drop adds to the list; without it, a new file replaces the old one.

A file that accept does not match, or that is larger than maxSize (in bytes; 1 MB is 1,000,000), is not added: its message appears under the dropzone, is read by screen readers and describes the input. onReject receives the refused files. Check the files on the server too: before hydration, the browser submits whatever was chosen.

Inside a Field, the Field's label names the input, its description and errors describe it, and required is native: a submit with no file shows the Field's valueMissing message, and choosing a file withdraws it. A click on the Field's label focuses the dropzone without opening the picker.

Uploading as files are chosenCopy Anchor Link

When your code sends each file as soon as it is chosen, onFilesChange gives every held file with an id the component assigned; key your requests by it, and pass each file's state back as items:

'use client';
const [items, setItems] = useState<FileUploadItem[]>([]);

<FileUpload
  multiple
  items={items}
  onFilesChange={(files) => {
    for (const { id, file } of files) startUpload(id, file, setItems);
  }}
  onRetry={(id) => retryUpload(id)}
  onCancel={(id) => abortUpload(id)}
  onRemove={(id) => deleteUpload(id)}
/>;

An item is { id, status, progress, error }, with status uploading (a ProgressBar, determinate when you pass progress, 0 to 100), complete or error (with a Retry button). While any item is uploading, the dropzone's line shows how many are done. Cancel and Remove take a held file out of the list and the input before they call you. An item whose id matches no held file is listed too, after the held ones, so an edit form can show files uploaded earlier; give it a name.

Leave name off the FileUpload when you upload this way, or the form submits the files a second time; submit your upload ids in your own hidden inputs.

StringsCopy Anchor Link

Every string is in labels, with English defaults: prompt ({browse} marks where the brand coloured word goes), browse, release (shown while files are dragged over), summary, the rejection messages wrongType, tooLarge ({name}, {max}) and tooMany, and the list's remove, retry, cancel, uploading, complete and failed. Sizes are formatted for locale. Pass hint for the line under the prompt and icon for the mark above it.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { FileUpload } from '@nizivo/react/file-upload';

/** Stands in for an `@nizivo/icons` glyph (Lucide's `upload`). */
function UploadMark(): JSX.Element {
  return (
    <svg
      viewBox="0 0 24 24"
      width="1em"
      height="1em"
      fill="none"
      stroke="currentColor"
      strokeWidth={1.92}
      strokeLinecap="round"
      strokeLinejoin="round"
    >
      <path d="M12 3v12" />
      <path d="m17 8-5-5-5 5" />
      <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
    </svg>
  );
}

export function FileUploadExample(): JSX.Element {
  return (
    <div style={{ maxInlineSize: 400 }}>
      <Field
        label="Product images"
        required
        messages={{ valueMissing: 'Add at least one product image.' }}
      >
        <FileUpload
          name="images"
          accept="image/png,image/jpeg,image/webp"
          multiple
          maxSize={20_000_000}
          icon={<UploadMark />}
          hint="PNG, JPG or WebP, up to 20 MB"
          labels={{ prompt: 'Drop product images or {browse}' }}
        />
      </Field>
    </div>
  );
}

import type { JSX } from 'react';
import { FileUpload } from '@nizivo/react/file-upload';

/** Stands in for an `@nizivo/icons` glyph (Lucide's `upload`). */
function UploadMark(): JSX.Element {
  return (
    <svg
      viewBox="0 0 24 24"
      width="1em"
      height="1em"
      fill="none"
      stroke="currentColor"
      strokeWidth={1.92}
      strokeLinecap="round"
      strokeLinejoin="round"
    >
      <path d="M12 3v12" />
      <path d="m17 8-5-5-5 5" />
      <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
    </svg>
  );
}

export function FileUploadStatesExample(): JSX.Element {
  return (
    <div style={{ maxInlineSize: 400 }}>
      <FileUpload
        aria-label="Order attachments"
        multiple
        icon={<UploadMark />}
        hint="PDF or images, up to 10 MB"
        items={[
          { id: 'a', name: 'packing-slip.pdf', size: 248_000, status: 'uploading', progress: 60 },
          { id: 'b', name: 'invoice-1042.pdf', size: 1_200_000, status: 'complete' },
          {
            id: 'c',
            name: 'damaged-box.jpg',
            size: 3_400_000,
            status: 'error',
            error: 'The connection dropped',
          },
        ]}
      />
    </div>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { FileUpload } from '@nizivo/react/file-upload';

/** Stands in for an `@nizivo/icons` glyph (Lucide's `upload`). */
function UploadMark(): JSX.Element {
  return (
    <svg
      viewBox="0 0 24 24"
      width="1em"
      height="1em"
      fill="none"
      stroke="currentColor"
      strokeWidth={1.92}
      strokeLinecap="round"
      strokeLinejoin="round"
    >
      <path d="M12 3v12" />
      <path d="m17 8-5-5-5 5" />
      <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
    </svg>
  );
}

export function FileUploadDisabledExample(): JSX.Element {
  return (
    <div style={{ maxInlineSize: 400 }}>
      <Field label="Invoice" disabled description="Unlocks once the order is paid.">
        <FileUpload name="invoice" accept=".pdf" icon={<UploadMark />} hint="PDF, up to 5 MB" />
      </Field>
    </div>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

FileUploadFile type

import type { FileUploadFile } from '@nizivo/react/file-upload'

A file the component holds (and its input submits), with the id the component gave it.

Name	Type	Default	Description
filerequired	File	–
idrequired	string	–	Stays the same while the file is listed. Key your items and upload requests by it.

FileUploadItem type

import type { FileUploadItem } from '@nizivo/react/file-upload'

An item's upload state, from the app, which does the uploading. Matched to a held file by id; an item whose id matches no held file is listed too, after the held files (a file uploaded earlier, shown on an edit form).

Name	Type	Default	Description
error	string	labels.failed	The message while status is error.
idrequired	string	–
name	string	–	Shown in the list. Defaults to the held file's name; an item that matches no held file needs one, or its id is shown.
progress	number	–	0 to 100 while uploading; absent, the bar is indeterminate.
size	number	–	In bytes, shown beside the name. Defaults to the held file's size.
status	FileUploadStatus "uploading" | "complete" | "error"	–

FileUploadLabels type

import type { FileUploadLabels } from '@nizivo/react/file-upload'

Strings FileUpload renders (§16.4): serialisable, English defaults. {name} is a file's name, {max} the formatted maxSize, {browse} where the browse word goes, {complete} and {total} counts.

Name	Type	Default	Description
browserequired	string	'browse'	The word that reads as the picker's button, in the brand colour.
cancelrequired	string	'Cancel'	An item uploading.
completerequired	string	'Uploaded'	A complete item's status.
failedrequired	string	'Upload failed'	An item in error with no error text.
listrequired	string	'Chosen files'	The list's accessible name.
promptrequired	string	'Drop files here or {browse}'	The dropzone's line.
releaserequired	string	'Release to add files'	Replaces the prompt while a drag with files is over the dropzone.
removerequired	string	'Remove {name}'	Each item's remove button.
retryrequired	string	'Retry'	An item in error.
summaryrequired	string	'{complete} of {total} uploaded'	Replaces the prompt while an item is uploading.
tooLargerequired	string	'{name} is larger than {max}.'	A file over maxSize.
tooManyrequired	string	'{name} was not added: choose one file.'	Without multiple, every file of a drop after the first.
uploadingrequired	string	'Uploading {name}'	An uploading item's progress bar.
wrongTyperequired	string	'{name} is not an accepted file type.'	A file accept does not match.

FileUploadProps type

import type { FileUploadProps } from '@nizivo/react/file-upload'

The props of FileUpload, listed above.

FileUploadRejection type

import type { FileUploadRejection } from '@nizivo/react/file-upload'

Name	Type	Default	Description
filerequired	File	–
reasonrequired	FileUploadRejectionReason "type" | "size" | "count"	–

FileUploadRejectionReason type

import type { FileUploadRejectionReason } from '@nizivo/react/file-upload'

Why a chosen or dropped file was not added.

type FileUploadRejectionReason = "type" | "size" | "count"

FileUploadStatus type

import type { FileUploadStatus } from '@nizivo/react/file-upload'

Where an item's upload is. Absent on an item: chosen, not sent yet.

type FileUploadStatus = "uploading" | "complete" | "error"

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-file-upload, .nz-file-upload-browse, .nz-file-upload-dropzone, .nz-file-upload-hint, .nz-file-upload-icon, .nz-file-upload-input, .nz-file-upload-item, .nz-file-upload-item-actions, .nz-file-upload-item-complete, .nz-file-upload-item-error, .nz-file-upload-item-name, .nz-file-upload-item-size, .nz-file-upload-item-status, .nz-file-upload-list, .nz-file-upload-messages, .nz-file-upload-prompt, .nz-glyph, .nz-progress-bar.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• file-upload-dropzone: draws the outline when the hidden input inside it has keyboard focus.

In forced-colours mode these states keep a visible system colour: file-upload-dropzone[data-drag-over] (outline).

KeyboardCopy Anchor Link

Source: A native <input type="file"> (file-upload.client.tsx); react-aria 3.53.1 useDrop through _engines/react-aria/file-upload.client.tsx for the drop target only. Dropping is pointer-only; the input is the keyboard and screen-reader path. Checked by the browser lane (test/browser/file-upload.spec.tsx) in Chromium.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 7275:11548
• Ghost masters: none