cupertino_native_better library

Native iOS 26+ Liquid Glass widgets for Flutter.

This library provides native Cupertino widgets that leverage Apple's Liquid Glass design language introduced in iOS 26. All widgets automatically fall back to standard Cupertino or Material widgets on older platforms.

Getting Started

Just import and use! No initialization required:

import 'package:cupertino_native_better/cupertino_native_better.dart';

void main() {
  runApp(MyApp());
}

PlatformVersion now auto-initializes on first access.

Available Widgets

Platform Support

Feature iOS 26+ iOS < 26 macOS 26+ macOS < 26 Other
Liquid Glass Native Cupertino fallback Native Cupertino fallback Material fallback
SF Symbols Native Native Native Native Flutter Icon

Key Features

  • Reliable Version Detection: Uses Platform.operatingSystemVersion parsing instead of platform channels, fixing release build issues.
  • Comprehensive Fallbacks: Every widget gracefully degrades on older OS versions.
  • Multiple Icon Types: SF Symbols, custom IconData, and image assets.
  • Dark Mode Support: Automatic theme synchronization.
  • Glass Effect Unioning: Multiple buttons can share unified glass effects.

Classes

CNBottomSheet
Drop-in wrappers for Flutter's modal sheets that opt the CN-widget family into position-aware hide-on-modal behavior.
CNButton
A Cupertino-native push button.
CNButtonConfig
Configuration for CNButton with default values.
CNButtonData
Data model for button configuration in CNGlassButtonGroup.
CNButtonDataConfig
Configuration options for CNButtonData.
CNButtonDataPopupItem
Item for a popup menu button in CNGlassButtonGroup.
CNFloatingIsland
A floating pill widget inspired by Apple's Dynamic Island.
CNFloatingIslandController
Controller for imperatively managing CNFloatingIsland state.
CNGlassButtonGroup
A group of buttons that can be rendered together for proper Liquid Glass blending effects.
CNGlassCard
EXPERIMENTAL: A card widget with Liquid Glass effects, breathing animation, and spotlight effect that follows touch or responds to device tilt.
CNIcon
A platform-rendered SF Symbol icon, custom image asset, or IconData.
CNImageAsset
Describes a custom image asset to render natively.
CNListItem
A single row in a CNNativeList.
CNLoadingToastHandle
Handle for dismissing a loading toast.
CNNativeList
A natively-rendered, scrollable list used as the content of a tab.
CNPopupGesture
A widget that wraps a child and shows a popup menu on long press.
CNPopupMenuButton
A Cupertino-native popup menu button.
CNPopupMenuDivider
A visual divider between popup menu items.
CNPopupMenuEntry
Base type for entries in a CNPopupMenuButton menu.
CNPopupMenuItem
A selectable item in a popup menu.
CNSearchBar
A native expandable search bar with Liquid Glass effects.
CNSearchBarController
Controller for imperatively managing CNSearchBar state.
CNSearchScaffold
A full-screen scaffold with native iOS 26 tab bar and search support.
CNSearchScaffoldItem
A search scaffold item configuration.
CNSegmentedControl
A Cupertino-native segmented control.
CNSheetGeometryProbe
Invisible probe that lives at the root of a CNBottomSheet builder and publishes the sheet body's live global rect every frame.
CNSlider
A Cupertino-native slider rendered by the host platform.
CNSliderController
Controller for a CNSlider allowing imperative changes to the native NSSlider/UISlider instance.
CNSwitch
A Cupertino-native switch rendered by the host platform.
CNSwitchController
Controller for a CNSwitch that allows imperative updates from Dart to the underlying native UISwitch/NSSwitch instance.
CNSymbol
Describes an SF Symbol to render natively.
CNTab
Configuration for a native tab in CNTabBarNative.
CNTabAccessory
The bottom accessory pill that floats above the tab bar and slides inline into it when the bar minimizes (maps to UITabAccessory).
CNTabBar
A Cupertino-native tab bar. Uses native UITabBar/NSTabView style visuals.
CNTabBarItem
Immutable data describing a single tab bar item.
CNTabBarNative
A configurable native iOS 26 tab bar — the full-screen native take-over (UITabBarController via SwiftUI), with search, minimize-on-scroll, a bottom accessory, native lists, and optional Flutter content per tab — all driven from Dart.
CNTabBarRouteObserver
NavigatorObserver that lets CNTabBar auto-hide while a modal/sheet is presented over its route (Issue #31).
CNTabBarSearchController
Controller for programmatically managing the search tab state.
CNTabBarSearchItem
Configuration for a search tab in CNTabBar.
CNTabBarSearchStyle
Visual styling options for the search tab in CNTabBar.
CNToast
A native toast notification widget.
CupertinoNativeBetter
Top-level facade for simple plugin interactions.
CupertinoNativePlatform
The platform interface that platform implementations of this plugin must extend.
LiquidGlassConfig
Configuration for Liquid Glass effects.
LiquidGlassContainer
A container that applies Liquid Glass effects to its child widget.
MethodChannelCupertinoNative
An implementation of CupertinoNativePlatform that uses method channels.
PlatformVersion
Utility class for checking OS version with caching and auto-initialization.
PlatformViewGuard
Guards platform-view creation during app startup / hot-restart.
ThemeHelper
Utility class for accessing theme data with fallback support.

Enums

CNButtonStyle
Visual styles for CNButton and related controls.
CNFloatingIslandPosition
Position for the floating island.
CNGlassEffect
Liquid Glass effect variants for iOS 26+.
CNGlassEffectShape
Shapes for Liquid Glass effects.
CNImagePlacement
Image placement options for buttons with both image and label.
CNSpotlightMode
Defines the input mode for spotlight effects on glass components.
CNSymbolRenderingMode
Rendering modes for SF Symbols.
CNTabMinimizeBehavior
When the iOS 26 Liquid Glass tab bar collapses to a compact pill.
CNToastDuration
Duration presets for toasts.
CNToastPosition
Position for the toast on screen.
CNToastStyle
Style presets for toasts.

Extensions

LiquidGlassExtension on Widget
Extension on Widget to apply Liquid Glass effects.