FileUpload

Components/Form

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/fileupload

Overview

Copy

File upload allows users to upload one or multiple files at once. This wrapper opens a native upload dialog box when the user clicks a trigger.

Do

  • Let users upload all types of text or media files.
  • Let users upload one or more files at once.
  • Use it to add a file type selection to existing components like <AddItem/>.

Don't

  • Don't use it as a standalone item. It must always wrap a trigger component. For a standalone solution, use <FilePicker/> instead.

Feature examples

Basic structure

A trigger component must be added, so that users can open the upload dialog box. This trigger is defined as a child item of FileUpload.

Copy

File type selection

Select which types of files can be uploaded with the accept prop. The file types are separated by a comma.

Copy

Multiple files upload

Let users upload multiple files at once using the multiple prop.

Copy

Developer examples

Mobile considerations - Capture

capture tells FileUpload to open a device camera flow (mobile) instead of a regular picker.

  • "user" (default) opens the front-facing camera.
  • "environment" opens the rear-facing camera.
  • "none" disables camera capture and uses the regular file picker.

Desktop always opens the standard file picker.

Copy

Common use case examples

Upload files

Any library component can be used to open an upload dialog box. Nevertheless, it's better to use buttons or viewer components that have predefined interaction states and can be accessed with the keyboard (for accessibility reasons).

Copy

Add images

To let users add images, set <ImageViewer/> as the trigger component.

Copy

Add attachments

Let users attach files to messages, emails or contact details with the <Button/> or <TextButton/> components.

Copy

Code

Copy

Props

NameTypeDefaultDescription
acceptstring—Defines which file types to accept (i.e. .jpeg, .gif, .png). Each format should be separated by a comma.
capture"none" | "user" | "environment"userSpecifies that a new file should be captured and which camera to use to capture the image or video data. Use user for the user-facing camera and environment for the outward-facing camera. ##### Note: This only works on mobile devices; If your device is a desktop computer, you'll get a standard file picker.
children (required)(params: FileUploadChildrenProps) => ReactNode—Accepts any kind of component as a child item that calls out the file picker. ##### Syntax: function({ openFileUpload }): element * openFileUpload: A function that opens a file upload dialog when triggered. * return: A react element
dataHookstring—Applies a data-hook HTML attribute that can be used in tests.
multiplebooleanfalseAllows you to select and upload multiple files at once.
namestring—Specifies a form data name to be submitted along with the control value.
onChange (required)(files: FileList | null) => void—Defines a standard input onChange callback.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.289.0 (2026-06-17) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — fix: remove default "user" value from capture prop (#15991)
  • 1.254.0 (2026-02-03) — maintenance release, no component-specific changes
  • 1.228.0 (2025-11-18) — maintenance release, no component-specific changes
  • 1.189.1 (2025-05-16) — fix: reset file upload input value to allow re-uploading the same file (#14864)
  • 1.151.0 (2025-01-07) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?