NIB / DOCUMENTATION
State and controllers — NibComponents
Choose a state owner, connect callbacks, and dispose only the objects you create.
Open interactive viewChoose 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.
| Contract | Examples | Your responsibility |
|---|---|---|
| Required value + callback | NibCheckbox, NibSwitch, NibSlider, NibRadioGroup | Store the value and rebuild after accepting a callback. |
| Optional controlled value | NibFlipCard.isFlipped | Omit it for local state; provide it and onFlippedChanged for parent-owned state. |
| Optional controller | NibAccordion, NibTabs, NibSelect, NibNavigationMenu | Let the widget own its default controller, or retain and dispose an external one. |
| Native text editing | NibInput, NibTextarea | Choose controller or initialValue; connect Form validation separately. |
| Imperative result | showNibDialog, showNibBottomSheet | Await 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.
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.
Navigation selection and submenus
| API | Type | Default | Behavior |
|---|---|---|---|
| NibTabsController.animateTo | void Function(int) | Explicit operation | Select an index and request animated pager movement. |
| NibTabsController.jumpTo | void Function(int) | Explicit operation | Select an index without the programmatic pager animation. |
| NibAccordionController.open | void Function(int) | Single-open unless allowMultiple is true | Open an index, closing other indices in single-open mode. |
| NibNavMenuController.openChainTo | void Function(List<String>) | Empty chain | Set the root-to-deepest horizontal submenu path. |
| NibOtpController.clear | void Function() | Explicit operation | Clear 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.
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.