FilePicker

Components/Form/FilePicker

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

Overview

Copy

The file picker allows users to upload a single file at a time. The component handles the file upload via the native file browser dialog, the validation and preview of an uploaded file.

Do

  • Use it to upload text or media file
  • Use it to upload single file at a time

Don't

  • Don't use it if you need to upload multiple files at once, use <FileUpload/> instead.

Feature examples

Structure

File upload consists of two labels: `mainLabel` for action text and `subLabel` for a description.

Copy

Supported formats

Define file types that could be uploaded with the `supportedFormats` prop. Separate formats with a comma.

Copy

Max size

Define the maximum file size for an upload with the `maxSize` prop.

Copy

Error message

Describe an error status by using the `errorMessage` prop. Messages will only be revealed when the `error` status is `true`.

Copy

Add text or any other component in an area above the component using the `header` prop.

Copy

Code

Copy

Props

NameTypeDefaultDescription
dataHookstring—Applies a data-hook HTML attribute that can be used in tests.
errorboolean—Defines if an error should show or not.
errorMessagestring''Sets an error message to display.
headerReactNode—Allows to insert overline text at the top left of a component. Can also be overridden with any other component, i.e. .
idstring | number—Specifies a unique id for the element.
mainLabelstring'Choose File'Sets the main action label.
maxSizenumber5000000Defines the maximum size of a file that can be uploaded.
namestring—Defines a name for inner input.
onChange(file: File) => void—Defines a standard input onChange callback.
subLabelstring'No file chosen (Max size 5 MB)'Adds a supportive message below the action title.
supportedFormatsstring'*'Defines which file types to accept (i.e. .jpeg, .gif, .png). Formats should be separated by a comma.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
hasErrorChecks whether there's a visible error icon
errorMessageGets error message text
getSubLabelGets sub label text
getMainLabelGets main label text
getNameGets FilePicker input name
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.329.0 (2026-09-24) — 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.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.278.0 (2026-05-08) — maintenance release, no component-specific changes
  • 1.273.0 (2026-04-30) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — fix: roundness of FilePicker (tokenization) (#15976)
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.183.0 (2025-04-24) — fix: error message now wraps instead of ellipsis and doesn't have max-width (#14762)
  • 1.102.0 (2024-04-16) — 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?