# List View
List view displays a list of interactive items, and allows a user to navigate, select, or perform an action. It offers greater flexibility in the contents it can render and can distinguish between row selection and actions performed on a row. This makes list view an ideal component for turning table columns into interactive lists.
## Example
```python
from deephaven import ui
@ui.component
def ui_list_view():
return ui.list_view(
ui.item("Option 1"),
ui.item("Option 2"),
ui.item("Option 3"),
ui.item("Option 4"),
default_selected_keys=["Option 2", "Option 3"],
)
my_list_view = ui_list_view()
```
## Table Source Example
List view items can also be generated from a table directly or using `item_table_source`.
### Passing Table Directly
This method is ideal for quickly displaying a static dataset. By default, the first column is used as the key and label.
```python
from deephaven import ui, new_table
from deephaven.column import string_col
_colors = new_table(
[
string_col("Colors", ["Red", "Blue", "Green"]),
]
)
@ui.component
def ui_list_view_table():
return ui.list_view(_colors)
my_list_view_table = ui_list_view_table()
```
### Using item_table_source
`item_table_source` is used to create complex items from a table (ie., defining which columns are the keys/labels of the data).
```python
from deephaven import ui, new_table
from deephaven.column import string_col
_table = new_table(
[
string_col("Keys", ["key-0", "key-1", "key-2"]),
string_col("Labels", ["Option 0", "Option 1", "Option 2"]),
]
)
@ui.component
def ui_list_view_table_source():
source = ui.item_table_source(_table, key_column="Keys", label_column="Labels")
return ui.list_view(source)
my_list_view_table_source = ui_list_view_table_source()
```
## Events
List view accepts an action that can be triggered when a user performs an action on an item.
```python
from deephaven import ui, new_table
from deephaven.column import string_col
_table = new_table(
[
string_col("Keys", ["key-0", "key-1", "key-2"]),
string_col("Labels", ["Option 0", "Option 1", "Option 2"]),
]
)
@ui.component
def ui_list_view_actions():
action_item_keys, set_action_item_keys = ui.use_state(["", ""])
on_action = ui.use_callback(
lambda action_key, item_key: set_action_item_keys([action_key, str(item_key)]),
[],
)
source = ui.item_table_source(
_table,
key_column="Keys",
label_column="Labels",
actions=ui.list_action_group(
"Edit",
"Delete",
on_action=on_action,
),
)
lv = ui.list_view(source)
text_action = ui.text("Action: " + " ".join(map(str, action_item_keys)))
return lv, text_action
my_list_view_actions = ui_list_view_actions()
```
List view can also accept a handler that is called when the selection is changed.
```python
from deephaven import ui, new_table
from deephaven.column import string_col
_table = new_table(
[
string_col("Keys", ["key-0", "key-1", "key-2"]),
string_col("Labels", ["Option 0", "Option 1", "Option 2"]),
]
)
@ui.component
def ui_list_view_selection():
value, set_value = ui.use_state(["key-2"])
def handle_change(e):
set_value(e)
print("Selection: " + ", ".join(map(str, e)))
source = ui.item_table_source(
_table,
key_column="Keys",
label_column="Labels",
)
lv = ui.list_view(source, on_change=handle_change)
return lv
my_list_view_selection = ui_list_view_selection()
```
## Disabled Options
To disable certain rows in the `ListView` component, use the `disabled_keys` prop. By setting this prop with an array of keys, you can prevent interaction with those rows, providing greater control and customization options for the `ListView` behavior.
```python
from deephaven import ui, new_table
from deephaven.column import string_col
_table = new_table(
[
string_col("Keys", ["key-0", "key-1", "key-2"]),
string_col("Labels", ["Option 0", "Option 1", "Option 2"]),
]
)
@ui.component
def ui_list_view_disabled():
value, set_value = ui.use_state(["key-2"])
source = ui.item_table_source(
_table,
key_column="Keys",
label_column="Labels",
)
lv = ui.list_view(
source, selected_keys=value, on_change=set_value, disabled_keys=["key-0"]
)
return lv
my_list_view_disabled = ui_list_view_disabled()
```
## Quiet State
```python
from deephaven import ui
@ui.component
def ui_list_view_quiet():
value, set_value = ui.use_state(["Text 2"])
quiet_list = ui.list_view(
"Text 1",
"Text 2",
"Text 3",
aria_label="List View - Quiet",
on_change=set_value,
selected_keys=value,
is_quiet=True,
)
default_list = ui.list_view(
"Text 1",
"Text 2",
"Text 3",
aria_label="List View - Default",
on_change=set_value,
selected_keys=value,
)
return quiet_list, default_list
my_list_view_quiet = ui_list_view_quiet()
```
## Modifying Density
To adjust the vertical padding of each row in the list view, use the `density` prop.
```python
from deephaven import ui
@ui.component
def ui_list_view_density():
value, set_value = ui.use_state(["Text 2"])
compact_list = ui.list_view(
"Text 1",
"Text 2",
"Text 3",
aria_label="List View - Compact",
on_change=set_value,
selected_keys=value,
density="compact",
)
spacious_list = ui.list_view(
"Text 1",
"Text 2",
"Text 3",
aria_label="List View - Spacious",
on_change=set_value,
selected_keys=value,
density="spacious",
)
return compact_list, spacious_list
my_list_view_density = ui_list_view_density()
```
## Overflow Mode
The default behavior is to truncate content that overflows its row. Text can be wrapped instead by adding `wrap` to the `overflow_mode` prop.
Note: Currently not supported if a table source is used.
```python
from deephaven import ui
@ui.component
def ui_list_view_overflow():
value, set_value = ui.use_state(["Text 2"])
truncated_list = ui.list_view(
"Really long Text 1",
"Really long Text 2",
"Really long Text 3",
aria_label="List View - Quiet",
on_change=set_value,
selected_keys=value,
overflow_mode="truncate",
width="150px",
)
wrapped_list = ui.list_view(
"Really long Text 1",
"Really long Text 2",
"Really long Text 3",
aria_label="List View - Quiet",
on_change=set_value,
selected_keys=value,
overflow_mode="wrap",
width="150px",
)
return truncated_list, wrapped_list
my_list_view_overflow = ui_list_view_overflow()
```
## API reference
A list view that can be used to create a list of items. Children should be one of three types:
1. If children are of type Item, they are the list items.
2. If children are of type Table, the values in the table are the list items.
**Returns:** `Element` The rendered ListView.
## Item Table Source API reference
An item table source wraps a Table or PartitionedTable to provide additional information for
creating complex items from a table.
A PartitionedTable is only supported if the component itself supports a PartitionedTable as a child.
A PartitionedTable passed here will lead to the same behavior as passing
the PartitionedTable directly to a component, such as creating sections from the partitions in the case of a Picker.
**Returns:** `ItemTableSource` The item table source to pass as a child to a component that supports it.