Create and configure a list values control

A list values control lets a user choose one or more values from a list to include or exclude those values from targeted data elements.

A list values control displays a searchable dropdown list. If you want a small, always-visible list of single-select buttons instead, choose a segmented control.

User requirements

• You must have Can edit access to the document, or Can explore access to the workbook to make changes in a custom or saved view.

Create a list values control

To create a list values control, do the following:

1. Open the document for editing.

2. Add a control element from either the Add element bar or from a column:

   • Add element bar: On the Add element bar, select Controls, then select List values.
   • Column: Right-click the name of a column, then select Add control.

   The new control appears on the canvas.

3. Select the control element, then in the Properties tab of the editor panel, configure the control. See Configure the control.

4. (Optional) Select Targets to specify which elements to filter when the user interacts with the control. See Specify the target of the control.

Configure the control

To configure the control behavior, select the Settings tab. You can populate the values used by a list values control in different ways:

• Create a manual list. For your control to work, the list must correspond in some way with the data in the target data elements. Use a manual list when you want to control the exact values that are available, regardless of what’s in the data, or when the values don’t come from a single column.
• Create a list from a preset defined by Sigma. Use a preset when your list matches one of Sigma’s built-in options, such as month or weekday names, so you don’t have to enter the values yourself.
• Use a column in your data. Use a column from a data element or data source when you want the control’s values to stay in sync with the underlying data, such as a list that grows or changes over time.

Use a manual list

You can create a manual list to select custom values. You still reference a data table or a data element, but you can directly name the data segments you want to use, regardless of their relative frequency in the data.

1. In the Properties tab for the control, select the Settings tab.
2. For Value source, select Create manual list.
3. For Value type, specify the data type of the values that you add manually. The data type must match the data type of the columns targeted by the control. Choose between Text (default), Number, Date, and Boolean.
4. For Values, enter a custom list of values to use for the control. Press enter or return to add new values. You can optionally specify a display value to show in the control instead of the raw data value.

Use a list from a preset

This option lets you choose from a common set of presets: Month names, Weekday names, and Date parts. After you select one of these options, your control is a manual list. You can change it, remove values, and add new values.

1. In the Properties tab for the control, select the Settings tab.

2. For Value source, select Create list from preset and choose one of the preset options:

   • Month names
   • Weekday names
   • Date parts

3. After selecting a preset list, the Value type and Values automatically update. The Value source changes to Create manual list to reflect that a preset list is a pre-populated manual list.

4. Modify the preset list as desired, removing unneeded values and changing display values. To delete a value, hover over the value and select x.

Use a column from a data element or data source

1. In the Properties tab for the control, select the Settings tab.

2. For Value source, select a data source or data element in use on the workbook.

3. For Source column, the first column of the data source is shown. Select the column to open a drop-down menu and choose the column that you want to use to populate the control.

   Up to 200 distinct values from the column can be displayed in the list values control.

4. (Optional) To use a different related column as the display values for the data, turn on the Set display column toggle and choose a display column from the same data source.

   For example, you might use an ID column as the data source, but a name column as the display value. This option isn’t available when the source column contains logical (Boolean) values.

Additional control settings

After the control values are populated, you can configure the following options:

(Optional) Decide whether to update the default Control ID. See About control IDs.

Specify the target of the control

Add targets to a control to specify which data elements and data sources to filter:

1. Select the control, then in Properties, click Targets.

2. Click + (Add filter target).

3. Select one or more elements in your workbook that you want to be changed by the control.

   The table appears under Targets, and the count of targets for the control increases to 1. As you add other targets to this control, the count increases.

4. Update the column targeted by the control. By default, the control targets the first column of the table. To change the target column, click the current column and choose the new target column.

   As you change the target column, the default name of the control updates to match the selected column.

Format and design a list values control

You can format and design the list values control to match the styling of your workbook. To review and update the formatting options, select the Format tab.

Update the element style

You can customize the style of the element, such as the background. See Customize element background and styles.

Update the control label

Update the alignment of the control

You can align a list values control within the element boundaries on the workbook canvas. Choose from the horizontal alignment options Left align (default), Right align, and Stretch, and the vertical alignment options Top align, Center align, and Bottom align.

Related resources

• Intro to control elements
• Create and manage a control element
• Reference control values as parameters
• Create and configure a segmented control