Selecting options from an external file

Last updated: 25 Nov 2025

Select from file questions allow you to use a list of choice options stored in an external file instead of defining them directly in your form. There are two types: select_one_from_file for selecting a single choice, and select_multiple_from_file for selecting multiple choices.

Using a separate file for your choice list makes it easier to manage long lists, reuse them across multiple forms, and update options when needed. Supported file formats include CSV, XML, and GeoJSON.

This article explains how to format your external file, set up your XLSForm to use select from file questions, and upload your external file to KoboToolbox.

Note: This article focuses on adding select from file questions in XLSForm. To learn about adding select from file questions in the KoboToolbox Formbuilder, see Select One or Many From External File Question Type.

For hands-on practice with select from file questions in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.

Formatting external choice lists

To get started, create your list of choices in a separate external file. The required structure of this file depends on the format you choose (CSV, XML, or GeoJSON). Use a separate file for each choice list.

To learn more about formatting XML or GeoJSON files, see XLSForm and ODK documentation. GeoJSON files are primarily used for selecting options from a map.

For CSV files, the structure is similar to the choices worksheet in an XLSForm. It should include the name and label columns, but the list_name column is not needed.

External CSV file

name

label

option1

Option 1

option2

Option 2

option3

Option 3

If your file uses different names for the choice name and label, you can specify this in your XLSForm (see instructions below).

Note: Use short, simple file names for your external files, avoiding spaces or special characters. The file name will be used in your XLSForm to link questions to their choice lists. If you use multiple external files, make sure each one has a unique name, even if they use different file types.

Setting up your XLSForm

To add a select from file question to your XLSForm:

  1. In the type column of the survey worksheet, enter the select from file question type (select_one_from_file or select_multiple_from_file).

  2. In the same cell, instead of the choices list_name, add a single space and the name of the external file, including the file extension.

    • For example: select_one_from_file households.csv

survey worksheet

type

name

label

select_one_from_file households.csv

hh

Select household

survey

Configuring choice name and label columns

If your external file uses different column names instead of name and label:

  1. Add a parameters column to the survey worksheet

  2. In the select from file question row, specify the custom names with the value and label parameters.

    • value represents the choice name.

    • label represents the choice label.

survey worksheet

type

name

label

parameters

select_one_from_file households.csv

hh

Select household

value=housenum label=housename

survey

Uploading the external file to KoboToolbox

When uploading your XLSForm to KoboToolbox, you must also upload the external file that contains your list of choices:

  1. In KoboToolbox, navigate to the project SETTINGS page.

  2. In the Media tab, upload the external file. Ensure the file name matches exactly the file name specified in the XLSForm.

To update your list of choices, edit the external file as needed, re-upload it to KoboToolbox, and redeploy your form.

Upload media

Troubleshooting

Translated choice lists Select from file questions do not currently support translated choice lists. Your external choice file can include only a single label column. Any additional translated label columns will be ignored in Enketo or will cause an error in KoboCollect. For forms that include translations, use internal choice lists instead, or set up multiple select from file questions using skip logic to pull from different files depending on the form language.