Get startedFoundationsComponentsPatternsGuidelinesResourcesAI
This site is a work in progress as part of GovTech {build} hackathon. Content may be incomplete or subject to change.

File upload

Allows users to upload files of various sizes and formats.

GitHubGitHub logocomponents/file-upload
StorybookStorybook logocomponents/file-upload
DesignUsageAccessibilityUpdates

Purpose

Attach files to a task

File upload gives users a clear, accessible way to attach documents, images, or other files as part of completing a form or workflow.

Show what's been added

Once a file is selected, the component confirms the filename and size so users know their upload was received before submitting.

Constrain accepted types

File type and size restrictions can be communicated upfront, reducing failed uploads and back-and-forth with users.

Anatomy

Upload document
1

Upload button

2

Selected file list

3

Feedback area

Configuration

Default

The file upload component provides a button for attaching files and displays selected file names.

Upload document

Renders an upload control with a file selection button and attachment feedback. Use when users need to submit supporting documents or media as part of a form.

Playground

BETA
Upload document

Structure

Upload document

Component tokens

Component tokens are specific to each component. Use the table title as the prefix: border-color-muted under sgds/file-upload means sgds/file-upload/border-color-muted.

sgds/file-upload
CategoryComponent tokenSemantic tokenValueBorderborder-color-mutedsgds/border-color-muted#DFDFDFColourcolor-mutedsgds/color-muted—Formform-border-radius-mdsgds/form/border-radius/md—form-border-width-defaultsgds/form/border-width/default—form-gap-2-xlsgds/form/gap/2-xl—form-gap-lgsgds/form/gap/lg—form-gap-mdsgds/form/gap/md—form-gap-xlsgds/form/gap/xl—form-padding-xsgds/form/padding/x—form-padding-ysgds/form/padding/y—form-success-color-defaultsgds/form/success/color/default—form-surface-defaultsgds/form/surface/default—

Usage

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.

Best practices

Upload document
Keep the input clear

Use clear labels, predictable values, and a single obvious action for the control.

Upload document Upload document
Do not increase input effort

Too many repeated controls or unclear prompts make form completion slower and less confident.

Accessibility considerations

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.

Keyboard interaction

KeyInteractionTabMoves focus from the upload or remove-file button to the next focusable element.Shift+TabMoves focus to the previous interactive element.EnterActivates the focused upload or remove-file button.SpaceActivates the focused upload or remove-file button.

Updates

DateVersionDescriptionLoading updates…

Roadmap

Planned itemStatusTargetFuture enhancements for file uploadPlannedTBD

Feedback

Have suggestions or feedback?

Share them with us on Slack → #design-system-feedback

Bug Reports

Found a bug or issue?

Report it on GitHub Issues → sgds/components/file-upload

Singapore Government Design System

The Singapore Government Design System was developed to empower teams in creating fast, accessible and mobile-friendly digital services.