Skip to main content


Upload or process files in Superblocks APIs

Use the FilePicker when your users upload assets like images, or when you need to manipulate text files like CSVs. Files can only be handled inside Superblocks API steps (i.e. the Upload Multiple Files action in S3, Python step, JavaScript step, etc.). If you are using the On-Premise Agent, files are sent directly from the user's computer to your agent. Superblocks supports files up to 500Mb.

Working with files in APIs

Each file that you upload is wrapped in a special <FilePickerComponentName>.files array item. To read the contents of a file, use the following language-specific syntax.


await <FilePickerComponentName>.files[<index>].readContentsAsync(<optional mode>)

API Step Bindings

{{ await <FilePickerComponentName>.files[<index>].readContentsAsync(<optional mode>) }}


<FilePickerComponentName>.files[<index>].readContents(<optional mode>)

Available modes

  • Returns a utf-8 encoded string
  • Default for non-binary files (e.g., .txt, .csv, .html)
  • Configure manually by setting <optional mode> to text
  • Read file contents as utf-8 string

Guide - Upload CSV and display in Table

This guide will quickly walk you through how to use the FilePicker in order to create a basic recipes explorer.

Use FilePicker to import files

  1. Start by dragging a Container component from the Components panel to the empty canvas.
  2. Now add a FilePicker component inside of the Container component.
  3. Add a Button component inside of the Container component as well. Change the Label to Load File.
  4. Lastly, add a Text component inside of the Container component. Change the Text to Add the Recipes CSV. Change the Text Size to Heading 2.

Add a container, filepicker, button, and text component to the canvas

To configure our FilePicker to only allow certain file types, follow these steps:

  1. Click the FilePicker widget to open the right side Properties panel.
  2. Change Selection type to Single select.
  3. Update the Allowed file types to only allow .csv and .txt file types:

Update allowed file types for a file picker component

Now that we've restricted the file types allowed, you'll see that only .txt and .csv are available after clicking browse files.

Only .txt and .csv files are available when browsing files

Create an API to parse imported CSV

Now let's create an API in order to add some more functionality to our FilePicker component and show its data in a Table.

  1. Click New API and select Python as the type
  2. Change the name of the API to readCSVFile
  3. Change the name of the step to parseCSV
  4. Paste in the following code, which loads and reads the .csv file:
from io import StringIO
import csv

scsv = FilePicker1.files[0].readContents()
f = StringIO(scsv)

reader = csv.DictReader(f, delimiter=',')

return [row for row in reader]

Create an API to read CSV files

Now that the API is up and running, update the Button component to have the readCSVFile API run when it's clicked. Select Run API as the Action Type for the onClick trigger and choose the readCSVFile API.

Update button component to run an API when clicked

Show the file's data in a Table

  1. Drag a Table component from the Component panel and place it below the Container component.
  2. Update Table Data to {{readCSVFile.response}}
  3. Update Table Header to the following code snippet to dynamically update the table's header based on the file loaded:
{{FilePicker1.files[0] ? "Viewing Recipes from: " + FilePicker1.files[0].name : "Waiting for Recipe Upload..."}}

Create a table to show the loaded CSV data when a button is clicked

You now have a working app that imports a csv file and shows it in a table!

Use the filepicker component to import CSV files and view them in a table

Guide - File upload to S3

In this example, we will allow users to upload PDF and Microsoft Office documents to our S3 store.

Use a form component and filepicker to upload a file to S3

  1. Before starting, set up an S3 integration and note the name of the S3 bucket that you will upload to.

  2. Drag and drop the Form component, and then drag and drop the FilePicker component inside the Form.

  3. Change the "Allowed Files Types" to ["application/pdf", ".doc", ".docx"].

  4. Click the Submit button to open the button properties. Under "onClick", add a new API to call. Choose the S3 integration from above.

  5. Change the S3 action to "Upload Multiple Files", and configure the bucket name. Type {{FilePicker1.files}} as the File Objects Array. Alternatively, to allow for uploading a single file, set the S3 action to "Upload File" and set File Content to {{FilePicker1.files[0].readContents("raw")}}.

  6. If you want to customize the name of each file, for example by adding a prefix, write this snippet instead:

    {{ => ({...file, name: '/prefix/' + }))}}

  7. Go back to the User Interface editor and select a file. Click "Submit" to upload the file. When the API is finished running, the form will clear itself.

Guide - Display an uploaded file in an image component

This is a short guide on how to display a jpeg file that was uploaded via a FilePicker component in an Image component. Instructions for uploading and displaying other types of data can be found below:


Files uploaded via the FilePicker are temporarily stored in your browser and do not persist between sessions. Consider uploading files to an external storage location (e.g., Amazon S3) for permanent storage.

Display an file in image component that was uploaded via the file picker.
  1. Add a FilePicker component to the canvas.
  2. Add an Image component to the canvas.
  3. Add a new Backend API that has a single Python step.
  4. Add the following code to the Python step to construct a Data URL from the file content:
file_content = FilePicker1.files[0].readContents();
return "data:image/jpeg;base64," + file_content
  1. Rename the API to generateDataURL.
  2. Click on the Image component and set the Image property to {{generateDataURL.response}}.
  3. Upload a .jpeg file via the FilePicker.
  4. Run the Backend API by clicking the blue Run button.

What are Data URLs?

Data URLs, also known as data URIs (Uniform Resource Identifiers), are a type of URI scheme that allows data to be embedded directly within a URL. In other words, a data URL contains the actual data itself instead of pointing to a separate resource.

Data URLs consist of four components: a prefix (data:), a MIME type that specifies the data type, an optional base64 token when dealing with non-textual data, and the actual data. The mediatype is a MIME type:


Replace the Data URL in the guide above with an example from the table below if you want to upload and display a file of a different data type:

File typeData URL
jpegdata:image/jpeg;base64," + file_content
pngdata:image/png;base64," + file_content
gifdata:image/gif;base64," + file_content
pdfdata:application/pdf;base64," + file_content
...find more types here.

Example: Display a pdf file uploaded via a file picker in a PDF viewer component:


The PDF files that are uploaded via the File Picker component and passed to the PDF viewer component must be < 2 MB.

Display an file in PDF viewer component that was uploaded via the file picker.

FilePicker Properties

Component Properties

FilePicker PropertyDescription
Selection TypeSet the FilePicker widget to Multi select to handle multiple files or Single select to restrict it to one file at a time
Allowed File TypesFile types can either be mime types or suffixes. * represents a wildcard
VisibleControls the visibility of the component, values are a boolean
RequiredMakes adding a file mandatory, values are a boolean
Loading AnimationControls the loading state of the component, values are a boolean

Reference Properties

Properties can be accessed from other frontend components and backend APIs by adding the name of the FilePicker, and dot referencing the property. For a FilePicker named FilePicker1:

FilePicker1.filesReturns an array of files
FilePicker1.isVisibleReturns the boolean value of the component's visibility (True, if it is visible)