Read page as text

NIB / DOCUMENTATION

API reference — NibComponents

Use the right state and overlay entry point for each control.

Open interactive view

Keep controllers alive for the whole interaction

The table snippet belongs inside a StatefulWidget. Declare tableController as a field on State, return the table from build, and call tableController.dispose before super.dispose. Creating it inside build loses selection whenever the parent rebuilds. With no external controller, the table creates its own; use that simpler mode when no other widget needs to command selection or sorting.

A column’s cellBuilder controls how one cell looks. sortValue supplies the value used for local comparisons, so a formatted currency label can still sort numerically. Adding onSort changes responsibility: the table reports the request and expects the host to provide rows in the requested order. For a remote query, show loading, preserve the current rows until a response is accepted, and avoid letting an older response replace a newer sort request.

Selection uses row values, while rowKey identifies Flutter rows for animation. In a real model, derive the key from a stable record ID, not the visible name or its current position. Two people can share a name, and positions change when sorting. Begin with selectionMode.none, then enable single or multi only when a selected-row action actually exists.

Sort and select table rows

NibDataTable<T> requires columns and rows. Without onSort it sorts locally. If onSort is set, the host supplies rows in the requested order, which is the right shape for server-side sorting.

Use a stable rowKey when animated rows can reorder or be replaced. Create and dispose NibDataTableController<T> in the owner state if another widget needs to change sorting or selection.

final tableController = NibDataTableController<String>();

NibDataTable<String>(
  controller: tableController,
  columns: [
    NibDataColumn<String>(
      label: 'Name',
      cellBuilder: (context, name) => Text(name),
      sortValue: (name) => name,
    ),
  ],
  rows: const ['Ada', 'Lin'],
  rowKey: (name) => ValueKey(name),
  selectionMode: NibDataTableSelectionMode.single,
  onSelectionChanged: (selected) => debugPrint(selected.join(', ')),
)
APITypeDefaultBehavior
columns / rowsList<NibDataColumn<T>> / List<T>requiredColumn schema and current row values.
selectionModeNibDataTableSelectionModenoneNone, single, or multi row selection.
rowHeight / headerHeightdouble48 / 48Table metrics in logical pixels.
stickyHeaderbooltrueKeeps column labels visible during table scrolling.
onSortcallback?nullWhen supplied, host owns sorted row order.

Give tabs one vertical scroll

NibTabs expects bounded height. Put content above the tabs in header and content after the active panel in footer; do not wrap the entire widget in another vertical ScrollView. The widget has its own single vertical scroll and a pinned bar.

An external NibTabsController lets a parent animateTo or jumpTo an index. Dispose it when the parent is removed. panelGap is 16 logical pixels by default.

APITypeDefaultBehavior
tabsList<NibTab>required nonemptyEach tab has a label and lazy panel builder.
controllerNibTabsController?nullExternal selection owner; otherwise internally owned.
panelGapdouble16Space between panels and before footer in logical pixels.
barHeightdouble44Pinned tab bar height in logical pixels.
scrollableboolfalseIntrinsic-width horizontal tab strip when true.

Pick a dialog entry point

NibDialog is a placed widget with trigger or NibDialogController. showNibDialog<T> opens one imperatively and returns Future<T?>. A dismissed dialog resolves to null; NibDialogScope.of(context).close(result) supplies a result.

NibCommandPalette can use its platform-aware open shortcut: Command-K on Apple platforms or Control-K elsewhere. Scope command actions to the host and dispose an external palette controller.

APITypeDefaultBehavior
NibDialog.contentWidgetrequiredModal body.
NibDialog.barrierDismissiblebooltrueAllows barrier dismissal.
NibDialog.animatedboolfalseOpt-in overlay transition.
showNibDialog<T>(...)Future<T?>null on dismissOpens modal content without a placed trigger widget.
NibCommandPalette.openShortcutShortcutActivator?platform shortcutOpens the palette from the keyboard.

Wait for a dialog result before changing data

Put this function in your screen’s State and call it from a button. The Builder provides a context inside the dialog’s scope. Using the page context for NibDialogScope.of cannot find that scope. close(true) resolves the returned Future with true; dismissal through Escape, the barrier or the close control resolves with null.

The example only reports a local confirmation. Replace that message with your host operation after you have defined its failure and retry behavior. Check mounted after awaiting the result because the original page may have been removed. Do not dispose a controller you did not create, and do not add an external dialog controller simply to obtain a return value: the imperative function already returns one.

For tabs, return NibTabs from a bounded page region such as Scaffold.body or Expanded. Use its header and footer for surrounding scrollable content. A NibTab.builder builds the panel; it does not select a route. Try a short and long panel and watch the pinned bar. If the page traps scrolling, inspect the outer constraints and scroll ownership before adding another controller.

Future<void> confirmArchive() async {
  final confirmed = await showNibDialog<bool>(
    context,
    title: 'Archive this draft?',
    content: Builder(
      builder: (dialogContext) => NibButton(
        label: 'Archive',
        onPressed: () => NibDialogScope.of(dialogContext).close(true),
      ),
    ),
  );
  if (!mounted || confirmed != true) return;
  ScaffoldMessenger.of(context).showSnackBar(
    const SnackBar(content: Text('Archive confirmed locally')),
  );
}