Read page as text

NIB / DOCUMENTATION

State and controllers — NibComponents

Choose a state owner, connect callbacks, and dispose only the objects you create.

Open interactive view

Choose the contract before adding a controller

A value and an event are different things. value describes the current state. onChanged asks your app to accept a new state. A controlled widget keeps showing the old value until its parent rebuilds with the new one. An optional controller instead stores widget-specific state and exposes operations that another part of the screen can call.

ContractExamplesYour responsibility
Required value + callbackNibCheckbox, NibSwitch, NibSlider, NibRadioGroupStore the value and rebuild after accepting a callback.
Optional controlled valueNibFlipCard.isFlippedOmit it for local state; provide it and onFlippedChanged for parent-owned state.
Optional controllerNibAccordion, NibTabs, NibSelect, NibNavigationMenuLet the widget own its default controller, or retain and dispose an external one.
Native text editingNibInput, NibTextareaChoose controller or initialValue; connect Form validation separately.
Imperative resultshowNibDialog, showNibBottomSheetAwait the returned future; use an open helper handle for external close control.
// Field and widget inside a State class.
bool enabled = false;

Widget buildSwitch() => NibSwitch(
  label: 'Sync drafts',
  value: enabled,
  onChanged: (next) => setState(() => enabled = next),
);

Create once; dispose when the owner leaves

Create an external controller in State, not inside build or an onPressed callback. Pass the same instance to the component and dispose it in the owning State.dispose. Components detach from external controllers; they do not dispose them for you. When no controller is supplied, the component manages its internal controller.

If you add your own controller listener, remove it before disposing the owner. When a parent replaces a supplied controller, detach from the old instance in didUpdateWidget and attach to the new one. Do not dispose the old external object unless your object created it and still owns it.

Tabs and scroll ownership

class TabScreen extends StatefulWidget {
  const TabScreen({super.key});
  @override
  State<TabScreen> createState() => _TabScreenState();
}

class _TabScreenState extends State<TabScreen> {
  final tabs = NibTabsController(initialIndex: 0);

  @override
  void dispose() {
    tabs.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => Scaffold(
    body: Column(children: [
      NibButton(label: 'Open notes', onPressed: () => tabs.animateTo(1)),
      Expanded(child: NibTabs(
        controller: tabs,
        tabs: [
          NibTab(label: 'Summary', builder: (_) => const Text('Summary')),
          NibTab(label: 'Notes', builder: (_) => const Text('Notes')),
        ],
      )),
    ]),
  );
}

Use the operation that matches the state

Controllers are specific to a family. NibTabsController.animateTo requests an animated switch; jumpTo requests an immediate switch. NibAccordionController coordinates open indices, including single-open behavior. NibNavMenuController separates a horizontal flyout path from the set of expanded vertical items. None of these controllers performs application routing.

Accordion state

Navigation selection and submenus

OTP input and verification

APITypeDefaultBehavior
NibTabsController.animateTovoid Function(int)Explicit operationSelect an index and request animated pager movement.
NibTabsController.jumpTovoid Function(int)Explicit operationSelect an index without the programmatic pager animation.
NibAccordionController.openvoid Function(int)Single-open unless allowMultiple is trueOpen an index, closing other indices in single-open mode.
NibNavMenuController.openChainTovoid Function(List<String>)Empty chainSet the root-to-deepest horizontal submenu path.
NibOtpController.clearvoid Function()Explicit operationClear the entered code; it does not cancel your verification request.

Preserve selection as well as text

TextEditingController.value contains text, selection, and the composing range. Reassigning controller.text during every rebuild can discard the cursor and interrupt input methods. Change it only for an explicit edit or accepted external update. Use a complete TextEditingValue when your application must set both text and selection.

For NibInput and NibTextarea, initialValue seeds internally owned text. It is not a live command to replace the draft on each rebuild. Passing both initialValue and controller is an assertion error. In the current candidate, switching from an external controller to internal ownership preserves the editing value; switching to a supplied controller adopts that controller’s value. Prefer stable ownership for an ordinary form.

Fields, cursor behavior, and controls

Keep request state in the application

NibSwitch.loading and NibButton.loading block repeated interaction and show busy feedback. They do not start, authorize, retry, or cancel a request. Set busy before awaiting work, keep the previous accepted value until success if that is your interaction policy, and clear busy on failure. Check mounted before calling setState after an await.

When multiple requests can overlap, give each request an identity and ignore stale responses. Unmounting a widget does not cancel an HTTP request. Dispose controllers and cancel subscriptions or requests in their respective owners; keep those duties separate from a component’s presentation state.

Switch value and loading behavior

Validation and submission