OverlayEntry class

A place in an Overlay that can contain a widget.

Overlay entries are inserted into an Overlay using the OverlayState.insert or OverlayState.insertAll functions. To find the closest enclosing overlay for a given BuildContext, use the Overlay.of function.

An overlay entry can be in at most one overlay at a time. To remove an entry from its overlay, call the remove function on the overlay entry.

Because an Overlay uses a Stack layout, overlay entries can use Positioned and AnimatedPositioned to position themselves within the overlay.

For example, Draggable uses an OverlayEntry to show the drag avatar that follows the user's finger across the screen after the drag begins. Using the overlay to display the drag avatar lets the avatar float over the other widgets in the app. As the user's finger moves, draggable calls markNeedsBuild on the overlay entry to cause it to rebuild. In its build, the entry includes a Positioned with its top and left property set to position the drag avatar near the user's finger. When the drag is over, Draggable removes the entry from the overlay to remove the drag avatar from view.

By default, if there is an entirely opaque entry over this one, then this one will not be included in the widget tree (in particular, stateful widgets within the overlay entry will not be instantiated). To ensure that your overlay entry is still built even if it is not visible, set maintainState to true. This is more expensive, so should be done with care. In particular, if widgets in an overlay entry with maintainState set to true repeatedly call State.setState, the user's battery will be drained unnecessarily.

OverlayEntry is a Listenable that notifies when the widget built by builder is mounted or unmounted, whose exact state can be queried by mounted. After the owner of the OverlayEntry calls remove and then dispose, the widget may not be immediately removed from the widget tree. As a result listeners of the OverlayEntry can get notified for one last time after the dispose call, when the widget is eventually unmounted.

Differences between OverlayPortal and OverlayEntry

The main difference between OverlayEntry and OverlayPortal is that OverlayEntry builds its widget subtree as a child of the target Overlay, while OverlayPortal uses OverlayPortal.overlayChildBuilder to build a child widget of itself. This allows OverlayPortal's overlay child to depend on the same set of InheritedWidgets as OverlayPortal, and it's also guaranteed that the overlay child will not outlive its OverlayPortal.

On the other hand, OverlayPortal's implementation is more complex. For instance, it does a bit more work than a regular widget during global key reparenting. If the content to be shown on the Overlay doesn't benefit from being a part of OverlayPortal's subtree, consider using an OverlayEntry instead.

See also:

  • OverlayPortal, an alternative API for inserting widgets into an Overlay using a builder callback.
  • Overlay, a stack of entries that can be managed independently.
  • OverlayState, the current state of an Overlay.
  • WidgetsApp, a convenience widget that wraps a number of widgets that are commonly required for an application.
  • MaterialApp, a convenience widget that wraps a number of widgets that are commonly required for Material Design applications.
Implemented types


OverlayEntry({required WidgetBuilder builder, bool opaque = false, bool maintainState = false, bool canSizeOverlay = false})
Creates an overlay entry.


builder WidgetBuilder
This entry will include the widget built by this builder in the overlay at the entry's position.
canSizeOverlay bool
Whether the content of this OverlayEntry can be used to size the Overlay.
hashCode int
The hash code for this object.
no setterinherited
maintainState bool
Whether this entry must be included in the tree even if there is a fully opaque entry above it.
getter/setter pair
mounted bool
Whether the OverlayEntry is currently mounted in the widget tree.
no setter
opaque bool
Whether this entry occludes the entire overlay.
getter/setter pair
runtimeType Type
A representation of the runtime type of the object.
no setterinherited


addListener(VoidCallback listener) → void
Register a closure to be called when the object notifies its listeners.
dispose() → void
Discards any resources used by this OverlayEntry.
markNeedsBuild() → void
Cause this entry to rebuild during the next pipeline flush.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
remove() → void
Remove this entry from the overlay.
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that the object notifies.
toString() String
A string representation of this object.


operator ==(Object other) bool
The equality operator.