SliverGrid class

A sliver that places multiple box children in a two dimensional arrangement.

SliverGrid places its children in arbitrary positions determined by gridDelegate. Each child is forced to have the size specified by the gridDelegate.

The main axis direction of a grid is the direction in which it scrolls; the cross axis direction is the orthogonal direction.

This example, which would be inserted into a CustomScrollView.slivers list, shows twenty boxes in a pretty teal grid:

SliverGrid(
  gridDelegate: SliverGridDelegateWithMaxCrossAxisExtent(
    maxCrossAxisExtent: 200.0,
    mainAxisSpacing: 10.0,
    crossAxisSpacing: 10.0,
    childAspectRatio: 4.0,
  ),
  delegate: SliverChildBuilderDelegate(
    (BuildContext context, int index) {
      return Container(
        alignment: Alignment.center,
        color: Colors.teal[100 * (index % 9)],
        child: Text('grid item $index'),
      );
    },
    childCount: 20,
  ),
)

Child elements' lifecycle

Creation

While laying out the list, visible children's elements, states and render objects will be created lazily based on existing widgets (such as in the case of SliverChildListDelegate) or lazily provided ones (such as in the case of SliverChildListDelegate).

Destruction

When a child is scrolled out of view, the associated element subtree, states and render objects are destroyed. A new child at the same position in the sliver will be lazily recreated along with new elements, states and render objects when it is scrolled back.

Destruction mitigation

In order to preserve state as child elements are scrolled in and out of view, the following options are possible:

Moving the ownership of non-trivial UI-state-driving business logic out of the sliver child subtree. For instance, if a list contains posts with their number of upvotes coming from a cached network response, store the list of posts and upvote number in a data model outside the list. Let the sliver child UI subtree be easily recreate-able from the source-of-truth model object. Use StatefulWidgets in the child widget subtree to store instantaneous UI state only.
Letting KeepAlive be the root widget of the sliver child widget subtree that needs to be preserved. The KeepAlive widget marks the child subtree's top render object child for keep-alive. When the associated top render object is scrolled out of view, the sliver keeps the child's render object (and by extension, its associated elements and states) in a cache list instead of destroying them. When scrolled back into view, the render object is repainted as-is (if it wasn't marked dirty in the interim).

This only works if the SliverChildDelegate subclasses don't wrap the child widget subtree with other widgets such as AutomaticKeepAlive and RepaintBoundary via addAutomaticKeepAlives and addRepaintBoundaries.
Using AutomaticKeepAlive widgets (inserted by default in SliverChildListDelegate or SliverChildListDelegate). Instead of unconditionally caching the child element subtree when scrolling off-screen like KeepAlive, AutomaticKeepAlive can let whether to cache the subtree be determined by descendant logic in the subtree.

As an example, the EditableText widget signals its sliver child element subtree to stay alive while its text field has input focus. If it doesn't have focus and no other descendants signaled for keep-alive via a KeepAliveNotification, the sliver child element subtree will be destroyed when scrolled away.

AutomaticKeepAlive descendants typically signal it to be kept alive by using the AutomaticKeepAliveClientMixin, then implementing the wantKeepAlive getter and calling updateKeepAlive.

Constructors

SliverGrid({Key key, @required SliverChildDelegate delegate, @required SliverGridDelegate gridDelegate }): Creates a sliver that places multiple box children in a two dimensional arrangement.
const
SliverGrid.count({Key key, @required int crossAxisCount, double mainAxisSpacing: 0.0, double crossAxisSpacing: 0.0, double childAspectRatio: 1.0, List<Widget> children: const [] }): Creates a sliver that places multiple box children in a two dimensional arrangement with a fixed number of tiles in the cross axis. [...]
SliverGrid.extent({Key key, @required double maxCrossAxisExtent, double mainAxisSpacing: 0.0, double crossAxisSpacing: 0.0, double childAspectRatio: 1.0, List<Widget> children: const [] }): Creates a sliver that places multiple box children in a two dimensional arrangement with tiles that each have a maximum cross-axis extent. [...]

Properties

gridDelegate → SliverGridDelegate: The delegate that controls the size and position of the children.
final
delegate → SliverChildDelegate: The delegate that provides the children for this widget. [...]
final, inherited
hashCode → int: The hash code for this object. [...]
read-only, inherited
key → Key: Controls how one widget replaces another widget in the tree. [...]
final, inherited
runtimeType → Type: A representation of the runtime type of the object.
read-only, inherited

Methods

createRenderObject(BuildContext context) → RenderSliverGrid: Creates an instance of the RenderObject class that this RenderObjectWidget represents, using the configuration described by this RenderObjectWidget. [...]
override
estimateMaxScrollOffset(SliverConstraints constraints, int firstIndex, int lastIndex, double leadingScrollOffset, double trailingScrollOffset) → double: Returns an estimate of the max scroll extent for all the children. [...]
override
updateRenderObject(BuildContext context, covariant RenderSliverGrid renderObject) → void: Copies the configuration described by this RenderObjectWidget to the given RenderObject, which will be of the same type as returned by this object's createRenderObject. [...]
override
createElement() → SliverMultiBoxAdaptorElement: RenderObjectWidgets always inflate to a RenderObjectElement subclass.
inherited
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children. [...]
@protected, inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node. [...]
inherited
didUnmountRenderObject(covariant RenderObject renderObject) → void: A render object previously associated with this widget has been removed from the tree. The given RenderObject will be of the same type as returned by this object's createRenderObject.
@protected, inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a non-existent method or property is accessed. [...]
inherited
toDiagnosticsNode({String name, DiagnosticsTreeStyle style }) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by toStringDeep. [...]
inherited
toString({DiagnosticLevel minLevel: DiagnosticLevel.debug }) → String: Returns a string representation of this object.
inherited
toStringDeep({String prefixLineOne: '', String prefixOtherLines, DiagnosticLevel minLevel: DiagnosticLevel.debug }) → String: Returns a string representation of this node and its descendants. [...]
inherited
toStringShallow({String joiner: ', ', DiagnosticLevel minLevel: DiagnosticLevel.debug }) → String: Returns a one-line detailed description of the object. [...]
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(dynamic other) → bool: The equality operator. [...]
inherited

widgets library