Aliases
upload field
FileUpload
File picker with validation limits and a selected-file list.
Playground
file upload
No files selected
Overview
- Use the change callback to handle selected files. The component does not upload files to a server.
Foundations
When to use
- Use
FileUploadwhen the user needs to choose one or more local files through a standard file picker. - Use helper text to clarify accepted formats or expectations.
When not to use
- Do not use
FileUploadfor drag-and-drop media workspaces or complex upload dashboards. - Do not hide file constraints; place them in the description or nearby supporting copy.
Structural parts
field wrapper
root Carries the label, helper text, and chosen-file feedback.
file picker button
trigger Opens the native file chooser.
selected file summary
file-list Shows the chosen file names after selection.
Public interface
| Name | Type | Default | Description |
|---|---|---|---|
label | string | — | Visible label used for the field or control. |
description | string | — | Provides field guidance associated with the control. |
error | string | — | Shows a validation error associated with the control. |
placeholder | string | — | Placeholder text shown before a user makes a selection or enters text. |
required | boolean | false | Marks the control as required. |
disabled | boolean | false | Prevents interaction and exposes the disabled state. |
name | string | — | Form field name used for native form submission. |
id | string | — | Sets the control ID for external labels and descriptions. |
size | 'sm' | 'md' | 'lg' | 'md' | Sets the component size. |
multiple | boolean | false | Allows selecting more than one file. |
accept | string | — | Native file accept filter. |
buttonLabel | string | 'Choose files' | Visible trigger label. |
onChange | (detail: { files: File[] }) => void | — | Receives the selected files. |
theme | ThemeContract | — | Sets the theme used to resolve component styles. |
| Name | Payload | Description |
|---|---|---|
change | { files: File[] } | Fires with the selected files. |
| Name | Description |
|---|---|
default | FileUpload is prop-driven and does not expose content slots. |
Variants, sizes, and states
Variants
default:FileUploaduses one shell and varies mainly by size.
Sizes
sm: Compact file picker.md: Default file picker.lg: Larger file picker.
States
rest: No file has been selected.selected: One or more files have been selected.disabled: The upload control cannot be activated.
Accessibility
Semantics
- Associates the control with its visible label, description, and error.
- Exposes disabled and required semantics through the underlying form control.
- Uses the native file input under a styled DK field shell.
Keyboard
- Supports native focus and text entry behavior.
- Supports standard focus and activation behavior through the trigger.
Screen readers
- Connects visible label, helper text, and error text to the native control.
- Label and helper text remain associated with the underlying file input.
Checklist
- Verify that the control has an accessible name.
- Verify that keyboard focus is visible in every state and size.
- Identify disabled, selected, and error states with text or symbols as well as color.
Tokens and CSS variables
root
- --dk-field-stack-gap
- 0.45rem
label
- --dk-field-label-color
- #16181c
- --dk-field-label-size
- clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
- --dk-field-label-weight
- 600
field
- --dk-file-upload-bg
- #f2f5fb
- --dk-file-upload-fg
- #16181c
- --dk-file-upload-border
- #95989d
- --dk-file-upload-radius
- clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
- --dk-file-upload-padding
- clamp(1.778rem, 1.6296rem + 0.658vw, 2.222rem)
- --dk-file-upload-gap
- clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
- --dk-file-upload-button-bg
- #d7e9ff
- --dk-file-upload-button-fg
- #000f4d
- --dk-file-upload-button-radius
- clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
- --dk-file-upload-button-block-size
- 44px
- --dk-file-upload-button-inline-padding
- clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
- --dk-file-upload-button-font-size
- clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
- --dk-file-upload-copy-size
- clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
button
- --dk-file-upload-button-weight
- 650
copy
- --dk-file-upload-copy-color
- #16181c
list
- --dk-file-upload-list-gap
- clamp(0.563rem, 0.5156rem + 0.208vw, 0.703rem)
item
- --dk-file-upload-item-size
- clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
description
- --dk-field-description-color
- #16181c
- --dk-field-description-size
- clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
error
- --dk-field-error-color
- #cc272e
- --dk-field-error-size
- clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
Implementation notes
- Handle selected files in your app to upload them.
Examples
Starter
One asset picker
A file picker with format guidance.
<FileUpload label="Assets" description="Upload supporting files." />Common patterns
Multi-file upload
Allow multiple files when the workflow expects a batch.
<FileUpload label="Attachments" multiple={true} />Edge cases
Filtered file types
Use accept when the workflow only supports known formats.
<FileUpload label="Brand assets" accept=".png,.svg,.pdf" buttonLabel="Choose assets" />Mathematical fixtures
Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.
default (size=sm)
passsize=sm
- Evidence: mathematical
- Coverage: complete (3 / 3 declared kinds evaluated)
- Declared: contrast, target, layout
- Evaluated: contrast, target, layout
- Contrast: 98.5 Lc
- Target: 44 px
- Layout: field · single-line 0 px single-line estimate; 0 px minimum width 280 px: pass 360 px: pass 460 px: pass
default (size=md)
passsize=md
- Evidence: mathematical
- Coverage: complete (3 / 3 declared kinds evaluated)
- Declared: contrast, target, layout
- Evaluated: contrast, target, layout
- Contrast: 98.5 Lc
- Target: 44 px
- Layout: field · single-line 0 px single-line estimate; 0 px minimum width 280 px: pass 360 px: pass 460 px: pass
large
passsize=lg
- Evidence: mathematical
- Coverage: complete (3 / 3 declared kinds evaluated)
- Declared: contrast, target, layout
- Evaluated: contrast, target, layout
- Contrast: 98.5 Lc
- Target: 48 px
- Layout: field · single-line 0 px single-line estimate; 0 px minimum width 280 px: pass 360 px: pass 460 px: pass
invalid (size=sm)
passsize=sm
- Evidence: mathematical
- Coverage: complete (3 / 3 declared kinds evaluated)
- Declared: contrast, target, layout
- Evaluated: contrast, target, layout
- Contrast: 98.5 Lc
- Target: 44 px
- Layout: field · single-line 0 px single-line estimate; 0 px minimum width 280 px: pass 360 px: pass 460 px: pass
invalid (size=md)
passsize=md
- Evidence: mathematical
- Coverage: complete (3 / 3 declared kinds evaluated)
- Declared: contrast, target, layout
- Evaluated: contrast, target, layout
- Contrast: 98.5 Lc
- Target: 44 px
- Layout: field · single-line 0 px single-line estimate; 0 px minimum width 280 px: pass 360 px: pass 460 px: pass
invalid (size=lg)
passsize=lg
- Evidence: mathematical
- Coverage: complete (3 / 3 declared kinds evaluated)
- Declared: contrast, target, layout
- Evaluated: contrast, target, layout
- Contrast: 98.5 Lc
- Target: 48 px
- Layout: field · single-line 0 px single-line estimate; 0 px minimum width 280 px: pass 360 px: pass 460 px: pass