cupertino_native_better 2.7.4
cupertino_native_better: ^2.7.4 copied to clipboard
The real iOS 26 and iOS 27 Liquid Glass controls in Flutter: native tab bars, buttons, menus, sliders, switches, alerts and sheets, with Cupertino fallbacks.
2.7.4 #
Fixed: on iOS 26 and later, a tap just above
CNTabBar's glass capsule, or beside it, did nothing (#162). It now reaches the Flutter content behind the bar, as in a native app. Also fixed: on a bar shorter than its own height, a tap on the top of an icon, where it draws above the capsule, now selects its tab.
Fixed — taps above and beside the tab bar's capsule (#162) #
The native bar sits 14 pt below the top of its platform view, which leaves room for the Liquid Glass selection pill, and the iOS 26 capsule doesn't fill the bar's width. A touch in that room, or beside the capsule, hit the bare view behind the bar and was dropped. UIKit's own bar takes no touches there, so in a native app they reach the content behind it.
Now the native bar tells Flutter where it takes touches, found with UIKit's own hit testing after each layout, and Flutter sends only those touches to the platform view. Any other touch on the view goes to the Flutter content behind the bar, such as a list row, a button or the start of a scroll. Until the bar has reported, the view takes every touch on it, as before.
Fixed — taps on the top of a short bar's icons (#162) #
A bar given a height shorter than its own draws its icons up past the top of its capsule, into the room above the bar. A tap on that part of an icon hit the bare view and did nothing. Now the bar hands it to the item below, which selects it with the glass press, as a tap on the capsule does. A tap on the room between and above the icons goes to the content behind.
Thanks to @djedi for the report and PR #162, whose way of handing those touches to the bar this uses.
Checked #
These checks use the iPhone 17 Pro Max simulator on iOS 26.2, the iPhone 17 Pro simulator on iOS 26.0 and the iPhone 17 simulator on iOS 27.0, with five bars: labeled and icon-only, each at its own height and at height: 60, and a split bar.
- Where each bar takes touches: the area it reports is its capsule on the screen, 274 by 62 pt, 14 pt below the top of the view; the split bar reports its two capsules.
- Taps sent through Flutter's hit testing:
- In the room above the capsule, beside it, and 1 pt above it, the taps reach the content behind the bar.
- On the capsule, they stay with the bar.
- Short bars: the parts of icons above the capsule stay with the bar. In the running app, the native view hands a touch there to the capsule, and a touch on the room between the icons to no view.
- Not checked here: the simulator can't be sent real taps, so the bar's selection after such a handed-over touch rests on the PR author's check on an iPhone with iOS 26.
- Build: the Swift compiles with Xcode 26.0's compiler against the iOS 26.0 SDK.
- Example app: the new #162 screen floats a bar over a list. Taps above and beside the capsule reach the rows, with the full bar and with a short icon-only bar.
- Tests: 4 new; 648 tests pass.
2.7.3 #
Fixed: on a page hosted in a
PageRouteBuilder, glass widgets withautoHideOnModal: falseshowed a square box around their glass while a sheet package's sheet was open or held mid-drag (#161, new in 2.7.2). Also fixed: the first frame of a sheet route's push cut the glow of the glass widgets the open sheet would cover, before the sheet had appeared, on any page.
Fixed — a box around the glass under a sheet, on a page in a PageRouteBuilder (#161) #
A page in a PageRouteBuilder transitions with any page route pushed over it, and a sheet package's sheet route (modal_bottom_sheet's) is a page route. So the sheet moved the page's secondary animation, as a page pushed over it does. 2.7.2 then took the sheet route's whole box, which is the whole screen, for a page covering the widget, and hid all of its glow outside its bounds. That left a square box around the glass for as long as the sheet moved or was held.
Now a sheet route that the page transitions with counts as a modal: what covers the widget is its sheet, measured as for any other sheet (#156). The new CNTabBarRouteObserver.secondaryAnimationFollowsModal tells whether it does. showCupertinoSheet moves the secondary animation of every page under it, so it takes the same path.
Fixed — the glow cut before a sheet route appears #
A sheet route that is a page route (modal_bottom_sheet's, or showCupertinoSheet's) is offstage for the first frame of its push, and laid out open. The observer measured that layout as the open sheet, so a glass widget under where the sheet ends up had its glow cut all round before the sheet appeared. On the simulator, where that first frame is slow, this showed as a box for several frames. Now an offstage route paints nothing, and so does a route back from offstage until a frame lays it out again.
Thanks to @Ashhad08 for the report, the test matrix and the diagnosis.
Checked #
These checks use the iPhone 17 Pro Max simulator on iOS 26.2 and the iPhone 17 simulator on iOS 27.0, with the reporter's sample (modal_bottom_sheet 3.0.0, a heart CNButton.icon on light cards):
PageRouteBuilderpage,CupertinoScaffold.showCupertinoModalBottomSheet, dragged down in 60 pt steps and held at each:- On 2.7.2 a grey box showed around the heart at every held step.
- Now the heart keeps its glass and soft shadow at every step, also on every frame of a recording of the open and the drag.
- Plain
showCupertinoModalBottomSheeton aPageRouteBuilderpage, and both sheets on aMaterialPageRoutepage: glass and shadow at every step. With the sheet's edge just below a heart, the shadow stops at the edge. showCupertinoSheet, frame by frame:- On 2.7.2 a box showed around the heart for a few frames before the sheet reached it.
- Now the heart keeps its glass until the sheet covers it, and on every frame of the close.
- Earlier cases (#149, #156, #159): their tests are unchanged and pass.
- Example app: the new #161 screen opens a page in a
PageRouteBuilder, with a sheet route held mid-drag andshowCupertinoSheet. - Tests: 11 new; 644 tests pass. 10 of the new ones fail on 2.7.2.
2.7.2 #
Fixed: glass widgets with
autoHideOnModal: falseflat while a sheet's edge is near or over them (#156), and flat while a page is popped off them, then blinking back when the pop ends (#159). They now hide only the part of their glow that the sheet or page covers.
Fixed — glass flat next to a sheet's edge, and while a page slides over or off it (#156, #159) #
A glass widget's glow draws past its bounds, over whatever Flutter painted there. So while a sheet, popup, dialog or page came within reach of it, the widget was clipped to its bounds and its shadow cleared, which left it flat (no rim or shadow):
- Sheets (#156): with a sheet's edge near or over the widget, the widget stayed flat. It got its glass back only once the sheet was dragged clear of it.
- Pages (#159): the widget stayed flat for the whole push or pop. When a pop ended, its glass and shadow came back in a single frame, so the widget blinked each time you came back to the page.
Now the widget keeps its full glass and shadow, and the native view masks out only the part of its glow that the sheet or page covers. Inside its bounds, Flutter already draws the sheet or page above it.
- Sheets:
CNTabBarRouteObserveralready measures where the sheet is after every frame. - Pages: it now does the same for a page pushed over the widget, popped off it, or dragged by the back gesture. The new
CNTabBarRouteObserver.movingRouteRectgives that rect. - Fallback: when the position can't be told, the widget is clipped flat as before, for example without a
CNTabBarRouteObserverin the navigator, or for a modal whose bounds aren't known yet. This also applies on macOS, where the engine clips every platform view to its bounds anyway.
This applies to CNButton, CNPopupMenuButton, CNGlassButtonGroup, LiquidGlassContainer, CNSearchBar, CNFloatingIsland and CNTabRail.
Thanks to @Ashhad08 for both reports and their videos.
Checked #
These checks use the iPhone 17 Pro Max simulator on iOS 26.2 and the iPhone 17 simulator on iOS 27.0, with a CNButton and a CNPopupMenuButton in a page header:
modal_bottom_sheetsheet (CupertinoScaffold): the sheet's edge started at the bottom of the buttons and was dragged down in 8 pt steps.- On 2.7.1 the buttons were flat while the edge was at them or just below them.
- Now they keep their rim and shadow at every step, and the shadow stops at the sheet's edge.
CupertinoPageRoutepush and pop, frame by frame:- On 2.7.1 the buttons were flat for the whole pop, and their glass came back in one frame at the end.
- Now they keep their glass on every frame, and their glow stops at the page's edge.
- The back gesture, held partway, also keeps the glass.
- One frame at the start of a push shows the glow cut just before the page covers the buttons. This happens because the page's first frame reaches the screen after the native mask does.
- Example app: the #156 screen has a tall sheet whose edge starts at the button, and the new #159 screen pushes and pops a page.
- Tests: 9 new tests, 15 rewritten; 633 tests pass. 17 of these fail on 2.7.1.
2.7.1 #
Fixed: glass widgets with
autoHideOnModal: falseflat while a sheet package's sheet moves the page, including for as long as the sheet is held mid-drag (#156).CNScrollEdgeEffectnow fades the content toward the page's colour as native apps do, and itshardstyle works (#150). New:CNScrollEdgeEffect.backgroundColor.
Fixed — glass flat while a sheet moves the page, and while it is held mid-drag (#156) #
With a sheet that scales the page under it (as CupertinoScaffold sheets do), a glass widget with autoHideOnModal: false went flat (no rim or shadow) while the sheet came and went, and for as long as a finger held the sheet part-way down. 2.7.0 flattened it on purpose: unflattened, a square box showed around its glow while the page moved.
That box came from the widget itself. CNButton, CNPopupMenuButton and CNGlassButtonGroup wrapped their native view in a ClipRect exactly its own size. It clips nothing in Flutter, but under a scaled page the engine can't always tell that it covers the view (a rounding difference, on about half of the frames), and then masks the native view to its bounds, which cuts the glow into a box. The clip is gone, and so is the flattening: the widget keeps its full glass while the sheet scales the page, while it is dragged and held, and while it comes and goes, dimmed like the rest of the page. It is still contained while the sheet, popup or dialog comes within reach of its glow.
Thanks to @Ashhad08 for the report and the drag-and-hold repro.
Fixed — CNScrollEdgeEffect only blurred, and hard looked like soft (#150) #
Native apps fade the content under the edge toward the scroll view's background colour, besides blurring it, and the hard style is an opaque band of that colour. The widget's scroll view is clear (the content is Flutter's, behind it), so the system had no colour: the effect was only a light blur, and hard looked the same as soft. The widget now gives UIKit the colour of the page behind it.
- New
backgroundColor: the colour of the content under the edge. It defaults to theCupertinoTheme's scaffold background colour; a transparent colour leaves only the blur. softblurs the content under the band and fades it toward that colour, as under a navigation bar with a title, and is gone just past the band. Over dark content the system darkens the band instead, as it does in a native table.hardis an opaque band of that colour, ending in a sharp line.- The view is 48 pt taller than the band (24 before), so the end of the effect isn't cut off.
Thanks to @Ashhad08 for the comparison with the App Store.
Checked #
- #156, iPhone 17 Pro Max simulator, iOS 26.2, the reporter's repro app (
modal_bottom_sheet3.0.0,CupertinoScaffold), frame by frame: dragging the sheet down 350 pt and holding it, the headerCNButtonand aCNPopupMenuButtonnext to it keep their full glass while the page moves, while held and after release (flat before); no box on any frame (before the fix, about half of the frames of a moving page showed one when not flattened); the sheet opening and closing, a dialog elsewhere fading in and out and a half-heightshowModalBottomSheetthe same. - #156, iPhone 17 simulator, iOS 27.0: the same drag and hold, no box on any frame.
- #150, against a UIKit table under a navigation bar with a title and glass buttons, same rows and scroll offset: iOS 26.2
softandhard, and iOS 27.0hard, match the native screen (the rows under the bar blurred and faded, the row below it sharp; the hard band and its line in the same place). On iOS 27.0, nativesoftreaches about 30 pt further below a bar with glass buttons than the widget does; under the band they match. A dark row under the band darkens it, natively too. A colour changed at run time reaches the effect. - Tests: 2 new tests for #156 and 1 for #150, 2 rewritten; 624 tests pass; the new #156 tests fail on 2.7.0.
2.7.0 #
New:
CNScrollEdgeEffect, the iOS 26 scroll edge effect over Flutter content (#150), andCNTabScaffold.bottomScrollEdgeEffect. Fixed: glass widgets withautoHideOnModal: falseflat under a sheet from a sheet package, or while a dialog elsewhere fades in or out (#156).
New — CNScrollEdgeEffect (#150) #
The soft blur native apps get where content scrolls under the status bar, a bar or the home indicator, over Flutter content. Flutter content isn't in a UIScrollView, so the widget is a clear platform view with a scroll view of its own, its top or bottom edge effect on, and a UIScrollEdgeElementContainerInteraction that shapes the effect to the band. iOS draws the effect over the Flutter content behind the view: it is the system's own (UIScrollEdgeEffect, public API only), so it matches native apps and follows accessibility settings.
edge(top or bottom),height(the band; by default the safe area on that edge),style(softorhard),brightness.- With a
controller(orscrollMetrics), the effect shows while content is under the edge and is gone at rest, as in a native scroll view. iOS switches it on as soon as content is under the edge; it doesn't fade in with the offset. - It places itself at its edge and lets touches through to the content.
CNTabScaffold(bottomScrollEdgeEffect: true)puts it behind the tab bar, following the body's scroll view.- iOS 26 and later; elsewhere it draws nothing.
Thanks to @Ashhad08 for the request and its precise requirements.
Fixed — glass flat under a sheet package's sheet, and while a dialog fades (#156) #
Glass widgets with autoHideOnModal: false (CNButton, CNPopupMenuButton, CNGlassButtonGroup, LiquidGlassContainer, CNSearchBar, CNFloatingIsland):
- Under a sheet from a sheet package they stayed flat (no rim or shadow) for as long as the sheet was open, even with the sheet nowhere near them. The package wraps its sheet in a full-screen
OverlayPortaland gesture detector, whichCNTabBarRouteObserverdidn't know paint only their child, so it measured the sheet as the whole screen. It now measures the sheet itself, and the widget keeps its full glass while the sheet is up, dimmed like the rest of the page. - While a dialog, popup or sheet elsewhere fades in or out, or slides, their shadow and rim dropped out and came back once it stopped. Where the modal is now decides while it moves too, so they keep their full glass. They are still contained while the modal comes within reach of their glow (its bounds lead its motion by a frame), and while a sheet moves the page under it, as sheet packages that scale the page down do.
Thanks to @Ashhad08 for the report, the repro app and the recordings.
Checked #
- #156, iPhone 17 Pro Max simulator, iOS 26.2, with the reporter's repro app: under the package's sheet, full glass at rest (flat before), contained while the sheet scales the page; through a dialog's fade-in, rest and fade-out, the shadow stays on every frame (it dropped out before); the same with a half-height
showModalBottomSheet. - #156, iPhone Duo simulator, iOS 27.1, Flutter 3.47.9 (where #124's box showed): with no containment while a dialog fades, there is no box around the button, frame by frame at 10× slow motion; a dialog over the button still contains it.
- iPhone 17 Pro Max simulator, iOS 26.2: text under the top band (status bar included, full width) and the bottom band blurred, measured against the same frame without the effect; nothing at rest at the top or at the end of the list; soft and hard; light and dark; behind
CNTabScaffold's tab bar. - iPhone 17 simulator, iOS 27.0: the same; there the system already softens content under the status bar, and the effect extends it to the band.
- Tests: 12 new tests (7 for
CNScrollEdgeEffect, 5 for #156); 621 tests pass.
2.6.0 #
CNButtonlabels that change often (#154) and label colours for light and dark glass (#153). New:CNButtonConfig.animateSizeChanges,labelColorLightandlabelColorDark(also onCNPopupMenuButton). Fixed: vertical padding, and a tint or style change that dropped the label's font and padding.
Fixed — a new label drawn for a frame at the old width (#154) #
With shrinkWrap: true, a new label was shown at once inside the old width, so a wider one was truncated for a frame ("8/…"), and the width followed a frame later. A new button also started at an 80 pt placeholder. The new label is now measured first and set in the layout pass that gives the button its width, as CNPopupMenuButton does since 2.5.2. A button that hasn't been measured yet stays hidden until it has its size, and measured sizes are remembered, so a button built again with a label it had before starts at its size. The same applies on macOS. CNPopupMenuButton now also holds a new label for a width change of less than half a point, which could still wrap it for a frame.
New — animateSizeChanges (#154) #
CNButtonConfig(animateSizeChanges: true) eases the button to its new size instead of jumping (sizeAnimationDuration, 200 ms by default, and sizeAnimationCurve, Curves.easeOut). The new label shows at once and stays whole while the glass grows around it. On macOS, a wider label waits until the button is wide enough for it.
Fixed — vertical padding (#154) #
Only the horizontal values of CNButtonConfig.padding reached the UIKit button. The top and bottom values now apply to a button with a label, and its height grows to fit the label and that padding (at least minHeight, or 44). A side left at 0 keeps the style's inset, as before. On macOS the padded height is used as well, and a horizontal padding smaller than the bezel's own inset no longer truncates the label.
New — label colours for light and dark glass (#153) #
labelColor is one colour on light and on dark glass. labelColorLight and labelColorDark set one colour each, and the label switches with the glass, as the default label does when Liquid Glass takes a light or dark appearance from what is behind it. A side without its own colour keeps labelColor, else the style's. CNButton and CNPopupMenuButton both take the pair. On macOS the glass keeps the window's appearance, so the pair follows light and dark mode.
Fixed — a tint or style change dropped the label style #
Changing CNButton.tint or its style rebuilt the button's configuration without the label's font, line break and image placement, or its padding: a 14 pt label went back to 17 pt and could wrap onto two lines. They are now kept.
Thanks to @Ashhad08 for both reports and their frame-by-frame traces.
Checked #
- iPhone 17 Pro Max simulator, iOS 26.2: a shrink-wrapped counter recorded through two cycles of labels and three rebuilds, with and without
animateSizeChanges(no frame with a truncated label or at the old width; the animated one eases); vertical padding 4 and 20; a tint change keeps a 14 pt label; badges withlabelColorLight/labelColorDarkand a popup menu button on dark, light and switching backgrounds (the light side is the exact colour set, the dark side too, switching with the glass); the #147 header unchanged. - iPhone 17 simulator, iOS 27.0: the same counter recordings and screens.
- macOS: vertical padding, the tint change and the label colours.
- Tests: 8 new tests; 608 tests pass.
2.5.2 #
Three fixes: glass widgets under bottom sheets (#149), the
CNPopupMenuButtonlabel frame left over from 2.5.1 (#147), and tap to seek on a thumblessCNSlider(#151).
Fixed — glass widgets under bottom sheets, whichever API opened them (#149) #
Only sheets opened through CNBottomSheet told the CN-widgets where they were, so with showModalBottomSheet, showCupertinoModalPopup or a sheet package every glass widget on the page disappeared while the sheet was up, wherever it was, and one with autoHideOnModal: false was clipped flat for as long as the sheet was up. CNTabBarRouteObserver now measures where the sheet, popup or dialog of any modal route is, after every frame while it is up. A widget the sheet covers is removed as before. One it doesn't cover stays up with its full Liquid Glass, dimmed by the barrier like the rest of the page. Its glow is clipped only while the modal fades in or out or is dragged (#124), or while the sheet is within reach of it. CNSheetGeometryProbe is now only needed for a sheet that isn't a route.
Fixed — CNPopupMenuButton label drawn at the wrong width for a frame (#147) #
Since 2.5.1 a new label changes in place, but it reached the screen one frame before the new width, so a longer label wrapped onto two lines for that frame. A new button also showed one frame at the 80 pt placeholder width ("New / est"). The new label is now measured first and set in the same layout pass that applies its width. A button that hasn't been measured yet stays hidden until it has its measured width. Measured widths are remembered, so a button built again with a label it had before (a row rebuilt while a list reloads) takes its width from its first frame. The same applies on macOS.
Fixed — tap to seek on a thumbless CNSlider (#151) #
seekOnTap mapped a tap between the thumb's centres at the minimum and the maximum, and a thumbless slider still reports a thumb about 37 pt wide although it draws none, so taps landed too far towards the ends (75% of an 88 pt slider gave 0.93). A thumbless slider now maps taps across its track.
Thanks to @Ashhad08 and @cogwheel0 for the reports and their precise traces.
Checked #
- iPhone 17 Pro Max simulator, iOS 26.2: the results header from #147 recorded through four label changes and three rebuilds of the row (no frame with a wrapped label or a placeholder width; a rebuilt row keeps its place); glass close buttons under
showModalBottomSheet,showCupertinoModalPopupandCNBottomSheet.showModalPopup(both stay up with their shadow; before, one disappeared and the other was flat). - iPhone Duo simulator, iOS 27.1: the same sheets recorded frame by frame, with and without the old clipping: no box around unclipped glass under the barrier as a sheet fades in, rests or leaves, and none around the #124 dialogs.
- iPhone 17 simulator, iOS 27.0: tap mapping of thumbless sliders of 88 and 240 pt (25%, 50% and 75% map to 0.25, 0.50 and 0.75; a slider with a thumb is unchanged).
- macOS: the #147 header through the same label changes and rebuilds.
- Tests: 4 new tests and 14 more containment cases; 600 tests pass.
2.5.1 #
Two fixes:
CNTabRailunder a pushed page (#146), andCNPopupMenuButtonlabel changes (#147). New:CNTabRail.autoHideOnPageTransitionandautoHideOnModal, on by default.
Fixed — CNTabRail under a pushed page and under modals (#146) #
The rail had none of the page and modal handling the other glass widgets have, so while a page was pushed over the rail's page, its glass edge was drawn over the incoming page. The rail now stops drawing while its page is pushed over, popped back to or covered by another page, as CNTabBar does (autoHideOnPageTransition, on by default): its platform view stays alive, so it is there again at once after the pop, but it draws nothing and takes no touches meanwhile. Under a modal its platform view is removed and created again afterwards (autoHideOnModal, on by default), and with either option off its glass is clipped to its own box while it could show. CNTabScaffold's rail gets this too.
Fixed — CNPopupMenuButton label changes (#147) #
A new buttonLabel (or a new item label) created the native button again: it vanished for a frame and its row jumped through several widths. The label now changes in place, and the button is measured again once. Found while checking it: measured in place, a configuration button's width followed its old title, so a longer label wrapped onto two lines; it is now measured at its natural width. While a button is first prepared, its space keeps the width it will take.
Thanks to @LucasLau00 and @Ashhad08 for the reports.
Checked #
- iPhone Duo simulator, iOS 27.1: the rail during a push and a pop (recorded: no glass over the incoming page, against the edge lines drawn before), the rail back after the pop; the results header changing its sort label four times ("Save" takes one position per change, none in between, and no label wraps).
- Tests: 3 new tests; 582 tests pass.
2.5.0 #
Eleven reports, from @cogwheel0 (#134 to #140) and @Ashhad08 (#141 to #144), all fixed or added. New: fonts from
pubspec.yamlon native views, right to left from Flutter, label styles for popup menu buttons and segmented controls, fonts for alerts and action sheets, a lifted preview for context menus, popover gauges, tap to seek, and a test switch for the Flutter fallbacks. Three behaviour changes, listed at the end.
Added — fonts from pubspec.yaml on native views (#142) #
A font family declared under fonts: in pubspec.yaml is a Flutter asset that UIKit and AppKit don't know, so labelFontFamily: 'Nunito' silently fell back to the system font. The native views now find the family in Flutter's font manifest and register its files with the system the first time it is used, then pick the face nearest the weight asked for. It works for CNTabBar, CNButton (CNButtonConfig.labelFontFamily), CNPopupMenuButton, CNSegmentedControl, CNAlert and CNActionSheet, on iOS and macOS. A weight now applies together with a family too. A family found nowhere logs one line in debug builds.
Added — right to left from Flutter (#142, #143, #144) #
UIKit lays views out by the app's language, which an app that switches language in Dart never tells it about, so an Arabic app had a left-to-right native tab bar. CNTabBar, CNSegmentedControl, CNAlert and CNActionSheet now take the ambient Directionality (or their new textDirection): the first tab or segment is on the right, badges and split halves are mirrored, and an alert's title and message align right with its buttons mirrored. On macOS the tab bar, the segmented control and the alerts follow it too.
Added — CNTabBar.labelFontWeight and selectedLabelFontWeight (#142) #
The selected tab can be heavier than the others, as on the system bar: by default a custom family gets the system's medium and semibold (its nearest faces). A family whose glyphs sit higher in their line than San Francisco's (many fonts with Arabic glyphs) is moved down to sit where the system label would, instead of over the icon.
Added — label style and label updates for CNSegmentedControl (#143) #
labelFontFamily, labelFontSize, labelFontWeight, labelColor, selectedLabelFontFamily, selectedLabelFontWeight and selectedLabelColor style the segment titles of that control only, and change without recreating it. New labels or sfSymbols now reach the control in place, keeping the selected segment, so a language switch updates the titles. On macOS a segmented control has one font for all segments and no title colours, so there the family, size and weight apply to every segment.
Added — fonts and direction for CNAlert and CNActionSheet (#144) #
fontFamily draws the title, the message and the buttons in that family at the sizes and weights the system gives them (the preferred button stays bold, a destructive one red); titleStyle, messageStyle and actionStyle (CNDialogTextStyle) override a part's family, size, weight or colour. The font stays on while a button is pressed and while the dialog closes. textDirection sets the direction, by default the ambient Directionality. On macOS the title and message take the font and the direction and the buttons are mirrored; AppKit draws an alert's buttons itself, so they keep the system font. The Flutter fallbacks take the same styles.
Added — CNPopupMenuButton: icon with label, label style, callbacks (#141) #
- A text button can show
buttonIcon,buttonCustomIconorbuttonImageAssetnext to its label, placed byimagePlacement(leading, trailing, top, bottom) withimagePadding. An SF Symbol at the default size takes the label's size. labelFontFamily,labelFontSize,labelFontWeightandlabelColorstyle the label. A native menu has no font setting, so the menu's items keep the system font.onOpenedandonClosedare called each time the menu shows and closes, with or without a choice; the fallback sheet calls them too.keepsSourceVisible(iOS 26+) leaves the button out of the menu's morph: the menu grows out of a clear stand-in at the button's place, so the button is not hidden into the menu and is there again the moment the menu closes. The menu still opens over the button's place.
Added — CNContextMenu.showsPreview (#138) #
On iOS, a long press lifts a picture of the child above the dimmed screen with the menu beside it, as a system context menu does in Photos or Messages, and settles it back when the menu closes. A menu opened from code is a button menu, which UIKit never shows with a preview, so a clear native view with a UIContextMenuInteraction is laid over the child; a tap still reaches the child. Each such region is a platform view. previewCornerRadius matches the child's corners.
Added — popover gauges, and failures you can tell from a dismissal (#135) #
CNPopoverContent.gauges(CNPopoverGauge) shows labelled native bars under the message, such as storage used: the label and a value text over a SwiftUIProgressView, read by VoiceOver as one element.- A popover that can't be shown returned null, like a cancel. With
throwOnFailure: true,CNPopover.showthrows aPlatformExceptioninstead (no_anchor,refusedwhen UIKit didn't present it, or the native code), so the app can fall back to another UI.CNAlert.showandCNActionSheet.showtake the same option. Without it nothing changes.
Added — CNSlider tap to seek, onChangeStart and onChangeEnd (#137) #
seekOnTap: true(iOS 26+) moves the value to a tapped point, as a media scrubber does; a thumbless slider had no way to pick a point.onChangeStartandonChangeEndare called when a drag or a tap starts and ends, on iOS, macOS and the fallbacks, so a scrubber can seek once when the finger lifts.
Added — PlatformVersion.debugForceFallbacks (#139) #
flutter test runs on the host machine, and on a Mac a test that targets iOS still got the native views. Set this in a test that checks a fallback, and PlatformVersion.reset() afterwards.
Fixed — CNSearchBar (#134) #
- The iOS 26 bar is created again after a modal (
autoHideOnModal), and came back empty and collapsed while the app still filtered by the old query. It now comes back with its text and expanded state, on macOS too. - New
textCapitalization,autocorrectandkeyboardType; the fallback field takes them too. - VoiceOver read the clear button as "Close", the name of its symbol. It now reads
clearButtonSemanticLabel, by default the localized "Clear". searchIconandclearIconwere drawn at 16 pt whatever theirCNSymbol.size. They now take it, and follow Dynamic Type like the field's text.- Cancel on a bar with
expandable: falseleft the text in the field. It now clears it and reports"".
Fixed — CNSlider repeats the value (#137) #
A touch that ended without moving sent the value the slider already had to onChanged, so an app that seeks there seeked to where it already was. A value the app already has is no longer reported.
Fixed — CNTabBar height and the bar with a search tab (#136) #
- A bar created with a
heightthat later became null never measured itself and stayed at the 50 pt fallback. It now measures itself again whenheightchanges. - The bar with a
searchItemdrew only SF Symbols and labels. Its items now show image assets, custom icons, icon sizes, badges (dots too) and names as on a bar without search, its search tab drawsCNTabBarSearchItem.icon,activeIconand the style's icon size and colours, andactivateSearch()shows the search tab selected. - The docs said the search tab expands into a search field. On iOS 26 it is the system search tab at the end of the bar, which reports that search is active so the app can show its own search UI; for the system search field in the tab bar, use
CNTabBarNative.
Fixed — CNTabBarItem.semanticLabel on iOS 27 (#140) #
iOS 27.1 no longer copies a tab item's accessibility label to the tab buttons VoiceOver reads, so icon-only tabs were unnamed again. The bar now names its tab buttons itself after each layout, the selection lens's copies too.
Thanks to @cogwheel0 and @Ashhad08 for detailed reports, each with the cause in the code.
Behaviour changes #
- Direction: the native tab bar, segmented control, alerts and action sheets now follow Flutter's
Directionality, not the system's language. They differ only in an app whose Flutter direction and system direction differ; passtextDirectionto keep a fixed one. CNSearchBar.textCapitalizationdefaults to none, as for the system search fields and the Flutter fallback. The native field capitalized sentences before.CNPopupMenuButton.isIconButtonis now true only for the round button ofCNPopupMenuButton.icon; a text button with an icon is not one.
Checked #
- iOS 27.0 simulator: each issue's new screen in the example's Testing list. The search bar after a dialog (text and expansion kept), the 24 pt icon and Cancel; popover gauges and a refused popover; the bar's height after
heightgoes to null (60 to 97 pt) and the search bar's images, badges, icon andactivateSearch(); tap to seek (one change, with start and end); the context menu's lifted preview (choice and taps on the child); the popup menu button's icon with label, Tajawal label, callbacks andkeepsSourceVisible(a recording shows no frames without the button when the menu closes, against six without it); the tab bar in Tajawal and in Arabic; the segmented control's labels switching to Arabic in place; the alert in Tajawal and right to left, through a press and its closing. - iOS 27.1 simulator (iPhone Duo): the tab buttons' VoiceOver names, unnamed without the fix and named with it.
- macOS 27: the segmented control's labels switching to Arabic in place, right to left, and the alert in Tajawal and right to left (title and message; buttons mirrored).
- Tests: 14 new tests; 579 tests pass.
- Analyzer and SDKs:
flutter analyzeis clean with Flutter 3.44, andflutter analyze libwith 3.38. The iOS code compiles against the iOS 26.0 and 26.2 SDKs, the macOS code against the macOS 26.5 SDK.
2.4.0 #
Seven reports from @cogwheel0, all fixed or added, plus three bugs found while checking them. New: read-only popover rows, tab bar action items and accessibility names for tabs. Nothing changes for existing code.
Added — CNTabBarItem.onPressed: an item that runs an action (#131) #
An item with onPressed, such as Compose, runs it and is never selected: the selected tab stays as it is, onTap is not called and no selection highlight grows on the item. In a split bar (split: true, rightCount: 1) a single action is the right-hand capsule, as in iOS 26 apps. VoiceOver reads it as a button, not a tab.
A standalone UITabBar selects an item before it tells anyone, so a clear button over the item now takes the tap, and the bar's own selection gesture sits that touch out. Reached another way (VoiceOver, or a finger sliding along the bar onto it), the bar puts its selection back and runs the action, as items with menus do. The macOS bar and the Flutter fallback run the action without selecting too.
Added — CNTabBarItem.semanticLabel, and height for icon-only bars on iOS 26 (#132) #
semanticLabel is the name VoiceOver reads for a tab, so an icon-only tab gets one without a visible title. On iOS it is the item's accessibilityLabel; on macOS the description of the tab's image.
A bar given a shorter height keeps its own height on iOS 26, as a squeezed iOS 26 bar puts its labels over its icons. A bar with no labels has nothing to squeeze and now uses the given height there too, as on iOS 27: with height: 89, the platter is 54 pt instead of about 61 pt.
Added — CNPopoverRow.readOnly (#129) #
A read-only row only shows information, such as a label and its trailingText value. It is not a button: a tap on it keeps the popover open, it is drawn at full strength, and VoiceOver reads it as text ("Prompt, 1,204") rather than as a button.
Fixed — CNSearchBar controller on iOS (#126) #
On the iOS 26 search bar, setText, clear, focus and unfocus did nothing, and neither did expand and collapse. All six now work as they do on macOS: setText and clear report the new text through onChanged, expand and collapse through onExpandStateChanged (collapsing also clears the text and ends editing), and focus opens a collapsed bar before it brings up the keyboard. Each change is reported once.
Fixed — presenting something from a CNPopover result (#127) #
CNPopover.show completed while the popover was still animating away, so an app that opened a browser, a share sheet or an alert from the result did it too early, and UIKit dropped it. The call now completes once the popover has gone.
Found while checking it: CNAlert.show and CNActionSheet.show could present on a controller that was being dismissed, so the alert never appeared and the call never completed. They now wait for the controller to leave (closing a popover from code and showing an alert at once works), and a presentation UIKit refuses ends the call instead of leaving it waiting.
Fixed — CNFloatingIsland changes after creation (#128) #
The sizes (collapsedHeight, collapsedWidth, expandedHeight, expandedWidth), cornerRadius, tint and the spring reached the native island only when it was created. They now update it, animated and without recreating the view. The iOS 26 glass also shows the tint now; it ignored it before.
Found while checking it:
- A change of
isExpandedby the app never reached the native island; only the controller'sexpand()andcollapse()did. It now opens and closes the island. onExpandStateChangedwas called during the parent's build whenisExpandedchanged, so an app that mirrored it withsetStatehit an assertion. It is now called after the frame.
Fixed — CNIcon replace transition with a colour change (#130) #
When the symbol and its colour changed in the same build, the replace transition was cut off and the new symbol appeared at once. The change now goes out in one update, so the transition plays and ends on the new symbol in the new colour.
Fixed — popover separators with mixed icons (#129) #
When some rows had a leading icon and others didn't, the rows without one started their text at the edge, left of the separators. Every row now keeps the icon column, so all titles line up with the separators. On macOS too.
Thanks to @cogwheel0 for seven precise reports, each with the cause in the code.
Checked #
- iOS 27.0 simulator: each issue's new screen in the example's Testing list. Search bar controller calls; popover → alert at once, popover closed from code → alert, and popover → popover; floating island size, tint, corners, width and collapse; popover rows (VoiceOver roles and taps); icon replace (25 animated frames on every toggle, as the control); the action item (no change in the bar while Compose runs, tabs still switch) and the tab buttons' VoiceOver names and traits.
- iOS 26.2 simulator: the icon-only bar at
height: 89, and the action item. - macOS 27: the action item and the popover rows.
- Tests: 10 new tests; 564 tests pass.
- Analyzer and SDKs:
flutter analyzeis clean with Flutter 3.44, andflutter analyze libwith 3.38. The iOS code compiles against the iOS 26.0 and 26.2 SDKs, the macOS code against the macOS 26.5 SDK.
2.3.2 #
Patch:
CNTabRailnow changes tabs when you press and slide, and glass widgets withautoHideOnModal: falseno longer show a box through a dialog's barrier. No API changes.
Fixed — CNTabRail: press and slide to change tabs (#123) #
On the system vertical bar (iPhone Duo's outer display, and its inner display in landscape) you can press a tab and slide to another; the selection follows your finger. CNTabRail, which CNTabScaffold puts in that bar, reacted only to taps.
The rail now works like the system bar:
- the highlight follows your finger, and the tab under it is selected when you lift your finger;
- released far from the rail, the press selects nothing;
- at accessibility text sizes, a long press shows the item in the Large Content Viewer, and lifting your finger selects it.
VoiceOver still reads each tab as a button with its badge and selected state. The sidebar style stays tap-only, like the system sidebar.
Fixed — a box around glass widgets with autoHideOnModal: false under a dialog (#124) #
While a dialog faded in over a glass CNButton with autoHideOnModal: false, a lighter box could show around the button: its Liquid Glass glow, unclipped (the #29 artifact). The glow is clipped to the view while it could show past it, but only during page transitions, and a dialog doesn't start one. With the default autoHideOnModal: true the view is removed under a modal, so only widgets that opted out were affected.
For widgets with autoHideOnModal: false, the glow now also stays clipped from a modal's push until its exit animation ends. This covers dialogs, popups and sheets. Like autoHideOnModal, it needs CNTabBarRouteObserver() in navigatorObservers.
The fix covers all six widgets that clip their glow, which now share one implementation: CNButton, CNPopupMenuButton, CNGlassButtonGroup, LiquidGlassContainer, CNSearchBar and CNFloatingIsland.
Thanks to @LucasLau00 for both reports. #124 came with the root cause and a fix tested on a device, which this release applies to all six widgets.
Checked #
- iPhone Duo simulator (iOS 27.1): taps, press and slide, hold then slide, release far from the rail, the Large Content Viewer at accessibility text sizes, VoiceOver activation, and taps in the sidebar style.
- iOS 26.2 simulator: the example's new #124: Button halo under dialog screen at 10× slow motion. The button dims evenly and looks the same as before at rest. The box itself shows only on a physical device, where the reporter tested the same approach.
- Tests: 23 new tests for the clipping cover all six widgets, dialogs, page transitions and a dialog over a dialog. 554 tests pass.
- Analyzer and SDKs:
flutter analyzeis clean with Flutter 3.44, andflutter analyze libwith 3.38. The iOS code compiles against the iOS 26.0 to 27.0 SDKs.
2.3.1 #
Patch: the repository and the published package no longer contain files that Flutter, Xcode and FVM generated on the maintainer's machine, and every pull request now runs CI. Nothing changes for apps that use the package: no API, native or visual changes.
Fixed — generated files with machine paths were committed (#121) #
The repository tracked 20 generated files:
- the example app's
Generated.xcconfig,flutter_export_environment.sh, plugin registrants andFlutter/ephemeral/files; - the
ios/.symlinks/and.fvm/links; - an Xcode user-state file.
Six of them held paths from the maintainer's Mac and four were symlinks into it. A fresh clone therefore got dangling links and settings that pointed to a Flutter install that wasn't there, and git status showed changes after every build.
These files are no longer committed. Flutter recreates them on flutter pub get and flutter run. The example app now has Flutter's standard iOS and macOS .gitignore files, and the Flutter version pin is in .fvmrc.
The example's macOS scheme now includes Flutter's Swift Package Manager pre-action, as the iOS scheme already did. Before, a clone's first macOS build changed the scheme.
The published package no longer includes the example's ios/Flutter/ephemeral/ folder, one file of which held a machine path.
Thanks to @runoob-coder for #121. It keeps the analyzer out of build/, ios/ and macos/, and it led to this fix.
Added — CI #
Every pull request now runs these checks:
flutter analyzeon the package and the example app,dart formatandflutter test;flutter analyze libwith Flutter 3.38, so the package keeps working on older Flutter versions;- a check that fails if a generated or machine-specific file is committed.
Checked #
- Fresh clone. It ran
flutter pub get, built the example for the iOS simulator and for macOS, and ranflutter analyze.git statuswas clean after every step. - Tests and analyzer. All 531 tests pass.
flutter analyzeis clean with Flutter 3.44, andflutter analyze libis clean with Flutter 3.38. - Dry run.
flutter pub publish --dry-runshows 0 warnings; 2.3.0 had 1, for these files.
2.3.0 #
The Mac window goes native, and five new controls. On macOS,
CNTabBarNativebecomes the window's sidebar,CNNativeSheetits inspector and the newCNToolbarits toolbar, around your unchanged Flutter content. New on both platforms:CNPopover,CNPopUpButton,CNGauge,CNToolbarandCNSidebar. Fixes #120 and four older bugs. Checked on macOS 27.2 and on the iOS 27 and 26.2 simulators, touches included; code that only runs on macOS 12–26 was reviewed, not run. Compiles with every Xcode from 26.0 on.
Added #
CNPopover: a native popover that points at a widget or a rect.NSPopoveron macOS; a UIKit popover on iPhone and iPad (it stays a popover on iPhone instead of becoming a sheet); Liquid Glass on 26. Its content is native and described by data: a title and message,CNListItemrows with a checkmark for choice lists, switches that report changes while it stays open, and default, cancel and destructive buttons.showreturns the chosen id, or null when it is dismissed;updateanddismisschange or close it. It follows its anchor, closes on navigation and on hot restart, and VoiceOver treats it as modal. Escape and Return work on macOS. Flutter widgets cannot go inside it.CNPopUpButton: the native pop-up button, a value picker that shows the current choice.NSPopUpButtonon macOS; on iOS 26 a button whose menu selects one item. SF Symbol and image-asset items, dividers, titled sections, disabled items, theCNButtonstyles (glass on macOS 26 and iOS 26), a controlledvalueand the native width.CNGauge: the native gauge, a level indicator on macOS. Capacity, discrete capacity, relevancy and rating onNSLevelIndicator; linear and circular SwiftUIGaugestyles on both platforms. Warning and critical zones, tick marks (macOS), labels, and an editable star rating that VoiceOver can adjust. A gauge that only shows a value lets taps through to the row under it.CNToolbar: the Apple toolbar. On macOS it puts anNSToolbaron the window while the widget is mounted (unified, unified compact or expanded, with the window title and subtitle): buttons with badges and the prominent style on macOS 26, segmented groups, menus, a search field (NSSearchToolbarItem), spaces, and the sidebar and inspector toggles while the window has a sidebar or inspector. The widget takes no room; the window keeps its frame and gets its own toolbar back when the widget goes away. On iOS 26 it is a Liquid Glass bottom toolbar with grouped items (toolbar badges need iOS 27). Items update in place.CNSidebar: a native sidebar list in your own layout: SwiftUIList(.sidebar)on macOS, on Liquid Glass on 26, with sections, symbols, images, badges and selection. On iOS it draws aCNTabRailsidebar.
macOS — the window #
CNTabBarNativeturns the window into a native split view: the tabs become sidebar rows with symbols, badges and selection, beside your Flutter content, which is moved, not recreated. The search tab is the sidebar's search field, and a tab with aCNNativeListshows that list instead of the Flutter content. Same API and callbacks as on iOS; View › Show Sidebar (⌃⌘S) is added.disable()gives the window back as it was.bottomAccessoryandminimizeBehaviorhave no Mac counterpart and are ignored.CNNativeSheet.showopens the window's inspector with the same pages, a segmented page switcher and a close button whendismissible; it returnstrueon macOS now. Detents have no Mac meaning. The sidebar and the inspector work together.CNTabRailandCNTabScaffolddraw a native sidebar on macOS instead of a Flutter one.CNSearchScaffoldputs its tabs and its search field in the window toolbar.- Typing, scrolling, right-clicks and full screen keep working in Flutter content inside the split view, and the window comes back as it was after a hot restart.
Fixed #
- #120:
CNSegmentedControlfollows a press-and-drag across segments. Its platform view declared no gesture recognizers, so inside a scrolling list Flutter's gesture arena kept every drag and the control only got taps. Taps and horizontal drags now go to the native control, on iOS and macOS; a vertical drag that starts on it still scrolls the list. Thanks to @LucasLau00 for the report and the fix. CNTabBarNative: popping its page in code left the bar on screen. The bar was presented full screen, which takes the Flutter view out of the window; Flutter then drew no frames, so the page's exit animation never finished and itsdispose(with itsdisable()) never ran. The bar is now presented over the Flutter view and looks the same. The home indicator now follows your app's setting, as on your Flutter screens (Flutter hides it after a few seconds unless the app setsSystemUiMode.edgeToEdge). The bar is marked modal for VoiceOver, so the page under it stays out of reach.- iOS
CNSearchScaffoldshowed an empty tab bar on iOS 26 and 27. Its fallback tab bar also shows each item's symbol instead of a placeholder circle. Selecting the search tab in code (currentIndex) now opens the search field with the keyboard, as a tap does: UIKit never did this on iOS 26 and not reliably on iOS 27.CNTabBarSearchController.activateSearch()brings up the keyboard too. - macOS: a popover or toolbar no longer stays on the window after a hot restart.
Changed #
CNTabBarNative.enable(isDark: null)follows the system appearance on macOS; on iOS it stays light, as before.CNTransitionObserveris exported from the package library. It was public and documented, but only reachable through its own file.
Checked #
Each new control was checked on macOS 27.2 in light and dark, and on the iOS 27 and iOS 26.2 simulators, with real touches on iOS: popover rows, switches, buttons and outside taps; pop-up selection, press-and-drag and scrolling; the editable rating; toolbar segments, menus and badges; the segmented control's press-and-drag. The Swift code was compiled against the iOS 26.0, 26.1, 26.2, 26.4, 26.5, 27.0 and 27.1 SDKs and the macOS 26.5 and 27.2 SDKs, each with its Xcode's Swift version. The Dart code was analyzed and tested with Flutter 3.38 and 3.44, and every page of the example app was compared with 2.2.1 on macOS, iPhone and iPad.
2.2.1 #
Patch: the iOS part of the package compiles with every Xcode from 26.0 on again (#119). No API changes, no visual changes.
Fixed — #119 CNNativeSheet.swift still failed to build with Xcode 26 #
2.1.2 moved one cause of the #119 error, but archiving with Xcode 26 then stopped at the sheet's toolbar buttons: "No exact matches in call to static method 'buildExpression'". The buttons were a ForEach of toolbar items, and only the iOS 27 SDK (Xcode 27) has a ForEach that takes toolbar items. The buttons are now one toolbar item group with the ForEach inside it, which every SDK accepts. They share one glass capsule as before: with no, one and two buttons the sheet is pixel-identical to 2.2.0 on the iOS 27 simulator, and with two buttons on iOS 26.2.
Fixed — CNTabBarNative failed to build with Xcode 26.1 #
The bottom accessory used tabViewBottomAccessory(isEnabled:) whenever the compiler was Swift 6.2.1 or newer, but that API first ships in the iOS 26.2 SDK, so Xcode 26.1 stopped with an error. Xcode 26.2 and 26.3, whose compiler reports Swift 6.2, skipped it and showed the empty accessory pill that #93 fixed. The check now asks for the SwiftUI version of the iOS 26.2 SDK instead. Apps built with Xcode 27 are unaffected.
Checked #
The package's iOS Swift code was compiled against the iOS 26.0, 26.1, 26.2, 26.3, 26.4, 26.5, 27.0 and 27.1 SDKs, each with its Xcode's Swift version, and the macOS code against the macOS 26.5 and 27.2 SDKs. All compile. Xcode 16 was never supported (the package uses iOS 26 APIs throughout), and the App Store needs Xcode 26 anyway; the README now says so.
2.2.0 #
macOS goes native. Every control that has an AppKit counterpart now uses it on every supported macOS (12 and later), not only on macOS 26: buttons, pop-up buttons, sliders, switches, steppers, date pickers, colour wells, segmented controls and the tab bar. Alerts are window sheets, action sheets are menus, search bars are search fields, and image assets and SVGs draw on macOS. New:
CNContextMenu(right-click on macOS, long press on iOS) andCNProgressIndicator. Fixes the macOS hang in #47. Checked on macOS 27.2 and on the iOS 27 and 26.2 simulators; code that only runs on macOS 12–26 was reviewed and forced on macOS 27, not run on those versions.
Fixed — #47 the example hung on macOS with a debugger attached #
Some widgets sent the macOS view a method it did not implement (setSemanticLabel, setInteraction, setLabelStyle, the tab bar's search calls) without awaiting the call. The resulting MissingPluginException was uncaught, and a debugger that breaks on uncaught exceptions (the IDE default) paused the UI isolate. On macOS the UI isolate runs on the main thread (merged platform and UI threads), so the whole window stopped with a spinning cursor and no error. With FLTEnableMergedPlatformUIThread off the window kept answering but the Flutter content froze, which is why the workaround looked broken. Calls a platform may not implement now treat a missing implementation as "not supported here", the macOS views implement the missing methods, and macOS answers the beginTransition / endTransition calls CNTransitionObserver sends on every route change. A test now checks that every call a widget sends has an answer on macOS.
macOS — native controls on every macOS #
CNButtonandCNPopupMenuButtonare AppKit buttons on every macOS. An icon-only button is a circle and a button with a title a capsule; before, every button was drawn as a 44 pt circle with its title spilling out. On macOS 26 the glass styles use the glass bezel, prominent stylesbezelColorwithtintProminence, and every styleborderShapeand acontrolSizethat follows the height;clearGlassis a borderless button in clearNSGlassEffectView. Before macOS 26 they use the push and circular bezels.labelColor, font size, family and weight apply. AppKit glass takes its look from the window's appearance, not from what is behind it: over a photo, setlabelColorand icon colours.CNSlideris anNSSlider: tick marks fornumberOfTicks,tickValuesandstep,neutralValueon macOS 26, and its colour from the first frame.CNStepper,CNDatePicker,CNColorWell,CNSegmentedControluse their AppKit controls on every macOS, andCNSwitcha SwiftUI toggle that draws the AppKit switch.CNSegmentedControl.colortints the selection and symbol colours apply;CNDatePickercompact is the date field with a calendar overlay and wheels the field with a stepper;CNColorWellfollowssize.CNTabBarshows each tab's symbol and label, keeps the selected tab readable (it was blue on blue), is no longer clipped at the window's bottom, uses the macOS 27 tabs role (in apps built with the macOS 27 SDK), draws badges, follows item, badge, font and selection changes, and turns a search item into a search tab.LiquidGlassContainerusesNSGlassEffectViewon macOS 26, with its outline visible (it was clipped), and anNSVisualEffectViewbefore 26.- Image assets, image bytes, SVGs and custom icons draw on macOS in
CNIcon,CNButton,CNPopupMenuButton(button and items),CNTabBar(imageAsset,activeImageAsset) andCNGlassButtonGroup. SVGs are read byNSImage(checked on macOS 27.2). - Native menus on macOS (
CNPopupMenuButton,CNContextMenu,CNActionSheet) are built the same way: disabled items are greyed out and can no longer be chosen, also inside submenus; destructive items are red; checked items show a checkmark; inline and palette sections end at a separator. Item icons stay visible on macOS 27, which hides them by default, and a single-colour icon with no colour follows the menu's text colour in light and dark.keepsMenuPresentedhas no AppKit equivalent and is ignored on macOS. - VoiceOver:
semanticLabelreaches VoiceOver on macOS forCNButton,CNPopupMenuButton,CNSlider,CNSwitch,CNSegmentedControl,CNStepper,CNDatePickerandCNColorWell.
macOS — dialogs, menus and search #
CNAlertis a nativeNSAlertshown as a sheet on the window: the default action takes Return, cancel takes Escape, destructive actions are marked, and text fields (secure ones too) sit in the alert. Same API as on iOS.CNActionSheetis anNSMenudropping down fromanchorRect, or anNSAlertsheet without an anchor. Closing it resolves to null.CNSearchBaris a nativeNSSearchFieldon every macOS (it was a blank area). Escape clears the text, then ends the search and hands the keyboard back to Flutter; an expandable bar behaves like a toolbar search item. NewrecentsAutosaveNamekeeps recent searches.CNGlassButtonGroupis native Liquid Glass on macOS 26, with badges and menus (it was a blank area). Before 26 it stays a row of native buttons.CNPopupGesturealso opens a native menu on a secondary click.CNFloatingIslandand the experimentalCNGlassCardspotlight no longer create native views macOS does not have; they draw in Flutter there.
Added #
CNContextMenu, a native context menu for any widget. On macOS a right, two-finger or Control-click opens anNSMenuat the pointer, also over a background window. On iOS 17.4 and later a long press opens the system menu at the pressed point. Elsewhere it uses the action sheet fallback. It takes the same entries asCNPopupMenuButtonand reports the chosen path.CNProgressIndicator, a native progress bar or spinner, determinate or indeterminate, with tint and size: SwiftUI'sProgressView, which drawsNSProgressIndicator, on macOS;UIProgressView/UIActivityIndicatorViewon iOS 26 and later; Cupertino and Material fallbacks elsewhere. New enumsCNProgressStyleandCNControlSize.PlatformVersion.shouldUseNativeControls: true on every macOS and on iOS 26 and later, for widgets whose native view is a standard control.CNSegmentedControl.semanticLabel, on iOS too.
Fixed #
CNTabBardid not send a change of an item'simageAsset,activeImageAsset, image bytes orcustomIconto the native bar once it was created, and aftersetItemsan asset could be swapped for its blurry 1x file. Both are fixed, on iOS and macOS.- iOS: a raster
imageAssetinCNTabBarwas drawn at its pixel size, far larger than the tab; it now fits the item. - iOS: a PNG or JPG
imageAsseton aCNPopupMenuButton(and wherever a raster asset is loaded with a size) was read at one pixel per point and not fitted, so a @3x icon was drawn three times too large and clipped: the popup's check-circle showed as a blurry zoomed checkmark, and a tinted one showed no icon. Raster assets now use their variant's density and fit the requested size. - iOS: in debug builds the first SVG an app showed could be missing. SVGKit's device check threw on the first parse, which a warm-up parse raced; the warm-up now runs before any real SVG.
- iOS (#66): uncoloured single-colour image assets on
CNButtonandCNPopupMenuButtonare now drawn as templates that take the tint or adapt to the glass, as 1.6.0 intended. The check that decides it never ran: Core Graphics rejected the bitmap context it used. - iOS:
CNButtonConfig.labelFontWeightwas ignored. - iOS 26/27: a stray outline above the context menu.
Changed #
- The plugin's macOS minimum is 12.0 (it was 11.0; Xcode 27.1 rejects lower deployment targets).
Example #
- Back buttons on macOS for the full-screen pages (Music, Files, iPhone Duo, Native Sheet).
- Captions on the Button page are readable in dark mode.
- New pages: Tab Bar, Search Bar, Glass Button Group, Progress Indicator, Context Menu.
lib/mac_page_entry.dartopens any demo page by name on macOS, for screenshots and checks.
2.1.2 #
Patch:
CNNativeSheetfailed to compile with some Xcode versions (#119). No API changes.
Fixed — #119 a build error in CNNativeSheet.swift #
Building or archiving an app with 2.1.0 or 2.1.1 could stop with "Static method 'buildExpression' requires that 'some ToolbarContent' conform to 'View'" in CNNativeSheet.swift, depending on the Xcode version. An availability check sat inside the sheet's toolbar builder, which not every Xcode accepts there. The check now sits outside it, with the same result: on the iOS 27 simulator the sheet is pixel-identical to 2.1.1.
2.1.1 #
Patch: four fixes contributed by @yagizdo (#115-#118), and a follow-up to #116. Each was reproduced on 2.1.0 and verified with the fix on the iOS 27 simulator; #115, #117 and the #118 alert also on iOS 26.2. The changes below iOS 26 (#116, the #118 segmented control) were verified with the Flutter fallbacks forced on iOS 27 and with widget tests, as no iOS 18 simulator was available. No API changes.
Fixed — #115 CNTabBar dropped split, font and icon size changes made together with a badge #
When only the badges changed, the tab bar sent the badges and stopped, so a split, labelFontSize/labelFontFamily or iconSize change in the same setState never reached the native bar, until a later update that did not also change a badge. Everything changed in one rebuild now goes out together.
Fixed — #116 the CNSearchBar fallback overflowed its parent #
Below iOS 26 the fallback bar was as wide as the screen, so in a padded list, column or row it overflowed by the padding, and an expanded bar pushed its Cancel button off screen, where it could not be tapped. The bar now expands into the width its parent gives it, next to Cancel. It also works inside IntrinsicHeight and IntrinsicWidth. iOS 26 and later are unchanged.
Fixed — #117 an uncoloured CNIcon was black on a dark theme #
Without a color, the native icon was drawn black whatever the theme, so it almost disappeared on a dark page. That also hit every CNButton with an SF Symbol below iOS 26, and the CNGlassButtonGroup fallback. It now takes the theme's label colour (black in light, white in dark) and follows theme changes. A given colour, and the hierarchical, palette and multicolour modes, are unchanged.
Fixed — #118 open modals and pickers follow the system appearance #
CNAlertandCNActionSheetin an app whose theme follows the system kept the old appearance when the system switched while they were open. Under a theme without a brightness they now follow the system; a theme with a brightness still sets theirs.- An open colour picker (
CNColorWell) or compact date popover (CNDatePicker) now switches with the app's brightness too, instead of keeping the one it opened with. - The
CNSegmentedControlfallback below iOS 26 drew white segments on a dark page. The segments now take the page's background colour.
Example #
- Check pages for #115-#118:
PROBE=pr115topr118.
2.1.0 #
A native sheet over the Flutter app:
CNNativeSheetrests at a few heights, keeps the screen behind it usable, holds a native list and tab bar, and collapses to a glass capsule with only the tab bar.
Added #
CNNativeSheet: a native sheet over the Flutter app, drawn by UIKit and SwiftUI (UISheetPresentationController). It rests atCNSheetDetents (collapsed,medium,large, a height or a fraction) and can be dragged between them;collapsedshrinks a sheet with a tab bar to a glass capsule holding only the tab bar, as Find My's does. Up toundimmedDetentthe app behind it stays undimmed and keeps taking touches, so a map behind it still pans, anddismissible: falsekeeps it from being dragged closed. On iOS 26 it is Liquid Glass at its partial heights. The content is native: eachCNSheetPagehas a title, buttons beside it (CNSheetButton) and a list ofCNListItems, and with more than one page a tab bar sits inside the sheet. Checked against Find My's People sheet on iOS 27, at its middle height and collapsed: the title, buttons, rows, separators, capsule and tab bar land within a pixel of Find My's. Flutter widgets cannot be placed inside the sheet, because an iOS app has one Flutter view, and it stays behind. iOS 17 and later.CNListItem.leadingImageandtrailingText, for a contact photo and a value such as a distance.CNNativeSheetrows show them.
Example #
- Native Sheet demo page over a drawn map, and
PROBE=sheet.
2.0.0 #
Major: four new native controls (
CNDatePicker,CNStepper,CNColorWell,CNPageControl), SF Symbol effects inCNIcon, clear glass buttons, sliders without a thumb and with tick marks, tab bar items that open a menu (#113, thanks @johan-perso), palettes and inline sections in pop-up menus, and the iOS 27 prominent tab. Three APIs deprecated since 1.3.0 and 1.5.0 are removed, andCNButtonStylegains two values; see "Breaking changes".
Breaking changes #
PlatformVersion.initialize()is removed. It has been deprecated since 1.3.0:PlatformVersionreads the OS version the first time it is used. Delete the call.CNTabBarNative.checkIsEnabled()is removed. It has been deprecated since 1.5.0. Use the synchronousCNTabBarNative.isEnabled.CNTabBarNative.enableno longer takesonSearchSubmitted,onSearchCancelledoronSearchActiveChanged. They have been deprecated and never called since 1.5.0; the search tab reports throughonSearchChanged.CNTabBarSearchItem.onSearchActiveChangedandCNSearchScaffold.onSearchActiveChangedare unchanged.CNButtonStylehas two new values,clearGlassandprominentClearGlass. An exhaustiveswitchover it needs two more cases.
The minimum Flutter and Dart versions do not change.
Docs — four new showcase screens #
The README's "What's new" section shows four new Showcase screens of the example app, built only from this package's widgets and recorded on the iOS 27 simulator: a New Event form (date pickers, a stepper, a colour well, pop-up menus), Notes (a "+" tab that opens a menu, and a menu with a formatting palette), a Welcome pager (symbol effects and page dots) and a photo Editor (clear glass buttons and a ticked slider). Run them with flutter run -t lib/showcase/showcase_app.dart --dart-define=SCENE=event|notes|welcome|editor.
Added — CNDatePicker #
A native date and time picker: UIDatePicker on iOS 26+, NSDatePicker on macOS 26+. It has date, time, dateAndTime and yearAndMonth modes in the compact, inline and wheels styles, with minimumDate, maximumDate, minuteInterval, tint, locale and semanticLabel. The native view reports its size, so the compact pill fits in a Row and the inline calendar takes its own height. Its popover opens from the pill and follows the app's theme. A UTC DateTime is shown and returned in UTC, a local one in the device's time zone. Below 26 it falls back to CupertinoDatePicker, with a pill that opens it in a popup for the compact style.
Added — CNStepper #
A native − / + stepper: the system stepper on iOS 26+, an NSStepper on macOS 26+, and a Flutter stepper shaped like the iOS 18 one below that. It takes min, max, step, wraps, autorepeat, enabled and a color, and VoiceOver reads it as one adjustable element with its semanticLabel and value. On iOS 26+ UIStepper ignores a tint and has no disabled look, so the native stepper is SwiftUI's, which draws the same control, takes the colour, and dims both buttons while disabled.
Added — CNColorWell #
A round colour well: UIColorWell on iOS 26+, which opens the system colour picker itself (grid, spectrum, sliders, eyedropper), an NSColorWell on macOS 26+, and below that a swatch that opens a sheet of system colours with an opacity slider. It takes supportsAlpha, title, supportsEyedropper (iOS 26) and enabled. The picker opens in the app's theme, not the phone's, and VoiceOver reads the well's semanticLabel and its colour. onChanged always receives an sRGB colour: a Display P3 pick is converted to sRGB and clipped to its gamut.
Added — CNPageControl #
Page dots: UIPageControl on iOS 26+, and drawn in Flutter with the same geometry on macOS, which has no native page control, and below iOS 26. Pass a PageView's PageController as controller and the dots follow the PageView, and a tap on them animates it. It takes backgroundStyle (automatic, prominent, minimal), hidesForSinglePage, allowsContinuousInteraction, enabled and dot colours. The colours default to the label colours, since UIKit's white dots vanish on a light background.
Added — SF Symbol effects in CNIcon #
CNIcon.effectruns aCNSymbolEffectwhile it is set:pulse,variableColor,scale, and from iOS 18 / macOS 15bounce,wiggle,breatheandrotate; switching betweendrawOffanddrawOn(iOS 26 / macOS 26) draws the symbol out and back in. Set it to null to stop.CNIcon.triggeredEffectplays once each timeeffectTriggerchanges (bounce by default): a bell that bounces on each new message.CNIcon.replaceTransitionanimates a change ofCNSymbol.name:replace,downUp,upUp,offUp, ormagic(iOS 18 / macOS 15).- Effects take a direction,
byLayer/wholeSymbolscope, speed and repeat (once,periodic,continuous). Each needs the OS version that introduced it (iOS 17 / 18 / 26, macOS 14 / 15 / 26); below it, and on other platforms, the icon stays still. Creation params are unchanged when no effect is used.
Added — clear glass buttons #
CNButtonStyle.clearGlassand.prominentClearGlassuseUIButton.Configuration.clearGlass()/.prominentClearGlass()on iOS 26, for buttons over photos and video. With aglassEffectUnionIdorglassEffectIdthey useGlass.clear, tinted for the prominent style.CNPopupMenuButtonandCNGlassButtonGrouptake them too. On macOS without those IDs, and below iOS/macOS 26, they look likeglass/prominentGlass.- The label and icon of a
prominentClearGlassbutton are white, as onprominentGlass. UIKit's own configuration keeps the dark label colour, which is unreadable on a dark tint. An icon colour overrides the white, and so doeslabelColoron a button without a glass ID.
Added — thumbless and ticked CNSlider #
CNSlider.style: CNSliderStyle.thumblessdraws a media-style slider without a thumb (iOS 26).numberOfTicksortickValuesdraw tick marks,allowsTickValuesOnly(default true, as in UIKit) snaps to them, andneutralValuefills the track from a middle value, such as 0 on a -100…100 exposure slider (iOS 26 / macOS 26). Below iOS/macOS 26 the Flutter slider snaps to the same ticks but draws no marks.
Added — #113 tab bar items that open a menu (thanks @johan-perso) #
CNTabBarItem.menuItemsturns an item into a button that opens a native menu instead of selecting itself, for example a "+" that lets the user pick what to create. It takes the same entries asCNPopupMenuButton: items, dividers, subtitles and submenus. The menu opens from a clear button over the item's icon, placed the way the dot badges are found, since aUITabBarItemcan't carry a menu. The item never gets selected nor callsonTap, and its glass still reacts under the finger. Sliding a finger along the bar onto it opens the menu too.CNTabBar.onMenuSelected(int index, List<int> path)gets the item and the path of the chosen entry, asCNPopupMenuButton.onPathSelecteddoes.- Without the iOS 26 native bar (iOS < 26, Android, web), the menu opens as a
CupertinoActionSheetwith a further sheet for each submenu, asCNPopupMenuButton's fallback does. Both now use the same sheet. - Menu entries show SF Symbols and image assets, not
customIcon. On the iOS 26 bar with asearchItemand on the native macOS bar the item is a plain tab, and the bar is not sent its menus. - VoiceOver reads each such item once, as the tab it is (the menu button over it is hidden from VoiceOver), and activating it opens the menu.
CNPopupMenuButtonand the tab bar now build their menus with the same code (PopupMenuBuilder.swift, andpopup_menu_fallback_sheet.dartfor the sheet);CNPopupMenuButtonbehaves as before.
Added — CNPopupMenuButton: palettes, inline sections, items that keep the menu open #
CNPopupMenuSubmenu.styleshows a submenu's items in the parent menu instead of a nested one:inlineas a section under its label,paletteas one row of icons (iOS 17+), like the formatting row of a text menu. Their items report the same paths as nested ones. On macOS both are a section with a header; the action sheet fallback lists them in place.CNPopupMenuSubmenu.elementSize(small,medium,large) sets how big its items are (iOS 16+):smallfits several icons on a row.CNPopupMenuItem.keepsMenuPresentedkeeps the menu open after the item is chosen (iOS 16+), for actions the user repeats, such as zooming in.- The same options work in
CNTabBarItem.menuItems. A menu that uses none of them sends exactly the payload it did before.
Added — CNTab.isProminent, the iOS 27 prominent tab #
CNTabBarNative can mark one tab as prominent: iOS 27 draws it apart from the others, as a glass circle with its icon at the trailing end of the bar, for the tab users reach for most. A search tab then sits with the other tabs. Below iOS 27, and in apps built with an older SDK, it is a regular tab.
Fixed #
- Dot badges in right-to-left layouts were drawn on the mirrored item: the icons are found from left to right, and the first item is the rightmost there.
CNButtonkept its last tint whentintwas set back to null. Only non-null tints were sent to the native button, so a button that lost its highlight stayed coloured. It now returns to the colour of a button created without a tint, on iOS and macOS.CNTab.activeSfSymbolwas never sent to the native tab bar, soCNTabBarNativedrewsfSymbolon the selected tab too. The selected tab now showsactiveSfSymbol. The native bar already draws symbols filled, so pick a different symbol rather than the.fillone.
Example #
- Showcase scenes
SCENE=event|notes|welcome|editor(see "Docs" above). - Date Picker, Stepper, Color Well and Page Control demo pages; symbol effects, clear glass buttons over a photo, and iOS 26 sliders on the icon, button and slider pages.
- Testing screens:
PROBE=datepicker|stepper|colorwell|pagecontrol|controls|symboleffects|clearglass|slider26|tabmenus|prominent|menulayout. Add--dart-define=FALLBACK=truetostepper|colorwell|pagecontrol|controlsfor the Flutter fallbacks.
1.9.1 #
Patch: six fixes contributed by @yagizdo (#108-#111, #114) and @johan-perso (#112), with review follow-ups, and a fix for a squeezed tab bar on iOS 26. #109, #110, #111 and #112 were reproduced on 1.9.0 and verified with the fix on the iOS 26.2 and iOS 27 simulators. #108 and #114 change only what runs below iOS 26 and were verified by code review and widget tests, as no iOS 18 simulator was available. No API changes.
Fixed — #108 CNActionSheet crashed on a large iPhone in landscape below iOS 26 #
1.8.3 (#95) set the presentation delegate when the window had a regular width, as on an iPad. A Plus or Pro Max iPhone in landscape has one too, but UIKit still presents the sheet as an alert there, and setting that controller's delegate threw NSInternalInconsistencyException. Below iOS 26 the delegate is now set only when the sheet is presented as a popover.
Fixed — #110 a sheet undid tab bar changes made after the bar appeared #
With autoHideOnModal (the default), CNTabBar removes its native bar while a sheet is up and creates it again when the sheet closes, from the values it was first created with. A badge, label, tint, theme, label font or split layout changed since then came back with its old value. The new bar now gets the current values.
Fixed — #109 cut or shrunk labels after the tab bar changed width #
On iOS 26 and 27 a bar first laid out narrow or invisible, inside Opacity(0) or built narrower off screen, kept labels sized for that width: "Favo…", missing labels, or a smaller font. The bar now lays its items out again when its width changes. A bar whose width animates does this on every frame.
Fixed — #112 the split tab bar with five items, and splitSpacing, on iOS 26+ #
- A single right item is a circle again with five items, instead of a narrow pill with its icon and label shrunk. When the two groups are laid out by proportion, the right bar got 1/5 of the width with five items, and iOS 26 draws one item in a bar that narrow as a pill. The right group now gets at least 100 pt, the width it gets with four items on a 402 pt wide phone; two items or more already get enough.
splitSpacingis the gap between the two glass capsules. iOS 26 draws each capsule at its content's size and centres it in its bar, leaving about 22 pt of empty bar on each side, so the visible gap wassplitSpacingplus about 44 pt. The two bars now overlap by that empty part, which holds no item. With the default 12 pt the gap looks like the one in Apple's apps.
Fixed — CNTabBar.height below the bar's own height on iOS 26 #
On iOS 26 the native bar measures about 97 pt for itself, the top 14 of them room for the selection pill. With a smaller height, such as 85, the glass capsule came out short and the labels sat on the icons. On iOS 26 such a bar now keeps its own height at the bottom of the box, its transparent top reaching above it; the space it takes in the layout does not change. Taller heights, and iOS 27, are unchanged.
Fixed — #111 native widgets and modals follow the app theme #
CNSearchBar,CNFloatingIslandandCNGlassButtonGroupread the theme only when they were created. After a switch to dark they stayed light-styled on iOS 27; on iOS 26.2 the glass followed the backdrop, but the search placeholder stayed light. They now switch with the theme, asCNButton,CNSliderand the other controls already did.CNActionSheetandCNAlertopened in the system appearance instead of the app theme, so a light app on a dark phone got a dark sheet. Both now open in the app's brightness.
Fixed — #114 tab badges below iOS 26 #
Below iOS 26 CNTabBar draws a Flutter fallback, which ignored CNTabBarItem.badge and dotBadge. Both fallback bars, with and without a searchItem, now draw them at the size and place UITabBarItem uses on iOS 18, and VoiceOver reads the count as the tab's value. Badges sit on the leading side in right-to-left layouts, keep their size with large text, and appearing or clearing no longer rebuilds the icon. CNTabRail's fallback badge now uses the dark system red in dark mode.
Example #
- Testing screens for #109 / #110 (
PROBE=pr109fade|pr109narrow|pr110, with--dart-define=OBSERVER=truefor #110), #111 (pr111), #112 (split5), the iOS 26 height fix (overlap), and issues #60, #68 and #70 (issue60|issue68|issue70).
1.9.0 #
Minor: subtitles and submenus in
CNPopupMenuButton(#106, thanks @johan-perso),CNTabBarNative.enable(showCloseButton:), fixes from @tgrushka (#94) and @Honahec (#107), and a new pub.dev page with native recordings of every component. Nothing changes for code that does not use the new options;CNPopupMenuButton.onSelectedbecomes nullable (see below).
Docs — a new pub.dev page #
The README opens with recordings of the example app's new Showcase screens (Display & Brightness, Files, Photos, Account, Music and iPhone Duo), built only from this package's native widgets and recorded on the iOS 27 simulator, followed by a close-up of each component and a Contributors section. The pubspec screenshots are the new showcase and four of the recordings, 2.5 MB instead of 6.4 MB.
Added — subtitles and submenus in CNPopupMenuButton #
CNPopupMenuItem.subtitleshows a second line under the label:UIAction.subtitleon iOS,NSMenuItem.subtitleon macOS 14.4+, a smaller line in theCupertinoActionSheetfallback.CNPopupMenuSubmenuopens a nested menu ofitems, which can hold further submenus. It takes the same label, subtitle, icon andenabledoptions as an item. It is a nestedUIMenuon iOS and anNSMenuItem.submenuon macOS; the fallback opens it as a second action sheet.UIMenuhas no disabled state, so a disabled submenu is shown as a disabled action and cannot be opened.onPathSelected(List<int> path)is called for every selection with the path to the selected item, one index per level, dividers included:[3]foritems[3],[2, 1]for the second entry of the submenu atitems[2].onSelectedis now optional. It keeps its index, and for an item inside a submenu it gets the index of the top-level submenu it is under, so every selection reaches whichever callback is set. A debug assertion requires at least one of the two callbacks, and another oneonPathSelectedwhenitemscontain a submenu, sinceonSelectedalone cannot tell which of its items was chosen. Its type is nowValueChanged<int>?: call sites compile unchanged, but code that callsbutton.onSelected(i)on aCNPopupMenuButtonneeds a?.or!.
Verified on the simulator (iPhone 17, iOS 26.0) and on macOS 26.2: subtitles, nested submenus, a disabled submenu, and the values both callbacks receive.
The platform channel only gains keys: a level that uses no subtitle and no submenu is encoded to exactly the arrays it was before (covered by a test), and itemSelected still carries index, now with path beside it. Entries are now encoded by one recursive function, encodePopupMenuEntries, shared by creation and setItems, which also builds each submenu's level.
Changed — preserveTopToBottomOrder uses the system's fixed order on iOS 16+ #
preserveTopToBottomOrder reversed the top-level items itself when the button sat in the lower 60 % of the screen, so that a menu opening upward still read 1, 2, 3 from the top. That reversal cannot reach a submenu: opened from a button at the bottom of the screen, its items showed in reverse. On iOS 16+ the option now sets preferredMenuElementOrder = .fixed, which keeps the given order whichever way the menu opens, submenus included; the top level reads the same as before. On iOS 15 the reversal is unchanged.
Fixed — a customIcon after a divider showed another item's icon #
The rendered custom icons were collected with one slot per entry, dividers included, but read back with a counter that only counted items. After the first divider every item read the slot before its own: the icon of the previous item, or the divider's empty one. The icons are now looked up by the icon itself (icon, size and colour), which submenus needed anyway, and which also finds them again after a rebuild whose items are new objects.
Fixed — the CNPopupMenuButton fallback ignored enabled #
The CupertinoActionSheet used below iOS 26 and on other platforms reported a disabled item when tapped and opened a disabled submenu. Both are now dimmed and ignore taps.
Added — CNTabBarNative.enable(showCloseButton:) #
showCloseButton: false hides the close button in each tab's navigation bar, for a root-mode app whose tab bar is the whole app; it then closes only through disable(). Defaults to true, as before.
Fixed — #94 CNTabBarNative showed an empty accessory pill on iOS 26.1+ (#93) #
Since iOS 26.1, tabViewBottomAccessory draws its pill even around an empty view, so bottomAccessory: null and setBottomAccessory(null) left an empty glass pill above the tab bar. The accessory is now disabled when there is none, through the iOS 26.1 tabViewBottomAccessory(isEnabled:); switching it on and off keeps the selected tab. Apps built with Xcode 26.0, whose SDK lacks that call, keep the previous one. Verified on iOS 26.0, 26.2 and 27.0 simulators.
Fixed — #107 CNTabBar resent its items on the first rebuild when iconSize was set #
The native bar's iconSize was not remembered at creation, so the first rebuild after it (a theme change, any parent setState) saw a changed size and replaced every tab item of a bar that was already up to date. Bars without iconSize were not affected.
Example #
- New Testing screen: PopupMenu subtitles & submenus, with nested and disabled submenus, a custom icon after a divider, and a log of both callbacks.
- Testing screens for #94 (TabBarNative null accessory,
PROBE=pr94) and for popup menu icons after a rebuild (PROBE=pr106), and widget tests for #107 and the popup menu fixes.
1.8.3 #
Patch: six fixes contributed by @yagizdo (#95-#100). Each was reproduced on 1.8.2 and verified with the fix on the iOS 27 simulator (#100 also on iOS 26.0 and 26.2), and all six together on an iPhone with iOS 27.2; #95 by code review, as no iOS 18 simulator was available. No API changes.
Fixed — #98 the tab bar selection jumped through every tab when the bar appeared (#101) #
Right after a native CNTabBar was created, the label-refresh workaround (#6) selected each tab in turn, yielding to the run loop between them, so the Liquid Glass pill visited every tab — twice — before resting on currentIndex (#35, #101). The cycle now runs in one block without animation, so only the final state is drawn, in single and split mode; labels still render. It also no longer turns UIKit animations off app-wide during each cycle. Because a cycle can no longer be interrupted, two cycles can no longer overlap and restore the wrong tab after a sheet closes (#86).
Fixed — #97 a flat Flutter tab bar flashed before the Liquid Glass bar #
On iOS 26 and later every new CNTabBar showed the pre-iOS 26 CupertinoTabBar fallback for a frame or two (longer in debug builds) while the native bar was prepared. The slot now stays empty, at the bar's height, until the native bar lands. Added on top: if native preparation fails and every retry is used up, the bar shows the fallback after all, so a failure never leaves an app without a tab bar.
Fixed — #100 labelFontFamily and labelFontSize on the native bar #
The native bar now draws the label font itself: the appearance carries it before the items exist, and a change at runtime sets the items again so their views pick it up. labelFontSize without labelFontFamily now sizes the system font (SF Medium, SF Semibold in the selection pill), setting both back to null restores the native label, and a taller label moves the icon up by half its extra height and itself down by half, so the two stay clear of each other. This replaces 1.8.2's label override, which is reduced to letting a custom-font title shrink to fit a narrow tab — the lone tab in split mode.
Fixed — #96 taps on a native CNIcon inside a button were lost #
CNIcon draws SF Symbols in a UiKitView, whose recognizer won the gesture arena over an enclosing CupertinoButton or GestureDetector: the button dimmed but onPressed never ran, and only taps on the padding counted. The icon now stays out of the arena while keeping its hit area. This affects the iOS < 26 fallbacks of CNButton.icon, CNPopupMenuButton and the CNTabBar fallback, and any app that puts a CNIcon in its own button.
Fixed — #99 CNIcon showed a filled circle before its native view (debug builds) #
While PlatformViewGuard waits after a cold start or hot restart (debug and profile builds only), CNIcon drew a filled circle for SF Symbols and image assets. The slot now stays empty at the icon's size until the native view lands.
Fixed — #95 CNActionSheet crashed on iPhone below iOS 26 #
Below iOS 26 a compact-width action sheet is presented by a controller that throws when its delegate is set. The delegate is now set only on iOS 26 and later or for popover presentations, and cleared only when it was set.
Example #
- Testing screens for #96 / #99 (
CNIcontaps and placeholder), #97 / #98 (tab bar mount) and #100 (label font at runtime), and an integration test that taps aCNIconinside a button through the gesture arena.pr_probe_entry.dartgainsPROBE=pr86|pr96|pr97|pr100andPROBE=tour, which plays them one after another for a device recording.
1.8.2 #
Patch: three
CNTabBarfixes (#82, #103, #104) and one addition (#105,CNTabBarItem.dotBadge). Nothing changes for bars that do not use a custom label font, image assets in the fallback, items that change at launch, or dot badges.
Fixed — #82 labelFontFamily had no effect on iOS 26 and 27 #
Two causes. CupertinoTabBarPlatformView built the bar's first UITabBarAppearance before reading labelFontFamily / labelFontSize, so a font passed at creation never reached it (found by @johndavid92 in PR #82). And since iOS 26.2 the Liquid Glass UITabBar ignores the .font in titleTextAttributes altogether, whether set on the appearance or per item (Apple Developer Forums thread 809225, FB21291879). The simulators for iOS 26.0 and 27 ignore it too.
The font is now read before the bars are built, and the bar puts its appearance's font on the tabs' title labels after every layout itself: both copies the Liquid Glass bar keeps of each title, re-measured, and allowed to shrink a little rather than truncate when a custom font is wider than a tab (the lone tab in split mode). Bars without a custom font are not touched.
Verified before and after on the simulator, iOS 27.0 and 26.0, in single and split mode: first appearance, selection changes, setFont from a size change, setFont sent straight to the native channel, remount, and a sheet round-trip.
Fixed — #103 the bar could stay on its Flutter fallback when its items changed at launch #
_prepareCreationParams awaits several times and read widget.items again after each await. When an app changed its items in between (a tab added once its data loads), it indexed a list built for the old items past its end; the error was swallowed and nothing prepared the bar again, so it stayed on the Flutter fallback for the session. A smaller window let the native bar appear with the old items. Preparation now uses one snapshot of the items, prepares again when the items change before the native bar exists, and logs and retries a failed preparation twice. Reported from the Kinetrio app.
Verified on the simulator (iOS 27.0, 26.0) by adding a fifth tab after the first frame and 16, 40 and 100 ms later: before, the fallback stuck or the bar kept four tabs; after, five tabs on the native bar every time.
Fixed — #104 image assets drew black in the fallback #
The Flutter fallback passed an imageAsset to CNIcon without a colour, so template images ignored the bar's active and inactive colours and drew black. They now take those colours, as the native bar tints them; an asset with a color of its own keeps it.
Added — #105 CNTabBarItem.dotBadge #
badge: CNTabBarItem.dotBadge shows a small red dot instead of a count. UITabBarItem has no dot badge, and on iOS 26 and 27 a badge keeps one size whatever its text, so CNTabBar draws the dot at the top-right of the item's icon itself, in single and split mode, and CNTabRail draws it too. The dot views are kept across layouts, so the bar does not lay itself out again on every frame (checked: no layouts while idle). Requested from the Kinetrio app.
Example #
- New Testing screens: #103 / #104: TabBar items change early and #105: TabBar dot badge; the PR #82 screen gains Next tab.
pr_probe_entry.dartopens them withPROBE=pr82|issue103|issue105, andAUTO=truesteps all three screens through their cases for device screenshots.
1.8.1 #
Patch:
CNTabRail(and soCNTabScaffold's rail and sidebar) now draws image assets, and the first SVG image an app loads no longer occasionally fails to draw. No API changes.
Fixed — CNTabRail ignored imageAsset / activeImageAsset #
CNTabRail takes the same CNTabBarItems as CNTabBar, but drew only SF Symbols and custom icons, so a tab set built from CNImageAssets showed placeholder circles in the rail and the sidebar — including when CNTabScaffold moved tabs to the side on iPhone Duo. It now draws image assets (SVG or raster, from an asset path or imageData, with resolution variants) in both styles, natively and in the Flutter fallback, with the same priority as CNTabBar: imageAsset > customIcon > icon, and activeImageAsset for the selected tab when given. As in the system tab bar, icons are tinted and drawn at a fixed size.
Fixed — the first SVG image could fail to draw #
SVGImageLoader starts a warm-up parse on a background queue the first time it is used, and SVGKit's parser is not thread-safe. An SVG parsed on the main thread at the same moment could come back empty and fall back to a placeholder. Seen once on the first imageAsset of a CNTabRail; the same loader serves CNTabBar, CNButton, CNIcon and CNPopupMenuButton. SVG parsing is now serialised.
1.8.0 #
Minor: iPhone Duo support (#102) through four new public APIs —
CNTabScaffold,CNTabRail,CNFoldable/CNFoldableScope— a newsidebarOnWideScreensoption onCNTabBarNative.enable, and VoiceOver names for native controls (#88) through a newsemanticLabelonCNButton,CNPopupMenuButton,CNSwitchandCNSlider. Nothing changes for apps that do not use them.
Added — #102 iPhone Duo: tabs that move to the side, and a foldable API #
iPhone Duo (iOS 27.1) has an outer display and a larger inner display, and can stand partially open in a book or tabletop pose. On the outer display, and on the inner display in landscape, iOS moves the status bar and the tab bar to a vertical bar on one edge — but only for system containers. See the README's iPhone Duo (foldable) section.
CNTabBarNativeis a system container, so it gets the vertical bar with no code change once the app is built with Xcode 27.1. NewsidebarOnWideScreens: trueturns the tabs into a native sidebar on the open inner display (.sidebarAdaptable, with the sidebar as the default placement): beside the content in landscape, behind a sidebar button in portrait.CNTabScaffoldbrings the same behaviour toCNTabBar, which as a standalone bar never turns vertical. It shows aCNTabBarat the bottom, swaps it for aCNTabRailin the vertical-bar column whenever iOS uses one (moving it clear of the camera region), and withsidebarOnWideScreensshows a sidebar on screens at least 600 pt wide. The body stays mounted across every change, so folding never resets the page.CNTabRailis a vertical tab bar taking the sameCNTabBarItems: icons in a Liquid Glass capsule (rail), or icon-and-label rows in a glass panel (sidebar). Badges, custom icons, VoiceOver labels and the selected trait are supported; Cupertino-drawn fallback below iOS 26.CNFoldablereports the hinge (UIHingeInteraction: closed / partially open / fully open, and the angle), the physical side of the vertical bar, and the reserved regions — the fold and the camera — in Flutter's logical coordinates.CNFoldableScopeexposes it toCNFoldable.of(context)and adds the active fold and the camera toMediaQuery.displayFeatures, which Flutter does not populate on iOS itself, so Flutter's dialogs and popups keep clear of the fold.
The iOS 27.1 APIs are compiled only with the iOS 27.1 SDK (canImport(UIKit, _version: 9127.0.85)). Built with an older Xcode the package still compiles, CNFoldable reports CNFoldableState.unsupported, and CNTabScaffold keeps a bottom bar.
Requested by @mark8055 (#102). Verified on the iPhone Duo simulator (Xcode 27.1, iOS 27.1, Flutter 3.44.0) in every pose: closed (vertical rail, 0°), open in landscape (vertical rail, 180°) and portrait (bottom bar or sidebar), book pose (a layout split left and right at the fold) and tabletop pose (split above and below it), and a cold start while unfolded.
Added — #88 VoiceOver names for native controls, and an Accessibility section #
semanticLabelonCNButton(andCNButton.icon),CNPopupMenuButton(and.icon),CNSwitchandCNSlider: what VoiceOver reads for the native control. Without it, an icon-only button is read by its SF Symbol's built-in name — the example app's theme toggle was announced as "do not disturb", the name of themoonsymbol — and a switch or slider has no name at all, because a native control cannot merge with the Flutter text beside it. The label is applied natively (the button's, slider's and SwiftUI toggle's accessibility label) and on the Flutter fallbacks.CNTabRailsupports the Large Content Viewer, like the system tab bars: its icons keep a fixed size, and with a large text size a long press shows the item enlarged.- README Accessibility section: what VoiceOver gets from each native widget, Dynamic Type, the Large Content Viewer, and a Flutter engine limitation that affects VoiceOver touch exploration over scrolling lists (flutter/flutter#194389).
Requested by @tgrushka (#88). Checked through the iOS accessibility tree on the iPhone Duo simulator (iOS 27.1): the names, roles and values of buttons, menus, the slider, switches, the segmented control and the rail, before and after semanticLabel.
Changed — package #
misc/(the README's images and videos) andtool/(development scripts) are no longer published; the README already loads its media from GitHub. The archive is about 8 MB smaller.- The pub.dev screenshots open with the iPhone Duo animation.
Example app #
- New iPhone Duo page (Navigation): a live hinge gauge, a player that splits at the fold, an even-numbered grid that reflows, and an overlay of the reserved regions.
- The home list now keeps clear of the iPhone Duo outer display's vertical status bar.
- The debug banner is off, so the light/dark toggle in the top-right corner can be tapped on macOS (#88).
- The icon-only buttons in the navigation bar have VoiceOver names.
- The macOS deployment target is 12.0: Xcode 27.1 rejects anything lower.
1.7.0 #
Minor rather than patch: three new public APIs (
CNActionSheet,CNAlert,CNTabBar.precacheIcons), and native widgets under aCupertinoAppwhose theme leavesbrightnessunset now follow the system brightness instead of coming up light.
Fixed — #80 Swift Package Manager builds fail on CocoaLumberjack 3.10.0 #
SVGKit 3.0.0 lets CocoaLumberjack resolve to 3.10.0 (released 2026-09-21), which requires iOS 15, while SVGKit's own target still declares iOS 9 (built as 12.0). Xcode's target-integrity check then rejects every Swift Package Manager build of an app that depends on this package: The package product 'CocoaLumberjack' requires minimum platform version 15.0 for the iOS platform, but this target supports 12.0. CocoaPods builds were not affected.
Fix: the iOS manifest caps CocoaLumberjack to 3.7.0..<3.10.0 and lists its product on the plugin target, which is what makes Swift Package Manager apply the cap. It can go once SVGKit ships a release with its own cap. An app that already resolved 3.10.0 may need Xcode's File → Packages → Reset Package Caches (or a deleted Package.resolved) to pick the cap up.
Reported by @dogankarakus, fixed by @yagizdo (PR #83). Verified with a fresh Swift Package Manager app on Flutter 3.44.0: 1.6.0 resolves CocoaLumberjack 3.10.0 and fails to build; this release resolves 3.9.1 and builds.
Added — #78 CNActionSheet, a native action sheet #
CNActionSheet.show presents a real UIAlertController in .actionSheet style on every supported iOS version, so the sheet is the system control: destructive red, disabled actions, VoiceOver, Dynamic Type, and the Liquid Glass look on iOS 26. Pass anchorRect to anchor it to the control that opened it; from iOS 26 that is how action sheets present on iPhone as well as iPad. Other platforms fall back to CupertinoActionSheet. See the README's Action Sheet section.
Because it is a UIKit presentation rather than a Flutter route, inline CN widgets on the page stay mounted while it is open. Under a Flutter CupertinoActionSheet route, ModalHideMixin tears them down and recreates them on dismiss.
Hardened before release:
- iPad: an unanchored sheet whose presenter reports compact width (an iPad form sheet, for example) got no popover source, and UIKit throws on that. Whether a synthetic source is needed is now decided by the device and the window, not the presenter.
- A sheet with no
cancelLabeland no enabled action is refused (asserts in debug, resolves tonullwithout presenting in release). Below iOS 26 such a sheet cannot be dismissed. Previously only a sheet with no actions at all was refused.
Contributed by @yagizdo (PR #78). Verified on an iPhone (iOS 26.5.2): system look, anchored presentation, inline widgets stay mounted, an outside tap resolves to null, and back-to-back, superseding and chained calls all resolve. The unanchored iPad path was checked on an iPad Pro simulator.
Added — #79 CNAlert, a native alert with text fields #
CNAlert.show presents a UIAlertController in .alert style: default, cancel and destructive actions, disabled actions, and text fields (secure entry included) whose contents come back in CNAlertResult.textFields. Other platforms fall back to CupertinoAlertDialog. On iOS a second show replaces the alert on screen and resolves the first call to null. Configurations UIKit cannot render (no enabled action, two cancel or two default actions) assert in debug. See the README's Alert section.
Contributed by @yagizdo (PR #79). Verified on an iPhone (iOS 26.5.2): system look, typed text returned, inline widgets stay mounted, back-to-back and chained calls resolve.
Added — #73 CNTabBar.precacheIcons #
A bar whose items use customIcon renders those icons to images before its native view can be created, so its first mount showed the Flutter fallback bar for a few frames: a visible flash when the bar appears right after the native splash. CNTabBar.precacheIcons(items, iconSize: …) renders them into the existing icon cache ahead of time. Pass the same items and iconSize as the bar.
Reported and contributed by @TjarkGomollaDev (PR #90). On an iPhone (iOS 26.5.2, release build), a first mount showed the fallback for 5 frames (113–281 ms); after precacheIcons it showed 1 frame (49–50 ms), the same as a mount with cached icons. That last frame stays in every case because the bar builds its creation parameters asynchronously.
Fixed — #76 CNPopupGesture menu invisible until a hot reload, wrong item index #
- The menu sat under
Opacity(animation.value), whichshowGeneralDialog's page builder reads once (0.0) and never rebuilds, so the menu stayed invisible until a hot reload. The route's transition already fades it in, so the wrapper is gone. - Every item reported the same out-of-range index (one shared counter). Each item now reports its own index, dividers excluded.
- SF Symbol icons were drawn as a placeholder circle. They now render through
CNIcon.
Reported by @dogankarakus. Fixed in PR #89 and verified on an iPhone (iOS 26.5.2).
Changed — #84 widgets follow the system brightness when the theme sets none #
ThemeHelper read Theme.of(context).brightness, which under a CupertinoApp comes from the Cupertino theme with a light fallback. An app whose CupertinoThemeData leaves brightness null, i.e. follows the system, therefore created its native widgets light on a dark device. It now uses CupertinoTheme.brightnessOf(context), which falls back to the platform brightness. CNSearchBar, CNFloatingIsland, CNGlassCard and CNToast now take their brightness from ThemeHelper too.
Apps that set brightness explicitly see no change. An app that left it null and relied on the light result now gets dark widgets on a dark device.
Contributed by @yagizdo (PR #84). Verified on an iPhone (iOS 26.5.2) with the theme set to none, dark and light.
Known limitations #
- iOS 26.2 and later ignore custom tab bar title fonts, so
CNTabBar.labelFontFamilyandlabelFontSizehave no visible effect there (Apple Feedback FB21291879). Verified on iOS 26.5.2, both throughUITabBarAppearanceand per item.
1.6.0 #
Minor rather than patch because
CNGlassEffectgains a value (clear). That is source-breaking for anyone with an exhaustiveswitchover the enum. 1.5.5 was tagged during development and never published; everything it contained is here.
Added — #69 CNGlassEffect.clear, and LiquidGlassConfig.effect is now honoured #
LiquidGlassConfig.effect was serialised over the channel as 'effect': config.effect.name, parsed natively, stored, handed to the SwiftUI view and even used as an .animation(_:value:) key — and then glassEffectForConfig() ignored it and hardcoded Glass.regular on both iOS and macOS. CNGlassEffect.regular and CNGlassEffect.prominent therefore rendered identically, and SwiftUI's third variant, Glass.clear, was unreachable.
clear matters for glass over imagery: regular frosts what is behind it, clear lets it through — the treatment Apple's own media controls use over video and artwork.
Fix: CNGlassEffect.clear is added and both containers honour the value they were already being given.
prominent is unchanged and still falls back to regular — SwiftUI's Glass has no prominent counterpart to map onto. The enum value is kept so existing code compiles and so the mapping can be filled in later; it is now documented as a fallback rather than left to be discovered by screenshot. Note also that clear barely blurs, so content layered on top of it needs its own contrast handling (a shadow or scrim) in a way regular does not.
Reported and fixed by @johndavid92 (PR #69). Verified on an iPhone 16 Pro / iOS 26 simulator with panels of identical size and position over vertical stripes that never vary along y — so every panel sees a pixel-identical backdrop and any difference is the glass alone. RMSE between panel interiors:
| comparison | RMSE |
|---|---|
before — regular vs prominent |
0.0010 |
| noise floor (same panel shifted 1px) | 0.0027 |
after — regular vs prominent |
0.0010 (unchanged) |
after — regular vs clear |
0.337 |
Before the fix the two effects differed by less than a one-pixel shift of the same image: peak difference 1/255, zero differing pixels at 2% fuzz. macOS could not be built in the verification environment (pre-existing Swift Package Manager scaffolding issue, unrelated to the change), so the macOS glassEffectForConfig body was type-checked against the MacOSX26.0 SDK directly instead.
CNGlassButtonGroup still hardcodes Glass.regular in GlassButtonSwiftUI.swift on both platforms — a separate surface that does not take CNGlassEffect, left for a follow-up.
Fixed — #66 Uncoloured imageAsset icons don't adapt to Liquid Glass #
An imageAsset supplied without an explicit color was handed to UIKit as a non-template UIImage, so it kept its baked pixels. On an iOS 26 glass button the material resolves its light/dark appearance from the backdrop, so a black-baked glyph over a dark backdrop went invisible — and a white-baked one did the same over a light backdrop. customIcon and SF Symbols already receive .alwaysTemplate and were unaffected, which is what made the inconsistency easy to miss until an app mixed the two.
Fix: uncoloured image assets are rendered as templates in CupertinoButtonPlatformView and CupertinoPopupMenuButtonPlatformView, so the control's tint — and Liquid Glass's automatic foreground adaptation — applies. Explicit imageAsset.color values keep their existing baked-tint behaviour.
Templating is gated on the artwork actually being single-colour. .alwaysTemplate keeps only the alpha channel: lossless for a black glyph or a grey stroked SVG, but it flattens anything multi-colour to a silhouette. ImageUtils.isEffectivelyMonochrome(_:) samples the image on a capped 32×32 grid, compares only near-opaque pixels (so antialiased edges don't read as a second colour) and returns on the first distinct colour — so multi-colour assets are left exactly as they were.
Also in this change:
GlassButtonSwiftUI.effectiveIconColorwastint ?? iconColor, so a control-level tint overrode an explicit per-icon colour. NowiconColor ?? tint.- The
setButtonIcontemplate pass is scoped to image assets. Applied to every icon source it would also template SF Symbols, so amulticolor/palettesymbol without an explicit colour rendered correctly on creation and then flattened after any icon update.
Behaviour change: the plain glass style no longer sends a forced theme-accent tint from Dart, so the native side can resolve its own foreground. On iOS 26 this is mostly invisible for icons — UIButton.Configuration.glass() already overrode the image foreground, so a glass SF Symbol rendered as the adaptive system colour rather than the accent even before this release. It is visible on glass button labels, which now use the system label colour instead of CupertinoThemeData.primaryColor. Set CNButton.tint explicitly to keep an accent-coloured glass label. prominentGlass keeps its accent fallback, and the pre-iOS-26 fallback still reads primaryColor from the Cupertino theme.
Reported and fixed by @azharul-islam (PR #66). Reproduced and verified on an iPhone 16 Pro / iOS 26 simulator: over a black backdrop in light mode, a black-baked imageAsset was invisible on the glass before the fix and adapts to white after, while a deliberately four-colour asset keeps all four colours.
Fixed — #67 customIcon glyphs pixelated on thin strokes #
iconDataToImageBytes painted the glyph at 1× fontSize, then the "scale to fill" re-blit upscaled the cropped ink — icon fonts pad their glyphs inside the em box, so the ink is smaller than the requested size. At 1× there is no sub-pixel detail to upscale from, so thin strokes (chevrons, checkmarks, plus signs, outline glyphs) came out with visible staircase edges. Every customIcon path in the package routes through this function: CNButton, CNPopupMenuButton, CNTabBar, CNIcon, CNGlassButtonGroup.
Fix: the glyph is rasterised onto a canvas scaled to 2× the device pixel ratio, and the re-blit downscales with FilterQuality.high instead of the Paint() default of FilterQuality.none. Output dimensions are unchanged.
Measured on an iPhone 16 Pro / iOS 26 simulator against a ground-truth render — mean absolute alpha error, chevron at 20 pt, 3× screen:
| intermediate buffer | MAE | |
|---|---|---|
| before | 27k px | 7.00 |
FilterQuality change alone |
27k px | 6.82 |
2× canvas + FilterQuality.high |
108k px | 2.98 |
| 4× linear (font and canvas) | 434k px | 1.78 |
The FilterQuality change on its own is close to a no-op — the re-blit is only a ~1.1× upscale, so the filter barely matters and it measured worse on 5 of 12 glyph/size combinations. The intermediate resolution was the actual problem. The last row is what PR #67 originally proposed; it measures better but is not distinguishable at real icon sizes, and it costs 16× the pixels in a buffer that is walked pixel-by-pixel to find the ink bounds.
Reported and fixed by @azharul-islam (PR #67), refined to 2× on merge.
Performance — iconDataToImageBytes is now memoised #
There was no cache on icon rasterisation, and CNButton and CNIcon build FutureBuilder(future: iconDataToImageBytes(...)) inside build() — so every rebuild re-ran three canvas passes plus a pixel-by-pixel scan of the intermediate buffer.
Results are memoised per (glyph, font, size, colour, device pixel ratio). Futures rather than results are cached, so concurrent callers share one rasterisation; and because FutureBuilder only re-subscribes when its future's identity changes, those widgets now keep their snapshot across rebuilds instead of dropping back to a blank placeholder. The map is capped at 256 entries with oldest-first eviction, since size is caller-supplied and can be animated. clearIconImageCache() is exported for tests and for apps that swap icon fonts at runtime.
Example app #
- New:
Testing → PR #66: glass imageAsset tint— puts the same artwork through SF Symbol,customIcon, uncolouredimageAssetand explicitly colouredimageAsseton a glass button, over a selectable backdrop (black / white / photo / split) and either brightness. Includes a deliberately four-colour row as the regression check for template flattening, plus popup-menu and button-group rows. - New:
Testing → PR #67: icon supersampling— renders the same glyph through the renderer with the supersample factor andFilterQualityexposed as separate knobs, blown up nearest-neighbour so real pixels are visible, with mean-alpha-error and intermediate-buffer cost per variant. - New:
Testing → PR #69: LiquidGlass config.effect— one panel perCNGlassEffect.valuesover vertical stripes that never vary along y, so every panel sees a pixel-identical backdrop and two panels that render differently can only differ because of the glass. Backdrop switches to a photo for the over-imagery case. - New:
example/lib/pr_probe_entry.dart— an alternate entrypoint that boots straight into one test page in one configuration via--dart-define, for capturing before/after screenshots without tapping through the demo list.
1.5.4 #
Fixed — #64 LiquidGlassContainer glass renders short in the bottom safe area #
When a LiquidGlassContainer's frame reached into the bottom safe area — the common "floating bottom panel" layout on home-indicator devices — the native glass stopped short of the frame it was given. Flutter-drawn children stayed in the right place, so they visually spilled outside the glass.
Cause: LiquidGlassContainerPlatformView hosts the SwiftUI glass in a UIHostingController, which propagates the screen's safe area into its SwiftUI content. Where the platform view's frame overlapped the home-indicator inset, the hosted GeometryReader/shape was inset by that overlap, so the glass filled only the reduced size.
Fix: self.hostingController.safeAreaRegions = [], matching the intent of the existing safeAreaInsets override in CupertinoSwitchPlatformView.swift. safeAreaRegions is iOS 16.4+ and the class is already @available(iOS 26.0, *), so no extra availability guard is needed.
Reported and fixed by @fbernack (PR #64), who measured up to 22 pt short on an iPhone 17 Pro (iOS 26.4 simulator). Independently reproduced and verified on a physical iPhone running iOS 26.5: with a 140 pt panel pinned flush to the bottom of a 34 pt inset, the glass fell ~21 pt short of its frame before the fix and filled it completely after.
macOS is unaffected — LiquidGlassContainerNSView uses NSHostingController, and macOS windows have no bottom safe-area inset in practice.
Example app #
- New:
Testing → PR #64: LiquidGlass safe-area clip— a glass panel whose bottom offset, height, and shape (rect/capsule/circle) are adjustable live. A solid red strip fills exactly the safe-area inset (the zone the bug leaves uncovered), a Flutter-drawn magenta outline marks the panel's true frame, and a cyan dashed line marks the safe-area boundary — so "glass short of frame" is directly visible rather than a judgement call. Sliding the bottom offset past the boundary shows whether the glass stays attached to its frame.
1.5.3 #
Fixed — #62 CNTabBar taps swallowed by ancestor gesture recognizers #
CNTabBar stopped responding to taps whenever any ancestor widget held an active gesture recognizer over the same region. The reporter's minimal repro:
GestureDetector(
onLongPress: () {}, // any active recognizer is enough
child: CNTabBar(items: [...], currentIndex: i, onTap: ...),
)
Tapping a tab did nothing. In the wild this surfaced via requests_inspector, which wraps the whole app in a long-press GestureDetector — installing it silently killed the tab bar.
Cause: _buildNativeTabBarPlatformView constructed the iOS UiKitView / macOS AppKitView without a gestureRecognizers set. With none supplied, the platform view is a passive arena participant and only receives touches if nothing else claims them, so the ancestor won uncontested.
Fix: both platform-view branches now pass Factory<EagerGestureRecognizer>(() => EagerGestureRecognizer()). EagerGestureRecognizer.addAllowedPointer immediately calls resolve(GestureDisposition.accepted), so the platform view claims the pointer on pointer-down and touches forward to the native UITabBar regardless of what is competing.
Note the trade-off: gestures made directly over the tab bar (long-press, drag) now go to the native bar instead of bubbling to ancestor recognizers. This is the intended behaviour for a tab bar, which is only ever tapped.
Reported and originally patched by @MohamedAboElM3aTy (#62, PR #63). The submitted patch used a bare TapGestureRecognizer(), which is a no-op — Flutter's TapGestureRecognizer.isPointerAllowed returns false when none of onTapDown/onTap/onTapUp/onTapCancel/onTapMove are set, so the recognizer never enters the arena. Amended to EagerGestureRecognizer before merge and verified on-device (iPhone, iOS 26.5).
Known — same gap remains in other components (#65) #
The identical issue affects other platform-view widgets and is tracked in #65. It is not a uniform fix, so it was deliberately kept out of this release:
button.dart,switch.dart,slider.dart,popup_menu_button.dartpass a bareTapGestureRecognizer()and therefore carry the same latent no-op.segmented_control.dart,glass_button_group.dart,icon.dart,liquid_glass_container.dart,floating_island.dart,search_bar.dart,search_scaffold.dartpass nogestureRecognizersat all.- Several of those must not get a claiming recognizer —
icon.dartis decorative (it would steal taps from parent widgets),liquid_glass_container.dart/floating_island.dart/search_bar.dartdeliberately wrap the platform view inIgnorePointerand handle interaction Flutter-side, andsearch_scaffold.dart's view isPositioned.fillbehind all Flutter content. - The button-like components need an armed tap recognizer (
TapGestureRecognizer()..onTap = () {}) rather than an eager one, so drags still fall through to a parent scrollable —button.dart:654documents that intent explicitly.
Example app #
- New:
Testing → #62 / PR #63: CNTabBar tap gesture arena— three switchable scenarios verifying the fix on-device: an ancestorGestureDetector(onLongPress:)(the reporter's minimal repro), an ancestorPageView(drag-vs-tap competition), and a no-ancestor baseline for regression coverage. Each scenario avoids nesting aScrollablein the gesture region so ancestor gestures resolve deterministically.
1.5.2 #
Fixed — #61 CNBottomSheet.showCupertino compile error on Flutter < 3.44 #
CNBottomSheet.showCupertino in v1.5.1 called Flutter's showCupertinoSheet() with a scrollableBuilder: named parameter. That parameter was only added to showCupertinoSheet in Flutter 3.44.0 (via flutter/flutter#177337, 2026-01-23). Anyone consuming the package on stable 3.35 – 3.41.x — including a substantial share of production Flutter users, FlutterFlow environments, and CI setups — hit a hard compile error:
No named parameter with the name 'scrollableBuilder'.
Fix: switched to builder: (the current API on 3.35 – 3.41; deprecated-but-still-accepted on 3.44+). The lambda didn't use its ScrollController anyway, so the swap is behaviour-preserving. Compatible from Flutter 3.35 through today's master.
Thanks @ArkayGit for the clean, precisely-scoped bug report.
Fixed — #46 CNToast queue deadlock after route pop #
CNToast stored the caller's BuildContext on each queued _ToastEntry and re-resolved Overlay.of(entry.context) inside _showNext() — which fires from a Timer after each toast's duration. If the caller's widget was disposed while toasts were pending (typical: user shows a toast then taps back), the framework crashed with:
Looking up a deactivated widget's ancestor is unsafe.
Worse, after the throw, _isShowing was left true and the queue was permanently stuck — every subsequent CNToast.show/success/error/warning/info call would silently _queue.add() without displaying, until app restart. Only CNToast.loading() still worked (it bypasses the queue and inserts into the overlay directly).
Fix (in lib/components/toast.dart):
_ToastEntrynow stores anOverlayState(resolved eagerly atCNToast.show()time), not aBuildContext._showNext()no longer touches the caller's context and cannot throw on a deactivated widget.- Added
entry.overlay.mountedshort-circuit and atry/catcharoundoverlay.insert(...)— if the OverlayState disappears between enqueue and display (extremely rare), the entry is dropped and the queue keeps draining._isShowingis guaranteed to reset.
Fixed — #46 CNToast renders with yellow double-underline under MaterialApp (reporter's screenshot) #
The same issue also carried a second, unrelated defect surfaced by @macedondev's screenshot: text rendered as dim red monospace with a yellow double-underline. That's MaterialApp._errorTextStyle (flutter/lib/src/material/app.dart:45), Flutter's built-in "your Text has no Material ancestor" debug fallback. MaterialApp installs it as the ambient DefaultTextStyle at the app root; _ToastOverlay renders its Text inside an OverlayEntry with no Material between them, so the fallback style wins. CupertinoApp doesn't install _errorTextStyle, which is why the maintainer couldn't reproduce the bug locally.
Fix: wrap the toast content in Material(type: MaterialType.transparency, ...) inside _ToastOverlay.build(), positioned between IgnorePointer and Align so Positioned still sees the Overlay's Stack as its direct parent (a Material between them would break Positioned's parent-data contract and throw Incorrect use of ParentDataWidget). Transparent Material paints nothing, so CupertinoApp users see no visual change; MaterialApp users get proper text-style resolution and the yellow underlines are gone. Applies to both the queued (_showNext()) and direct-insert (loading()) toast paths.
Thanks @macedondev for the report.
Example app #
- New:
Testing → #46: CNToast use_build_context_synchronously— two labeled scenarios. Bug A (queue crash on dispose): spam-and-pop button that queues 5 toasts then pops the route ~250ms in, reproducing the "Looking up a deactivated widget's ancestor" crash pre-fix and demonstrating the queue-drains-cleanly behaviour post-fix. Bug B (yellow underlines): a route whose body is a nestedMaterialAppsoCNToastfires into an overlay with the ambient_errorTextStyle— reproduces the reporter's exact rendering. Plus a quick-trigger row for all sixCNToast.*variants for regression coverage.
1.5.1 #
Fixed — #53 PlatformView z-order bleed under bottom sheets #
iOS hybrid composition was reusing the same PlatformViewContainer for both a host-page CN-widget and a CN-widget inside a presented sheet, causing the host-page widget's pixels to leak through the sheet's scrim (and vice-versa).
Fix: new ModalHideMixin (in lib/utils/modal_hide_mixin.dart) applied to all 9 CN widgets that use a PlatformView — CNButton, CNGlassButtonGroup, CNSwitch, CNSegmentedControl, CNPopupMenuButton, CNSearchBar, CNLiquidGlassContainer, CNFloatingIsland, CNSlider. Each widget now destroys its PlatformView (with a same-size placeholder reserving the layout slot) while a sheet covers it, and recreates it when the sheet dismisses.
Each affected widget gained an autoHideOnModal: bool = true constructor parameter so users can opt out per-instance.
New — CNBottomSheet + CNSheetGeometryProbe #
For the modal-hide to be position-aware (only widgets actually behind the sheet hide, not the entire host route), the sheet has to publish its rect each frame. Two new public APIs cover this:
-
CNBottomSheet(inlib/components/bottom_sheet.dart) — drop-in wrappers that inject the probe automatically:CNBottomSheet.show(context: context, builder: (ctx) => MySheet()); CNBottomSheet.showCupertino(context: context, builder: (ctx) => MySheet()); CNBottomSheet.showModalPopup(context: context, builder: (ctx) => MySheet()); -
CNSheetGeometryProbe— wrap your own sheet builder manually if you need to keep using the framework APIs directly:showModalBottomSheet( context: context, builder: (ctx) => CNSheetGeometryProbe(child: MySheet()), );
Without one of these the package falls back to a conservative "hide every CN-widget on this route while any modal is up" behavior — safe, but coarser than needed (an app-bar CN-button could disappear behind a 30%-height sheet).
CNTabBarRouteObserver also gained topModalRect: ValueNotifier<Rect?> and publishTopModalRect(Rect?), used by the probe.
Fixed — #55 CNPopupMenuItem.isDestructive #
CNPopupMenuItem gained isDestructive: bool = false. When true:
- iOS 14+ adds
UIMenuElement.Attributes.destructive→ the label renders in the system destructive red (previously only the icon could be red viaiconColor). - iOS 13 legacy fallback uses
UIAlertAction.Style.destructive. - iOS < 26 / non-iOS Cupertino fallback uses
CupertinoActionSheetAction(isDestructiveAction: true).
Thanks @ashellz for the report.
Fixed — CNGlassButtonGroup remount blink #
CNGlassButtonGroup's FutureBuilder returned SizedBox.shrink() for one frame between the modal-hide placeholder removal and the platform view actually mounting — text below jumped up then back down on every sheet dismiss. The pending branch now mirrors the placeholder's axis-aware dimensions so the layout slot is held across the swap.
Fixed — PR #57 macOS CNSwitch rendered as a checkbox #
The macOS Toggle defaulted to a checkbox under recent SDKs. Applied .toggleStyle(.switch) to force the switch appearance. iOS unaffected. Thanks @jonathanfristedt.
Fixed — MissingPluginException storm during transitions #
ch.invokeMethod('setTransitioning', …) calls now use .catchError((_) {}) to swallow async rejections, and fallback platform-view classes (iOS < 26) register no-op MethodChannel handlers so Dart-side calls from ModalHideMixin and route-transition containment don't throw.
Docs #
pubspec.yamldocumentation:now points to https://gunumdogdu.com/docs.- README documents
CNBottomSheet/CNSheetGeometryProbeusage and the navigatorObserver requirement for modal-hide to work.
Example app #
- New:
Testing → #53: CNButton under bottom sheet— four sheet-opener variants over a host page full of CN widgets. - New:
Testing → #55: PopupMenu isDestructive— text, icon, and mixed menus with destructive items. - New:
Testing → Glass widgets modal halo test— all 9 CN widgets behind sheets. - New:
Testing → CNButton modal halo test— modal route push/pop animations. - New:
Testing → #37: CNAppBar button halo test.
Known limitations #
CNGlassButtonGroupglass merging at default spacing still shows a "dumbbell" between buttons. The single-uniform-pill rewrite hit a SwiftUI hit-testing limitation (.glassEffect()intercepts touches at a layer below.allowsHitTesting(false)); a UIKitUIVisualEffectViewrewrite is queued for the next release.
1.5.0 #
New — CNTabBarNative gains minimize, native lists, accessory & root mode #
Building on the existing CNTabBarNative (the native iOS 26 Liquid Glass tab bar), this release adds:
- Minimize-on-scroll (resolves #32) —
minimizeBehavior:withCNTabMinimizeBehavior.{automatic, never, onScrollDown, onScrollUp}, changeable at runtime viasetMinimizeBehavior(...). Requires a tab backed by aCNNativeList, since iOS drives the minimize from a real native scroll view. - Native list tabs —
CNTab(nativeList: CNNativeList(items: [CNListItem(...)]))renders a native scrollable list;onListItemTap(tabIndex, itemIndex)reports taps. NewCNNativeList/CNListItemmodels (now exported from the package). - Bottom accessory pill —
bottomAccessory: CNTabAccessory(...)floats above the bar and slides inline when it minimizes;onAccessoryTapreports taps; show/update/hide at runtime withsetBottomAccessory(...)(passnullto hide). - Presentation modes —
asRoot:selects modal presentation (default) or root presentation; in root mode a tab with nonativeListhosts your real Flutter UI. - Search filtering option —
nativeSearchFilter(defaulttrue) filters the search tab's own list locally; setfalseto drive results yourself viaonSearchChanged+setItems. - Mutation API —
setItems(...)for dynamic/paginated data, plusonDismissed(fires when the bar is closed natively, e.g. via the ✕ button).
The native manager was rewritten (CNNativeTabBar.swift replaces CNNativeTabBarManager.swift) on a stable SwiftUI TabView view tree.
Docs #
- Rewrote the README "Native iOS 26 Tab Bar (CNTabBarNative)" section: native-takeover mental model, a
CNTabBarvsCNTabBarNativecomparison table, presentation modes, and a per-method API reference. Added a preview GIF (minimize + accessory + search). - Documented that
CNTabBarNativeis a native takeover, not a Flutter bottom-nav — for Flutter screens per tab, useCNTabBar(clarifies #7).
Deprecated #
CNTabBarNative.enableparametersonSearchSubmitted,onSearchCancelled,onSearchActiveChanged— the search tab now reports throughonSearchChanged; these are no longer fired and will be removed in a future major release.CNTabBarNative.checkIsEnabled()— use the synchronousisEnabledgetter instead.
Notes #
- #48 (color the unselected tab item): investigated and intentionally not added to
CNTabBar. iOS 26's Liquid Glass tab bar enforces the system color for unselected items and ignores customization — verified on-device with both the legacyUITabBar.unselectedItemTintColorand the modernUITabBarAppearanceper-stateiconColor/ titleforegroundColor. The selectedtintis honored; the unselected state is system-owned, so a public knob would silently no-op on the package's target OS.
1.4.6 #
Bug Fixes #
- Fixed #39 / merged PR #42 —
CNTabBar.iconSizeis now honored forcustomIconitems (anyIconDatalikeCupertinoIcons.houseorIcons.home). Previously the custom-icon rasterizer was hardcoded to 25pt regardless of the bar-leveliconSizeor per-itemicon.size. Bug originally surfaced via #39 (SVGimageAssetlayout glitch on v1.4.3) and addressed by @Azzeccagarbugli's PR #42, with an extra refinement on top:lib/components/tab_bar.dart:_prepareCreationParamsnow passeswidget.iconSize ?? item.icon?.size ?? 25.0toiconDataToImageBytes; same precedence onactiveCustomIcon;_buildTabIcon(Flutter fallback) mirrors the precedence across all icon kinds.lib/utils/icon_renderer.dart: full rewrite oficonDataToImageBytes. Drops the heavyRenderRepaintBoundary+BuildOwnersetup in favor of aTextPainter+ canvas + alpha-channel crop approach. Final step (refinement on top of the PR): re-blit the cropped glyph into a squaresize × sizecanvas with the glyph scaled to fill, so custom icons at a given pointSize match SF Symbol's visible ink at the same pointSize (matches SF Symbol's "pointSize is ink size" convention — previously, font em-box padding made customIcon visually smaller than equivalent SF Symbols at the same size).test/widget_test.dart: 6 new widget tests verifying theiconSize > icon.size > 25ptprecedence across SF Symbol / customIcon / imageAsset in the Flutter fallback path.
New #
-
Swift Package Manager support — fixes #44. The plugin now ships a
Package.swiftmanifest for both iOS and macOS targets and is recognized bypanaas "Swift PM-ready".Flutter's SPM rollout is well underway: SPM support landed in Flutter 3.24 (Aug 2024) as opt-in, became the default for new apps in Flutter 3.44, and CocoaPods is being phased out — Firebase stops publishing to CocoaPods in October 2026 and the CocoaPods registry becomes read-only on December 2, 2026. Plugins without SPM support already lose pana points and trigger build warnings on modern Flutter versions.
Compatibility (no users locked out): the plugin's own pubspec constraints stay at
sdk: ^3.9.0/flutter: '>=3.3.0'. The SPMPackage.swiftsits alongside the existing podspec and is only consulted by Flutter 3.24+. Older Flutter consumers continue to resolve the package via CocoaPods exactly as before — the podspec'ssource_filespath was updated to point at the new SPM-shaped source directory (ios/cupertino_native_better/Sources/cupertino_native_better/**, mirrored on macOS) so both build paths produce the same result.Consumer Flutter Build path 3.3 – 3.23 (pre-SPM) CocoaPods via podspec. Package.swift ignored. Unchanged from v1.4.5. 3.24 – 3.43 (SPM opt-in) CocoaPods by default; SPM if flutter config --enable-swift-package-manageris set. Both paths work.3.44+ (SPM default) SPM via Package.swift.Thanks to @josec-ecw for the PR.
Example app #
- Added:
Testing → PR #42: CNTabBar iconSize (customIcon)— three side-by-sideCNTabBars (SF Symbol / customIcon / SVG imageAsset) with aniconSizeslider so all three icon kinds can be verified to scale identically. Four Stratis UI Figma SVGs bundled (camera-01,card-add,chromecast,home-03) — same source as #39 reporter — for SVG verification.
Pana #
- 160/160 (now includes "Swift PM-ready" recognition)
1.4.5 #
Bug Fixes #
-
Fixed #35 / #41 (recreate animation on launch + navigation) —
CNTabBarno longer plays a visible "morph through every tab" animation on app launch or after navigating away and back.- Launch glitch (#35): Swift
refreshcyclesbar.selectedItemthrough every tab to force UITabBar's label layout (workaround for an old "5 items, sporadic missing labels" bug — Issue #6). On iOS 26 with Liquid Glass, that cycling was visible as the selection pill morphing through every tab. The cycle is now wrapped inUIView.setAnimationsEnabled(false) … true— labels still render correctly, but the pill no longer animates between items. Tab bar appears instantly with the configuredcurrentIndex. - Recreate-on-return (#41 part 1):
autoHideOnPageTransitionpreviously swapped the platform view to aSizedBoxduring route slides, destroying the nativeUITabBar. On return, a fresh view was created and_onCreatedre-ransetSelectedIndex+refresh→ visible animate-to-index. Fix: whenautoHideOnPageTransitionis on,CNTabBar.buildnow always returns anIndexedStack(children:[SizedBox, UiKitView]); only the painted index toggles between 0 and 1 across the transition. TheUiKitView's element stays mounted in both states, so the nativeUITabBaris preserved across navigation. Bar just appears with the correct index, no animation.
- Launch glitch (#35): Swift
-
Fixed #41 (PlatformViewGuard 500 ms fallback flash on first build) — non-iOS26 fallback widgets briefly visible during cold start.
- Cause:
PlatformViewGuard.ensureScheduledalways delayed platform-view creation by 500 ms to give Flutter'sFlutterPlatformViewsControllertime to purge stale registrations from a previous Dart isolate after a hot restart. That race only exists in debug; release builds (cold-start, no isolate recycling) were paying the same flash-of-fallback cost for nothing. - Fix:
PlatformViewGuardis now ready immediately inkReleaseMode. Native iOS 26 widgets render from the first frame in production; debug-mode hot-restart safety is preserved unchanged.
- Cause:
-
Fixed #36 follow-up —
LiquidGlassContainer's rectangular layer drop shadow leaking past its rounded glass corners while a modal/sheet was presented above (was already targeted in v1.4.4 but only clipped the rectangular layer bounds; rounded clip wasn't applied across all shape configurations correctly). The corner-radius clip inapplyTransitionContainmentnow consistently matchesrect(configured cornerRadius),capsule(min(width, height)/2), andcircle(min(width, height)/2) — no more square shadow nubs.
New #
-
Fixed #40 (CNButton label customization) —
CNButtonConfignow accepts:labelFontFamily— custom font family (must be registered inInfo.plistor as a Flutter font asset).labelFontSize— point size override.labelColor— explicit foreground color (overrides thetint-derived default for non-filled styles, and the system default for filled / borderedProminent / prominentGlass).labelFontWeight— FlutterFontWeightoverride.
Implementation: Swift side applies them via
UIButton.Configuration.titleTextAttributesTransformer, so the overrides take effect on the native label without losing the iOS 26 Liquid Glass / prominent / tinted button background. Both creation-time (creationParams) and runtime (setLabelStylechannel call from_syncPropsToNativeIfNeeded) updates are supported. FlutterFontWeight.value(0-8) is mapped toUIFont.Weight.Example:
CNButton( label: '1', tint: CupertinoColors.systemOrange, onPressed: () {}, config: const CNButtonConfig( style: CNButtonStyle.prominentGlass, width: 80, minHeight: 80, labelFontSize: 36, labelFontWeight: FontWeight.w600, labelColor: CupertinoColors.white, ), )
Behavioural details #
CNTabBar.autoHideOnPageTransitionkeeps its defaulttrue. With the IndexedStack-based hide it's now zero-cost: state is preserved across navigation while still preventing the original page-wide PlatformViewLayer occlusion artifact during route slides.- Multi-label
CNButton(e.g. dial-pad style: large number + small letters underneath) is intentionally not added toCNButton's API. The same effect composes cleanly viaLiquidGlassContainerwrapping aColumnof two FlutterTexts — fullTextStylefreedom on both labels with the native iOS 26 Liquid Glass background. See the closing comment on Issue #40 for a snippet.
Example app #
- Added:
Testing → #40: CNButton label style— interactive screen for verifying the new label-style params (font-size slider, color swatches, font-family segmented control, style picker).
Pana #
- 160/160
1.4.4 #
Bug Fixes #
- Fixed #36 —
LiquidGlassContainer's rectangular layer drop shadow leaking past its rounded glass corners while a modal/sheet was presented above. Visible as four square shadow nubs at the card's corners through the modal's scrim, even though the visible glass was rounded.- Root cause:
applyTransitionContainment(true)(added in v1.4.3 for the dynamic halo containment) only setclipsToBounds = trueon the container's CALayer, which clips to the rectangular layer bounds — leaving the four corners outside the rounded glass shape unclipped. The layer's drop shadow rendered into those corners and bled through the modal scrim. - Fix: in
LiquidGlassContainerView.swift,applyTransitionContainment(true)now also setscontainer.layer.cornerRadius(and the hosting view's) to match the configured glass shape:rectshape → uses the configuredcornerRadiuscapsule/circle→min(width, height) / 2
- The clip is now rounded, matching the visible glass exactly. Reverted to 0 when containment goes inactive so it doesn't affect the at-rest visual.
- Root cause:
Documentation #
- README: added a prominent "Required Setup: register
CNTabBarRouteObserver" section directly under Quick Start, documenting:- Why the observer is needed (hybrid composition, halo containment, z-order with sheets).
- Where to register it:
CupertinoApp/MaterialApp/GoRoutersnippets. - What it fixes across all 7 glass widgets, with explicit references to Issues #29, #31, #36.
- Manual
markAnyModalActive/markAnyModalInactiveAPI for non-route overlays (Scaffold.showBottomSheet). - Several users reported needing this observer to fix sheet bleed-through; with this section it should now be impossible to miss during initial setup.
Example app #
- Added:
Testing → #36: LiquidGlassContainer behind modal— focused reproduction page for Issue #36. Card-shapedLiquidGlassContainermatching the issue reporter's_AdaptiveGlassContainerwidget exactly (cornerRadius: 15,rect,EdgeInsets.all(13), no tint), four sheet variants including the reporter's exactshowModalBottomSheetinvocation (rounded top, scaffold-bg,Clip.antiAlias, bounce animation,useRootNavigator: true), and aCalendarDatePickerinside each sheet matching the modal content from the issue's screenshots. White scaffold + black/white pill buttons mirror the reporter's app styling.
Pana #
- 160/160
1.4.3 #
Bug Fixes #
-
Fixed #34 — CNButton glass capsule not stretching with its parent frame; icon overflowing a small pill when wrapped in
SizedBox/Expanded. Regression introduced in v1.4.0.- Root cause: the v1.4.0 "feat: fixes" commit added always-on
container.clipsToBounds = true+uiButton.clipsToBounds = true(plus layer shadow/background clearing) across every iOS 26 glass widget as part of the #29 halo containment.UIButton.Configuration.glass()renders its capsule via an internal background subview whose visual size includes a soft-edge glow extending slightly beyond the button's layer bounds — the always-on clipping was cropping that glow AND preventing the capsule from growing with a stretched frame. - Fix: reverted all the always-on clipping across
CNButton,CNPopupMenuButton,CNFloatingIsland,CNGlassButtonGroup,LiquidGlassContainer,CNSearchBar. Containers are unclipped at rest, so the glass capsule renders its full soft-edge glow and stretches properly withSizedBox/Expanded/Container(width: ...).
- Root cause: the v1.4.0 "feat: fixes" commit added always-on
-
Fixed #29 (fully) — the original halo-during-route-transition artifact is now resolved via a dynamic containment pattern instead of always-on clipping. This also catches the popup/sheet bleed cases that the v1.4.0 fix didn't cover (popup routes, persistent bottom sheets).
- New native method
setTransitioning(active:)onCNButton,CNPopupMenuButton,CNFloatingIsland,CNGlassButtonGroup,LiquidGlassContainer,CNSearchBar, and the regularCNTabBarvariant. When active, it applies the halo-containment clipping + shadow/background clearing; when inactive, it reverts. - Dart side listens to two signals and calls
setTransitioning(true)when either fires:ModalRoute.secondaryAnimation— catchesCupertinoPageRoute/MaterialPageRouteforward/reverse transitions.- A new
CNTabBarRouteObserver.anyModalDepthcounter that tracks anyPopupRoute/ Sheet / Popup / Dialog-named route (showCupertinoSheet,showCupertinoModalPopup,showModalBottomSheet,DialogRoute, etc.).
- For the split-search variant of
CNTabBar(whose native container is intentionally unclipped so the floating search orb can render above the bar), the auto-hide trigger is broadened toanyModalDepthso popups over a search-enabled tab bar no longer leak shadow through the sheet's top edge.
- New native method
New #
-
CNTabBarRouteObserver.anyModalDepth(read-onlyValueListenable<int>) — broader counter than the existingmodalDepth. Tracks every modal-like route (allPopupRoutes plus any route whose runtime type containsSheet/Popup/Dialog). Used internally by the glass widgets for halo-containment activation. -
CNTabBarRouteObserver.markAnyModalActive()/markAnyModalInactive()— public manual API for non-route overlays thatNavigatorObservercan't see, notablyScaffold.showBottomSheet(persistent bottom sheet anchored toScaffoldState, not the Navigator):final controller = Scaffold.of(context).showBottomSheet(...); CNTabBarRouteObserver.markAnyModalActive(); controller.closed.whenComplete(CNTabBarRouteObserver.markAnyModalInactive);
Example app #
- Added:
Testing → CNButton modal halo test— stretched CNButton variants + 4 sheet types (showCupertinoSheet,showCupertinoModalPopup,showModalBottomSheet,showBottomSheet) for verifying halo containment across every overlay variant. - Added:
Testing → Glass widgets modal halo test— same 4-sheet matrix againstCNPopupMenuButton,CNGlassButtonGroup,LiquidGlassContainer,CNSearchBar,CNFloatingIsland. - Updated:
Stack+Positioned tab barandSplit-search clip reproscreens now include all 4 sheet types for regression coverage. - Added:
DefaultMaterialLocalizations.delegateto the rootCupertinoAppso demos can mixshowModalBottomSheet(Material) with Cupertino routes without addingflutter_localizations.
Behavioural details #
- At rest, glass widgets render the full iOS 26 Liquid Glass capsule (including the soft-edge glow that extends slightly beyond the view's layer bounds) and stretch to fill bounded parent frames. This matches native iOS behaviour.
- During a route transition or while a modal/sheet/popup/dialog is above the widget's route, the native container is clipped and layer shadows are suppressed — the visible change is essentially invisible (the widget's visible frame is unchanged), but Flutter snapshots of the outgoing/incoming page no longer include a halo that extends past the platform-view bounds.
CNTabBarwithoutsearchItemstill uses the narrow Sheet-onlymodalDepthheuristic for its auto-hide (avoids the recreate-and-restore flash on quick action-sheet popups).CNTabBarwithsearchItemuses the broaderanyModalDepthbecause its container can't be clipped (the floating search orb needs to render above the bar's top edge).
Pana #
- 160/160
1.4.2 #
New #
-
CNTabBarRouteObserver— aNavigatorObserverthat letsCNTabBarauto-hide while a full-screen sheet is presented over its route. Resolves Issue #31 (MaterialTextFieldinvisible insideshowCupertinoSheetwhenCNTabBaris in the bottom nav slot).The native
UITabBaris rendered inside a FlutterUiKitView. When a Flutter-rendered sheet route is presented over the same navigator, hybrid composition can leave the tab bar's UIView at a higher z-index than the modal's Flutter content — makingTextFields inside the sheet invisible and letting the bar bleed through during sheet drags. Auto-hide swaps the platform view for an empty placeholder while the sheet is up, mirroring what iOS does natively when aUITabBarControllerpresents a full-screen modal.Setup (one line per app):
CupertinoApp( navigatorObservers: [CNTabBarRouteObserver()], // ... )Or
MaterialApp(navigatorObservers: [CNTabBarRouteObserver()], ...). Without this observer registered,CNTabBarstill renders correctly — it just won't auto-hide on top of sheets and you may hit the Issue #31 z-order glitch. -
CNTabBar(autoHideOnModal: bool = true)— opt-out for the auto-hide behaviour. Defaulttrue. Setfalseto keep the tab bar visible behind sheets (rare; typically requires a native sheet that won't trigger the z-order issue).
Bug Fixes #
- Fixed: tab bar's selected index resetting to 0 after a modal/sheet closed and the platform view was recreated (Issue #2 page repro).
- Root cause: in
_onCreatedwe calledrefreshbeforesetSelectedIndex. The nativerefreshmethod (a workaround for the 5-item-label-rendering bug Issue #6) capturesbar.selectedItemat start, cycles through items asynchronously, then "restores" the captured value — overriding thesetSelectedIndex(currentIndex)we sent right after, leaving the bar stuck at the stalecreationParams.selectedIndex = 0. - Fix: swapped the order —
setSelectedIndexnow runs BEFORErefresh. Refresh then captures the correct index and restores to it. Applied to both the 50ms and 200ms recreation passes.
- Root cause: in
Behavioural details #
- Auto-hide is intentionally narrow: it triggers only for routes whose runtime type name contains
Sheet(CupertinoSheetRoute,ModalBottomSheetRoute). Action-sheet popups (CupertinoModalPopupRoute), dialogs, and regular page pushes do NOT trigger auto-hide. This avoids a visible "platform view recreate + index restore" jump animation on quick popups, while still fixing the z-order issue for full-screen sheets.
Example app #
- Added:
Testing → #31: TextField — NO search variant (hypothesis test)— same flow as the Issue #31 reproduction but withCNTabBarconfigured withoutsearchItemandautoHideOnModal: false, used to verify the bug isn't search-specific. - Added: registered
CNTabBarRouteObserver()on the example app'sCupertinoAppso all demo screens benefit from auto-hide.
Pana #
- 160/160
1.4.1 #
Bug Fixes #
- Fixed:
CNTabBariOS 26 Liquid Glass selection pill was being cropped at its top edge after the v1.4.0 Issue #2 fix.- Root cause: v1.4.0 clipped the platform-view container to block the Liquid Glass drop shadow from bleeding over modal bottom sheets. The same clip also cut off the selection pill, which extends ~12–14pt above the bar's top during its morphing animation between tabs.
- Resolution: the container still clips (shadow containment preserved), but the UITabBar is now positioned 14pt below the container's top edge, and the reported intrinsic height is bar-height + 14pt. The Liquid Glass selection pill — including its morph animation when rapidly switching tabs — renders fully inside the clipped container. Bar's visible position is unchanged at the bottom of the allocated space.
- Applied to all 5 layout sites: single-bar init, split-bar init, and the equivalent setLayout rebuilds, for both iOS 26+ and iOS < 26 code paths.
Example app #
- Added:
Testing → #33: SVG in CNTabBar— reproduction screen mirroring the SVG-icons-in-CNTabBar pattern reported in Issue #33, including the reporter'sNavBarItemwrapper,iconSize: 24, andtintconfiguration. Local iOS 26 verification shows SVGs render correctly; the screen is published so the reporter (and future users hitting the same symptom) can confirm on their own setup. - Added:
Testing → Stack+Positioned tab bar— demonstrates theStack+Positioned(bottom: 0)layout pattern as an alternative toScaffold.bottomNavigationBarfor users who need custom z-order control. - Enhanced:
Testing → CNTabBar split-search clip— bright teal background and a modal-bottom-sheet trigger button so both the search-orb top-edge clip and the Issue #2 shadow-bleed scenarios can be verified side-by-side on one screen. - Bumped: example app iOS deployment target from 14.0 to 15.0 (required by the plugin's
s.platform = :ios, '15.0').
Known issues #
- iOS simulator (not real device): iOS 26 Liquid Glass rendering on the simulator is software-rasterized and has visible differences from real Metal hardware. You may see the Liquid Glass selection pill appear slightly clipped at the top, or a brief rectangular outline around buttons on press. These artifacts do not appear on real iOS 26 devices. Always verify Liquid Glass behavior on a real iPhone/iPad before treating a visual quirk as a package bug.
Pana #
- 160/160
1.4.0 #
Bug Fixes #
-
Fixed:
CNTabBartop-edge shadow bleeding over modals / bottom sheets — the regression of Issue #2 that landed between v1.3.0 and v1.3.8 (Issue #2)- Root cause: in v1.3.3 the
clipsToBounds = truecontainment from the original v1.3.0 fix was made conditional and disabled on iOS 26+. That removed the only thing keeping the UITabBar's top-edge hairline inside the platform view's bounds. container.clipsToBounds = truerestored unconditionally on the regular tab-bar platform view (5 sites — single-bar and split-bar in bothinitandsetLayout)- Added
bar.shadowImage = UIImage()on everyUITabBarinstance as belt-and-suspenders against iOS 26 ignoring the appearance-level shadow override
- Root cause: in v1.3.3 the
-
Fixed: Liquid Glass halo rendering outside platform-view bounds during iOS route transitions — the "placeholder square" reported across CNButton, CNTabBar, and other widgets (Issue #29)
- Root cause: iOS 26 Liquid Glass effects (
UIButton.Configuration.glass(),UITabBarglass material,.glassEffect()SwiftUI modifier) render a translucent halo that extends slightly outside the view's frame. Without containment, that halo became visible during route transitions as a square outline around the widget on the outgoing page. - Same containment pattern as Issue #2 applied to:
CNButton,CNPopupMenuButton,CNSearchBar,CNFloatingIsland,CNLiquidGlassContainer container.clipsToBounds = true,container.layer.shadowOpacity = 0,container.layer.backgroundColor = clear,container.isOpaque = falseplus the same on the inner subview where applicable
- Root cause: iOS 26 Liquid Glass effects (
-
Fixed:
CNTabBarwithsearchItem— the floating Liquid Glass search orb's top edge was being cropped (commented in Issue #31 by @el2zay)- The iOS 26+ search-tab-bar variant (
CupertinoTabBarSearchPlatformView) now leaves its container un-clipped so the search orb can render its top edge correctly. Top-edge hairline is still suppressed viabar.shadowImage = UIImage()andbar.layer.shadowOpacity = 0, so the original Issue #2 shadow bleed does not return.
- The iOS 26+ search-tab-bar variant (
-
Fixed:
CNGlassButtonGroupbadge X-position — the last badge floated near the screen edge instead of sitting on its button when buttons were centered as a tight pill inside a wider containerupdateBadgePositions()now estimates each button's rendered width from icon size + padding + minHeight (capsule width = max(intrinsic, minHeight)), computes the centered-HStack starting offset, and places each badge at the actual button's top-right corner instead of dividing container width evenly across button count.
-
Fixed:
CNGlassButtonGroupAuto Layout_UITemporaryLayoutWidth = 0warning on initial mount — silenced by lowering hosting-view constraint priorities to.defaultHighso UIKit can break them silently during the brief temp-width=0 phase without logging.
Test demos added #
Testing → #2: Modal bottom sheet shadow— opens aCupertinoModalPopupover aCNTabBarso the top-edge shadow bleed (or its absence) is easy to inspectTesting → #29: Per-widget halo test— one slow-transition push per widget so each can be verified in isolationTesting → CNTabBar split-search clip—CNTabBarwith asearchItemso the floating orb is easy to inspect at the bottom-rightTesting → #31: TextField disappear in modal— MaterialScaffold+CNTabBar(withsearchItem) inbottomNavigationBar, opens a modal sheet with a MaterialTextFieldand aCupertinoTextFieldfor comparison
Pana #
- 160/160
1.3.9 #
New Features #
- Added:
checkedproperty onCNPopupMenuItemfor checkmark/selected state (Issue #28)- Native iOS uses
UIAction.state = .onfor native checkmark display - Supports single-selection, multi-selection, and mixed checked+disabled states
- Flutter fallback shows a checkmark icon before the label
- Native iOS uses
Bug Fixes #
- Fixed:
PlatformException(recreating_view)on iOS hot restart (PR #30 by @lucakramberger)- New
PlatformViewGuardutility delays platform view creation during startup CNTabBarrefactored from nested FutureBuilders to state-managed async pipeline- Native
deinitcleanup added to tab bar platform views
- New
1.3.8 #
Bug Fixes #
- Fixed: macOS build — resolved 5 compilation errors in native Swift code
badgeCountparameter missing fromsetupSwiftUIButtonmethod.clearcolor inference onCALayer.backgroundColor(now usesNSColor.clear.cgColor)FlutterPlatformViewprotocol replaced withNSViewfor LiquidGlassContainer- Removed invalid
namespaceargument fromGlassButtonSwiftUIcall NSButton.titlenon-optional handling
1.3.7 #
New Features #
- Added: Popup menu button support in
CNGlassButtonGroupviaCNButtonData.popup()(PR #23 by @byackee)- Mix regular icon buttons and popup menu buttons in the same glass button group
- Native SwiftUI rendering with
UIMenusupport CNButtonDataPopupItemmodel for popup menu items
- Added:
labelFontFamilyandlabelFontSizeproperties forCNTabBar(PR #26, Issue #16 by @byackee)- Customize tab bar label font with any registered font family
- Dynamic font updates via method channel
Bug Fixes #
- Fixed:
buttonCustomIconColornow works on iOS 26 with Liquid Glass rendering (PR #24, Issue #21 by @byackee)- Color is now sent to the native side via
capturedButtonIconColor - Native side applies
.withTintColor(.alwaysOriginal)to preserve custom icon colors - Menu item
iconColoralso supported for customIconDataicons
- Color is now sent to the native side via
- Fixed:
CNSwitchno longer pushed upward by keyboard (PR #25, Issue #4 by @byackee)- iOS 16.4+: uses
safeAreaRegions.remove(.keyboard)official API - Pre-iOS 16.4: runtime fix targeting the hosting view's private keyboard notification handler
- iOS 16.4+: uses
1.3.6 #
Bug Fixes #
- Fixed: Horizontal glass button group "waist" effect — reduced toolbar shrinkage between adjacent buttons by enforcing minimum 80pt glass spacing for horizontal groups with 2+ buttons (PR #20 by @byackee)
- Fixed:
CNTabBarnow shows a Flutter fallback tab bar while the native view initializes, instead of blank space for ~2 seconds (Issue #5) - Fixed:
CNTabBarwith 5 items no longer has sporadic missing labels — added a second refresh pass for slow-to-initialize native views (Issue #6)
Improvements #
- Added: macOS podspec for CocoaPods support (Issue #10)
1.3.5 #
Bug Fixes #
- Fixed:
CNTabBariconSizenow correctly applies toCNImageAsset(SVG/image) icons (Issue #19)- Previously, only SF Symbol icons respected the
iconSizeproperty - Image assets loaded via
loadFlutterAssetandcreateImageFromDatanow receive the size parameter
- Previously, only SF Symbol icons respected the
1.3.4 #
New Features #
- Added:
interactionproperty forCNButtonConfigandCNButtonDataConfig(PR #15 by @anirudhrao-github)- Allows disabling button touch handling without changing visual appearance
- When
interaction: false, button maintains normal look but doesn't respond to touches - Useful for conditional interactivity while preserving UI consistency
Improvements #
- Improved:
LiquidGlassContainerlayout simplified for better parent alignment control
1.3.3 #
New Features #
-
Added:
customIconSizeproperty forCNButtonConfigandCNButtonDataConfig(PR #12 by @anirudhrao-github)- Allows customizing the size of custom icons (IconData) in buttons
- Previously hardcoded to 20.0 points, now configurable
-
Added:
iconSizeproperty forCNTabBarto control SF Symbol icon sizes- Supports dynamic icon sizing with automatic height adjustment
- Note: Icons above 30pt may have minor visual quirks due to UITabBar constraints
Bug Fixes #
-
Fixed:
CNGlassButtonGroupno longer forces equal width on all buttons (PR #12 by @anirudhrao-github)- Buttons now use their intrinsic width based on content
- Label buttons can now be wider than icon-only buttons in the same group
- Uses SwiftUI
.fixedSize(horizontal: true, vertical: false)for proper sizing
-
Fixed:
CNTabBar.onTapnow fires for reselects (Issue #13)- Previously, tapping the already-selected tab did not trigger the callback
- Now all taps fire
onTap, allowing scroll-to-top or navigation reset on reselect
-
Fixed:
CNTabBaricon clipping on iOS 26+ Liquid Glass- Disabled
clipsToBoundson iOS 26+ to allow proper Liquid Glass pill overflow - Tab bar height now adjusts dynamically based on icon size
- Disabled
Improvements #
- Improved: Initial layout rendering for
CNGlassButtonGroup- Added immediate layout pass after view creation for correct first render
1.3.2 #
New Features #
- Added: Badge support for
CNGlassButtonGroupicon buttons (PR #11 by @anirudhrao-github)- New
badgeCountproperty onCNButtonData.icon()for displaying notification badges - Badges display as red circles with white text, showing "99+" for counts over 99
- Uses UIKit overlay on iOS to prevent glass effect sampling artifacts
- Proper clipping during page transitions
- New
Improvements #
-
Improved: Added library-level documentation for better API discoverability
- Enhanced dartdoc comments for
button,button_data,button_style, andcupertino_nativelibraries - 91.4% API documentation coverage
- Enhanced dartdoc comments for
-
Fixed: Dart formatting issues for pub.dev compliance
- Resolved formatting in
button.dartandglass_button_group.dart - Achieves 160/160 pana score
- Resolved formatting in
1.3.1 #
Bug Fixes #
- Fixed: Tint color now works correctly when buttons are inside
CNGlassButtonGroup(PR #8 by @anirudhrao-github)- Previously, button tint colors were ignored when placed inside grouped glass buttons
- Now buttons properly inherit and display their configured tint colors within button groups
1.3.0 #
New Features #
-
Added:
CNTabBarNative- Native iOS 26 Tab Bar with full UITabBarController integration- Uses native
UITabBarController+UISearchControllerfor authentic iOS 26 liquid glass effects CNTabBarNative.enable()/CNTabBarNative.disable()for app-level tab bar managementCNTabclass for tab configuration with SF Symbols and search tab support- Callbacks:
onTabSelected,onSearchChanged,onSearchSubmitted,onSearchCancelled,onSearchActiveChanged - Full badge count support and dynamic styling
- Uses native
-
Added:
CNSearchScaffold- Native search scaffold controller for standalone search UI -
Added:
CNToast- Toast notification widget with Liquid Glass effects- Static methods:
show(),success(),error(),warning(),info(),loading() - Duration presets: short (2s), medium (3.5s), long (5s)
- Position options: top, center, bottom
- Auto-dismiss with queue management
CNLoadingToastHandlefor dismissing loading toasts
- Static methods:
-
Added:
labelproperty toCNTabBarSearchItemfor customizing the search tab label- Defaults to 'Search' to match iOS native behavior
-
Added:
preserveTopToBottomOrderproperty toCNPopupMenuButton(Issue #3)- When
true, menu items maintain top-to-bottom order (1,2,3,4) regardless of menu direction - Default
falsepreserves native iOS behavior where item 1 stays closest to the button - Uses
UIDeferredMenuElement.uncachedfor dynamic position detection
- When
Improvements #
-
Enhanced:
PlatformVersionnow auto-initializes on first access- No longer need to call
await PlatformVersion.initialize()inmain() - Just use
PlatformVersion.isIOS26OrLaterdirectly - Old
initialize()method kept for backwards compatibility (marked deprecated)
- No longer need to call
-
Added: New helper properties to
PlatformVersion:isIOS,isMacOS,isAndroid,isAppleisIOSVersionInRange(min, max),isMacOSVersionInRange(min, max)
Bug Fixes #
-
Fixed:
CNPopupMenuButton.iconnow respects the order defined in items (Issue #3)- Added
preserveTopToBottomOrderparameter to control item ordering behavior - Native iOS behavior keeps first item closest to button; set
preserveTopToBottomOrder: truefor consistent top-to-bottom order
- Added
-
Fixed: Tab bar shadow artifact appearing over modals and bottom sheets (Issue #2)
- Changed
configureWithDefaultBackground()toconfigureWithTransparentBackground() - Added explicit shadow removal:
shadowColor = .clear,shadowImage = UIImage() - Added
container.clipsToBounds = trueandlayer.shadowOpacity = 0
- Changed
-
Fixed: Search bar keyboard auto-opening behavior (Issue #1)
automaticallyActivatesSearch: falsenow properly prevents keyboard from auto-opening- This is native iOS behavior - the search bar expands but keyboard only opens on text field tap
1.2.0 #
New Features #
-
Added: iOS 26 Search Tab Feature for CNTabBar with animated Liquid Glass expansion
- Native
UISearchTab-style search integration that follows Apple's iOS 26 design - Search button expands into a full search bar with smooth spring animation
- Tabs collapse to icon-only mode when search is active
- Full Flutter fallback for iOS < 26 with identical behavior
- Native
-
Added:
CNTabBarSearchItemconfiguration class for search tab customizationplaceholder: Custom placeholder text for the search fieldonSearchChanged: Callback for live filtering as user typesonSearchSubmit: Callback when user submits searchonSearchActiveChanged: Callback for expand/collapse state changesautomaticallyActivatesSearch: Control keyboard auto-activation behavior
-
Added:
CNTabBarSearchStylefor visual customization- Icon sizes, colors, and active states
- Search bar dimensions, padding, and border radius
- Animation duration control
- Clear button visibility toggle
-
Added:
CNTabBarSearchControllerfor programmatic search controlactivateSearch()/deactivateSearch(): Expand/collapse search programmaticallytextproperty: Get/set search textclear(): Clear search text with optional deactivation- Listener support for reactive state management
Improvements #
- Enhanced:
automaticallyActivatesSearchnow properly controls keyboard behavior- When
false: Search bar expands but keyboard only opens when user taps the text field - When
true(default): Keyboard opens automatically when search expands - Mirrors
UISearchTab.automaticallyActivatesSearchfrom UIKit
- When
Bug Fixes #
- Fixed:
MissingPluginExceptionerrors during hot reload forsetItemsandrefreshmethods- Added try-catch error handling to prevent crashes during development
- Search view now handles all expected method channel calls
1.1.9 #
New Features #
- Added: Lightweight
setBadgesmethod for CNTabBar to update badge values without rebuilding the entire tab bar- Previously, badge updates required recreating all tab bar items which caused visible flicker
- New implementation only updates
badgeValueon existing UITabBarItems for smooth, instant badge changes - Automatically detected when only badges changed (not labels, icons, or symbols) and uses fast path
Improvements #
- Optimized: CNTabBar now detects badge-only updates in
_syncPropsToNativeIfNeeded()and calls lightweight nativesetBadgesmethod instead of fullsetItemsrebuild - Performance: Badge updates are now instant with no view recreation or animation interruption
1.1.7 #
Fixes #
-
Fixed: Split mode tab selection bug where the wrong tab appeared selected on first load
- Issue: When using
split: truein CNTabBar, the right bar (e.g., Rewards tab) would incorrectly appear selected even when the left bar tab (e.g., Discover) was actually selected - Root Cause: In the
refreshmethod, when restoring selection after cycling through tabs for label rendering, the code was incorrectly settingright.selectedItem = rightItems.firstwhenrightOriginalwas nil - Solution: Changed to restore the original selection directly (
right.selectedItem = rightOriginal), which correctly keeps the right bar unselected when a left bar tab is active
- Issue: When using
-
Fixed: Added
setSelectedIndexcall afterrefreshin Flutter widget to ensure correct selection state after view initialization
1.1.5 #
Breaking Changes #
- iOS Minimum Version: Raised iOS deployment target from 13.0 to 15.0
- Required for
@FocusStateand other iOS 15+ SwiftUI features - Most production apps already target iOS 15+ (released September 2021)
- Required for
Fixes #
- Fixed: Swift compiler error
'FocusState' is only available in iOS 15.0 or newer - Fixed: Swift compiler error
'self' used before 'super.init' callin CNSearchBar - Fixed: Pod installation issues when used in projects with iOS 15+ deployment target
1.1.3 #
Fixes #
- Fixed: Full 50/50 pub.dev static analysis score (160/160 pana points)
- Fixed: All remaining lint and formatting issues
1.1.0 #
Documentation Overhaul #
- Added: Complete documentation for all widgets with real iOS 26 screenshots
- Added: CNSwitch documentation with controller examples
- Added: CNPopupMenuButton documentation with text and icon variants
- Added: CNSegmentedControl documentation with SF Symbols support
- Added: Button Styles Gallery showcasing multiple button styles
- Added: Popup menu opened state preview image
- Enhanced: Features table with Controller column
- Enhanced: All images now use centered alignment for better presentation
New Screenshots #
- Real iOS 26 Liquid Glass component screenshots (replacing AI-generated placeholders)
- Button styles gallery (4 preview images)
- Switch, Slider, Popup Menu, Segmented Control, Tab Bar previews
- Popup menu opened state preview
Test Suite Updates #
- Added: Comprehensive widget tests for CNSearchBar, CNFloatingIsland, CNGlassButtonGroup
- Added: Controller tests for CNSearchBarController, CNFloatingIslandController, CNSliderController
- Added: Data model tests for CNButtonData, CNButtonDataConfig, CNSymbol, CNImageAsset
- Updated: Platform and method channel tests with error handling and null response tests
- Updated: Enum tests for all new enums (CNGlassEffect, CNGlassEffectShape, CNSpotlightMode, etc.)
- Total: 82 tests covering all major components and APIs
1.0.6 #
Improvements #
- Fixed: Dart formatting issues to achieve full 50/50 static analysis score on pub.dev
- Added: Preview image for pub.dev package page
1.0.5 #
Improvements #
Static Analysis Cleanup
- Fixed: All
use_build_context_synchronouslywarnings by capturing context-derived values before async gaps - Fixed:
dangling_library_doc_commentswarning - Fixed:
unnecessary_library_nameandunnecessary_importwarnings - Improved: Pub points score (static analysis section)
1.0.4 #
Bug Fixes #
CNButton Tap Detection (iOS < 26 Fallback)
- Fixed: Unreliable tap detection in CupertinoButton fallback mode
- Issue: Buttons showed press animation but
onPresseddidn't fire consistently - Solution: Added
minSize: 0to prevent CupertinoButton's internal minimum size from conflicting with SizedBox constraints - Added: Explicit
borderRadiusandpressedOpacityfor better hit testing and visual feedback
1.0.3 #
Bug Fixes #
Critical: iOS 18 Crash Fix
- Fixed: Reverted GestureDetector overlay that caused crash on iOS 18
- Error:
unrecognized selector sent to instance 'onTap:' - Solution: Removed Stack/GestureDetector approach, kept simple CupertinoButton
Icon Button Padding (kept from 1.0.2)
- Fixed: Increased default padding for icon buttons from 4 to 8 pixels
1.0.2 (BROKEN - DO NOT USE) #
Bug Fixes #
CNButton Tap Detection (iOS < 26 Fallback)
- BROKEN: Added GestureDetector overlay that crashed on iOS 18
- Use 1.0.3 instead
Icon Button Padding
- Fixed: Increased default padding for icon buttons from 4 to 8 pixels
- Icons now have proper breathing room from the button border
1.0.1 #
- Pub Points Improvement: Addressed static analysis issues to improve package score.
- Fix: Resolved
use_build_context_synchronouslywarnings across multiple components. - Fix: Replaced deprecated
Color.valueandwithOpacityusages with modern alternatives. - Documentation: Added missing documentation for public members.
1.0.0 #
Major Release - Complete iOS Fallback Fixes
This release addresses critical issues that caused components to malfunction on iOS versions below 26.
Breaking Changes #
- Package renamed from
cupertino_native_plustocupertino_native_better - Main import changed to
package:cupertino_native_better/cupertino_native_better.dart
Bug Fixes #
CNButton Label Disappearing (iOS < 26)
- Fixed: Buttons with both icon AND label now correctly display both elements in fallback mode
- Root Cause:
widget.isIconwas returningtruefor any button with an icon, even if it also had a label - Solution: Changed fallback check to
widget.isIcon && widget.label == nullto only treat truly icon-only buttons as icon-only
CNTabBar Icons Not Showing (iOS < 26)
- Fixed: Tab bar icons now render correctly using CNIcon instead of empty placeholder circles
- Root Cause: Fallback code only checked for
customIcon, ignoring SF Symbols (icon/activeIcon) - Solution: Added
_buildTabIcon()helper that properly handles all icon types with correct priority
CNIcon/CNButton/CNPopupMenuButton Showing "..." (iOS < 26)
- Fixed: All CN components now properly render SF Symbols on older iOS versions
- Root Cause: Components were checking
shouldUseNativeGlass(iOS 26+) for SF Symbol support, but SF Symbols work on iOS 13+ - Solution: Added new
supportsSFSymbolsgetter that always returns true on iOS/macOS
New Features #
- Added
PlatformVersion.supportsSFSymbolsfor checking SF Symbol availability (iOS 13+, macOS 11+) - Comprehensive dartdoc documentation for all public APIs
- Full comparison table with other packages in README
Documentation #
- Complete rewrite of README with feature comparison
- Migration guide from cupertino_native_plus
- Comprehensive code examples for all widgets
0.0.9 #
- Package preparation for public release
- Updated repository URLs
0.0.8 #
- Fixed SF Symbol rendering in fallback mode for CNButton
- Fixed SF Symbol rendering in fallback mode for CNPopupMenuButton
- Added proper imports for CNIcon in button and popup components
0.0.7 #
- Added
supportsSFSymbolsgetter to PlatformVersion - SF Symbols now render natively on all iOS versions (13+), not just iOS 26+
- Separated Liquid Glass support (iOS 26+) from SF Symbol support (iOS 13+)
0.0.6 #
- Dark Mode Support for LiquidGlassContainer: Added automatic dark mode detection and synchronization for LiquidGlassContainer, ensuring the glass effect correctly adapts to Flutter's theme changes
- Gesture Detection Fixes: Fixed gesture handling in LiquidGlassContainer by wrapping platform views in IgnorePointer, preventing the native view from intercepting touch events and allowing child widgets to receive gestures properly
- Brightness Syncing Improvements: Enhanced brightness synchronization for icons and other components, ensuring they automatically update when the system theme changes
0.0.5 #
- Performance Improvements: Added method channel updates for button groups to prevent full rebuilds and eliminate freezes when updating button parameters
- Preserved Animations: Button groups now update smoothly without losing native animations when button properties change (icon, color, image asset, etc.)
- Efficient Updates: Implemented granular updates for individual buttons in groups, only updating changed buttons instead of rebuilding the entire group
- Reactive SwiftUI Updates: Converted button group SwiftUI views to use ObservableObject pattern for efficient reactive updates
- Button Parameter Updates: Individual buttons in groups can now be updated dynamically via method channels without full view rebuilds
0.0.4 #
- PNG Image Support: Added full support for PNG images in all components (buttons, icons, popup menus, tab bars, glass button groups)
- Automatic Asset Resolution: Implemented automatic asset resolution based on device pixel ratio, similar to Flutter's automatic asset selection. The system now automatically selects the appropriate resolution-specific asset (e.g.,
assets/icons/3.0x/checkcircle.pngfor @3x devices) or falls back to the closest bigger size - ImageUtils Consolidation: Consolidated all image loading, format detection, scaling, and tinting logic into a shared
ImageUtils.swiftclass for better code maintainability and consistency - Fixed PNG Rendering: Fixed PNG image rendering issues in buttons and glass button groups
- Fixed Image Orientation: Fixed image flipping issues for both PNG and SVG images when colors are applied
- Made buttonIcon Optional: Made
buttonIconparameter optional inCNPopupMenuButton.iconconstructor, allowing developers to use onlybuttonImageAssetorbuttonCustomIcon - Improved Glass Effect Appearance: Fixed glass effect appearance synchronization with Flutter's theme mode to prevent dark-to-light transitions on initial render
- Enhanced Image Format Detection: Improved automatic image format detection from file extensions and magic bytes
- Better Fallback Handling: Improved fallback behavior when asset paths fail to load, ensuring images still render from provided image bytes
0.0.3 #
- Updated README to showcase all icon types (SVG assets, custom icons, and SF Symbols)
- Added comprehensive examples for all icon types in Button, Icon, Popup Menu Button, and Tab Bar sections
- Added icon support overview at the beginning of "What's in the package" section
- Clarified that all components support multiple icon types with unified priority system
0.0.2 #
- Updated README with corrected version requirements and improved documentation
- Fixed iOS minimum version requirement (13.0 instead of 14.0)
- Removed incorrect Xcode 26 beta requirement
- Added Contributing and License sections
- Improved package description and introduction
0.0.1 #
- Initial release
- Fixed iOS 26+ version detection using Platform.operatingSystemVersion parsing
- Native Liquid Glass widgets for iOS and macOS
- Support for CNButton, CNIcon, CNSlider, CNSwitch, CNTabBar, CNPopupMenuButton, CNSegmentedControl
- Glass effect unioning for grouped buttons
- LiquidGlassContainer for applying glass effects to any widget
