FileUpload

Quick Preview

payment-receipt.pdf

PDF, 1.8 MB

42% uploaded

Composition

FileUpload is a display primitive. The consuming app owns file selection, upload transport, retries, cancellation, and preview URL cleanup.

FileUpload
|-- FileUploadPreview
|   |-- FileUploadImage
|   |-- FileUploadOverlay
|   |   `-- FileUploadCircularProgress
|   `-- FileUploadPreviewAction
|       `-- FileUploadCancel
|-- FileUploadIcon
`-- FileUploadContent
    |-- FileUploadHeader
    |   |-- FileUploadName
    |   |-- FileUploadStatus
    |   `-- FileUploadCancel
    |-- FileUploadMeta
    `-- FileUploadProgress

Usage

<FileUpload value={progress} state="uploading">
  <FileUploadIcon />
  <FileUploadContent>
    <FileUploadHeader>
      <FileUploadName>{file.name}</FileUploadName>
      <FileUploadCancel onClick={cancelUpload} />
    </FileUploadHeader>
    <FileUploadProgress />
  </FileUploadContent>
</FileUpload>

Examples

Receipt with linear progress

Compose the icon, metadata, status, progress, and cancel action for document uploads.

payment-receipt.pdf

PDF, 1.8 MB

42% uploaded

Image with circular progress

Layer the circular indicator over an image preview and attach the cancel action to its top-right corner.

64%

Props

Prop/API	Type	Default	Description
`value` on `FileUpload`	`number`	required	Upload percentage, normalized to an integer from 0 to 100.
`state` on `FileUpload`	`"pending" \| "uploading" \| "complete" \| "error"`	`"uploading"`	Semantic upload state exposed through context and data attributes.
`showValue` on `FileUploadProgress`	`boolean`	`true`	Shows the formatted percentage next to linear progress.
`variant` on `FileUploadCancel`	`"ghost" \| "surface"`	`"ghost"`	Uses a quiet inline action or an elevated action for preview overlays.
state labels on `FileUploadStatus`	`ReactNode`	built-in copy	Overrides pending, uploading, complete, or error text.
`children` on `FileUploadStatus`	`ReactNode \| (context) => ReactNode`	state label	Replaces status copy with static or context-aware content.
progress props	Progress props	-	Linear and circular progress props pass through to their corresponding primitives except `value`.
`className`	`string`	-	Overrides each slot without changing the compound API.
native props	React component props	-	Passed through to each underlying element.

Accessibility

Give each upload a useful label when nearby text does not identify it.
Progress indicators expose normalized values and accessible default labels.
FileUploadStatus announces state changes politely and includes text so status is not communicated by color alone.
FileUploadCancel is a native button with a default Cancel upload label; provide a more specific label when multiple uploads are shown.
Use meaningful image alternative text when the preview content matters, or an empty alt when the filename already identifies it.

On this page