Getting started with XLSForm

Last updated: 25 Nov 2025

When creating survey forms with KoboToolbox, you can build your form with the KoboToolbox Formbuilder or using XLSForm. XLSForm is very effective for creating both basic and advanced forms in a user-friendly format.

For more information about XLSForm, see Introduction to XLSForm. For a comprehensive introduction to form development using XLSForm, we recommend KoboToolbox Academy’s self-paced online XLSForm Fundamentals Course.

This article explains how to set up an XLSForm using Microsoft Excel or other spreadsheet programs, including:

• Setting up the basic structure of your XLSForm

• Adding questions and option choices

• Adding form settings and optional columns

• Uploading and previewing your XLSForm in KoboToolbox

Note: Some XLSForm features are not currently available in the Formbuilder, but KoboToolbox forms can be downloaded, modified in XLSForm, and uploaded back to KoboToolbox.

Setting up an XLSForm

To set up the basic structure of an XLSForm:

1. Create a workbook in your preferred spreadsheet software.

2. Create three worksheets: survey, choices, and settings.

   • Worksheet names must be all lowercase letters.

3. In the survey worksheet, create three columns with the headings: type, name, and label.

4. In the choices worksheet, create three columns with the headings: list_name, name, and label.

5. The settings worksheet is optional. It can be used to include additional form specifications and customizations.

   • For example: form_title, style, and default_language.

To get started with XLSForm, download a sample XLSForm here.

Mandatory columns in XLSForm

The following columns are mandatory in XLSForm:

survey worksheet

Column name	Description
type	Defines the question type (e.g., text, integer, select_one)
name	Defines a short, unique name to refer to each question
label	Defines the question text as it will be displayed in the form

choices worksheet

Column name	Description
list_name	Defines the unique identifier for a list of option choices
name	Defines a short, unique name to refer to each option choice
label	Defines the choice text as it will be displayed in the form

Adding questions

In XLSForm, questions are added in the survey worksheet. To add questions in XLSForm:

1. In the type column of the survey worksheet, enter the question type of the question you want to add.

2. In the name column, enter a name used to identify the question.

   • Each question must have a unique name and cannot contain spaces or symbols (except underscores).

3. In the label column, enter the question text as it should be displayed in the form during data collection.

survey worksheet

type	name	label
text	yourname	What is your name?
survey

4. If you are adding select type questions (select_one, select_multiple, or rank): in the type column, after the question type, add a space and enter the name of the list of choices.

   • The name of the list of choices is later defined in the choices worksheet as the list_name.

survey worksheet

type	name	label
select_one sex	baby_sex	What is your baby’s sex?
survey

To learn more about question types in XLSForm, see Question types in XLSForm.

Adding option choices

For select type questions, option choices are added in the choices worksheet. To add option choices in XLSForm:

1. In the list_name column of the choices worksheet, enter the name of the list of option choices.

   • The list_name is a unique identifier for a list of option choices. It must match the list name entered in the type column of the survey worksheet.

2. In the name column, add a short name for each option choice.

   • Each choice within a list must have a unique name, which cannot contain spaces or symbols (except underscores).

3. In the label column, enter the choice text as it should be displayed in the form during data collection.

choices worksheet

list_name	name	label
sex	male	Male
sex	female	Female
choices

To learn more about managing option choices in XLSForm, see Managing option choices in XLSForm.

Adding settings

There are many optional settings that can be added to the settings worksheet in XLSForm.

Common form settings include:

Setting	Description
form_title	Title displayed at the top of the form
default_language	Default form language
style	Themes for Enketo web forms
version	Form version ID

For example, to add a form title:

1. Add a column in the settings worksheet named form_title.

2. Enter the form title in the form_title column.

Note: All form settings are optional. If you do not define a form title in your XLSForm, the Excel file name will be used as the project name in KoboToolbox by default. This can be edited in KoboToolbox.

settings worksheet

form_title
Getting started with XLSForm
settings

To learn more about the settings worksheet in XLSForm, see Form settings in XLSForm.

Adding optional columns to the survey worksheet

To further customize your XLSForm, you can add optional columns to configure form logic, question options, and advanced settings. Common optional columns include:

Column name	Description
hint	Question hint
guidance_hint	Guidance hint
required	Option to make a question mandatory
relevant	Skip logic conditions for the question
constraint	Validation criteria for the question
constraint_message	Error message when validation criteria are not met
appearance	Options for how questions are displayed
choice_filter	Criteria for cascading select
parameters	Settings for specific question types
calculation	Mathematical expression for calculate question
default	Default response for a question

To learn more about optional columns in XLSForm, see Using question options in XLSForm, Question appearances in XLSForm, and Introduction to form logic in XLSForm.

Uploading and previewing your XLSForm in KoboToolbox

Once you have finished developing your XLSForm, you can upload and preview it in KoboToolbox:

1. Go to the Project home page in KoboToolbox and click NEW.

2. Select Upload an XLSForm and upload your XLSForm file.

3. Enter the project details and click CREATE PROJECT.

4. Click the Preview button.

If your XLSForm contains an error, an error message will appear, usually indicating the exact row, question, or expression where the issue is located. After correcting the error in your XLSForm, you will need to upload the file again.

To learn how to download an XLSForm from KoboToolbox, import your XLSForm via URL, and use KoboToolbox to validate and test your XLSForm, see Using XLSForm with KoboToolbox.