---
title: "ListView"
description: "ListView api."
---
import CodeSnippetMD from '@slint/common-files/src/components/CodeSnippetMD.astro';
import Link from '@slint/common-files/src/components/Link.astro';

A ListView is like a [ScrollView](/latest/docs/slint/reference/std-widgets/views/scrollview.md) but it should have a `for` element, and the contents are
automatically laid out in a list.

In a ListView, elements are only instantiated if they are visible, which guarantees stable performance with a practically unlimited number of items.
[ScrollView](/latest/docs/slint/reference/std-widgets/views/scrollview.md) is more suitable for free-form content.

<CodeSnippetMD imagePath="/src/assets/generated/std-widgets-listview-example.png"  imageWidth="200" imageHeight="200"  imageAlt='listview example'>
```slint playground
import { ListView, VerticalBox } from "std-widgets.slint";
export component Example inherits Window {
    width: 150px;
    height: 150px;

    VerticalBox {
        ListView {
            for data in [
                { text: "Blue", color: #0000ff, bg: #eeeeee},
                { text: "Red", color: #ff0000, bg: #eeeeee},
                { text: "Green", color: #00ff00, bg: #eeeeee},
                { text: "Yellow", color: #ffff00, bg: #222222 },
                { text: "Black", color: #000000, bg: #eeeeee },
                { text: "White", color: #ffffff, bg: #222222 },
                { text: "Magenta", color: #ff00ff, bg: #eeeeee },
                { text: "Cyan", color: #00ffff, bg: #222222 },
            ] : Rectangle {
                height: 30px;
                background: data.bg;
                width: parent.width;
                Text {
                    x: 0;
                    text: data.text;
                    color: data.color;
                }
            }
        }
    }
}
```
</CodeSnippetMD>

## Properties

Same as [ScrollView](/latest/docs/slint/reference/std-widgets/views/scrollview.md).


## Callbacks

Same as [ScrollView](/latest/docs/slint/reference/std-widgets/views/scrollview.md).

## Functions

### ensure-row-visible(row: int, behavior: ScrollBehavior)

Call this function to scroll the list so that the row at index `row` is fully visible.
A row above the viewport, or a row taller than the viewport, ends up at the top edge.
Any other row ends up at the bottom edge.
A row that's already fully visible doesn't move, but a running scroll animation stops.
If `row` is out of range, the call does nothing.
Pass `ScrollBehavior.instant` to jump or `ScrollBehavior.smooth` to animate, see [`ScrollBehavior`](/reference/property-types/builtin-enums/#scrollbehavior).

```slint {9}
import { Button, ListView, VerticalBox } from "std-widgets.slint";
export component Example inherits Window {
    width: 150px;
    height: 150px;

    VerticalBox {
        Button {
            text: "Show row 42";
            clicked => { list.ensure-row-visible(42, ScrollBehavior.instant); }
        }
        list := ListView {
            for i in 100 : Text { text: "Row \{i}"; }
        }
    }
}
```