Read page as text

NIB / DOCUMENTATION

Troubleshooting and migration — NibComponents

Fix common state, validation, and layout mistakes.

Open interactive view

A field does not update or validate

Do not pass controller and initialValue together to NibInput or NibTextarea. When you supply a controller, update or inspect that controller; when you do not, the widget owns it.

Form.validate triggers the field validator even if autovalidateMode is disabled. A non-null errorText forces an error above validator output, so clear it after a successful server response.

A choice snaps back

If a checkbox or switch snaps back, check whether its callback assigns the proposed value and rebuilds the widget. A non-null callback can run while value remains unchanged. Use the repair below to see the full loop. For NibSelect, do not apply this rule blindly: it keeps selection in its controller, value and values seed internal state, and an external controller takes precedence.

NibSelect requires exactly one option source, options or groups. In multi-select mode, use onSelectionChanged for the complete List<T>. NibDataTable has a separate ownership switch: adding onSort asks your host to supply sorted rows. Without it the table sorts locally. A callback that only logs the request will not reorder server-owned data.

Repair the value-to-callback loop first

Put enabled on your State class and this switch in build. Tap it and verify both the switch and the text change. Temporarily remove setState from the callback: the variable changes, but the widget tree keeps its previous configuration until another rebuild. Restore setState. This small experiment distinguishes a callback problem from a rendering or theme problem.

When a text field loses its draft, look for a new TextEditingController, a changing key, or a replacement form key created inside build. A rebuild should reuse the owner’s controller. A reset should be a deliberate action, such as FormState.reset or assigning controller.text. Do not use a key change to force a label update; that replaces widget state and can also discard focus.

// On State:
bool enabled = false;

// In build:
Column(mainAxisSize: MainAxisSize.min, children: [
  NibSwitch(
    value: enabled,
    onChanged: (next) => setState(() => enabled = next),
  ),
  Text(enabled ? 'Notifications on' : 'Notifications off'),
])

Reduce a failing screen to one interaction

Start with the first error in the console. An assertion about controller and initialValue means two owners were supplied; choose one before changing validation. An options/groups assertion means the select has zero or two sources; provide one. A layout error about unbounded height means a viewport cannot determine its size; place it in a finite region and remove competing vertical scroll owners. Later errors can be consequences of the first failure.

For an overlay that opens but will not close from its content, check the BuildContext used to find its scope. The page context exists above the newly inserted dialog. Wrap dialog content in Builder and use its inner context for NibDialogScope.of. For a result that never updates the page, check the awaited result and mounted before calling setState. Barrier dismissal normally produces null; it is not the same as a confirmed action.

Migrate one working interaction at a time. Keep the same host values, validation and save method while swapping the visual control. Verify typing, focus, submit, cancellation and failed submission before adding optional motion. The form demo gives a small reference flow; the theme demo helps isolate inherited colors from state. If a problem appears only with custom colors, remove instance overrides and test the built-in palette.

For a useful bug report, include a small runnable widget, package versions, platform, viewport size, text scale, the action sequence and the first exception. Avoid copying private form values or a full production response. A reproduction that begins in a known state and ends with a specific incorrect result is much easier to verify than a screenshot of the final screen alone.

Move one screen at a time

Replace a Flutter control with the corresponding Nib widget while leaving its state owner in place. Start with the public barrel import, confirm the callback and nullable value behavior, then register NibTheme if the default palette is not right for the screen.

If tabs trap the page scroll, remove the outer vertical scroll and move surrounding content into NibTabs.header and footer. Dispose any external controllers or focus nodes that the old screen created.