Skip to content

Adds migration guide for default cache extent change #13177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
chunhtai wants to merge 1 commit into from
+98 −0
Closed

Adds migration guide for default cache extent change #13177

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 96 additions & 0 deletions src/content/release/breaking-changes/default-cache-extent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
---
title: Default cache extent changed
description: >-
The default `cacheExtent` for scrolling widgets changed from 250 pixels to 0.8 times the viewport size.
---

{% render "docs/breaking-changes.md" %}

## Summary

The default cache extent for scrolling widgets (`ListView`, `GridView`, `CustomScrollView`, and `Scrollable`) changed from a fixed value of `250.0` pixels to `0.8` times the viewport's dimension along the main axis.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This line exceeds 80 characters and does not use semantic line breaks as required by the project's style guide. Additionally, consider adding ScrollView to the list of widgets, as it is the base class that defines the property.

Suggested change
The default cache extent for scrolling widgets (`ListView`, `GridView`, `CustomScrollView`, and `Scrollable`) changed from a fixed value of `250.0` pixels to `0.8` times the viewport's dimension along the main axis.
The default cache extent for scrolling widgets
(`ScrollView`, `ListView`, `GridView`, `CustomScrollView`, and `Scrollable`)
changed from a fixed value of `250.0` pixels
to `0.8` times the viewport's dimension along the main axis.
References
  1. The project requires semantic line breaks of 80 characters or fewer for documentation. (link)


## Context

Previously, the default cache extent was `250.0` pixels. A fixed pixel cache extent is too small on large monitors and unnecessarily large on very small screens. Furthermore, the fixed 250-pixel cache extent can be too small to accommodate accessibility scrolling, which is based on the viewport size. This sometimes causes iOS VoiceOver to lose its current focus because the currently focused item scrolls outside of the cache extent.

The new default cache extent is `0.8` times the viewport extent. The cache region extends 80% of the viewport's main axis dimension both before and after the visible area. This preloads an appropriate amount of content for any screen size.
Comment on lines +15 to +17
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

These lines exceed 80 characters and should use semantic line breaks to improve readability and diffing, as specified in the PR checklist.

Suggested change
Previously, the default cache extent was `250.0` pixels. A fixed pixel cache extent is too small on large monitors and unnecessarily large on very small screens. Furthermore, the fixed 250-pixel cache extent can be too small to accommodate accessibility scrolling, which is based on the viewport size. This sometimes causes iOS VoiceOver to lose its current focus because the currently focused item scrolls outside of the cache extent.
The new default cache extent is `0.8` times the viewport extent. The cache region extends 80% of the viewport's main axis dimension both before and after the visible area. This preloads an appropriate amount of content for any screen size.
Previously, the default cache extent was `250.0` pixels.
A fixed pixel cache extent is too small on large monitors
and unnecessarily large on very small screens.
Furthermore, the fixed 250-pixel cache extent can be too small
to accommodate accessibility scrolling, which is based on the viewport size.
This sometimes causes iOS VoiceOver to lose its current focus
because the currently focused item scrolls outside of the cache extent.
The new default cache extent is `0.8` times the viewport extent.
The cache region extends 80% of the viewport's main axis dimension
both before and after the visible area.
This preloads an appropriate amount of content for any screen size.
References
  1. The project requires semantic line breaks of 80 characters or fewer for documentation. (link)


## Description of change

Any scrolling widget that relies on the default cache extent will now have a cache extent relative to its viewport size instead of a fixed `250.0` pixels.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This line exceeds 80 characters. Please use semantic line breaks.

Suggested change
Any scrolling widget that relies on the default cache extent will now have a cache extent relative to its viewport size instead of a fixed `250.0` pixels.
Any scrolling widget that relies on the default cache extent
will now have a cache extent relative to its viewport size
instead of a fixed `250.0` pixels.
References
  1. The project requires semantic line breaks of 80 characters or fewer for documentation. (link)


For example, on a device with a scroll view height of 1000 pixels:

* Old behavior: The cache area is 250 pixels above and below the visible area.
* New behavior: The cache area is `1000 * 0.8 = 800` pixels above and below the visible area.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This line exceeds 80 characters. Please use semantic line breaks.

Suggested change
* New behavior: The cache area is `1000 * 0.8 = 800` pixels above and below the visible area.
* New behavior: The cache area is `1000 * 0.8 = 800` pixels
above and below the visible area.
References
  1. The project requires semantic line breaks of 80 characters or fewer for documentation. (link)


This change does not affect widgets where the cache extent is explicitly provided (such as `ListView(cacheExtent: 500)` or `ListView(scrollCacheExtent: ScrollCacheExtent.pixels(500))`).
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This line exceeds 80 characters. Please use semantic line breaks.

Suggested change
This change does not affect widgets where the cache extent is explicitly provided (such as `ListView(cacheExtent: 500)` or `ListView(scrollCacheExtent: ScrollCacheExtent.pixels(500))`).
This change does not affect widgets where the cache extent is explicitly
provided (such as `ListView(cacheExtent: 500)` or
`ListView(scrollCacheExtent: ScrollCacheExtent.pixels(500))`).
References
  1. The project requires semantic line breaks of 80 characters or fewer for documentation. (link)


## Migration guide

Most applications do not require modifications. If your application relies on the 250-pixel default, you can restore the previous behavior by explicitly setting the cache extent property.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This line exceeds 80 characters. Please use semantic line breaks.

Suggested change
Most applications do not require modifications. If your application relies on the 250-pixel default, you can restore the previous behavior by explicitly setting the cache extent property.
Most applications do not require modifications.
If your application relies on the 250-pixel default,
you can restore the previous behavior by explicitly setting
the cache extent property.
References
  1. The project requires semantic line breaks of 80 characters or fewer for documentation. (link)


### Restoring the previous behavior

**Before:**

```dart
ListView(
children: // ...
)
```

**After:**

```dart
ListView(
scrollCacheExtent: const ScrollCacheExtent.pixels(250.0),
children: // ...
)
```

### Affected classes

* [`ScrollView`][]
* [`ListView`][]
* [`GridView`][]
* [`CustomScrollView`][]
* [`Scrollable`][]
* [`RenderViewport`][]
* [`RenderViewportBase`][]

## Timeline

Landed in version: TBD<br>
In stable release: TBD

## References

API documentation:

* [`ScrollCacheExtent`][]
* [`ScrollView.scrollCacheExtent`][]
* [`RenderViewportBase.scrollCacheExtent`][]

Relevant issue:

* [Issue 98572: Consider changing default cacheExtent to be based on viewport dimension][]

Relevant PR:

* [Change default cache extent][]

[`ScrollView`]: {{site.api}}/flutter/widgets/ScrollView-class.html
[`ListView`]: {{site.api}}/flutter/widgets/ListView-class.html
[`GridView`]: {{site.api}}/flutter/widgets/GridView-class.html
[`CustomScrollView`]: {{site.api}}/flutter/widgets/CustomScrollView-class.html
[`Scrollable`]: {{site.api}}/flutter/widgets/Scrollable-class.html
[`RenderViewport`]: {{site.api}}/flutter/rendering/RenderViewport-class.html
[`RenderViewportBase`]: {{site.api}}/flutter/rendering/RenderViewportBase-class.html
[`ScrollCacheExtent`]: {{site.api}}/flutter/rendering/ScrollCacheExtent-class.html
[`ScrollView.scrollCacheExtent`]: {{site.api}}/flutter/widgets/ScrollView/scrollCacheExtent.html
[`RenderViewportBase.scrollCacheExtent`]: {{site.api}}/flutter/rendering/RenderViewportBase/scrollCacheExtent.html

[Issue 98572: Consider changing default cacheExtent to be based on viewport dimension]: {{site.github}}/flutter/flutter/issues/98572
[Change default cache extent]: {{site.repo.flutter}}/pull/182905
2 changes: 2 additions & 0 deletions src/content/release/breaking-changes/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ They're sorted by release and listed in alphabetical order:
### Not yet released to stable

* [Changing RawMenuAnchor close order][]
* [Default cache extent changed][]
* [Deprecate `onReorder` callback][]
* [Deprecated `cacheExtent` and `cacheExtentStyle`][]
* [Deprecate `TextInputConnection.setStyle`][]
Expand All @@ -45,6 +46,7 @@ They're sorted by release and listed in alphabetical order:
* [Page transition builders reorganization][]

[Changing RawMenuAnchor close order]: /release/breaking-changes/raw-menu-anchor-close-order
[Default cache extent changed]: /release/breaking-changes/default-cache-extent
[Deprecate `onReorder` callback]: /release/breaking-changes/deprecate-onreorder-callback
[Deprecated `cacheExtent` and `cacheExtentStyle`]: /release/breaking-changes/scroll-cache-extent
[Deprecate `TextInputConnection.setStyle`]: /release/breaking-changes/deprecate-text-input-connection-set-style
Expand Down
Loading