document that the default Key is null and explain proper usage in list diffing by AbdeMohlbi · Pull Request #185197 · flutter/flutter

AbdeMohlbi · 2026-04-17T08:53:45Z

Pre-launch Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

gemini-code-assist

Code Review

This pull request updates the documentation for the Key class to clarify the behavior of unkeyed widgets and the role of keys in preserving state within collections. The feedback suggests improving the documentation's navigability by linking terms like runtimeType and StatefulWidget to their respective definitions, as required by the style guide.

Piinks

The breadcrumb suggestions from Gemini are good ones!

justinmc

This is a great improvement, thanks for attacking such an old issue. I left some comments about how I think this can be even better for readers.

AbdeMohlbi · 2026-05-12T12:59:10Z

@justinmc after much thought i think it is best to simplify the example because new users would get confused as to why the color changed but the counter did not follow the color, i suggest that we use the same example from the video https://www.youtube.com/watch?v=kn0EOS-ZiIc so users can follow the code example from the video and understand the concept behind it, at least this worked for me as some point.

CC @navaronbracke in case you have an opinion.

AbdeMohlbi · 2026-05-12T13:09:34Z

this is the suggested code:

import 'dart:math';
import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: PositionedTiles()));
}

class PositionedTiles extends StatefulWidget {
  const PositionedTiles({super.key});

  @override
  State<PositionedTiles> createState() => _PositionedTilesState();
}

class _PositionedTilesState extends State<PositionedTiles> {
  late List<Widget> tiles;

  void swapTiles() {
    setState(() {
      tiles.insert(1, tiles.removeAt(0));
    });
  }

  @override
  void initState() {
    super.initState();
    // unkeyed tiles
    // tiles =  [const StatefulColorfulTile(), const StatefulColorfulTile()];

    // keyed tiles
    tiles = [StatefulColorfulTile(key: UniqueKey()), StatefulColorfulTile(key: UniqueKey())];
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(child: Row(children: tiles)),
      floatingActionButton: FloatingActionButton(
        onPressed: swapTiles,
        child: const Icon(Icons.sentiment_very_dissatisfied),
      ),
    );
  }
}

class StatefulColorfulTile extends StatefulWidget {
  const StatefulColorfulTile({super.key});

  @override
  State<StatefulColorfulTile> createState() => _StatefulColorfulTileState();
}

class _StatefulColorfulTileState extends State<StatefulColorfulTile> {
  late final Color color;

  @override
  void initState() {
    super.initState();
    color = _generateRandomColor();
  }

  Color _generateRandomColor() {
    final random = Random();

    return Color.fromARGB(255, random.nextInt(256), random.nextInt(256), random.nextInt(256));
  }

  @override
  Widget build(BuildContext context) {
    return Container(width: 120, height: 120, color: color);
  }
}

a side note is that if we decide to use this example we need to mention that a hot reload won't do the trick here but a full hot restart is needed.
note 2: i just noticed that the example uses UniqueKey but serves the same idea, offcourse it won't be in valueKey deocs

navaronbracke · 2026-05-12T15:26:32Z

Code sample SGTM, but why the hot restart? Is that specific to not being able to use it because of the unkeyed widgets?

Piinks · 2026-05-12T16:45:31Z

+/// In such cases, a [ValueKey] is typically appropriate, using a value that is
+/// stable and unique for each item, such as an identifier from the data model.
+///
+/// {@tool snippet}


This is a really good example, why not make it a dartpad?

not sure where to put it, there is no examples/foundation and i think that examples/widgets is not a suitable place here

It would go under examples/api/ and you can be the first to add the foundation directory there!

added new folder, example and test.

AbdeMohlbi · 2026-05-12T16:51:38Z

Code sample SGTM, but why the hot restart? Is that specific to not being able to use it because of the unkeyed widgets?

well it's a bit complicated, firstly there was a problem with my current example because:

tiles =  [const StatefulColorfulTile(), const StatefulColorfulTile()];

isn't the same thing as:

tiles = const [StatefulColorfulTile(), StatefulColorfulTile()];

which is the reason for the crash i was seeing 🫠.

from the other side, tiles is assigned in initState which won't be rerun unless a hot restart is invoked.

from hot reload docs https://docs.flutter.dev/tools/hot-reload?gad_source=1

Hot reload loads code changes into the VM or the browser, and re-builds the widget tree, preserving the app state; it doesn't rerun main() or initState(). (⌘\ in IntelliJ and Android Studio, ⌃F5 in VSCode)

Piinks

LGTM! Thank you!

AbdeMohlbi · 2026-05-16T07:07:55Z

FWIW i'm going to add the example mentioned here #185197 (comment) in another PR, so you can ignore that comment in this PR.

AbdeMohlbi · 2026-05-22T21:43:21Z

@justinmc could you take another look ?

justinmc

LGTM with some nits. This is a big improvement in the docs for a tricky topic, thank you for working on this!

Piinks

LGTM!

auto-submit · 2026-05-28T20:32:06Z

autosubmit label was removed for flutter/flutter/185197, because The base commit of the PR is older than 7 days and can not be merged. Please merge the latest changes from the main into this branch and resubmit the PR.

…ffing

flutter/flutter@e70534d...b05a9d7 2026-05-29 engine-flutter-autoroll@skia.org Roll Skia from 47155534833e to d9d6b440c4e7 (1 revision) (flutter/flutter#187301) 2026-05-29 engine-flutter-autoroll@skia.org Roll Skia from f93ed13d77fb to 47155534833e (4 revisions) (flutter/flutter#187291) 2026-05-29 kevmoo@users.noreply.github.com [web_ui] Optimize skwasm text layout and path decoding to eliminate dynamic boxing churn under Wasm (flutter/flutter#186978) 2026-05-29 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from SBpmmPxqx3lAvGojE... to jMR_VXQi07kAk8vbR... (flutter/flutter#187279) 2026-05-29 burak.karahan@mail.ru Remove Material import from sliver tree rendering test (flutter/flutter#187000) 2026-05-29 bdero@google.com [Impeller] Remove the y_coord_scale Y-flip plumbing (flutter/flutter#187224) 2026-05-29 31859944+LongCatIsLooong@users.noreply.github.com Add/remove overlay child RenderObject from the tree in `attach`/`detach` (flutter/flutter#186564) 2026-05-29 engine-flutter-autoroll@skia.org Roll Skia from fcfe5975c945 to f93ed13d77fb (4 revisions) (flutter/flutter#187273) 2026-05-28 evanwall@buffalo.edu Handle complex RSE rendering in the uber SDF pipeline (flutter/flutter#186434) 2026-05-28 engine-flutter-autoroll@skia.org Roll Dart SDK from 082191101fcc to 683322426411 (2 revisions) (flutter/flutter#187270) 2026-05-28 mvincentong@gmail.com Clarify route transition animations (flutter/flutter#186552) 2026-05-28 116356835+AbdeMohlbi@users.noreply.github.com document that the default Key is null and explain proper usage in list diffing (flutter/flutter#185197) 2026-05-28 srawlins@google.com [flutter_tools] Use super parameters in missed spots (flutter/flutter#186197) 2026-05-28 mr_nadeem_iqbal@yahoo.com docs: Document MediaQueryData.alwaysUse24HourFormat on macOS, Windows, Linux, web (#160664) (flutter/flutter#186642) 2026-05-28 engine-flutter-autoroll@skia.org Roll Skia from 5493e4c144cd to fcfe5975c945 (3 revisions) (flutter/flutter#187256) 2026-05-28 30870216+gaaclarke@users.noreply.github.com Shares opengles golden context (flutter/flutter#187243) 2026-05-28 jason-simmons@users.noreply.github.com Update the Curl CIPD package in .ci.yaml to version 8.20.0 (flutter/flutter#187133) 2026-05-28 737941+loic-sharma@users.noreply.github.com Improve SizedBox's docs (flutter/flutter#187208) 2026-05-28 bdero@google.com [Impeller] Support instanced rendering across all backends (flutter/flutter#186653) 2026-05-28 43054281+camsim99@users.noreply.github.com [Android] Reset system UI visibility flags when setting edge-to-edge mode (flutter/flutter#187207) 2026-05-28 engine-flutter-autoroll@skia.org Roll Skia from a38708fb7926 to 5493e4c144cd (7 revisions) (flutter/flutter#187241) 2026-05-28 30870216+gaaclarke@users.noreply.github.com Turned on impeller by default on macos (flutter/flutter#186546) 2026-05-28 mvincentong@gmail.com Clarify lazy scroll extent docs (flutter/flutter#186864) 2026-05-28 mdebbar@google.com [web] Fix WebParagraph locales test (flutter/flutter#186813) 2026-05-28 engine-flutter-autoroll@skia.org Roll Packages from 4b424d7 to 10cbdc5 (3 revisions) (flutter/flutter#187238) 2026-05-28 engine-flutter-autoroll@skia.org Roll Dart SDK from f3db7b7d9801 to 082191101fcc (8 revisions) (flutter/flutter#187235) 2026-05-28 engine-flutter-autoroll@skia.org Roll Skia from 32acea791248 to a38708fb7926 (1 revision) (flutter/flutter#187221) 2026-05-28 bdero@google.com [Flutter GPU] Add r32Float and remove Apple-only XR pixel formats (flutter/flutter#187069) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC boetger@google.com,stuartmorgan@google.com on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

…r#11803) flutter/flutter@e70534d...b05a9d7 2026-05-29 engine-flutter-autoroll@skia.org Roll Skia from 47155534833e to d9d6b440c4e7 (1 revision) (flutter/flutter#187301) 2026-05-29 engine-flutter-autoroll@skia.org Roll Skia from f93ed13d77fb to 47155534833e (4 revisions) (flutter/flutter#187291) 2026-05-29 kevmoo@users.noreply.github.com [web_ui] Optimize skwasm text layout and path decoding to eliminate dynamic boxing churn under Wasm (flutter/flutter#186978) 2026-05-29 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from SBpmmPxqx3lAvGojE... to jMR_VXQi07kAk8vbR... (flutter/flutter#187279) 2026-05-29 burak.karahan@mail.ru Remove Material import from sliver tree rendering test (flutter/flutter#187000) 2026-05-29 bdero@google.com [Impeller] Remove the y_coord_scale Y-flip plumbing (flutter/flutter#187224) 2026-05-29 31859944+LongCatIsLooong@users.noreply.github.com Add/remove overlay child RenderObject from the tree in `attach`/`detach` (flutter/flutter#186564) 2026-05-29 engine-flutter-autoroll@skia.org Roll Skia from fcfe5975c945 to f93ed13d77fb (4 revisions) (flutter/flutter#187273) 2026-05-28 evanwall@buffalo.edu Handle complex RSE rendering in the uber SDF pipeline (flutter/flutter#186434) 2026-05-28 engine-flutter-autoroll@skia.org Roll Dart SDK from 082191101fcc to 683322426411 (2 revisions) (flutter/flutter#187270) 2026-05-28 mvincentong@gmail.com Clarify route transition animations (flutter/flutter#186552) 2026-05-28 116356835+AbdeMohlbi@users.noreply.github.com document that the default Key is null and explain proper usage in list diffing (flutter/flutter#185197) 2026-05-28 srawlins@google.com [flutter_tools] Use super parameters in missed spots (flutter/flutter#186197) 2026-05-28 mr_nadeem_iqbal@yahoo.com docs: Document MediaQueryData.alwaysUse24HourFormat on macOS, Windows, Linux, web (#160664) (flutter/flutter#186642) 2026-05-28 engine-flutter-autoroll@skia.org Roll Skia from 5493e4c144cd to fcfe5975c945 (3 revisions) (flutter/flutter#187256) 2026-05-28 30870216+gaaclarke@users.noreply.github.com Shares opengles golden context (flutter/flutter#187243) 2026-05-28 jason-simmons@users.noreply.github.com Update the Curl CIPD package in .ci.yaml to version 8.20.0 (flutter/flutter#187133) 2026-05-28 737941+loic-sharma@users.noreply.github.com Improve SizedBox's docs (flutter/flutter#187208) 2026-05-28 bdero@google.com [Impeller] Support instanced rendering across all backends (flutter/flutter#186653) 2026-05-28 43054281+camsim99@users.noreply.github.com [Android] Reset system UI visibility flags when setting edge-to-edge mode (flutter/flutter#187207) 2026-05-28 engine-flutter-autoroll@skia.org Roll Skia from a38708fb7926 to 5493e4c144cd (7 revisions) (flutter/flutter#187241) 2026-05-28 30870216+gaaclarke@users.noreply.github.com Turned on impeller by default on macos (flutter/flutter#186546) 2026-05-28 mvincentong@gmail.com Clarify lazy scroll extent docs (flutter/flutter#186864) 2026-05-28 mdebbar@google.com [web] Fix WebParagraph locales test (flutter/flutter#186813) 2026-05-28 engine-flutter-autoroll@skia.org Roll Packages from 4b424d7 to 10cbdc5 (3 revisions) (flutter/flutter#187238) 2026-05-28 engine-flutter-autoroll@skia.org Roll Dart SDK from f3db7b7d9801 to 082191101fcc (8 revisions) (flutter/flutter#187235) 2026-05-28 engine-flutter-autoroll@skia.org Roll Skia from 32acea791248 to a38708fb7926 (1 revision) (flutter/flutter#187221) 2026-05-28 bdero@google.com [Flutter GPU] Add r32Float and remove Apple-only XR pixel formats (flutter/flutter#187069) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC boetger@google.com,stuartmorgan@google.com on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

…t diffing (flutter#185197) Fixes flutter#13787 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [ ] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.  [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

github-actions Bot added the framework flutter/packages/flutter repository. See also f: labels. label Apr 17, 2026

AbdeMohlbi added the CICD Run CI/CD label Apr 17, 2026

github-actions Bot removed the CICD Run CI/CD label Apr 20, 2026

AbdeMohlbi added the CICD Run CI/CD label Apr 21, 2026

AbdeMohlbi marked this pull request as ready for review April 27, 2026 22:40

github-actions Bot removed the CICD Run CI/CD label Apr 27, 2026

AbdeMohlbi added the CICD Run CI/CD label Apr 27, 2026

gemini-code-assist Bot reviewed Apr 27, 2026

View reviewed changes

Comment thread packages/flutter/lib/src/foundation/key.dart Outdated

Comment thread packages/flutter/lib/src/foundation/key.dart Outdated

Piinks reviewed Apr 28, 2026

View reviewed changes

github-actions Bot removed the CICD Run CI/CD label Apr 29, 2026

AbdeMohlbi requested a review from Piinks April 29, 2026 10:00

AbdeMohlbi added the CICD Run CI/CD label May 7, 2026

AbdeMohlbi changed the title ~~document that default Key is null and explain proper usage in list diffing~~ document that the default Key is null and explain proper usage in list diffing May 7, 2026

navaronbracke previously approved these changes May 7, 2026

View reviewed changes

justinmc reviewed May 11, 2026

View reviewed changes

Comment thread packages/flutter/lib/src/foundation/key.dart Outdated

Comment thread packages/flutter/lib/src/foundation/key.dart

AbdeMohlbi dismissed navaronbracke’s stale review via 64487c7 May 12, 2026 12:31

github-actions Bot removed the CICD Run CI/CD label May 12, 2026

flutter-dashboard Bot added the CICD Run CI/CD label May 12, 2026

github-actions Bot removed the CICD Run CI/CD label May 12, 2026

AbdeMohlbi requested review from justinmc and navaronbracke May 12, 2026 13:12

Piinks reviewed May 12, 2026

View reviewed changes

flutter-dashboard Bot added the CICD Run CI/CD label May 15, 2026

github-actions Bot added d: api docs Issues with https://api.flutter.dev/ d: examples Sample code and demos labels May 15, 2026

Piinks previously approved these changes May 15, 2026

View reviewed changes

justinmc previously approved these changes May 27, 2026

View reviewed changes

AbdeMohlbi dismissed stale reviews from justinmc and Piinks via 2eaa43f May 28, 2026 10:13

github-actions Bot removed the CICD Run CI/CD label May 28, 2026

Piinks approved these changes May 28, 2026

View reviewed changes

AbdeMohlbi added autosubmit Merge PR when tree becomes green via auto submit App CICD Run CI/CD labels May 28, 2026

auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label May 28, 2026

AbdeMohlbi added 7 commits May 28, 2026 15:39

document that default Key is null and explain proper usage in list di…

fd1a9ec

…ffing

gemini has a point, kate also has a point

5e82b2c

justin has a point

f703d02

equals operator

acc2bc7

add tool snipet

ae00247

kate has a point

c2a40d6

address comments from justin

fac9e67

Piinks force-pushed the issue_13787 branch from 2eaa43f to fac9e67 Compare May 28, 2026 20:39

github-actions Bot removed the CICD Run CI/CD label May 28, 2026

Piinks added CICD Run CI/CD autosubmit Merge PR when tree becomes green via auto submit App labels May 28, 2026

auto-submit Bot added this pull request to the merge queue May 28, 2026

Merged via the queue into flutter:master with commit ba09ef4 May 28, 2026
94 checks passed

flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label May 28, 2026

engine-flutter-autoroll mentioned this pull request May 29, 2026

Roll Flutter from e70534db5a44 to b05a9d748865 (28 revisions) flutter/packages#11803

Merged

Uh oh!

Conversation

AbdeMohlbi commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Piinks left a comment

Choose a reason for hiding this comment

Uh oh!

justinmc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

AbdeMohlbi commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AbdeMohlbi commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

navaronbracke commented May 12, 2026

Uh oh!

Piinks May 12, 2026

Choose a reason for hiding this comment

Uh oh!

AbdeMohlbi May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Piinks May 12, 2026

Choose a reason for hiding this comment

Uh oh!

AbdeMohlbi May 15, 2026

Choose a reason for hiding this comment

Uh oh!

AbdeMohlbi commented May 12, 2026

Uh oh!

Piinks left a comment

Choose a reason for hiding this comment

Uh oh!

AbdeMohlbi commented May 16, 2026

Uh oh!

AbdeMohlbi commented May 22, 2026

Uh oh!

justinmc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Piinks left a comment

Choose a reason for hiding this comment

Uh oh!

auto-submit Bot commented May 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

AbdeMohlbi commented Apr 17, 2026 •

edited

Loading

AbdeMohlbi commented May 12, 2026 •

edited

Loading

AbdeMohlbi commented May 12, 2026 •

edited

Loading

AbdeMohlbi May 12, 2026 •

edited

Loading