unified_popups

pub package likes points popularity license

Languages: English · 中文

A unified Overlay popup system for Flutter: Toast / Loading / Confirm / Date / Sheet / FlowSheet / Menu / DropMenu / Custom — one runtime, one conflict & lifecycle model, one back-button and route policy.

No BuildContext required. Does not pollute the page route stack. Call from Services, network callbacks, or ViewModels.

Pop.xxx(Config) -> PopupOpenResult<T>

Use unified_popups

Why this package

Official showDialog / showModalBottomSheet answer “how do I show a Material widget?” Real apps also need:

Pain point unified_popups
No BuildContext in Services / async callbacks Global Pop.*, no Context plumbing
Separate Toast / Loading / Confirm / Sheet stacks One open model with configurable policies
Popups pushed onto Navigator, messy back stack Private Overlay; page routes stay clean
Inconsistent back / swipe / route-change behavior Shared backPolicy / routePolicy
Duplicate Loading, messy multi-step flows Key conflict policies + FlowSheet page stack

In short: official APIs are page-level route popups; this package is app-level popup governance. See Why Overlay (Chinese).

Capabilities · when to use which

API Typical use Default system back
Toast Success / error / light feedback without interrupting Ignore (does not intercept)
Loading Submit, upload, fetch wait states Block (prevent accidental exit)
Confirm Delete, discard edits, second confirmation Block (must tap a button)
Date Birthday, booking date, etc. Dismiss popup
Sheet Option lists, filters, single-page forms Dismiss popup
FlowSheet Multi-step wizards (nested page stack) Pop inner page first, then close sheet
Menu Anchor “more” custom menus Dismiss popup
DropMenu Filter bars, settings rows, nestable sections Dismiss popup
Custom Any content on the shared lifecycle Configurable

Preview

Screenshots from the Example app (FitPulse / API Lab).

Toast · light feedback

Saved, network error, copied — without interrupting the current page.

Toast

Loading · async wait

Submit, upload, payment fetch. Use PopupLifetime.until to dismiss when a Future settles.

Loading

Confirm · strong confirmation

Delete, clear, leave unsaved work — barrier tap and system back do not dismiss by default. The shell is described under Glass container below.

Confirm

Sheet · single panel

Option lists, filters, simple forms. Stack Confirm on top for in-panel confirmation. The shell is under Glass container below. Sheet and FlowSheet share SheetStyle.surface.

Sheet Sheet + Confirm
Sheet Sheet + Confirm

FlowSheet · multi-step flow

Wizards and multi-page forms: system back pops inner pages first, then closes the sheet. push keeps one page per id. Use popToRoot to return to the root page without closing the sheet. Use contains / popTo to return to a named page (result arrives on onPoppedTo). Use resetTo to replace the stack with a new home (animate: true slides it in, then collapses to a single root). Use completeAndCloseAll, then Pop.settleChannel, when the next step is a full-screen route. A Confirm on top can still block back.

FlowSheet

DropMenu · anchored menu

One-level filter menus, or nestable settings sections. DropMenu is glass by default; see Glass container below.

Single level Nested sections
DropMenu single DropMenu nested

Glass container

Confirm, Sheet, FlowSheet, Menu, and DropMenu share one switch: style.surface. Toast, Loading, Date, and Custom do not have this field.

API Style Default
Pop.confirm ConfirmStyle.surface PopupSurface.solid()
Pop.sheet / Pop.flowSheet SheetStyle.surface PopupSurface.solid()
Pop.menu PopupMenuStyle.surface PopupSurface.solid()
Pop.dropMenu DropMenuStyle.surface PopupSurface.glass()

PopupSurface.solid() is an opaque fill, PopupSurface.glass() is liquid glass, and PopupSurface.builder(...) swaps in an external container. Radius, blur, and shadow parameters are in doc/API_REFERENCE.md §5 玻璃容器.

Quick start (30 seconds)

dependencies:
  unified_popups: ^2.2.2
MaterialApp(
  navigatorObservers: [Pop.routeObserver],
  builder: Pop.hostBuilder,
  home: const HomePage(),
);

Calls made before the first Host mount are queued and shown when Host is ready.

Pop.toast(const ToastConfig.text('Saved', type: ToastType.success));

Pop.loading(const LoadingConfig.text('Submitting'));
try {
  await submit();
} finally {
  Pop.dismissChannel(PopupChannel.loading);
}

final ok = await Pop.confirm(
  const ConfirmConfig(
    title: 'Delete record',
    content: 'This cannot be undone.',
    confirmText: 'Delete',
    cancelText: 'Cancel',
  ),
).result;

Architecture

Business code, Services, and network callbacks all enter the same Runtime via Pop.xxx(Config). Popups render on a private Overlay above the app child and do not pollute the page route stack.

Unified Popups Architecture

Layering and the back bridge: Architecture (Chinese). Trade-offs vs official Dialog / Sheet: Why Overlay (Chinese).

Lifecycle

Every entry shares one state machine from created to disposed. Conflict policy decides stack, reject, replace, or in-place update. Dismiss may come from complete / manual / back / barrier / route / lifetime. The first dismiss request settles result / outcome; dismissed completes after the exit animation. Later dismiss calls are idempotent.

Popup Entry Lifecycle

Understand the return model first

Pop.xxx(config) is synchronous and always returns PopupOpenResult<T>. await does not choose between a value and a Handle — what you read from PopupOpenResult does.

Goal Call You get
Fire and forget Pop.toast(config) Ignore the open decision
Wait for a business value await Pop.confirm(config).result bool?
Imperative control Pop.loading(config).requireHandle() PopupHandle<void>
Handle conflicts final opened = Pop.menu(config) PopupOpenResult<T>
Pop.confirm(config)
        │
        ▼
PopupOpenResult<bool>
   ├─ .result ──────────> Future<bool?>
   ├─ .requireHandle() ─> PopupHandle<bool>
   ├─ .handleOrNull ────> PopupHandle<bool>?
   └─ switch ───────────> opened / updated / rejected / toggled

.result may be null on cancel, external dismiss, conflict reject, or toggle. Read handle.outcome for the reason. When a conflict is a valid outcome, use handleOrNull. Open decisions and Handle members are in doc/API_REFERENCE.md §3.

Prefer an app-level facade

SDK Configs expose full power. Real apps usually want shared visuals, copy, analytics, error handling, and defaults. Have business pages call your own AppPop:

abstract final class AppPop {
  static void success(String message) {
    Pop.toast(
      ToastConfig.text(message, type: ToastType.success),
    );
  }

  static Future<bool> confirm({
    required String title,
    required String content,
  }) async {
    return await Pop.confirm(
          ConfirmConfig(
            title: title,
            content: content,
            confirmText: 'OK',
            cancelText: 'Cancel',
          ),
        ).result ??
        false;
  }
}

Usage:

final confirmed = await AppPop.confirm(
  title: 'Delete record',
  content: 'This cannot be undone',
);

In the Example, FitPulse uses AppPop; the API Lab keeps raw Pop.xxx(Config) to show product wrapping vs the full SDK contract.

A few patterns you will need next

Sheet, Menu, and Custom builders receive a Handle: handle.complete(value) finishes, handle.dismiss() cancels.

Loading can follow one request and dismiss when that Future settles. A repeat open updates the same global Loading:

final request = saveData();

Pop.loading(
  LoadingConfig.text(
    'Saving',
    lifetime: PopupLifetime.until(request),
  ),
);

await request;

Menu’s default transparent barrier blocks scrolling underneath. Pass PopupBarrierConfig.hidden() when the page should keep scrolling and the menu should follow its anchor. DropMenu uses DropMenu.single or DropMenu.nested.

Before a full-screen route after closing a sheet, Pop.settleChannel waits out the exit animation. dismissChannel closes entries that are still showing.

Fields and the rest of the management API are in doc/API_REFERENCE.md: return model, Loading, Sheet, Menu, and global management.

Docs

Deep-dive docs are currently Chinese; use them alongside this English README:

Run the Example:

cd example
flutter run

Libraries

liquid_glass
可单独使用的液态玻璃表面。
unified_popups
Flutter 统一全局弹窗 SDK。