In Flutter, how does AnimatedList animate rows in and out, and why must insertItem and removeItem be paired with changes to your data?
answer
- it keeps its own item count
- GlobalKey<AnimatedListState>
- itemBuilder receives an Animation<double>
- removeItem needs a removed-item builder
- 300 ms by default
basics
~20 sAnimatedList keeps its own item count, starting from initialItemCount, and changes it only through AnimatedListState.insertItem and removeItem, reached with a GlobalKey. Change your data in the same step, and give removeItem a builder that draws the removed item.
solid answer
~40 s`AnimatedList` does not diff your data. It holds its own count, set once from `initialItemCount`, and changes it only when you call `insertItem` or `removeItem` on its `AnimatedListState`, usually through a `GlobalKey<AnimatedListState>` or `AnimatedList.of(context)`. Its `itemBuilder` gets `(context, index, animation)`, and I wrap the row in a transition such as `SizeTransition` or `FadeTransition` driven by that animation. To insert, I add to my list and call `insertItem(index)` together. To remove, I take the item out of my list first, keep it in a variable, and call `removeItem(index, (context, animation) => row(removed, animation))`: the index no longer maps to data, so the builder must draw the captured item while the animation runs backwards. Both default to 300 ms. `SliverAnimatedList` and `AnimatedGrid` work the same way.
code
dart · 53 linesimport 'package:flutter/material.dart';
class ToPackList extends StatefulWidget {
const ToPackList({super.key, required this.initial});
final List<String> initial;
@override
State<ToPackList> createState() => _ToPackListState();
}
class _ToPackListState extends State<ToPackList> {
final _listKey = GlobalKey<AnimatedListState>();
late final List<String> _items = [...widget.initial];
Widget _row(String label, Animation<double> animation, {bool interactive = true}) {
return SizeTransition(
sizeFactor: animation,
child: ListTile(
title: Text(label),
trailing: interactive
? IconButton(
icon: const Icon(Icons.check),
onPressed: () => _markPacked(label),
)
: null,
),
);
}
void _add(String label) {
_items.insert(0, label);
_listKey.currentState!.insertItem(0);
}
void _markPacked(String label) {
final index = _items.indexOf(label);
if (index < 0) return;
final removed = _items.removeAt(index);
_listKey.currentState!.removeItem(
index,
(context, animation) => _row(removed, animation, interactive: false),
);
}
@override
Widget build(BuildContext context) {
return AnimatedList(
key: _listKey,
initialItemCount: _items.length,
itemBuilder: (context, index, animation) => _row(_items[index], animation),
);
}
}go deeper
Recall the pieces: a GlobalKey<AnimatedListState>, insertItem and removeItem on that state, and an itemBuilder that receives an animation to wrap the row in a transition.
Explain that the list keeps its own count, why data and list must change together, and why removeItem needs a builder for the item that is already gone from the data.
Show how you keep them in sync under real updates: diffing a synced list into inserts and removes, non-interactive ghost rows, and index lookups by id at tap time.
Weigh animated insert and remove against its cost in code and bugs, and decide where the diffing logic lives so every animated list in the app shares it.
## What AnimatedList is `AnimatedList` is a scrolling list that **animates rows as they are inserted or removed**. A plain `ListView.builder` just shows whatever the data holds on the next build, so a new row pops in and a deleted row vanishes. `AnimatedList` instead runs an `Animation<double>` for each inserted or removed row and hands it to your builder, which turns it into a size, fade or slide transition. The family: | Widget | State class | Use | |---|---|---| | `AnimatedList` | `AnimatedListState` | a standalone scrolling list | | `AnimatedList.separated` | `AnimatedListState` | with separators, plus a `removedSeparatorBuilder` | | `SliverAnimatedList` | `SliverAnimatedListState` | a list inside a `CustomScrollView` | | `AnimatedGrid` | `AnimatedGridState` | a grid, with a `gridDelegate` | | `SliverAnimatedGrid` | `SliverAnimatedGridState` | a grid inside a `CustomScrollView` | ## It keeps its own count The key fact is that the list **does not look at your data**. Its state stores an item count, initialised from `initialItemCount` in `initState` and never read again. After that, the count changes only when you call methods on the state object: - `insertItem(int index, {Duration duration})` adds one slot and animates it in; - `insertAllItems(int index, int length, {Duration duration})` adds several; - `removeItem(int index, AnimatedRemovedItemBuilder builder, {Duration duration})` removes one and animates it out; - `removeAllItems(AnimatedRemovedItemBuilder builder, {Duration duration})` removes everything. The default duration is 300 milliseconds. To call these methods you need the state: pass a `GlobalKey<AnimatedListState>` as the list's `key` and use `key.currentState!`, or call `AnimatedList.of(context)` from a widget below the list. Because the count lives in two places, your list and the widget's state, they must change together. If you add to your data but forget `insertItem`, the new row never appears; if you remove from your data but forget `removeItem`, the builder is asked for an index that no longer exists and throws a `RangeError`. ## Inserting 1. Add the item to your list at `index`. 2. Call `insertItem(index)`. 3. The list calls `itemBuilder(context, index, animation)` with an animation running from 0.0 to 1.0; rows that are not animating get an already-completed animation. ## Removing Removal is the part people get wrong. The method's own documentation says the item is removed **immediately**: from that moment its index is no longer passed to `itemBuilder`, yet the row stays on screen for the whole duration. So the list cannot use `itemBuilder` to draw it, and it asks you for a separate builder: 1. Remove the item from your list and keep it: `final removed = items.removeAt(index);`. 2. Call `removeItem(index, (context, animation) => buildRow(removed, animation))`. 3. The animation runs from 1.0 back to 0.0, so the same `SizeTransition` shrinks the row away. The row drawn by that builder is a ghost of the removed item. It should not be interactive, because any index it captured now points at a different item. ## Packing list example In a travel app's packing list, ticking 'packed' on 'umbrella' removes it from the to-pack section. The handler removes the umbrella from the data, then calls `removeItem` with a builder that draws the same row, without its checkbox, inside a `SizeTransition`. The rows below slide up smoothly instead of jumping. Adding 'sunscreen' at the top is `items.insert(0, sunscreen)` followed by `insertItem(0)`. ## What AnimatedList is not - It is not a diffing list: a whole new data list requires working out the inserts and removes yourself. - It is not reorderable: `ReorderableListView` has no insert or remove animations, and `AnimatedList` has no drag-to-reorder. - Its row transitions are ordinary transition widgets driven by the given animation; implicit animations on a row's own properties are a separate tool. ## Choosing the transition The `animation` passed to the builders is a plain `Animation<double>` from 0.0 to 1.0, so any transition widget that takes one works: - `SizeTransition(sizeFactor: animation)` collapses or grows the row's height, so the rows below slide smoothly; it is the usual choice for lists; - `FadeTransition(opacity: animation)` fades the row but keeps its full height until the animation ends, so the rows below then jump; - combining a fade inside a size transition gives the common 'fade and collapse' look. Use the same transition in `itemBuilder` and in the removal builder, so an item leaves the way it arrived.
- Why does the code above call insertItem without setState?`insertItem` and `removeItem` call `setState` inside the list's own state, which rebuilds the list and asks `itemBuilder` for the new row. The parent only needs its own `setState` if something else it builds depends on the data, such as a counter in the app bar.
- How do you animate a whole new version of the list that arrives from a sync?Compare old and new by id, then apply removals from the highest index down with `removeItem`, and insertions from the lowest index up with `insertItem`, changing your data list at each step so both counts stay equal. `AnimatedList` will not do this diff for you, and changing `initialItemCount` later has no effect.
AnimatedList is like a stage manager who only knows how many dancers are on stage from your announcements: bring a dancer on without announcing it and they are never lit, send one off without announcing it and the manager calls for someone who is no longer there.
saying these in an interview costs you the question
- AnimatedList animates changes automatically when the data list passed to it changes.
- Changing initialItemCount later adds or removes rows with animation.
- removeItem can reuse itemBuilder because the item is still in the data.
- Call removeItem first and remove the item from the data when the animation ends.
- AnimatedList also supports drag-to-reorder out of the box.