CNButton class

A Cupertino-native push button.

Embeds a native UIButton on iOS 26+ and an NSButton on every macOS for authentic visuals and behavior. Falls back to CupertinoButton on iOS before 26 and on other platforms.

All buttons are round by default: an icon-only button is a circle, a button with a label a capsule. Use config to customize appearance.

On macOS the glass styles use the system's glass bezel from macOS 26; before that every style but CNButtonStyle.plain is a standard push button, filled with tint for the prominent styles.

Inheritance
Available extensions

Constructors

CNButton({Key? key, required String? label, CNSymbol? icon, VoidCallback? onPressed, bool enabled = true, Color? tint, IconData? customIcon, CNImageAsset? imageAsset, CNButtonConfig config = const CNButtonConfig(), bool autoHideOnModal = true, String? semanticLabel})
Creates a text button variant of CNButton.
const
CNButton.icon({Key? key, CNSymbol? icon, IconData? customIcon, CNImageAsset? imageAsset, VoidCallback? onPressed, bool enabled = true, Color? tint, int? badgeCount, CNButtonConfig config = const CNButtonConfig(style: CNButtonStyle.glass), bool autoHideOnModal = true, String? semanticLabel})
Creates a round, icon-only variant of CNButton.
const

Properties

autoHideOnModal → bool
When true (default), destroys the native button's PlatformView while a modal sheet is presented above this widget's host route. Fixes the iOS hybrid-composition z-order bleed (Issue #53) where a host-page CNButton's pixels leak through a sheet that also contains a CN-widget. Requires CNTabBarRouteObserver() to be registered in the app's navigatorObservers. No effect on iOS < 26 / non-iOS (Flutter fallback).
final
badgeCount → int?
Optional badge count to display on icon buttons.
final
config → CNButtonConfig
Button configuration.
final
customIcon → IconData?
Optional custom icon from CupertinoIcons, Icons, or any IconData. If provided, this takes precedence over icon but not imageAsset.
final
enabled → bool
Whether the control is interactive and tappable.
final
hashCode → int
The hash code for this object.
no setterinherited
icon → CNSymbol?
Optional button icon (SF Symbol). Can be used together with label to create a button with both text and icon. Priority: imageAsset > customIcon > icon
final
imageAsset → CNImageAsset?
Optional image asset (SVG, PNG, etc.) for the button icon. If provided, this takes precedence over icon and customIcon.
final
isIcon → bool
Whether this instance is configured as the icon variant.
no setter
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
label → String?
Button text (null in icon-only mode).
final
onPressed → VoidCallback?
Callback when pressed.
final
round → bool
Whether the button is round (always true).
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
semanticLabel → String?
What VoiceOver reads for the button.
final
tint → Color?
Accent/tint color.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<CNButton>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
liquidGlass({CNGlassEffect effect = CNGlassEffect.regular, CNGlassEffectShape shape = CNGlassEffectShape.capsule, double? cornerRadius, Color? tint, bool interactive = false}) → Widget

Available on Widget, provided by the LiquidGlassExtension extension

Applies a Liquid Glass effect to this widget.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited