OverlayPortal class

A widget that renders its overlay child on an Overlay.

The overlay child is initially hidden until OverlayPortalController.show is called on the associated controller. The OverlayPortal uses overlayChildBuilder to build its overlay child and renders it on the specified Overlay as if it was inserted using an OverlayEntry, while it can depend on the same set of InheritedWidgets (such as Theme) that this widget can depend on.

This widget requires an Overlay ancestor in the widget tree when its overlay child is showing. The overlay child is rendered by the Overlay ancestor, not by the widget itself. This allows the overlay child to float above other widgets, independent of its position in the widget tree.

When OverlayPortalController.hide is called, the widget built using overlayChildBuilder will be removed from the widget tree the next time the widget rebuilds. Stateful descendants in the overlay child subtree may lose states as a result.

Paint Order

In an Overlay, an overlay child is painted after the OverlayEntry associated with its OverlayPortal (that is, the OverlayEntry closest to the OverlayPortal in the widget tree, which usually represents the enclosing Route), and before the next OverlayEntry.

When an OverlayEntry has multiple associated OverlayPortals, the paint order between their overlay children is the order in which OverlayPortalController.show was called. The last OverlayPortal to have called show gets to paint its overlay child in the foreground.

Semantics

The semantics subtree generated by the overlay child is considered attached to OverlayPortal instead of the target Overlay. An OverlayPortal's semantics subtree can be dropped from the semantics tree due to invisibility while the overlay child is still visible (for example, when the OverlayPortal is completely invisible in a ListView but kept alive by a KeepAlive widget). When this happens the semantics subtree generated by the overlay child is also dropped, even if the overlay child is still visible on screen.

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:

• OverlayEntry, an alternative API for inserting widgets into an Overlay.
• Positioned, which can be used to size and position the overlay child in relation to the target Overlay's boundaries.
• CompositedTransformFollower, which can be used to position the overlay child in relation to the linked CompositedTransformTarget widget.