Drawing lists: rx.foreach

To-do lists, comments, product cards: whenever the same shape repeats on a page, you draw it from list data. In this lesson, you'll use rx.foreach to render a list stored in State.

3-1. Drawing a list with rx.foreach (3 min)

class ListState(rx.State):
    items: list[str] = ["Apple", "Banana", "Cherry"]


def render_item(item: rx.Var[str]):
    # Render a single item.
    # Note that item here is a Var, not a str!
    return rx.list.item(item)


def show_fruits():
    return rx.list.unordered(
        rx.foreach(ListState.items, render_item),
    )

You pass two things to rx.foreach:

1. A list Var: ListState.items
2. A function that renders one item: render_item. Pass the function itself, without parentheses.

Reflex applies render_item to each item in the list to build the components. If items are added to or removed from the list later, the list on the page updates too. You'll see this for yourself with the fruit basket in Lesson 6.

3-2. item is a Var, not a string (2 min)

Notice that the item that render_item receives is typed rx.Var[str], not str. This matters.

• render_item is a UI function too, so it runs only once, when the app starts. At that point there's no telling what the list will contain, so item is a Var that points to "a value to be filled in later."
• That's why you can't use Python built-ins like len(item). Instead, you use the Var operations Reflex provides for Vars: item.length() gives the number of characters, and item.upper() gives the uppercase version. This is also the topic of Lesson 4.

For the same reason, a Python list comprehension like [rx.list.item(i) for i in ListState.items] won't work either. To loop over a list in State, always use rx.foreach.

Exercises

1. Add two more fruits to items and check that they appear on the page.
2. Change render_item to return rx.badge(item) instead of rx.list.item. The same data is drawn in a different shape.
3. Write an event handler that adds a fruit to items when you click a button. The answer is in Lesson 6.

Checkpoint

• You can name the two things you pass to rx.foreach.
• You know why the item-rendering function receives a Var.
• You know to use rx.foreach rather than a list comprehension for lists in State.