Deprecated cacheExtent and cacheExtentStyle

Flutter 3.44 deprecates cacheExtent and cacheExtentStyle in scrolling-related widgets, such as ListView, GridView, CustomScrollView, and Viewport, and their corresponding render objects, such as RenderViewport. The new scrollCacheExtent property encapsulates both the value and the caching strategy (pixels or viewport).

Previously, cacheExtent was a double and cacheExtentStyle determined how that double was interpreted (either as pixels or as a fraction of the viewport). This split made the setting harder to understand.

The new scrollCacheExtent property uses a ScrollCacheExtent object that explicitly encapsulates both the value and the caching strategy (pixels or viewport), which provides type safety and clearer intent.

If your code uses cacheExtent, which defaults to pixels, use scrollCacheExtent with ScrollCacheExtent.pixels.

Before:

ListView(
  cacheExtent: 500.0,
  children: // ...
)

After:

ListView(
  scrollCacheExtent: const ScrollCacheExtent.pixels(500.0),
  children: // ...
)

If your code uses cacheExtent with CacheExtentStyle.viewport, which is common in Viewport, use scrollCacheExtent with ScrollCacheExtent.viewport.

Before:

Viewport(
  cacheExtent: 0.5,
  cacheExtentStyle: CacheExtentStyle.viewport,
  slivers: // ...
)

After:

Viewport(
  scrollCacheExtent: const ScrollCacheExtent.viewport(0.5),
  slivers: // ...
)

If your code manually sets properties on RenderViewport or a similar render object, use scrollCacheExtent.

Before:

renderViewport.cacheExtent = 500.0;
renderViewport.cacheExtentStyle = CacheExtentStyle.pixel;

After:

renderViewport.scrollCacheExtent = const ScrollCacheExtent.pixels(500.0);

Landed in version: 3.41.0-0.0.pre
In stable release: 3.44

API documentation:

• ScrollCacheExtent
• ScrollView.scrollCacheExtent
• RenderViewportBase.scrollCacheExtent

Relevant PRs:

• Introduce ScrollCacheExtent