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
import json

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

Use case - 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.

  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.

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)