# list
Whenever a list jig is configured either in the [list](https://docs.jigx.com/examples/readme/components/list) , or [list-item](https://docs.jigx.com/examples/readme/components/list/list-item) component, the list is automatically populated on the surface of the widget without needing additional configuration. There is also the option to extend the list widget by using the `Extend List Widget` property, which reuses the list jig configuration and its data to extend or override some of the properties in the widget. The item data is called from `=@ctx.current.item.value`.
There are, instances when you want to create a list widget on a jig that is not a list jig, such as a `jig.default`. This is primarily where the list widget is used.
List widgets
## Configuration options
A list widget can be used on any type of jig, i.e. list, default, composite, calendar and document.
| **Core options** | |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `item` | The `item` property includes the setup options of: [Product-item ](https://docs.jigx.com/examples/product-item)[List-item](https://docs.jigx.com/examples/list-item) |
| **Other options** | |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `badge` |
Add a badge to the list widget to highlight critical information and capture the user's attention, ensuring key updates or notifications are easily noticeable within the app. The badge can be configured at the root level of the jig file:
To display as a red dot using the empty value.
A red dot with a number using an expression to perform a count. For example, counting the number of tasks in the list.
|
| `bottom` | The component will be added to the bottom of the widget. |
| `data` | Provide the datasource for the list. For example: `data: =@ctx.datasources.tasklist` |
| `footer` | Add text to the footer of the widget. |
| `footerAlign` | Align the footer text to `left`, `right`, `center`. |
| `placeholders` | Specify a placeholder text to display if there is no data, for example - `title: No data to display`. |
| `top` | The component will be added to the top of the widget. |
| **State Configuration** | **Key** | **Notes** |
| ------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `=@ctx.current.state.` | amount checked | Applies to a list, list.item, product-item, and stage components. List's data is an array of records. The `=@ctx.current.state` is the state of the current object in the array. |
| `=@ctx.component.state.` | amount checked | State is the variable of the component. |
| `=@ctx.solution.state.` | activeItemId now | Global state variable that can be used throughout the solution. |
## Configuration options for extended list widget
The `Extended List Widget` can only be used on a list jig . The purpose of using this widget is to customize what shows in the widget on the Home Hub rather than showing its automatic list display. The `Extended List Widget` must be configured with a size 2x2 or greater. Reuse the data in the list jig , for example, `=@ctx.datasources.users.title` or `=@ctx.current.item.value`.
| **Core options** | |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `item` |
|
## Examples and code snippets
## Automatic widget display because of list jig type (Simple)
{% columns %}
{% column %}
Automatic list widget
{% endcolumn %}
{% column %}
When using a `jig.list` and any size widget larger than 1x1 the list will automatically be displayed without additional configurations. This is visible in this example.
In this example, the list on the widget is the same as the `jig.list` once the widget has been accessed.
**Examples**: See the complete example using static data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/jigs/jigx-components/list-item/static-data/list-with-left-elements/list-with-left-checkbox-sd.jigx). See the complete example using dynamic data in [GitHub](https://docs.jigx.com/examples/readme/widgets/list).
**Datasources**: See the complete datasource for static data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/datasources/services/repair-services-static.jigx). See the complete datasource for dynamic data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/datasources/services/cleaning-services-dynamic.jigx)
{% endcolumn %}
{% endcolumns %}
{% tabs %}
{% tab title=" list-widget (Static)" %}
```yaml
data: =@ctx.datasources.repair-services-static
item:
type: component.list-item
options:
title: =@ctx.current.item.service
subtitle: =@ctx.current.item.description
```
{% endtab %}
{% tab title="list-widget (dynamic)" %}
```yaml
data: =@ctx.datasources.cleaning-services-dynamic
item:
type: component.list-item
options:
title: =@ctx.current.item.service
subtitle: =@ctx.current.item.area
```
{% endtab %}
{% tab title="grid-item" %}
```yaml
# Grid-item for the static jig.
children:
- type: component.grid-item
options:
size: "2x2"
children:
type: component.jig-widget
options:
jigId: list-widget
```
{% endtab %}
{% endtabs %}
## Automatic widget display because of list jig type (UI elements)
{% columns %}
{% column %}
{% endcolumn %}
{% column %}
When using a `jig.list` and any size widget larger than 1x1 the list will automatically be displayed without additional configurations.
In this example, the list on the widget is exactly the same as the `jig.list` once the widget has been accessed.
**Examples**: See the complete example using static data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/jigs/components/list-item/static-data/list-with-left-elements/list-with-left-checkbox-sd.jigx). See the complete example using dynamic data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/jigs/components/list-item/dynamic-data/list-with-left-elements/list-with-left-avatar-dd.jigx).
**Datasources**: See the complete datasource for static data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/datasources/services/repair-services-static.jigx). See the complete datasource for dynamic data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/datasources/services/cleaning-services-dynamic.jigx).
{% endcolumn %}
{% endcolumns %}
{% tabs %}
{% tab title="list-with-left-element (static)" %}
```yaml
data: =@ctx.datasources.repair-services-static
item:
type: component.list-item
options:
title: =@ctx.current.item.service
subtitle: =@ctx.current.item.description
leftElement:
element: checkbox
initialValue: =(@ctx.current.item.materials) = true ? true :false
```
{% endtab %}
{% tab title="list-with-left-element (dynamic)" %}
```yaml
data: =@ctx.datasources.cleaning-services-dynamic
item:
type: component.list-item
options:
title: =@ctx.current.item.service
subtitle: =@ctx.current.item.time & ' minutes for task completion'
leftElement:
element: avatar
text: $substring($substringBefore(@ctx.current.item.service, " "), 1, 1) & $substring($substringAfter(@ctx.current.item.service, " ") , 1, 1)
uri: =@ctx.current.item.illustration
```
{% endtab %}
{% tab title="grid-item" %}
```yaml
# Grid-item for the static jig.
children:
- type: component.grid-item
options:
size: "2x2"
children:
type: component.jig-widget
options:
jigId: list-with-left-element
```
{% endtab %}
{% endtabs %}
## List widget with stage component items
{% columns %}
{% column %}
This example is for list items that have a left and right element and shows a start-and-end. An example of this is flight schedules, however, this can be used for many different use cases as you can choose a different icon. Here a slightly different setup is used to that in the actual list to show you the widget configuration.
**Examples**: See the complete example using static data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/jigs/widgets/list/static-data/widget-list-stage-sd.jigx). See the complete example using dynamic data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/jigs/widgets/list/dynamic-data/widget-list-stage-dd.jigx).
**Datasources**: See the complete datasource for static data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/datasources/expanders%20and%20stages/flight-schedule-static.jigx). See the complete datasource for dynamic data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/datasources/expanders%20and%20stages/flight-schedule-dynamic.jigx).
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
{% tabs %}
{% tab title="stage-list-widget (static)" %}
```yaml
widgets:
stageStatic-2x2:
type: widget.list
options:
data: =@ctx.datasources.flight-schedule-static
item:
type: component.stage
options:
icon: plane-1
right:
title: =@ctx.current.item.toabrv
subtitle: =@ctx.current.item.to
left:
title: =@ctx.current.item.fromabrv
subtitle: =@ctx.current.item.from
```
{% endtab %}
{% tab title="stage-list-widget (dynamic)" %}
```yaml
widgets:
stageDD-2x2:
type: widget.list
options:
data: =@ctx.datasources.flight-schedule-dynamic
item:
type: component.stage
options:
icon: plane-2
right:
title: =@ctx.current.item.toabrv
subtitle: =@ctx.current.item.to
left:
title: =@ctx.current.item.fromabrv
subtitle: =@ctx.current.item.from
```
{% endtab %}
{% tab title="grid-item" %}
```yaml
# Grid-item for the static jig.
children:
- type: component.grid-item
options:
size: "2x2"
children:
type: component.jig-widget
options:
jigId: stage-list-widget
widgetId: stageStatic-2x2
```
{% endtab %}
{% endtabs %}
## List widget with product items
{% columns %}
{% column %}
2x2 product- item list widget
{% endcolumn %}
{% column %}
This example shows product items with their images and respective prices.
**Examples**: See the complete example using static data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/jigs/widgets/list/static-data/widget-list-product-item-sd.jigx) See the complete example using dynamic data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/jigs/widgets/list/dynamic-data/widget-list-product-item-dd.jigx)
**Datasources**: See the complete datasource for static data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/datasources/products/products.jigx). See the complete datasource for dynamic data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/datasources/products/products-dynamic.jigx).
{% endcolumn %}
{% endcolumns %}
{% tabs %}
{% tab title="list-product-widget (static)" %}
```yaml
widgets:
productStatic-2x2:
type: widget.list
options:
data: =@ctx.datasources.products
item:
type: component.product-item
options:
title: =@ctx.current.item.title
image:
uri: =@ctx.current.item.uri
price:
value: =@ctx.current.item.price
format:
numberStyle: currency
```
{% endtab %}
{% tab title="list-product-widget (dynamic)" %}
```yaml
widgets:
productDD-2x2:
type: widget.list
options:
data: =@ctx.datasources.products-dynamic
item:
type: component.product-item
options:
title: =@ctx.current.item.title
image:
uri: =@ctx.current.item.uri
price:
value: =@ctx.current.item.price
format:
numberStyle: currency
```
{% endtab %}
{% tab title="grid-item" %}
```yaml
# Grid-item for the static jig.
children:
- type: component.grid-item
options:
size: "2x2"
children:
type: component.jig-widget
options:
jigId: list-product-widget
widgetId: productStatic-2x2
```
{% endtab %}
{% endtabs %}
## List widget with list items
{% columns %}
{% column %}
This example shows a basic `component.list-item` setup.
**Examples**: See the complete example using static data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/jigs/widgets/list/static-data/widget-list-items-sd.jigx). See the complete example using dynamic data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/jigs/widgets/list/dynamic-data/widget-list-items-dd.jigx).
**Datasources**: See the complete datasource for static data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/datasources/events-and-calendars/calendar-data.jigx). See the complete datasource for dynamic data in [GitHub](https://github.com/jigx-com/jigx-samples/blob/main/quickstart/jigx-samples/datasources/events-and-calendars/calendar-data-dynamic.jigx%22)
{% endcolumn %}
{% column %}
