CNPageControl class

A Cupertino-native page control: a row of dots, one per page, with the current page highlighted.

On iOS 26+ this embeds a UIPageControl through a platform view. macOS has no native page control, so on macOS, below iOS 26 and on other platforms it is drawn in Flutter, with the same look and interactions: a tap beside the current dot moves one page that way, and with allowsContinuousInteraction a drag across the dots scrubs through the pages.

With a PageView

Pass the PageController of a PageView as controller. The dots then follow the PageView as the user swipes it, and a tap on the dots animates the PageView to the new page (pageAnimationDuration, pageAnimationCurve); a scrub jumps to it. currentPage is not used, and onChanged is still called for each page the user picks on the dots.

final pages = PageController();

Column(
  children: [
    Expanded(child: PageView(controller: pages, children: slides)),
    CNPageControl(numberOfPages: slides.length, controller: pages),
  ],
)

Without a controller the page control is controlled: it shows currentPage, and onChanged reports the page the user picks, which the parent passes back as currentPage.

Inheritance
Available extensions

Constructors

CNPageControl({Key? key, required int numberOfPages, int currentPage = 0, ValueChanged<int>? onChanged, PageController? controller, Color? pageIndicatorColor, Color? currentPageIndicatorColor, CNPageControlBackgroundStyle backgroundStyle = CNPageControlBackgroundStyle.automatic, bool hidesForSinglePage = false, bool allowsContinuousInteraction = true, bool enabled = true, double height = 28.0, bool autoHideOnModal = true, String? semanticLabel})
Creates a Cupertino-native page control.
const

Properties

allowsContinuousInteraction → bool
Whether the user can drag across the dots to scrub through the pages. When false, only taps move, one page at a time. Defaults to true.
final
autoHideOnModal → bool
When true (default), destroys the native page control's PlatformView while a modal sheet is presented above this widget's host route. Prevents the iOS hybrid-composition z-order bleed (Issue #53) where the host-page PlatformView's pixels leak through a sheet that also contains a PlatformView (CN-widget). Requires CNTabBarRouteObserver() to be registered in the app's navigatorObservers. No effect on non-iOS or iOS < 26 (Flutter path).
final
backgroundStyle → CNPageControlBackgroundStyle
Background behind the dots. Defaults to CNPageControlBackgroundStyle.automatic, shown while the user interacts with the control.
final
controller → PageController?
The controller of a PageView the dots follow and move. See "With a PageView" above.
final
currentPage → int
The highlighted page, from 0. Clamped to the pages there are. Not used when a controller is given.
final
currentPageIndicatorColor → Color?
Colour of the current page's dot. Defaults to CupertinoColors.label.
final
enabled → bool
Whether the user can change the page on the dots. A disabled control looks the same, as UIPageControl does, and still follows currentPage or its controller: use it for dots that only show the page.
final
hashCode → int
The hash code for this object.
no setterinherited
height → double
Height of the control. The dots and their background keep the system size, centred in it.
final
hidesForSinglePage → bool
Whether the control hides itself when there is only one page. It keeps its space in the layout.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
numberOfPages → int
Number of pages, one dot each.
final
onChanged → ValueChanged<int>?
Called with the page the user picks on the dots.
final
pageIndicatorColor → Color?
Colour of the dots of the other pages. Defaults to CupertinoColors.tertiaryLabel.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
semanticLabel → String?
What VoiceOver reads for the control, before "page 2 of 5", e.g. 'Onboarding'.
final

Methods

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

Constants

pageAnimationCurve → const Curve
The curve of that animation.
pageAnimationDuration → const Duration
How long a tap on the dots animates the controller's PageView.