Skip to main content

Getting started with file inputs

Learn how to upload files and images in web apps.

Retool provides a number of components that enable users to upload files in web apps:

Features​

Key features of file inputs include:

  • Configuration of file types permitted.
  • Configuration of the number of files permitted.
  • Automatic file parsing.
  • Input validation, including file size and number of files.
  • Style options.

To see it in action, add one of these components to the canvas. This enables users to upload files from the web app.

Specify content options​

The Content section of the Inspector contains settings that control the content of an input field, such as:

  • File types.
  • Selection type.
  • Parse files.

Accepted file types​

Use the File types setting to specify an array of RFC2046 media types to allow for upload. The following examples are for common use cases.

The following list contains RFC2046 media types for commonly used files, such as PDFs and Microsoft Word documents.

[
  "text/*",
  "application/*",
  "application/pdf",
  "application/msword",
  "application/vnd.ms-excel",
  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "application/json",
  "application/rtf",
  "application/xml"
]

Refer to the RFC2046 reference for the full list of media types.

Single or multiple selection​

Use the Selection type setting to specify whether users can upload a single file, multiple files, or a directory of files. If you allow multiple files, you can also specify a minimum or maximum number of files to allow.

Parse text files​

Retool can parse uploaded text files (any file with a text/plain media type) and make the content available for use in the app. Enable the Parse files setting in the Inspector.

When enabled, the component's parsedValue property contains an array of strings for parsed text. The index of each item corresponds to the index of the uploaded file in value.

Configure user interaction​

The Interaction section of the Inspector contains settings that control user interaction and validation, such as:

  • Event handlers, which listen for and handle interactions with your components.
  • Validation rules, which define the types of user inputs that your components accept.

While Retool does not limit the size of file uploads, we recommend defining a maximum file size using the Validation rules setting to prevent the browser from crashing.

Save uploaded files and images​

You can reference value in queries to store files in a data store, such as Retool Storage or Amazon S3.

You can enable the Upload file to Retool Storage setting for the component to automatically store the file in Retool Storage. Retool Storage has a file size limit of 250 MB. For more information, refer to the Retool Storage quickstart.

Customize appearance​

You can customize the presentation of your component in the Spacing and Appearance sections of the Inspector. The settings available in the Appearance section depend on the type of component you use.

All components have a Hidden setting, which you can dynamically control with a truthy value that evaluates to true or false. You can also control the hidden property for a component using the .setHidden() method from event handlers and JavaScript queries.

You can also create custom style rules using the Styles setting. Each component has different styles that you can configure, but common ones include colors, fonts, and text styles. Use app-level or organization-level themes to set these styles across all components.

Reference uploaded file data​

Uploaded files are Base64-encoded. The component's value property contains an array of file objects that represent each uploaded file.

file​

object

Details about the selected file.

Properties

lastModified​

number

The last modified date as a UNIX timestamp.

name​

string

The file name with extension.

retoolStorageId​

string

The file ID if uploaded to Retool Storage.

size​

string

The file size, in bytes.

type​

string

The MIME type.

uploading​

boolean

Whether the file is uploading.

value is always an array of file objects, regardless of whether a user uploads a single file or multiple files. Single-file uploads are accessible using value[0].

You can reference Base64-encoded values anywhere in Retool that accepts a string value, including URLs. For example, you can set the URL of an Image component to {{ fileInput1.value[0] }} to display an uploaded image.