File Upload

Attachment cards for one file or a list, with an optional drag-and-drop surface. Bridge does not upload.

Introduction

File Upload lets people choose files, with an optional drag-and-drop surface (variant="dropzone"). Without multiple, the model is one item or null. With multiple, it is a list. Each item is a browser File, or a remote attachment { name, size?, type?, url?, file?, state?, progress?, description? }. Bridge does not upload — write state on the object when the app is uploading.

Selected files always render as the same attachment cards, whether you pick one file or many. A single file uses that card, with flat label, corner, description, and error chrome around it.

Import

import { FileUpload } from "@bridge-ui/vue/Components/FileUpload";
import { FileUploadItem } from "@bridge-ui/vue/Components/FileUploadItem";

import { FileUpload } from "@bridge-ui/react/Components/FileUpload";
import { FileUploadItem } from "@bridge-ui/react/Components/FileUploadItem";

Basic usage

Bind the selection with value / onChange in React or v-model in Vue. Once a file is chosen, the trigger hides and the selection shows as one attachment card.

Dropzone

Set variant="dropzone" for a large drop surface. title is the primary line. description is the secondary line inside the surface and the helper text below the list. color also highlights the surface while a file is dragged over it.

Multiple

Set multiple to keep the trigger visible and append files. In Vue, bind a boolean with :multiple="true". maxFiles caps the list. buttonLabel replaces the default “Choose file” / “Choose files” label.

Value

accept and maxSize apply only to a File that was just picked or dropped. Remote items still count toward maxFiles. Removing an item calls onRemove (React) or emits remove (Vue) with that item and its index.

A local File cannot carry state. Replace it with { file, name, size, type, state, progress } while the upload runs.

Color

color styles the trigger, the remove button, and the dropzone highlight while a file is dragged over it. Available colors match Button.

Sizes

Available sizes: xs, sm, md (default), and lg. xs hides the default type · size line. sm, md, and lg keep it and scale the card and the dropzone.

Shared form density can also come from global.formDefaults — see Default props.

Rounded

Use rounded for the dropzone, file cards, and media. Available values: none, xs, sm, md (default), lg, xl, 2xl, 3xl, 4xl, and full.

Orientation

horizontal (default) places the media beside the name and stacks cards. vertical puts the media above the name and lays cards in a row. A card can override the field with its own orientation inside slots.list.

Upload state

Leave state unset for the type · size card. Set it on the attachment object while the app uploads. description on the attachment, or on FileUploadItem, replaces that line — including state copy such as “Uploading” or “Upload failed. Try again.” null or "" hides the line at every size, including xs while state is set. progress (0–100) is shown for uploading. onRetry (React) or retry (Vue) adds a retry button when state is error.

List slot

When slots.list is set (Vue: the list slot), FileUpload does not render the default list. items follows the model order. Write the reordered array back through onChange or v-model. Use FileUploadItem to keep the default card. start sits before the file media (a drag handle). end replaces the remove button.

slots.start and slots.end on FileUpload do the same thing for the default list. In React, a function receives the item.

Validation

accept filters the native picker. maxSize is a per-file byte cap checked in the UI — the app still enforces it on upload. Set error and errorMessage for invalid chrome.

Accessibility

• The optional label is associated with the hidden file input.
• The dropzone is a button, so it is in the tab order and activates with Enter or Space.
• Each remove control is named Remove {filename}.
• When state is error and a retry listener is set, the card includes a retry button.
• error with errorMessage exposes the validation text below the list.
• disabled blocks picking and dropping.

Anatomy

div (root)
├── header — label, corner
├── trigger — button variant, hidden once a single file is chosen
├── dropzone — variant="dropzone"
├── ul (list)
│   └── li (item) — start, media, name, meta, end / remove
├── description
└── error message

Target parts with classes and customProps: root, label, trigger, dropzone, list, item, media, content, title, actions, description, errorMessage, and input.

Related components

Button, EmptyState

API

FileUpload

FileUploadItem

Props from the list slot (index, value, remove, and the rest) can be spread onto FileUploadItem. Set description, orientation, and slots when this card should differ from the field.