NIB / DOCUMENTATION
Overlays and result lifecycles — NibComponents
Choose a surface, control its lifetime, and understand which overlay receives it.
Open interactive viewChoose by interaction, not appearance
Use a dialog for a focused task or decision, a bottom sheet for a task that benefits from draggable height, and a popover for content anchored to a trigger. A hover card provides supporting information on hover or focus. A context menu offers actions at a pointer position. A toast reports a brief status without becoming the only place essential information is available.
Close through the surface’s scope
showNibDialog<T> returns Future<T?>. Close it through NibDialogScope from a context inside the dialog. A Builder supplies that inner context when the content is created at the call site. Navigator.pop is not the close mechanism: these helpers insert OverlayEntry objects rather than Navigator routes.
Keep the returned value compatible with T. The scope accepts Object?, but the helper casts a non-null result to T. Barrier, Escape, and close-button dismissal produce null. In a confirmation flow, act only on an explicit affirmative result. Check context.mounted before using the original context after awaiting the dialog.
Future<bool?> askToContinue(BuildContext context) {
return showNibDialog<bool>(
context,
title: 'Keep these changes?',
content: Builder(
builder: (dialogContext) => NibButton(
label: 'Keep changes',
onPressed: () => NibDialogScope.of(dialogContext).close(true),
),
),
);
}| API | Type | Default | Behavior |
|---|---|---|---|
| showNibDialog | Future<T?> | animated: false; barrierDismissible: true | Insert a dialog and return its result future. |
| NibDialogScope.of | NibDialogScope | Nearest scope | Requires a context under the dialog. Calling it outside asserts. |
| NibDialogHandle.closed | Future<T?> | Pending until close is requested | The result can complete before the animated exit has fully removed the surface. |
Know where the helper inserts its content
The dialog, bottom-sheet, and context-menu helpers call Overlay.of(context, rootOverlay: true). Toasts also select a root overlay. NibPopover and NibHoverCard use the nearest overlay. A nested Navigator supplies an overlay, but nesting alone does not contain helpers that explicitly request the root.
These Nib helpers expose no useRootNavigator argument. That parameter belongs to Flutter route helpers such as showDialog or showModalBottomSheet; their policies must not be copied onto a Nib call. Read the actual helper signature when selecting a local or application-wide presentation.
This website uses the package’s page-modal root-overlay helpers for dialogs, alert dialogs, sheets, and context menus. Nearest-overlay controls use the preview’s local Navigator overlay. In your own application, choose that host policy explicitly and verify barrier bounds, dismissal, and focus for each helper. A local preview Navigator alone does not contain a helper that asks for the root overlay.
Own an overlay that can outlive its caller
Use openNibDialog or openNibBottomSheet when another part of the screen must close the surface. Their handles expose closed, close, and isOpen; the sheet handle also exposes snapTo. Store the handle in the screen owner and close it when that owner no longer needs the surface. There is no handle.dispose method.
The declarative NibDialog and NibBottomSheet widgets connect their own overlay handles to optional controllers and close them during their lifecycle. With an imperative helper, the caller owns the decision to close. A root overlay is not automatically tied to a nested route’s lifetime.
Closing an animated surface has two stages: a result is reported, then the exit finishes and the entry is removed. Do not treat the result future as a screenshot-ready guarantee that every exit frame has completed. Dialog and sheet handles report whether the entry is still mounted through isOpen.
Account for focus, theme, and toast ownership
Dialogs create a focus scope, hide underlying semantics, and restore the previous focus when removed. barrierDismissible governs barrier and Escape dismissal. If you disable dismissal, keep an explicit reachable action inside the surface. Sheets have their own dismissible and drag-handle controls; test the specific exit paths you enable.
Dialog and sheet entries recapture the caller’s inherited themes when rebuilding and depend on the root theme. Theme capture does not copy arbitrary application state objects into the overlay. Pass the data and callbacks the content needs, and avoid reading a disposed caller after an async operation.
showNibToast returns an ID rather than a result future. Supply a context with an Overlay, or install NibToaster for context-free calls. Keep the ID if you must dismiss the toast using dismissNibToast. Duration.zero leaves it visible until dismissal. Reusing an ID follows onDuplicateTrigger; the default is shake, with ignore and replace alternatives.