CNPopUpButton<T> class

A native pop-up button: a button that shows the current choice and opens a menu of choices when pressed, the standard picker of a value from a short list.

Unlike CNPopupMenuButton, which runs an action, a pop-up button selects one of its items: the selected item has a checkmark in the menu and its label is the button's title. It is controlled: onChanged reports the chosen item's value, and the button shows the new choice once value changes to it. If value stays the same, the button returns to it.

CNPopUpButton<String>(
  value: _size,
  items: const [
    CNPopUpButtonItem(value: 's', label: 'Small'),
    CNPopUpButtonItem(value: 'm', label: 'Medium'),
    CNPopUpButtonItem(value: 'l', label: 'Large'),
  ],
  onChanged: (v) => setState(() => _size = v),
)
macOS iOS 26+ iOS < 26, other platforms
control NSPopUpButton UIButton with a UIMenu, changesSelectionAsPrimaryAction CupertinoButton and a CupertinoActionSheet
width the widest item, as NSPopUpButton sizes itself the selected title the selected title

The button takes its native width, unless the parent forces one (an Expanded or a tight SizedBox), and its height (see there).

Use a CNPopUpButtonItem whose value stands for "none", such as null in a CNPopUpButton<String?>, for a "Choose…" placeholder. When no item has value, the first enabled item is shown as selected.

VoiceOver reads semanticLabel with the selected item's label as the value ("Size, Medium, pop-up button").

Inheritance
Available extensions

Constructors

CNPopUpButton({Key? key, required List<CNPopUpButtonEntry<T>> items, required T value, required ValueChanged<T>? onChanged, bool enabled = true, CNButtonStyle? buttonStyle, Color? tint, double? height, String? semanticLabel, bool autoHideOnModal = true})
Creates a native pop-up button.
const

Properties

autoHideOnModal → bool
When true (default), replaces the native view with an empty box of the same size while a modal sheet covers it (Issue #53). Requires CNTabBarRouteObserver() in the app's navigatorObservers.
final
buttonStyle → CNButtonStyle?
The button's look, as CNButton's. Null is the platform's own pop-up button: the bordered NSPopUpButton on macOS, and on iOS a plain tinted title with the pop-up indicator, as the system's menu pickers show.
final
enabled → bool
Whether the button can be pressed.
final
hashCode → int
The hash code for this object.
no setterinherited
height → double?
Height of the button. Null is the native height: 24 points on macOS (a regular-size pop-up button) and the height of the configured UIButton on iOS.
final
items → List<CNPopUpButtonEntry<T>>
The menu: choices, dividers and sections, in order.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
onChanged → ValueChanged<T>?
Called with the value of the item the user chooses. Null disables the button, as enabled false does.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
semanticLabel → String?
What VoiceOver reads for the button, before the selected item's label.
final
tint → Color?
Colour of the title (plain, gray, bordered, glass and tinted styles) or of the button (prominent styles). Null uses the theme's primary colour where the style is coloured; the default macOS pop-up stays uncoloured.
final
value → T
The selected choice: the item whose CNPopUpButtonItem.value equals it.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<CNPopUpButton<T>>
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