form-field — wyrd.component.file-upload
Dropzone and browse trigger for selecting files, reviewing selected file sizes, and removing files before submission.
Install @wyrd-company/react or the Flutter package and use it directly —
your DESIGN.md does the styling.
$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity: name: FileUpload tag: wyrd-file-upload package: wyrd.component.file-upload title: File Upload summary: Dropzone and browse trigger for selecting files, reviewing selected file sizes, and removing files before submission.relationships: related-to: - behavior-file-upload - l10n-formatting-runtimeclassification: category: form-field composition: collection interactive: truetarget-strategy: react: required flutter: requiredsurface: properties: - name: selected-files type: kind: array item: kind: object fields: name: kind: string size-bytes: kind: number required: false default: [] controlled: true serializable: true summary: Controlled selected file metadata, represented as name plus byte size. - name: max-size-bytes type: kind: number required: false default: 10485760 serializable: true summary: Maximum accepted size for one file, in bytes. - name: is-drag-over type: kind: boolean required: false default: false controlled: true reflects: true serializable: true summary: Controlled visual state for an active drag target. - name: is-disabled type: kind: boolean required: false default: false reflects: true serializable: true summary: Prevents drop, browse activation, remove, and clear interactions. - name: accept type: kind: string required: false serializable: true summary: File input accept attribute forwarded to the browse control. slots: - name: label required: false cardinality: zero-or-one accepts: - text summary: Optional visible label and accessible-name source for the upload control. events: - name: browse payload: action: kind: action-ref bubbles: true composed: true cancelable: true summary: Emitted when the browse trigger or keyboard activation requests the host file picker. - name: files-add payload: files: kind: array item: kind: object fields: name: kind: string size-bytes: kind: number action: kind: action-ref bubbles: true composed: true cancelable: true summary: Emitted when files are dropped or accepted from a host picker. - name: file-remove payload: name: kind: string action: kind: action-ref bubbles: true composed: true cancelable: true summary: Emitted when one selected file is removed. - name: files-clear payload: action: kind: action-ref bubbles: true composed: true cancelable: true summary: Emitted when the selected-file list is cleared. - name: file-reject payload: name: kind: string size-bytes: kind: number max-size-bytes: kind: number action: kind: action-ref bubbles: true composed: true cancelable: false summary: Emitted when a candidate file is rejected by the max-size rule. states: - name: idle source: behavior-runtime summary: No drag is active and no selected files are present. - name: drag-over source: behavior-runtime summary: A file drag is active over the dropzone. - name: has-files source: behavior-runtime summary: At least one file is selected. - name: disabled source: property summary: Disabled state derived from is-disabled. - name: rejected source: behavior-runtime summary: The last add attempt rejected at least one file. parts: - name: root summary: Field root and selected-file list owner. slots: - label - name: label summary: Optional label text. slots: - label - name: dropzone summary: Focusable drag-and-drop target and browse keyboard activation surface. - name: prompt summary: Drop prompt text. - name: browse-trigger summary: Button that requests the host file picker. - name: file-list summary: Selected-file list container. - name: file-item summary: Repeated selected-file row. - name: remove-trigger summary: Per-file remove affordance. - name: summary summary: Aggregate file count and total selected size. - name: error summary: Rejection message container. tokens: root: gap: spacing.sm label: color: color.on-surface font: typography.label-md dropzone: background: color.surface background-active: color.primary-hover foreground: color.on-surface foreground-active: color.on-primary border-color: color.outline border-color-active: color.primary border-width: 1px radius: rounded.md padding: spacing.lg gap: spacing.sm browse-trigger: background: color.primary foreground: color.on-primary radius: rounded.sm padding-x: spacing.md padding-y: spacing.sm font: typography.label-md file-item: background: color.surface-container foreground: color.on-surface radius: rounded.sm padding-x: spacing.md padding-y: spacing.sm gap: spacing.sm summary: color: color.on-surface-variant font: typography.body-md error: color: color.error font: typography.body-mdmessages: - key: file-upload.label description: Default visible label shown when the label slot is not supplied. - key: file-upload.drop-prompt description: Instructional text shown inside the dropzone. - key: file-upload.browse-label description: Browse trigger label. - key: file-upload.file-count description: Aggregate count of selected files. params: count: plural - key: file-upload.file-size-byte description: Per-file size shown in bytes. params: size: unit - key: file-upload.file-size-kilobyte description: Per-file size shown in kilobytes. params: size: unit - key: file-upload.file-size-megabyte description: Per-file size shown in megabytes. params: size: unit - key: file-upload.file-size-gigabyte description: Per-file size shown in gigabytes. params: size: unit - key: file-upload.total-size-byte description: Aggregate selected-file size shown in bytes. params: size: unit - key: file-upload.total-size-kilobyte description: Aggregate selected-file size shown in kilobytes. params: size: unit - key: file-upload.total-size-megabyte description: Aggregate selected-file size shown in megabytes. params: size: unit - key: file-upload.total-size-gigabyte description: Aggregate selected-file size shown in gigabytes. params: size: unit - key: file-upload.remove-file description: Accessible label for removing a selected file. params: name: string - key: file-upload.clear-label description: Clear selected files trigger label. - key: file-upload.file-too-large description: Rejection message shown when a file exceeds the maximum allowed size. params: name: string size: unit maxSize: unitobligations: accessibility: role: group name: Label slot or default label provides the accessible name for the file upload control. description: Drop prompt, selected-file summary, and rejection message are programmatically associated with the interactive dropzone. keyboard: - Dropzone is focusable when enabled. - Enter and Space on the focused dropzone activate the browse request. - Remove triggers are reachable by Tab and expose the filename in their accessible label. - Disabled upload prevents browse, drop, remove, and clear activation. semantics: - Dropzone exposes disabled state when the upload is disabled. - Selected files are exposed as a list with one item per file. - Rejection text is exposed as an alert or status update. behavior: model: behavior-runtime runtimeBlueprint: behavior/file-upload interactions: - Drag enter moves the machine from idle to drag-over unless disabled. - Drop or accepted browse result with at least one file moves to has-files. - Removing the final file returns to idle. - Clear returns from has-files or rejected to idle. hostEffects: - Activate the host file picker when browse is requested. - Dispatch files-add, file-remove, files-clear, and file-reject events. - Validate dropped or browsed file sizes before committing them to selected-files. conditions: - rtl - locale - reduced-motion - cvd-deuteranopia - density-compact - text-expansion - keyboard-inset sdui: status: partial serializableProperties: - selected-files - max-size-bytes - is-drag-over - is-disabled - accept serializableSlots: - label eventBindings: - browse - files-add - file-remove - files-clear - file-reject notes: File metadata and control state serialize; host file handles, drag data transfer, and native picker activation remain target-local.examples: - name: idle state: idle properties: selected-files: [] accept: image/png,image/jpeg,image/webp slots: label: Upload design assets - name: drag-over state: drag-over properties: is-drag-over: true selected-files: [] slots: label: Drop validation evidence - name: disabled state: disabled properties: is-disabled: true selected-files: [] slots: label: Upload release attachments
Generated from the contract's examples block.
Previews are the published @wyrd-company/react component, themed by the
brand's role tokens — flip the site's light/dark toggle and they follow.
import { WyrdFileUpload } from "@wyrd-company/react";
<WyrdFileUpload selectedFiles={[]} accept="image/png,image/jpeg,image/webp" label="Upload design assets" />
// events: onBrowse, onFilesAdd, onFileRemove, onFilesClear, onFileRejectimport 'package:wyrd_flutter/wyrd_flutter.dart';
WyrdFileUpload(
selectedFiles: [],
accept: 'image/png,image/jpeg,image/webp',
label: Text('Upload design assets'),
)
// events: onBrowse, onFilesAdd, onFileRemove, onFilesClear, onFileRejectimport { WyrdFileUpload } from "@wyrd-company/react";
<WyrdFileUpload isDragOver selectedFiles={[]} label="Drop validation evidence" />
// events: onBrowse, onFilesAdd, onFileRemove, onFilesClear, onFileRejectimport 'package:wyrd_flutter/wyrd_flutter.dart';
WyrdFileUpload(
isDragOver: true,
selectedFiles: [],
label: Text('Drop validation evidence'),
)
// events: onBrowse, onFilesAdd, onFileRemove, onFilesClear, onFileRejectimport { WyrdFileUpload } from "@wyrd-company/react";
<WyrdFileUpload isDisabled selectedFiles={[]} label="Upload release attachments" />
// events: onBrowse, onFilesAdd, onFileRemove, onFilesClear, onFileRejectimport 'package:wyrd_flutter/wyrd_flutter.dart';
WyrdFileUpload(
isDisabled: true,
selectedFiles: [],
label: Text('Upload release attachments'),
)
// events: onBrowse, onFilesAdd, onFileRemove, onFilesClear, onFileReject| Name | Type | Default | Summary |
|---|---|---|---|
selected-files | array | | Controlled selected file metadata, represented as name plus byte size. |
max-size-bytes | number | 10485760 | Maximum accepted size for one file, in bytes. |
is-drag-over | boolean | false | Controlled visual state for an active drag target. |
is-disabled | boolean | false | Prevents drop, browse activation, remove, and clear interactions. |
accept | string | undefined | File input accept attribute forwarded to the browse control. |
| Slot | Cardinality | Accepts | Summary |
|---|---|---|---|
label | zero-or-one | text | Optional visible label and accessible-name source for the upload control. |
| Event | Payload | Summary |
|---|---|---|
browse | action | Emitted when the browse trigger or keyboard activation requests the host file picker. |
files-add | files, action | Emitted when files are dropped or accepted from a host picker. |
file-remove | name, action | Emitted when one selected file is removed. |
files-clear | action | Emitted when the selected-file list is cleared. |
file-reject | name, size-bytes, max-size-bytes, action | Emitted when a candidate file is rejected by the max-size rule. |
The contract's token bindings. Open the shared contextual sidebar from any example; primary swatches reflect the color you pick there. Error swatches show the active preset's values; editing any knob switches to custom and resets error to TWW · Ink.
| Binding | Token | |
|---|---|---|
root.gap | spacing.sm | |
label.color | color.on-surface | |
label.font | typography.label-md | |
dropzone.background | color.surface | |
dropzone.background-active | color.primary-hover | |
dropzone.foreground | color.on-surface | |
dropzone.foreground-active | color.on-primary | |
dropzone.border-color | color.outline | |
dropzone.border-color-active | color.primary | |
dropzone.border-width | 1px | |
dropzone.radius | rounded.md | |
dropzone.padding | spacing.lg | |
dropzone.gap | spacing.sm | |
browse-trigger.background | color.primary | |
browse-trigger.foreground | color.on-primary | |
browse-trigger.radius | rounded.sm | |
browse-trigger.padding-x | spacing.md | |
browse-trigger.padding-y | spacing.sm | |
browse-trigger.font | typography.label-md | |
file-item.background | color.surface-container | |
file-item.foreground | color.on-surface | |
file-item.radius | rounded.sm | |
file-item.padding-x | spacing.md | |
file-item.padding-y | spacing.sm | |
file-item.gap | spacing.sm | |
summary.color | color.on-surface-variant | |
summary.font | typography.body-md | |
error.color | color.error | |
error.font | typography.body-md |
| State | Source | Summary |
|---|---|---|
idle | behavior-runtime | No drag is active and no selected files are present. |
drag-over | behavior-runtime | A file drag is active over the dropzone. |
has-files | behavior-runtime | At least one file is selected. |
disabled | property | Disabled state derived from is-disabled. |
rejected | behavior-runtime | The last add attempt rejected at least one file. |
From the contract's accessibility obligations. Role group; Label slot or default label provides the accessible name for the file upload control.
Status: partial. File metadata and control state serialize; host file handles, drag data transfer, and native picker activation remain target-local.
| Serializable | Members |
|---|---|
| Properties | selected-files, max-size-bytes, is-drag-over, is-disabled, accept |
| Slots | label |
| Events | browse, files-add, file-remove, files-clear, file-reject |