How to use a CSV file or static JSON data

TeleportHQ has two data sources for fixed lists that don't come from a database: CSV File, where you upload a spreadsheet export once, and JavaScript, where you type the list yourself as an array of items. Both are added from Data Sources → Add Data Source, and both can fill lists, tables and details pages on your site.

Before you start#

• Choose the right option. Use CSV File for a list exported from another tool, like a product catalog. Use JavaScript for a short list you type, like 5 team members.
• Neither updates by itself. To change the data later, upload a new file or edit the code. For data that changes often, use a Google Sheet or the TeleportHQ database.
• You can add as many CSV files and JavaScript lists as you need. Neither turns a TeleportHQ website into a web app.

Upload a CSV file to TeleportHQ#

To use a CSV file as a TeleportHQ data source:

1. In the left sidebar, click Data Sources (the database icon).
2. In the Data Sources panel, click + (tooltip Add Data Source).
3. Click the CSV File card. A panel titled CSV File opens with the section Setup CSV File.
4. In Data Source Name, type a name, for example Product catalog. Use letters, numbers, spaces and underscores.
5. Under Upload CSV File, click Click to select a CSV file and choose your .csv file. You can also drag the file onto that area.
6. Click Extract data from CSV.

7. The View Data section below shows the first rows. Check that the columns look right.
8. Click Save Data Source under the preview. If this is the project's first data source, a window titled IMPORTANT appears; click I understand.

If the first row is read as an item instead of column names, click Setup CSV File to open the setup again, turn off Automatically detect header row, turn on First row is header row, and click Extract data from CSV again.

Type static data with the JavaScript data source#

To type a fixed list as a TeleportHQ data source:

1. In the Data Sources panel, click + (tooltip Add Data Source).
2. Click the JavaScript card. A panel titled JavaScript opens. Its JavaScript Code box holds an example list with two items.
3. In Data Source Name, type a name, for example Team members. If you leave it empty, a name is created for you.
4. In JavaScript Code, replace the example with your list. The code must be a valid JavaScript array, as the panel says: "Write JavaScript code that returns an array." That is a pair of square brackets holding one { … } block per item.
5. Click Save Data Source. If this is the project's first data source, a window titled IMPORTANT appears; click I understand.

For example, a team list with three people:

[
  { id: 1, name: "Ana Pop", role: "Head baker", photo: "https://example.com/ana.jpg" },
  { id: 2, name: "Mihai Ionescu", role: "Pastry chef", photo: "https://example.com/mihai.jpg" },
  { id: 3, name: "Ioana Radu", role: "Front of house", photo: "https://example.com/ioana.jpg" }
]

The Save Data Source button stays disabled while the code has errors. When you edit an existing JavaScript source, it also stays disabled until you change something.

Check that it worked#

The new data source appears as a card in the Data Sources panel. Add an Array Mapper to a page and bind it to the source to see the items. See How to show a list of items.

Troubleshooting#

"Failed to parse CSV" The file isn't a valid CSV. Export it again from your spreadsheet app as "CSV (comma-separated values)" and upload the new file.

"Please load preview data before saving" Click Extract data from CSV before Save Data Source.

Save Data Source is greyed out (JavaScript) The code has an error, such as a missing comma, bracket or quote. Fix the highlighted line. The whole code must be one array that starts with [ and ends with ].

Good to know#

• The CSV contents are saved inside your project. Changing the original file on your computer doesn't change the site. To update, open the data source, click Click to select a different file, extract and save again.
• You can't edit CSV rows in TeleportHQ. To edit rows, sort them or add new ones in the editor, import the file into the TeleportHQ database instead: see Import data from a spreadsheet file. The same import takes a .json file holding a list of items and turns it into a table you can edit. In a JSON file every name is in double quotes, for example [{"name": "Ana Pop", "role": "Head baker"}].
• The JavaScript source has no preview step. Check the result on the canvas after binding a list to it.
• Both sources can power details pages, one page per item. See Create a page for each item.