NIB / DOCUMENTATION
Alert dialog — NibComponents
Ask for a decision and distinguish confirmation, cancellation, and dismissal.
Open interactive viewAsk one clear question
Use showNibAlertDialog when the next step needs a yes-or-no answer: applying a preference, leaving a draft, or acknowledging a result. The helper supplies the dialog surface and action buttons. It is a function; there is no public NibAlert widget in this package.
The example changes only its local result label. Apply locally returns true, Keep current returns false, and dismissal returns null. Your application decides what those answers authorize. An alert does not implement server permissions or undo.
Choose severity and content
NibAlertSeverity offers info, success, warning, and error. NibAlertSeverityX.defaultIcon() and accent(NibTheme) resolve the visual cue. Error chooses a destructive confirm button unless confirmVariant overrides it. A red button does not make an operation safe.
Supply title, description, or content. Custom content replaces the built-in body and must include its own heading and explanation. The live example uses that slot to show the severity icon and retain its scope for cleanup. icon, iconColor, titleTextStyle, and descriptionTextStyle customize the built-in body.
Handle one result, once
cancelText: null creates a single-action acknowledgment. onConfirm and onCancel run for the default buttons; outside dismissal is a third outcome. Put a business action in either the awaited result handler or the callback to avoid executing it twice.
actions replaces the default pair. Custom buttons own their result behavior and should close through NibDialogScope.of(aContextInsideTheDialog).close(true) or close(false). Use showNibDialog<T> for a result richer than a boolean.
await showNibAlertDialog(
context,
title: 'Changes saved',
severity: NibAlertSeverity.success,
confirmText: 'Continue',
cancelText: null,
);Fit the actions to the available space
buttonWidth, buttonPadding, cancelVariant, and confirmVariant shape the default buttons. actionsAlignment, actionsSpacing, actionsOverflowAlignment, actionsOverflowDirection, and cancelFirst control layout. The Material action OverflowBar can stack when labels do not fit. Test translations and text scaling.
adaptive defaults to false. When true, iOS and macOS receive the helper’s Cupertino-style presentation; other platforms retain the Material-style presentation. This is Nib’s implementation. A target-platform override in a widget test is not a physical iPhone accessibility pass.
Keep lifetime and focus explicit
The helper inserts into the root overlay. In the website, this is a deliberate page-modal task: its barrier can cover the page, rather than only the preview card. The surface captures inherited themes, creates a focus scope, and restores previous focus when removed. The alert body uses an inert initial focus sink, so do not assume the first action is selected.
Check mounted after awaiting. Dropping a Future does not cancel the surface. The complete example retains a close callback captured from the active scope and calls it on disposal. Never look up an ancestor from a deactivated context. Keep a visible action when outside dismissal is disabled.
Read dismissal correctly
barrierDismissible controls outside dismissal. animated defaults to false; transition configures optional motion. A null result is neither acceptance nor rejection. Use Builder inside content or actions when the page context cannot find NibDialogScope.
Validate the actual barrier area, Escape behavior, focus return, and action labels in your host. These local examples do not certify a production authorization flow, physical touch, or a screen reader.