File Picker

Updated:

A file picker that allows users to browse for or drag and drop files.

How To Use

  1. Configure the file picker via its props. Most importantly, define the file upload requirements, such as the permitted file types (fileTypes), maximum file size (maxFileSize), and the maximum number of files that can be uploaded (maxFiles).
  2. Listen for the tctChange event.
    • The event detail contains an object representing the selected files with two properties: invalidFiles and validFiles.
    • invalidFiles is an array of objects describing each file that did not meet the upload requirements. You can ignore this property or use it for logging purposes.
    • validFiles is an array of File (https://developer.mozilla.org/en-US/docs/Web/API/File) objects that met the upload requirements.
  3. When a tctChange event is fired, upload the files in the validateFiles array.
    • The file picker does not handle uploading itself; it simply provides an array of File objects that you can upload in the same way as File objects returned from a native file input field (https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file).
  4. After each file is uploaded, pass a FileStatus object (inside an array) to the file picker's status property.
    • A FileStatus object has the following properties:
      • name: The name of the file.
      • status: The file upload status, either "failed" or "uploaded".
      • message: An optional property for providing a custom status message. This is only applied if status is "failed", and is intended to allow developers to give more details on upload failures.
    • Updating the status property updates the associated file item displayed below the picker button or drop zone—this hides the loading spinner and shows a status icon.
    • Once all valid files are marked as "failed" or "uploaded", the spinner displayed in the file picker button or drop zone will disappear.
    • You can also update statuses in bulk after all files have been uploaded—just include a FileStatus object for each file in the array passed to status.

Slots

The q2-file-picker element has multiple slots that can be used to insert custom content into the component.

Learn more about slots

An optional slot to display a custom description.

An optional slot to display a custom label.

Properties

The q2-file-picker element has one or more properties that support text localization. Those properties are indicated by the localizable badge in the description.

Learn more about properties.

buttonSize
button-size

The size of the browse button.

description

A description of the field. This is announced by screen readers when the field is focused.

Localizable
disabled

Disables the file picker, preventing user interaction.

fileTypes
file-types

Allowed file types based on extensions (e.g., ['jpg', 'png', 'pdf'] or 'jpg, png, pdf'). When using the attribute, provide a comma-separated string (e.g., 'jpg, png, pdf'). Arrays can only be set programmatically via JavaScript.

label

The label for the field. This is announced by screen readers when the field is focused.

Localizable
maxFileSize
max-file-size

The maximum size (in bytes) of any file that can be selected.

maxFiles
max-files

The maximum number of files that can be selected.

status

An array of ValidFileStatus objects representing the upload status of files. Each ValidFileStatus object contains the following properties:

  • name: The file name.
  • status: The upload status, either "failed" or "uploaded".
  • message: (Optional) A custom status message, used only when status is "failed". This allows developers to provide more detail about upload failures while ensuring all other file status messages remain consistent with approved design/UX standards. Custom failure messages are limited to a single line.
Localizable
value

Returns an object representing the selected files with two properties:

  • invalidFiles: An array of InvalidFileStatus objects representing files that failed validation.
  • validFiles: An array of File objects representing files that passed validation.

Each InvalidFileStatus object includes the following properties:

  • file: The File object.
  • status: The validation status, which can be "invalid-type" (invalid file type), "over-size-limit" (file exceeds the size limit), or "over-max-files-limit" (total exceeds the max files limit).
variant

Determines if the file picker is a browse button or a drop zone with a browse link.

Events

The q2-file-picker element exposes events that can be used to send and receive data from the component based on user interaction.

Learn more about events.

tctChange

Custom event dispatched when the user selects files. The event detail contains an object representing the selected files with two properties:

  • invalidFiles: An array of InvalidFileStatus objects representing files that failed validation.
  • validFiles: An array of File objects representing files that passed validation.

Each InvalidFileStatus object includes the following properties:

  • file: The File object.
  • status: The validation status, which can be "invalid-type" (invalid file type), "over-size-limit" (file exceeds the size limit), or "over-max-files-limit" (total exceeds the max files limit).

Event Detail Type signature

{ invalidFiles: InvalidFileStatus[]; validFiles: File[]; }

The following CSS variables are available to override the default theme styles of the q2-file-pickercomponent.

Dependencies

Many Tecton components consume other components to maintain visual and functional consistency. If you are looking for a CSS variable you think should exist but are not seeing it, it may be defined in one of the dependent components below. Either way, if you think it's something we should expose more conveniently, let us know!

  • q2-loading
  • q2-icon
  • q2-link
  • q2-btn
  • q2-list
  • q2-item

    • There is 1 frequently asked question related to this page.