Read page as text

NIB / DOCUMENTATION

Button — NibComponents

A real action, a visible result, and the right busy state.

Open interactive view

Connect the action to an outcome

NibButton requires onPressed. A null callback disables activation; disabled: true also blocks it. The preview increments a local counter from the real callback, so a visible press corresponds to an actual action. In an application, return errors near the action and keep the label specific to its outcome.

Choose a visual role

NibButtonVariant has primary, secondary, outline, ghost, and destructive. They share the same box geometry for a given size. Use destructive for an action that needs that warning; the enum does not add confirmation or authorization. This preview only counts activations, including its destructive-colored variant.

Keep pending work from running twice

loading: true shows a loader and blocks taps while preserving the button footprint. loadingText can describe the pending action; loadingWidget replaces the default indicator. The host must set and clear loading around its own work. This example exposes a manual busy switch and does not simulate a server request.

setState(() => saving = true);
try {
  await saveChanges();
} finally {
  if (mounted) setState(() => saving = false);
}

Fit content without changing the action

NibButtonSize.sm, md, and lg use nominal heights 36, 44, and 52. NibButtonSizeMetrics.of(size) supplies height, font size, horizontal padding, icon size, and gap. Explicit height, width, padding, and borderRadius override the defaults. expand fills a bounded width; pill changes the shape. content replaces the normal label/icon layout, so provide its own semantics when necessary.

Keyboard and press feedback

Enter and Space activate an enabled focused button. focusNode belongs to the caller when provided; dispose it with your State. semanticLabel gives an icon-only button an accessible name. tooltip is extra help, not a substitute for that name. animated defaults to false; opting in animates the press response through NibMotion. The busy indicator is independent of that press flag.

When a press does nothing

Check onPressed, disabled, and loading in that order. A disabled callback cannot be repaired with an animation flag. If a label clips, remove a fixed width or use expand in a bounded parent. Test custom backgroundColor and foregroundColor together, including disabled, hover, and focus states; color overrides can remove the contrast supplied by NibTheme.