Please note: this is a legacy article which refers to features or aspects of our tools which have been or will be phased out in the future.


The Option List Hierarchy control allows you to create option lists which are organised into tiers or levels. Selecting an option at one level filters the options at the next level and so on.  At the bottom level, the final selection can be made.

How to set up an option hierarchy control

1. Add a text variable to your form. This is the input field and it will hold the data for the option list. Once you have created this field, hover over it and note the system-assigned field ID - you will need this to complete setting up the Option List Hierarchy. The data should be entered in the format below using tabs to indicate the option level. Each option should be on a new line and a colon should be used to separate the option label from the option value.

Tip: Set up your options using an application like Notepad and then paste it back into the default box for the variable that you've just created.


On the first level in this example, the province is selected (denoted by P); on the second level area is selected (denoted by A); and on the third level, a school is selected (denoted by S). Note how the values for each option has been set up, however, the values can be set up in any way that you would like them to be.

2. Create a second text variable. This is the output field and it will hold the final selection made by the fieldworker. Once you have created the field, hover over it and note the system-assigned ID as you will need it later. The default value for this variable does not need to be populated.

3. Once you have completed steps 1 and 2, you will need to add the Option List Hierarchy menu item to your form as follows:

  • Click on 'Optional Form Settings'.

  • Once the tab has opened, click on ‘Form Menu and Enhanced controls’.

  • Add the menu item.

4. Next you will need to add an instruction field to your form that will display on the fieldworker's handset. When the fieldworker reaches this field, they will need to select 'Options' to see the option list. Remember to tick the Option List Hierarchy control (under Custom Menu) to enable it on this field.


Your Option List Hierarchy control is now set up. This is what it will look like on a handset:

Note: The ordering of the fields is important. If the Instruction field (step 4) is before the variable fields (step 1 and 2), then the options will not display correctly.