File upload

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

• Choose, drop, and remove files as one selection state.
• The native file input registers as a Field.Control, so the shared Form keeps required validation, server errors, and real File submission.
• Transfers don't start automatically. The transport you provide runs per file.
• The drop zone is a surface, not a dashed outline. Its background highlights while a file is dragged over it.
• Chosen files continue the drop zone as rows, divided by lines, so the field stays one plane and a drop on the list adds files too.
• Keyboard focus on the choose button and the field error display are preserved.

• Don't treat accept as validation. It's a selection hint, and client-side validation doesn't replace server validation.
• Don't expect FileUpload to handle directory uploads, chunked transfers, resuming, or signed URL policies. Handle them in the transport or the product.
• Don't prefill files already uploaded to the server as if they were local Files. List them separately.
• Don't read actual files from Form.onFormSubmit's string model. Read FormData in onSubmit instead.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

FileUpload owns Field.Root → Label + Description + dropzone (native Field.Control(type=file) + visible picker label, then one row per file with status/actions/progress) + rejection alert + Field.Error + one polite announcement

Keyboard and accessibility

Tabbing to the native file input shows a focus ring on the choose button. Enter or Space opens the file picker. In the file list, Tab reaches the Upload, Cancel, Retry, and Remove buttons. Enter or Space activates them. Every file selection works without dragging. disabled blocks selection and submission, and cancels transfers in progress.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { FileUpload, Form } from '@surflane/ui'

<Form
  onSubmit={(event) => {
    event.preventDefault()
    const data = new FormData(event.currentTarget)
    const files = data.getAll('artifacts')
    // Submit using your application transport.
  }}
>
  <FileUpload
    name='artifacts'
    label='Build artifacts'
    description='Up to three JSON files, 1 MB each.'
    accept='.json,application/json'
    multiple
    required
    maxFiles={3}
    maxFileSize={1024 * 1024}
    transport={async (file, { signal, onProgress }) => {
      await yourUpload(file, { signal, onProgress })
    }}
  />
</Form>

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens