NIB / DOCUMENTATION
Start with components — NibComponents
Install the published widget library and wire a control to app state.
Open interactive viewAdd the package
Run the package command in an existing Flutter app. nib_components declares nib_motion as a dependency, so pub resolves the animation layer with it.
Import the public barrel. The widgets also work without a registered NibTheme; they choose the built-in light or dark palette from the surrounding Flutter Theme.
flutter pub add nib_componentsBuild a complete first screen
You need a Flutter app that already runs with MaterialApp. Add the package with the command above, then replace lib/main.dart with this small screen. MaterialApp supplies Flutter theme and direction; Scaffold supplies the page surface. The example keeps one integer in State. Each press runs onPressed, increments the integer inside setState, and rebuilds the text. NibButton handles focus, tapping and appearance; the integer remains application state.
Run the screen before adding animation. Press Add one twice and verify that the number is two. The live button demo follows the same flow and also has Reset. Try moving the integer declaration into build: it returns to zero on every rebuild. Move it back to State to restore persistence. This distinction applies to form keys, selected values and controllers throughout the library.
import 'package:flutter/material.dart';
import 'package:nib_components/nib_components.dart';
void main() => runApp(const MaterialApp(home: CountPage()));
class CountPage extends StatefulWidget {
const CountPage({super.key});
@override
State<CountPage> createState() => _CountPageState();
}
class _CountPageState extends State<CountPage> {
int count = 0;
@override
Widget build(BuildContext context) => Scaffold(
body: Center(
child: Column(mainAxisSize: MainAxisSize.min, children: [
Text('Pressed $count times'),
NibButton(
label: 'Add one',
onPressed: () => setState(() => count++),
),
]),
),
);
}Let app state decide
NibButton calls onPressed; it does not own the state that the button changes. Store that state in your widget, controller, or application model and rebuild with the new value.
A null onPressed, disabled: true, or loading: true blocks input. Keep a useful label or semanticLabel when the visible content is only an icon.
bool saved = false;
NibButton(
label: saved ? 'Saved' : 'Save draft',
variant: NibButtonVariant.primary,
onPressed: () => setState(() => saved = true),
)| API | Type | Default | Behavior |
|---|---|---|---|
| label | String? | null | Visible button text; content or an icon can supply the body instead. |
| onPressed | VoidCallback? | required | Host callback. Null disables the button. |
| variant | NibButtonVariant | primary | Primary, secondary, outline, ghost, or destructive styling. |
| size | NibButtonSize | md | Preset control metrics; md is about 44 logical pixels high. |
| animated | bool | false | Opts into the component motion path for supported state changes. |
Add loading after the action works
For an asynchronous save, store a saving boolean beside the result. Set it before starting the request and pass it as loading. The button then blocks additional presses and shows its loader; loadingText can explain the work. On failure, keep the input, show a useful error and clear saving so the person can retry. After an await, check mounted before updating a State object that may have left the screen.
Loading changes presentation and input handling; it does not start, cancel or retry a request. Likewise, the destructive variant changes styling but does not confirm a delete. Put confirmation and persistence in the host action. Once the behavior is correct, try animated: true for the small press effect. Leave it false if the screen does not need extra motion. Both settings still provide native button interaction.
If nothing happens, first check whether onPressed is null, disabled is true, or loading is still true. Then put a breakpoint in the callback. A callback that runs without a visible update usually means the host changed a variable without rebuilding the widget that reads it.
Choose the state owner
The state owner is the object that keeps a value between builds. A simple button uses your State object; a checkbox receives value and onChanged; a select can keep selection in an internal controller. These are different contracts. Decide whether another part of your app needs to read or change the value before introducing an external controller.
Create long-lived controllers once in State, not inside build. A widget disposes an internal controller that it created. You dispose a controller that you passed in. Rebuilding a widget is routine; disposing its controller ends that controller’s lifetime. Keep those operations separate so a theme change or validation message does not erase the user’s work.