File upload

01Preview

Change the controls, then drop or browse for a file. The preview renders the real dropzone and reports what it received. Nothing on this page uploads: files stay in your browser.

import { FileUpload } from '@nuton/ui'

<FileUpload
  hint="PDF, DOCX, or PPTX, up to 20 MB."
  accept=".pdf,.docx,.pptx"
  multiple
  onFilesSelected={(files) => startUploads(files)}
  onFilesRejected={(files) => explainRejection(files)}
/>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

Peer dependencies: react and react-dom 18 or later. @remixicon/react supplies the upload, status and action icons (D1).

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

3. Bring your own upload code

The components don't send files anywhere. FileUpload hands you the chosen File objects; your code uploads them and passes each file's status and progress to FileUploadItem. Map --nu-font-body to your loaded Inter font as described on the Button page.

03Usage

import { useState } from 'react'
import { FileUpload, FileUploadItem, FileUploadList } from '@nuton/ui'

type Upload = { id: string; file: File; progress: number; status: 'uploading' | 'completed' | 'error' }

export function LessonMaterials({ upload }: { upload: (file: File, onProgress: (p: number) => void) => Promise<void> }) {
  const [uploads, setUploads] = useState<Upload[]>([])
  const update = (id: string, patch: Partial<Upload>) =>
    setUploads((list) => list.map((u) => (u.id === id ? { ...u, ...patch } : u)))

  const start = (files: File[]) =>
    files.forEach((file) => {
      const id = crypto.randomUUID()
      setUploads((list) => [...list, { id, file, progress: 0, status: 'uploading' }])
      upload(file, (progress) => update(id, { progress }))
        .then(() => update(id, { status: 'completed' }))
        .catch(() => update(id, { status: 'error' }))
    })

  return (
    <>
      <FileUpload hint="PDF, DOCX, or PPTX, up to 20 MB." accept=".pdf,.docx,.pptx" multiple onFilesSelected={start} />
      <FileUploadList aria-label="Lesson materials">
        {uploads.map((u) => (
          <FileUploadItem
            key={u.id}
            fileName={u.file.name}
            fileSize={u.file.size}
            status={u.status}
            progress={u.progress}
            onRemove={() => setUploads((list) => list.filter((x) => x.id !== u.id))}
          />
        ))}
      </FileUploadList>
    </>
  )
}

• FileUpload only reports files through onFilesSelected. Upload state lives in your code; FileUploadItem just displays it.
• Always pass a hint that matches accept and your size limit. There's no default, because only you know the rules.
• accept also filters dropped files. Handle onFilesRejected and tell people why a file wasn't added.
• The component doesn't check file size. Check it yourself and show the reason with status="error" and statusText.
• Give every item an onRemove, and an onCancel while uploading if your upload can be stopped. No handler means no button.

04Variants and sizes

File upload is four parts: the FileUpload dropzone, a FileUploadItem card per file, FileUploadList to stack them, and the FileFormatIcon inside each card. Items come in two densities; the format icon has types, colours, sizes and two appearances.

Dropzone text and icon

The title and button label have English defaults from Figma. Override them to translate, or to fit a specific upload such as a space cover image.

<FileUpload
  title="Add a cover image for your space"
  hint="JPEG or PNG, at least 1200 × 600 px, up to 5 MB."
  browseLabel="Choose image"
  icon={<RiImageAddLine />}
  accept="image/jpeg,image/png"
  onFilesSelected={setCover}
/>

Item text

The size reads from fileSize, or “uploaded of total” when you also pass bytesUploaded. sizeText and statusText replace the defaults, for example with a specific error.

<FileUploadList aria-label="Item text examples">
  <FileUploadItem fileName="cell-structure.pdf" fileSize={1_240_000} bytesUploaded={496_000} progress={40} />
  <FileUploadItem fileName="week-3-reading.docx" status="completed" fileSize={86_000} />
  <FileUploadItem fileName="field-trip-recording.mp4" status="error" fileSize={48_000_000} statusText="File too large. The limit is 20 MB." />
  <FileUploadItem fileName="quiz-answers" status="completed" sizeText="12 questions" formatLabel="QUIZ" formatColor="teal" />
</FileUploadList>

These items have no handlers, so they show no buttons. Sizes use Figma's units (B, KB, MB) in 1024 steps. The number is formatted in English by default; pass locale to format the digits for another language.

Translated strings

<FileUploadItem
  fileName="cours-photosynthese.pdf"
  fileSize={2_400_000}
  bytesUploaded={1_800_000}
  progress={75}
  locale="fr"
  lang="fr"
  labels={{
    uploading: 'Envoi en cours…',
    sizeOf: (uploaded, total) => `${uploaded} sur ${total}`,
  }}
/>

Set lang on the item, or a parent, when its strings differ from the page language. The remaining strings (completed, error, retry, cancel, remove) are listed under FileUploadItemLabels.

Compact card

density="compact" is Figma's attached-file card (File Upload Cards [1.1], 117:1055): 10px padding, a red delete button, and only the size once the file is uploaded (“Completed” is still announced to screen readers). Use it for files already attached to a lesson or message. URLs work too: YouTube and web links get their own icons.

<FileUploadList aria-label="Lesson materials">
  <FileUploadItem density="compact" fileName="Design System! Ep. 1.pptx" status="completed" fileSize={122_880} onRemove={remove} />
  <FileUploadItem density="compact" fileName="https://youtu.be/dQw4w9WgXcQ" status="completed" sizeText="Video · 12:04" onRemove={remove} />
  <FileUploadItem density="compact" fileName="https://nuton.app/guides/photosynthesis" status="completed" sizeText="Web page" onRemove={remove} />
  <FileUploadItem density="compact" fileName="lab-results.xlsx" fileSize={2_400_000} bytesUploaded={900_000} progress={38} onCancel={cancel} />
</FileUploadList>

These examples have no handlers, so they show no buttons. With onRemove, the compact card shows Figma's red delete button.

Format icon types

Figma's File Format 2 has seven types: a coloured badge with short text, or an icon for YouTube and web links, in a soft tile: 36px in Figma, 40px by default in code (P4). FileUploadItem picks the type from the file name or URL with getFileFormat; use FileFormatIcondirectly in your own lists. Six more types are code-only, for files Figma doesn't cover.

// Figma types
<FileFormatIcon type="pdf" />
<FileFormatIcon type="ppt" />
<FileFormatIcon type="xls" />
<FileFormatIcon type="doc" />
<FileFormatIcon type="txt" />
<FileFormatIcon type="youtube" />
<FileFormatIcon type="link" />

// Code-only types (FC-21): pass the extension as the label
<FileFormatIcon type="image" label="PNG" />
<FileFormatIcon type="video" label="MP4" />
<FileFormatIcon type="audio" label="MP3" />
<FileFormatIcon type="archive" label="ZIP" />
<FileFormatIcon type="code" label="JSON" />
<FileFormatIcon type="file" />                 // unknown, no extension

Format icon sizes and appearance

40 is the default (P4) and 36 is Figma's size. 24, 32 and 48 keep the same proportions (badge two-thirds of the tile). appearance="plain"drops the tile and lets the badge fill the box, like Figma's inner “File Format” badge; use it at 24 and 32, where the tile leaves the text too small.

<FileFormatIcon type="pdf" size={48} />
<FileFormatIcon type="pdf" />            // 40, the default
<FileFormatIcon type="pdf" size={36} /> // Figma
<FileFormatIcon type="pdf" size={32} />
<FileFormatIcon type="pdf" size={24} />

<FileFormatIcon type="pdf" size={32} appearance="plain" />
<FileFormatIcon type="pdf" size={24} appearance="plain" />
<FileFormatIcon type="youtube" size={24} appearance="plain" />

Format icon colours and custom badges

Each type has a colour; color, label and icon override it, for example a quiz or a flashcard deck. Badges hold up to four characters; four-character text is set slightly smaller.

<FileFormatIcon label="QUIZ" color="teal" />
<FileFormatIcon label="CARD" color="purple" />
<FileFormatIcon icon={<RiMicLine />} color="pink" />

// Every colour
{['red', 'crimson', 'orange', 'yellow', 'green', 'teal', 'blue', 'purple', 'pink', 'gray'].map((c) => (
  <FileFormatIcon key={c} label="ABC" color={c} />
))}

The icon is decorative: the file name next to it carries the meaning, so the badge's small white text isn't held to text contrast. Code-only colours use a darker shade so the text stays legible. They, the extra sizes and the plain appearance need design confirmation (FC-21).

Dimensions

Taken from the component CSS, which follows Figma's geometry. The 12px list gap is a code choice: Figma's 24px is the spacing of its documentation canvas, not a spec (pending a decision).

05States and interactions

Dropzone

Drag-over is also a code addition (C40): Figma defines only Default and Hover. Hover styles apply only on devices with hover.

Item

Status changes are announced politely. The item action has no focus state in Figma, so code uses the button focus effects (C40, C5). The error card's delete uses Figma's dark-surface style, whose hover is invisible on white; code uses the ghost hover instead (C40).

State tokens

Figma binds the card's spinner and progress to a remote blue/500; code uses the local State/Primary/Base (blue/600) and the local Progress bar, following C20 (C40).

06Composition examples

Lesson materials

The full flow: add files, watch them upload, cancel, remove and retry. Press “Add example files” or pick your own. Every third file fails once at 55%; files over 20 MB fail straight away with a reason and no retry. Uploads are simulated with timers.

<FileUpload
  id={browseId}
  hint="PDF, DOCX, PPTX, PNG, or MP4, up to 20 MB each."
  accept=".pdf,.docx,.pptx,.png,.mp4"
  multiple
  onFilesSelected={startUploads}
  onFilesRejected={(files) => setMessage(`${files.map((f) => f.name).join(', ')} isn't a supported format.`)}
/>
<p role="status">{message}</p>
<FileUploadList aria-label="Lesson materials">
  {uploads.map((u) => (
    <FileUploadItem
      key={u.id}
      fileName={u.name}
      fileSize={u.size}
      bytesUploaded={u.status === 'uploading' ? u.bytesSent : undefined}
      status={u.status}
      progress={u.progress}
      statusText={u.statusText} // "Connection lost", "File too large. The limit is 20 MB."
      onCancel={() => { cancel(u.id); document.getElementById(browseId)?.focus() }}
      onRemove={() => { remove(u.id); document.getElementById(browseId)?.focus() }}
      onRetry={u.retryable ? () => retry(u.id) : undefined}
    />
  ))}
</FileUploadList>

Removing an item removes the focused button. Move focus somewhere sensible, here back to the browse button, so keyboard users aren't sent to the top of the page.

Inside a Field

Wrap the dropzone in Field for a label, hint and error. The browse button's name becomes “Lab report Browse File”, the hint and error describe it, and an error sets the invalid border. Submit without a file to see the error.

<form onSubmit={submit} noValidate>
  <Field label="Lab report" hint="PDF or DOCX, up to 20 MB." error={error}>
    <FileUpload
      id={browseId}
      accept=".pdf,.docx"
      onFilesSelected={(files) => startUpload(files[0])}
      onFilesRejected={() => setError("That file can't be used. Choose one PDF or DOCX file.")}
    />
  </Field>
  {file && (
    <FileUploadItem fileName={file.name} fileSize={file.size} status={file.status} progress={file.progress} onRemove={removeFile} />
  )}
  <Button size="sm" type="submit">Submit report</Button>
</form>

The hidden file input resets after each pick and has no name, so a native form post can't send the file. Upload from your own code (pending a decision).

07API reference

FileUpload props

FileUploadItem props

FileUploadItemLabels

FileUploadList props

FileFormatIcon props

Helpers

Plain functions with no React or browser dependencies, so they also run on the server.

import { fileMatchesAccept, formatFileSize, getFileExtension, getFileFormat } from '@nuton/ui'

fileMatchesAccept({ name: 'notes.pdf', type: 'application/pdf' }, '.pdf,.docx') // true
fileMatchesAccept({ name: 'photo.png', type: 'image/png' }, '.pdf,.docx')       // false
formatFileSize(4_400_000)              // "4.2 MB"
formatFileSize(4_400_000, 'fr')        // "4,2 Mo"
getFileExtension('lesson-plan.docx')   // "DOCX"
getFileFormat('lesson-plan.docx')      // { type: 'doc', label: 'DOC', color: 'blue' }
getFileFormat('https://youtu.be/abc')  // { type: 'youtube', label: '', color: 'crimson' }

Styling hooks

The dropzone renders .nu-file-upload with data-dragging, data-disabled and data-invalid; the item renders .nu-file-upload-item with data-status; the icon renders .nu-file-format-icon with data-color and data-size. Use props rather than styling these. The tokens in State tokens are the supported override points.

Accessibility

You must: give a hint that states the allowed formats and size; explain rejected and failed files in words; move focus after removing an item; pass onRemove (and onCancel where possible) so people can undo a choice.

Figma mapping

Every binding on these components is remote. Code uses the same-valued local tokens, except the card's blue (see State tokens). The remote library calls green “Primary” and blue “Secondary”, the reverse of local naming, so Figma should be re-bound (C40).

08Guidelines and related components

Do and don't

Common mistakes

• Expecting the component to upload, or to post the file with a form. It only reports files; your code sends them.
• Ignoring onFilesRejected, so a dropped file silently disappears.
• Setting accept without a matching hint, or a hint that promises formats accept blocks.
• Removing an item without moving focus, which sends keyboard users back to the top of the page.
• Wrapping the dropzone in another button or link. The browse button is already the control.

Related components

• ProgressThe bar inside each uploading item, on its own.
• Inputs and fieldsLabel, hint and error for the dropzone.
• ButtonSubmit the form once uploads finish.
• Link buttonThe Try again action in failed items.