---
title: "Vision - List"
description: "The list component displays a list of options, allowing freeform selection of the items."
---

# Vision - List

> The list component displays a list of options, allowing freeform selection of the items.

![](list0.png)

**Component Palette Icon**:  

![](list1.png)

## Description

The List component displays a list of options, allowing freeform selection of the items. It is powered by a Dataset, from which it displays the first column.

## Properties
| Property 	| Description 	| Property Type 	| Scripting 	| Category 	|
|---	|---	|---	|---	|---	|
| Background Color 	| The background color of the component. Can be chosen from color wheel, chosen from color palette, or entered as RGB or HSL value. See [Color Selector](appendix/reference-pages/color-selector-reference/color-selector-reference.mdx). 	| Color 	| .background 	| Appearance 	|
| Border 	| The border surrounding this component. Options are No border, Etched (Lowered), Etched (Raised), Bevel (Lowered), Bevel (Raised), Bevel (Double), and Field Border.**Note**: The border is unaffected by rotation. As of 8.1.21, the "Button Border" and "Other Border" options are removed. 	| Border 	| .border 	| Common 	|
| Cursor 	| The mouse cursor to use when hovering over this component. Options are: Default, Crosshair, Text, Wait, Hand, Move, SW Resize, or SE Resize. 	| int 	| .cursorCode 	| Common 	|
| Data 	| A dataset that The data for the list. If multiple columns exist, the first will be used. 	| Dataset 	| .data 	| Data 	|
| Enabled 	| If disabled, a component cannot be used. 	| boolean 	| .componentEnabled 	| Common 	|
| Font 	| Font of text on this component. 	| Font 	| .font 	| Appearance 	|
| Foreground Color 	| The foreground color of the component. See [Color Selector](appendix/reference-pages/color-selector-reference/color-selector-reference.mdx). 	| Color 	| .foreground 	| Appearance 	|
| Layout Orientation 	| This property defines the orientation of the list elements. 	| int 	| .layoutOrientation 	| Appearance 	|
| Mouseover Text 	| The text that is displayed in the tooltip which pops up on mouseover of this component. 	| String 	| .toolTipText 	| Common 	|
| Name 	| The name of this component. 	| String 	| .name 	| Common 	|
| Opaque 	| If false, backgrounds are not drawn. If true, backgrounds are drawn. 	| boolean 	| .opaque 	| Common 	|
| Quality 	| The data quality code for any Tag bindings on this component. 	| QualityCode 	| .quality 	| Data 	|
| Row Height 	| An integer specifying the row height, or -1 for automatic row height. 	| int 	| .rowHeight 	| Appearance 	|
| Selected Background 	| The color of the background for the selected cell(s). 	| Color 	| .selectedBackground 	| Appearance 	|
| Selected Focus Border 	| The border for the selected, focused cell. 	| Border 	| .selectedFocusBorder 	| Appearance 	|
| Selected Foreground 	| The color of the foreground for the selected cell(s). See [Color Selector](appendix/reference-pages/color-selector-reference/color-selector-reference.mdx). 	| Color 	| .selectedForeground 	| Appearance 	|
| Selected Index 	| The index of the selected cell, or -1 if none. 	| int 	| .selectedIndex 	| Data 	|
| Selection Mode 	| This mode determines if only one cell can be selected at once, or single or multiple intervals. 	| int 	| .selectionMode 	| Behavior 	|
| Styles 	| Contains the component's styles. 	| Dataset 	| .styles 	| Appearance 	|
| Visible 	| If disabled, the component will be hidden. 	| boolean 	| .visible 	| Common 	|
| Visible Row Count 	| An integer specifying the preferred number of rows to display without requiring scrolling. 	| int 	| .visibleRowCount 	| Appearance 	|

### Deprecated Properties
| Property 	| Description 	| Property Type 	| Scripting 	| Category 	|
|---	|---	|---	|---	|---	|
| Data Quality 	| The data quality code for any Tag bindings on this component. 	| int 	| .dataQuality 	| Deprecated 	|

## Scripting
See the [Vision - List Scripting Functions](list-scripting-functions.md) page for the full list of scripting functions available for this component.

### Event Handlers
Event handlers allow you to run a script based off specific triggers. See the full list of available event handlers on the [Component Events](ignition-modules/vision/scripting-in-vision/component-events/component-events.md) page.

## Customizers
* [Vision Component Customizers](ignition-modules/vision/working-with-vision-components/vision-component-customizer/vision-component-customizer.md)
* [Style Customizer](ignition-modules/vision/working-with-vision-components/vision-component-customizer/vision-component-customizer.md#style-customizer)

## Examples
```py title="Code Snippet"
# This example will create a dataset, and assign the dataset to
#  the List component's Data property.
headers = ["my header"]
data = [["Thing 1"],["Thing 2"],["Thing 3"]]
 
dataset = system.dataset.toDataSet(headers, data)
 
# Assign the dataset. The path below may need to change depending on
# what component is triggering this script.
event.source.data = dataset
```
```py title="Code Snippet"
# The following code will print the selected value to the console when called on the 'mouseClicked' event handler.
value = event.source.getSelectedValue()
print(value)
```
```py title="Code Snippet"
# The following code uses setSelectedValues to set the selection on the component.
# Assuming the List component contains string values of either "Thing 1" or "Thing 2", both items will be selected.
 
# Build a Python list of things to check for in the List component
valueList = ["Thing 1", "Thing 2"]
 
# Locate the List component in the window, and call setSelectedValues, passing the valueList as an argument.
event.source.setSelectedValues(valueList)
```