ListView Animation Builder

You can combine ListView with Animation Builder to create scroll-driven animations. For example, you might want to fade in a header or change the opacity of a widget based on the scroll position.

How It Works

1. Create and bind a Scroll Controller to the ListView. See the Variables documentation for how to create Scroll Controller variables.

2. Bind the same controller to an Animation Builder widget.

3. Access the scroll value in the Animation Builder

   • Inside the Animation Builder's child, use the animationValue variable to access the current scroll offset.

   • Use this value to drive animations (e.g., changing opacity, scaling, or translating widgets).

Example Use Case

A common pattern is to show/hide an AppBar or change its style as the user scrolls.

Step-by-Step Implementation

1. Create a Scroll Controller Variable

   • Go to Variables in your project

   • Add a new Scroll Controller variable named listScrollController

2. Set up your ListView

   • Add a ListView widget to your page

   • In the Controller property, bind it: ${listScrollController}

   • Configure your data source and item template as usual

3. Add an Animation Builder

   • Place an Animation Builder widget where you want the scroll-driven animation (e.g., above the ListView for a dynamic header)

   • In the Controller property of the Animation Builder, bind the same controller: ${listScrollController}

4. Create the Animation

   • Inside the Animation Builder's child, use ${animationValue} to access the scroll offset

   • Example: To fade out a header as you scroll, set the opacity to ${diff(1, divide(animationValue, 200))} (this will fade from 1 to 0 as you scroll 200 pixels)

Common Patterns

Collapsing Header

As the user scrolls down, reduce the height or opacity of a header widget.

Opacity: ${max(0, diff(1, divide(animationValue, 200)))}
Height: ${max(50, diff(200, animationValue))}

Showing Scroll-to-Top Button

Display a button only after scrolling past a certain point.

Visible: ${gt(animationValue, 300)}

Parallax Effect

Move a background image slower than the scroll speed.

Transform Y: ${mul(animationValue, 0.5)}

Tip: Use mathematical operators like max(), min(), and arithmetic operations to create smooth, bounded animations. See the Math Operators documentation for more details.

Best Practices

• Keep animations smooth: Use animateTo() instead of jumpTo() when programmatically scrolling

• Set reasonable bounds: Use max() and min() to prevent values from going too high or low

• Test on devices: Scroll-driven animations can behave differently on various screen sizes

• Consider performance: Complex animations on every scroll event can impact performance on lower-end devices

Related Documentation

• Animation Builder - Complete Animation Builder widget reference

• Variables - Learn about Scroll Controller and other variable types

• ListView - Complete ListView widget reference