skip to content

In Flutter, how do ValueKey, ObjectKey and UniqueKey differ in what they compare, and which fits items loaded from an API?

level: middleimportance: must knowfreq 58%

answer

  1. what does each == compare
  2. ValueKey delegates to value ==
  3. ObjectKey uses identical()
  4. UniqueKey equals only itself
  5. runtimeType checked first

basics

~10 s

ValueKey equals a key of the same runtime type whose value is ==; ObjectKey needs the very same object (identical); UniqueKey equals only itself. For API data, ValueKey(item.id) survives refetches that build new objects.

solid answer

~40 s

All three are `LocalKey`s, so they only need to be unique among one parent's children. `ValueKey<T>` delegates equality to its value's `==`; `Key('x')` is simply a const factory for `ValueKey<String>`. `ObjectKey` compares its value with `identical()`, so it matches only the same instance. `UniqueKey` is equal to nothing but itself and has no const constructor. Every one of them also checks `runtimeType` first, so `ValueKey('a')` never equals `PageStorageKey('a')`. For items parsed from an API, each refresh creates new instances, so `ObjectKey(item)` changes on every fetch while `ValueKey(item.id)` stays equal: that is the default choice. `UniqueKey` created inside `build()` produces a new identity every rebuild and resets the subtree's state each time; use it only deliberately, created once and replaced when you want a reset.

code

dart · 7 lines
dart
ListView(
  children: [
    for (final Track track in tracks)
      // New Track instances arrive on every refresh; the id stays equal.
      TrackTile(key: ValueKey(track.id), track: track),
  ],
)

go deeper

for a junior

Remember one line per key: ValueKey compares values, ObjectKey compares identity, UniqueKey matches only itself.

for a middle

Explain what happens to each key after a refetch that creates new model objects, and why runtimeType is part of key equality.

for a senior

Catch UniqueKey in build and ObjectKey on parsed data in review, and choose the id that expresses real identity rather than whole-object equality.

for a principal

Treat stable ids in the data layer as a UI requirement too; a model without identity forces weaker keys everywhere it is rendered.

## Local keys and their scope A Flutter **key** decides which existing element a new widget updates: `Widget.canUpdate` reuses an element only when the old and new widgets have the same `runtimeType` and keys that compare equal with `==`. So the kind of key you pick is really a choice of **equality rule**. `ValueKey`, `ObjectKey` and `UniqueKey` all extend **`LocalKey`**. A local key only has to be unique among the children of a single parent; the same `ValueKey(1)` can appear in two different lists on one screen without conflict. (`GlobalKey`, the other branch of the hierarchy, is unique across the whole app and is a different tool.) ## The three equality rules side by side | Key | `==` is true when | Const? | Typical use | |---|---|---|---| | `ValueKey<T>(value)` | same runtime type and `value == other.value` | yes | an id or other stable value from the data model | | `ObjectKey(value)` | same runtime type and `identical(value, other.value)` | yes | the object instance *is* the identity | | `UniqueKey()` | only when compared with itself | no | forcing a fresh element on purpose | Two details from the source are worth knowing: - `Key('track-42')` is a const factory that builds a `ValueKey<String>`; it is not a separate kind of key. - Every `==` implementation starts with `other.runtimeType != runtimeType`. `ValueKey<int>(1)` and `ValueKey<num>(1)` are therefore different keys, and a `PageStorageKey` (a `ValueKey` subclass) never equals a plain `ValueKey` with the same value. The `ValueKey` docs even suggest a private subclass as a way to make keys that cannot collide with anyone else's. ## Why `ValueKey(item.id)` is the default for fetched data Consider a playlist loaded from a backend and refreshed with pull-to-refresh: 1. The first fetch parses JSON into `Track` objects and builds a `TrackTile` per track. 2. The refresh parses the response again, producing **new `Track` instances**, even for tracks that did not change. 3. With `ObjectKey(track)`, every new key wraps a different instance, `identical()` fails, and every stateful tile is torn down and rebuilt with a fresh `State`. 4. With `ValueKey(track.id)`, the ids are equal strings or ints, so each existing element and its `State` is reused. If `Track` overrides `==` by value (with a package such as `equatable`, or by hand), `ValueKey(track)` also works, but then every field participates: a changed title makes the key unequal and resets that tile. Keying by the id alone expresses the real identity. ## `ObjectKey`: when identity is the right answer `ObjectKey` fits when the object instance genuinely is the identity and survives rebuilds: an in-memory list of mutable view-model objects held in a `State`, or objects with no natural id. The docs describe it as tying "the identity of a widget to the identity of an object used to generate that widget". The shopping-list example in Flutter's own UI introduction keys its items with `ObjectKey(product)` for exactly this reason. ## `UniqueKey`: forcing a fresh subtree A `UniqueKey` never equals any other key, so a widget carrying a new `UniqueKey` can never reuse an old element. - **Created inside `build()`**: every rebuild of the parent produces a new key, so the child's `State` is disposed and recreated each time. Controllers restart, text fields lose their text and animations jump back. This is a bug, not a way to "make keys unique". - **Deliberate reset**: store a `UniqueKey` in the parent's `State` and replace it inside `setState` when you want the subtree to start over, for example restarting a track-preview widget. Incrementing a counter used as `ValueKey(counter)` achieves the same effect. ## Common mistakes to avoid - `ValueKey(index)` is not an identity. After a reorder, position 0 still has key 0, so matching is exactly as positional as with no key at all. - Keys must be unique among siblings; equal keys under one multi-child parent trigger the debug assertion "Duplicate keys found." - Putting the key on a widget nested inside each item instead of on the item's outermost widget means the parent never sees it.

  • When is a UniqueKey what you actually want in Flutter?
    When you intend to throw a subtree's state away. Keep the `UniqueKey` in the parent's `State` and assign a new one inside `setState` when the user asks for a reset; the child then gets a new element and runs `initState` again. Creating it inline in `build()` does the same thing on every rebuild, which is almost never intended.
  • Why is ValueKey(index) no better than no key at all?
    Because the index describes a position, not an item. After a sort, the widget at position 0 still carries `ValueKey(0)`, so `canUpdate` pairs it with the element that was at position 0, exactly as keyless matching would. It merely satisfies APIs that demand a key, such as `ReorderableListView`.
  • Does ValueKey<int>(1) equal PageStorageKey<int>(1) in Flutter?
    No. `ValueKey.==` returns false when `runtimeType` differs, and `PageStorageKey` is a subclass with its own runtime type. Subclassing `ValueKey`, especially privately, is the documented way to make keys that cannot collide with keys from other code that happen to wrap the same value.

  • ObjectKey compares its object with ==, so equal data gives equal keys.
  • A UniqueKey created in build keeps state stable because each key is unique.
  • ValueKey(index) keeps each item's state attached after a reorder.
  • Local keys must be unique across the whole app, not just among siblings.
  • Key('x') is a separate key type that compares by identity.