Skip to main content

File Picker

Upload or process files in Superblocks APIs

Use the file picker 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.

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>)

Here are some items to note 👇

  1. Binary files will default to base64 encoding.
  2. You can base64 encode files by using the binary mode.
  3. If using the S3 multiple file upload, you only need to provide {{ <FilePickerComponentName>.files }}.

Use File Picker to Import Files

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

  1. Start by dragging a Container component from the Components panel to the empty canvas.
  2. Now add a File picker 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, file picker, button, and text component to the canvas

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

  1. Click the File picker 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 File picker 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 file picker component to import CSV files and view them in a table

Simple file upload to S3

Using the Form component with the File picker is common, because the form includes Submit and Reset buttons automatically. In this example, we will allow users to upload PDF and Microsoft Office documents to our S3 store.

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

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

  2. Drag and drop the Form component, and then drag and drop the File picker 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.

File Picker Properties

Component Properties

File Picker PropertyDescription
Selection TypeSet the file picker 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 File Picker, and dot referencing the property. For a File Picker named FilePicker1:

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