---
tags:
- UI Page widgets
alias: user-guide-uipage-widgets-entity-list
widgetname: Entity List
description: "This documentation details a widget for displaying and managing lists of entities, offering customization options and integration with queries"
---

# Entity List

:core-static-grid-sm:{style="font-size: 100px"}

## Overview

The Entity List widget displays a list of instances for a given entity type, such as a **Material** or a **Resource**. An example is shown below, where this widget is used to show all the available **Materials**.

![Entity List widget displaying a list of available Materials.](images/uiPageExample7.png)

## General

{% include-markdown 'includes/pages/ui_widgets_general_steps.md' %}

![Entity List widget general settings page showing the widget configuration interface.](images/entitylistview_general.png)

## Style

{% include-markdown 'includes/pages/ui_widgets_style.md' %}

## Setup

In the **Setup** tab, provide the Selection and View mode details:

* **Selection Mode** - Select the widget's selection mode: None, Single, or Multiple.
* **Display Mode** - Choose how the Entities will be displayed, either in List or Icons mode.
* **Subtitle Property Path** - Specify the property path for the subtitle.
* **Auto-Select First Element** - Choose whether to automatically select the first item in the list. This option is set to `false` by default.
* **Keep Selection** - Determine whether the selection should be retained when the entities in the list change or when the data source updates. This option is set to `false` by default.

In the Data section of the **Setup** tab, you can configure the Entity Type.

![Entity List setup page showing selection, display, subtitle, and entity type settings.](images/entitylistview_setup.png)

## Inputs

Optionally, define **Inputs**. You can add as many Inputs as you desire (press :material-plus: in the top right of the wizard to add, and :material-trash-can: to remove).

![Entity List inputs configuration page showing the available input settings.](images/entitylistview_inputs.png)

## Links

Optionally, define the **Links** between this widget and other elements of the UI Page.

![Entity List links configuration page showing connections to other UI page elements.](images/entitylistview_links.png)

By saving and closing the settings, the widget will be changed accordingly.

## Real Use Case

An Entity List widget can be used to show a list of selectable entities and then run a query that uses the user-selected entity as a parameter. To accomplish this, follow the steps below:

1. Add a task for the Entity List to the page properties. For the Entity List to start displaying a list, this first has to be made available on the page. The easiest way to do so is to add a [[user-guide-system-tasks-data-sources#query|Query]] as a task.

    ![Screenshot showing a UI with Entity List settings, including task details and query options.](images/entitylist_usecase_1.png)

2. Link the Query to the Entity List widget:

    ![Screenshot showing the Links tab of the Entity List widget, with a link created to the Query task.](images/entitylist_usecase_2.png)

3. After saving, the Entity List widget will display a scrollable list of **Materials**:

    ![Screenshot showing a scrollable list of materials in the Entity List widget.](images/image-20210518175532268.png)

4. Add any [[user-guide-uipage-widgets-query]] (as widget of type Query) to the UI Page that uses the Material entity as a parameter, and link it to the Entity List:

    !!! note
        To use an entity parameter in a Query requires the actual database ID to be provided via the link on the UI page. To accomplish this, a string property has to be added to the page:

    ![Screenshot showing a query widget linked to an entity list with properties for property details.](images/entitylist_usecase_3.png)

5. This string property can then be used in the link together with the `Any To Any Property` converter to transfer the ID of the selected entity to the Query.

    === "Link"

        ![Screenshot showing the Link tab configuration mapping the string property to the Query parameter.](images/entitylist_usecase_4.png)

    === "Converter"

        ![Screenshot showing a list of entities with an ID selected, illustrating the step to transfer the ID using the Any To Any Property converter.](images/entitylist_usecase_5.png)

6. The final result on the UI Page should look like this:

    ![Completed UI page showing the Entity List, the linked Form, and the Query widget displaying the selected Material's data.](images/image-20210518180630960.png)