---
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

![EntityList][EntityList]

## 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 **Resources**.

![EntityListExample][EntityListExample]

## General Steps

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

![EntityListGeneral][EntityListGeneral]

## Widget Customization

1. Optionally, in the **Style** tab, you can define a Border Width and Color.

    ![Screenshot showing the Entity List settings with options for border customization.](images/entitylist_style.png)

2. 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** - Defines 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, you can configure the Entity Type.

    ![EntityListSetup][EntityListSetup]

3. 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).

    ![EntityListInputs][EntityListInputs]

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

    ![EntityListLinks][EntityListLinks]

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

## Real Use Case

An Entity List widget can be used to present the user with a list of selectable entities and then run a query that uses the user selected entity as parameter. To accomplish this, you should 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 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 Entity List widget settings with links to unknown details and a query key.](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 as parameter the Material entity and link it to the entity list:

    !!! note
        To use the 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 a list of entities with links and details.](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:

    ![Screenshot showing a UI page with a jumbled mix of letters and symbols.](images/image-20210518180630960.png)

[EntityList]: images/uiEntityListView.png
[EntityListExample]: images/uiPageExample7.png
[EntityListGeneral]: images/entitylistview_general.png
[EntityListInputs]: images/entitylistview_inputs.png
[EntityListSetup]: images/entitylistview_setup.png
[EntityListLinks]: images/entitylistview_links.png