Read page as text

NIB / DOCUMENTATION

Dialog — NibComponents

Open a focused task, return a typed result, and choose who owns its lifetime.

Open interactive view

Choose an ownership model

showNibDialog<T> returns Future<T?> when the caller only needs a result. openNibDialog<T> returns NibDialogHandle<T>, exposing closed, isOpen, and close(result). Keep that handle when an application event must close the task. NibDialog is the declarative wrapper, opened by a trigger or NibDialogController.

The three buttons exercise all three entry points with the same content. The scoped action returns a string for imperative calls. The declarative wrapper reports closure through onClose, rather than returning a typed Future. Avoid using an unrelated imperative surface and a controller to represent the same task.

Build the task inside the surface

content is required. title and description create the standard heading; header replaces that heading. footer holds actions below the scrolling content. Keep form keys, validation, and editing controllers in a stateful content widget when the task is a form.

NibDialogSize is a width ceiling: sm is 380, md is 512, and lg is 720 logical pixels. fullscreen fills the safe viewport and has no numeric ceiling. width overrides the ordinary ceiling; narrow screens still constrain it. nibDialogMaxWidth returns the preset ceiling, or null for fullscreen.

SettingMeaning
contentRequired scrolling task body
header / footerCustom heading / persistent actions
barrierDismissibleOutside dismissal; true by default
showCloseButtonBuilt-in close affordance; true by default

Return a value from the right context

NibDialogScope.of(context) is available inside the surface. Its close accepts a result compatible with T; isOpen describes the surface. A page context captured before insertion is above this scope. Builder inside content gives the correct context.

handle.closed completes after removal. Await it and check mounted before updating the caller. Treat null as dismissal. A repeated close is ignored by the surface. The handle is useful when cancellation comes from somewhere other than a dialog button.

final handle = openNibDialog<String>(
  context,
  title: 'Working draft',
  content: const Text('An application event can close this task.'),
);
if (handle.isOpen) handle.close('cancelled');
final result = await handle.closed;

Choose motion separately from timing

animated is false by default. NibDialogAnimation selects none, fade, scale, fadeScale, or slideUp; transition controls timing or spring response separately. resolveNibDialogEnter maps a preset to its NibAnim start: slideUp uses y: 16 and opacity zero; fadeScale uses scale .97 and opacity zero.

The none preset removes the card transform; an animated scrim can still fade. The surface respects reduced motion. Reopening a task is a new entrance, not an automatic retarget from one dialog into a different task.

Keep one controller and a clear focus path

Create NibDialogController once in State and dispose it there. open and close are idempotent; isOpen is observable through ChangeNotifier. Without an external controller the widget owns one. A trigger wrapper expects a non-interactive child; a nested NibButton should call controller.open itself.

The root overlay receives the dialog, inherited theme, and focus scope. These website dialogs are page-modal. Escape closes the focused surface and prior focus is restored when it is still attached. Test nested tasks and focus return in your actual app.

Close work when its owner leaves

An imperative dialog remains in its overlay until closed or that overlay is removed. The example captures the active scope object, retains a close callback, and calls it during disposal. It does not perform an ancestor lookup from dispose.

If opening does nothing, inspect nested gestures. If the wrong task closes, inspect the scope context. Validate a form before returning success and cancel or ignore stale async work. This component supplies presentation and lifecycle, not backend submission or authorization.