Attach files to a task
Use file upload when users need to attach documents, images, or other files.
Components
Show selected files
Display the filename and size so users can check what they added.
Set file requirements
Use accepted types, size guidance, and feedback to reduce upload errors.
1
Label (optional)
2
Action (button)
3
Hint text (optional)
Variant
File upload supports a default button-style picker and a drag-and-drop surface.
Use the default variant for compact forms or single file inputs.
Multiple files
Allow more than one file to be selected at once.
Only one file can be selected; reselecting replaces the previous one.
Accepted file types
Restrict the file picker to specific file types using the accept attribute.
No restriction on file type.
Disabled
Disable the upload button to prevent users from picking a file.
Default interactive state.
Validation feedback
Show error styling and feedback when the upload is invalid.
No feedback shown.
Design tokens used
Each row is a colour, spacing, or size value the component uses, and the right-most column tells you where in the component you'll see it.
sgds-form-padding-x—sgds-form-padding-y—sgds-form-gap-lg—sgds-form-gap-md—sgds-form-gap-sm—sgds-form-gap-xl—sgds-gap-md16pxsgds-border-radius-md8pxsgds-border-width-11pxsgds-border-width-2Width variessgds-form-border-width-defaultWidth variessgds-form-border-width-thickWidth variessgds-font-size-12—sgds-font-size-14—sgds-line-height-16Height variessgds-line-height-20Height variessgds-icon-size-md—sgds-icon-size-lg—sgds-margin-xl—sgds-padding-2-xl32pxsgds-motion-duration-standard—sgds-motion-easing-enter—sgds-motion-easing-exit—sgds-motion-easing-standard—sgds-form-outline-focus—sgds-form-outline-offset-focus—sgds-form-border-radius-md—When to use
- Use this component to collect or change a specific piece of information in a predictable way.
- Use it when the SGDS control matches the type of response users need to provide.
When not to use
- Do not use this component when another SGDS control would reduce effort or make the choice clearer.
- Do not ask for more information, options, or steps than users need at that point in the task.
State the accepted file types and size up front
Tell users which file types and sizes are accepted before they pick a file to reduce failed uploads.
Do not leave the upload action ambiguous
Use a clear verb-led label inside the slot, for example Upload report, rather than generic File or Browse.
Restrict file types in the picker
Set the accept attribute to filter the system file picker so users do not have to scan files manually.
Do not use file upload for very small text inputs
For a short value such as a reference number, use a text input. Uploading a file adds friction.
Allow several files only when users genuinely need it
Add the multiple attribute when the task expects several files in one go, such as photo evidence.
Show validation feedback when an upload is required
Pair required with hasFeedback and invalidFeedback so the empty state can be flagged inline.
Built-in accessibility
- File upload uses a native file input with SGDS button and close-button controls.
- Selected files are rendered as a list with remove actions.
Labels and content
- Explain accepted file types and size limits near the field.
- Use validation feedback when a file is missing or not accepted.
Focus and interaction
- Users should be able to reach the upload button and each remove-file button.
- Do not hide file requirements until after the upload fails.
TabShift+TabEnterSpaceHave suggestions or feedback?
Share them with us on Slack → #ask-sgds-v3
Found a bug or issue?
Report it on GitHub Issues → sgds/components/file-upload