base_widgets library

Base Widgets Library

Exports all adaptive widgets and components for building cross-platform UIs. Each widget automatically selects between Cupertino (iOS) and Material (Android/Fuchsia) implementations.

Core Widgets

  • BaseApp: Root application widget with theme support
  • BaseScaffold: Platform-aware scaffold with app bar and navigation
  • BaseAppBar: Adaptive app bar supporting custom actions
  • BaseButton: Multi-variant button supporting Material 3 and Cupertino styles
  • BaseNavigationBar: Bottom navigation bar with adaptive styling
  • BaseTabBar: Tab bar supporting Material 3 and Cupertino tab views

Native Components (iOS)

Material 3 Components

Classes

ActionSheetNavigationService
Navigation service for accessing context when needed
BaseActionSheet
Base wrapper for ActionSheet with native iOS support and cross-platform compatibility
BaseActionSheetAction
Represents a single action in an action sheet (cross-platform data model)
BaseActionSheetWidget
BaseActionSheetWidget (Deprecated - Old Widget-based Implementation)
BaseAlert
BaseAlert - Cross-platform native alert dialogs
BaseAlertAction
Represents an action button in an alert (cross-platform data model)
BaseAlertDialog
BaseAlertDialog with iOS 26 Liquid Glass Dynamic Material and Material 3 support
BaseApp
BaseApp theme, use cupertinoTheme by cupertino，use materialTheme by material. use CupertinoApp by cupertino not support CupertinoApp.router yet. *** use cupertino = { forceUseMaterial: true } force use MaterialApp/GetMaterialApp on cupertino. use MaterialApp or GetMaterialApp by material (controlled by useGetX parameter) not support MaterialApp.router yet. *** use material = { forceUseCupertino: true } force use CupertinoApp on material.
BaseAppBar
BaseAppBar
BaseBarItem
BaseBarItem use BottomNavigationBarItem by cupertino *** use cupertino = { forceUseMaterial: true } force use BottomNavigationBarItem on cuperitno. use BottomNavigationBarItem by material *** use material = { forceUseCupertino: true } force use BottomNavigationBarItem on material.
BaseBottomToolbar
BaseBottomToolbar - Cross-platform bottom toolbar with expandable search
BaseButton
BaseButton
BaseClass
Base class Cupertino mode uses buildByCupertino method, Material mode uses buildByMaterial method *** Parameters
BaseCNActionSheet
Legacy alias for backward compatibility
BaseCNAlert
@Deprecated - Use BaseAlert instead
BaseCNBottomToolbar
@deprecated Use BaseBottomToolbar instead.
BaseCNIcon
BaseCNIcon - Native iOS icon using SF Symbols via CNIcon
BaseCNPullDownButton
@Deprecated - Use BasePullDownButton instead
BaseCNToolbar
@Deprecated - Use BaseToolbar instead
BaseCupertinoInteractiveKeyboard
Base wrapper for CupertinoInteractiveKeyboard with cross-platform support
BaseCustomImageKey
Metadata for custom image-based tab bar items
BaseDialogAction
BaseDialogAction with iOS 26 Liquid Glass Dynamic Material and Material 3 support
BaseIcon
use Icon by cupertino *** use cupertino = { forceUseMaterial: true } force use Icon on cuperitno. use Icon by material *** use material = { forceUseCupertino: true } force use Icon on material.
BaseIconButton
BaseIconButton
BaseIndicator
BaseIndicator use CupertinoActivityIndicator by cupertino *** use cupertino = { forceUseMaterial: true } force use CircularProgressIndicator on cuperitno. use CircularProgressIndicator by material *** use material = { forceUseCupertino: true } force use CupertinoActivityIndicator on material.
BaseNativeSheet
BaseNativeSheet - Cross-platform native sheet with iOS UISheetPresentationController support
BaseNativeTabBarItemKey
Metadata for converting BottomNavigationBarItem to CNTabBarItem
BaseNavigationBar
Internal: CNNavigationBarAction from cupertino_native package Used only for iOS platform channel communication Public API should use BaseNavigationBarAction instead BaseNavigationBar - Cross-platform navigation bar with native iOS support
BaseNavigationBarAction
Cross-platform navigation bar action
BaseParam
Personalization parameters specific to Base components
BasePlatformMode
Runtime platform mode By default iOS, macOS use cupertino mode, others use material mode
BasePopupButton
BasePopupButton - Cross-platform popup button with native iOS support
BasePopupMenuButton
A cross-platform popup menu button that adapts to the platform
BasePopupMenuItem
Data class representing a popup menu item
BasePullDownButton
Internal: CN* classes from cupertino_native package Used only for iOS platform channel communication Public API should use Base* classes instead BasePullDownButton - Cross-platform pull-down button with native iOS support
BasePullDownButtonAnchor
BasePullDownButtonAnchor - Cross-platform pull-down button with menu anchoring
BasePullDownInlineAction
Inline action for horizontal button row at top of menu
BasePullDownMenuDivider
Menu divider for visual separation
BasePullDownMenuEntry
Abstract base class for all pull-down menu entries Used for type safety in menu construction
BasePullDownMenuInlineActions
Container for inline actions (horizontal row of buttons)
BasePullDownMenuItem
Regular menu item with icon, label, and optional callback
BasePullDownMenuSubmenu
Submenu with nested menu items
BaseRefresh
BaseIndicator use CustomScrollView + CupertinoSliverRefreshControl by cupertino *** use cupertino = { forceUseMaterial: true } force use RefreshIndicator on cuperitno. use RefreshIndicator by material *** use material = { forceUseCupertino: true } force use CupertinoSliverRefreshControl on material.
BaseRoute<T>
BaseRoute use CupertinoPageRoute or CupertinoButton.filled by cupertino *** use cupertino = { forceUseMaterial: true } force use MaterialPageRoute on cuperitno. use MaterialPageRoute *** use material = { forceUseCupertino: true } force use CupertinoPageRoute on material.
BaseScaffold
BaseScaffold use CupertinoPageScaffold by cupertino, tab's scaffold use CupertinoTabScaffold *** use cupertino = { forceUseMaterial: true } force use Scaffold on cuperitno. use Scaffold by material *** use material = { forceUseCupertino: true } force use CupertinoPageScaffold/CupertinoTabScaffold on material.
BaseScrollBar
BaseScrollBar use CupertinoScrollbar by cupertino *** use cupertino = { forceUseMaterial: true } force use Scrollbar on cuperitno. use Scrollbar by material *** use material = { forceUseCupertino: true } force use CupertinoScrollbar on material.
BaseSearchBar
BaseSearchBar - Cross-platform search bar with native iOS support
BaseSection
BaseSection use custom Container by cupertino or material
BaseSectionDivider
BaseSegmentedControl
BaseSegmentedControl - Cross-platform segmented control with native iOS support
BaseSlider
BaseSlider - Cross-platform slider with native iOS support
BaseState<T extends BaseStatefulWidget>
BaseStatefulWidget
Base stateful widget Cupertino mode uses buildByCupertino method, Material mode uses buildByMaterial method *** Parameters
BaseStatelessWidget
Base stateless widget Cupertino mode uses buildByCupertino method, Material mode uses buildByMaterial method *** Parameters
BaseSwitch
BaseSwitch - Cross-platform switch with native iOS support
BaseTabBar
BaseTabBar with iOS 26 Liquid Glass Dynamic Material and Material 3 support
BaseTabScaffold
BaseTabScaffold use CupertinoTabScaffold by cupertino *** use cupertino = { forceUseMaterial: true } to force use Scaffold material，use Scaffold by material *** use material = { forceUseCupertino: true } to force use CupertinoTabScaffold
BaseTextField
use CupertinoTextField by cupertino *** use cupertino = { forceUseMaterial: true } force use TextField on cuperitno. use TextField by material *** use material = { forceUseCupertino: true } force use CupertinoTextField on material.
BaseTile
BaseTile use custom InkWell by cupertino *** use cupertino = { forceUseMaterial: true } force use ListTile on cuperitno. use ListTile by material *** use material = { forceUseCupertino: true } force use custom InkWell on material.
BaseToolbar
Internal: CNToolbarAction from cupertino_native package Used only for iOS platform channel communication Public API should use BaseToolbarAction instead BaseToolbar - Cross-platform toolbar with native iOS support
BaseToolbarAction
Cross-platform toolbar action
CNActionSheet
Legacy CNActionSheet class for backward compatibility
CNActionSheetAction
iOS-specific action sheet action (internal use only)
CNAlert
Legacy CNAlert class for backward compatibility
CNAlertAction
iOS-specific alert action (internal use only)
CNBottomToolbar
Legacy CNBottomToolbar class for backward compatibility
CNPullDownButtonAnchor
A Cupertino-native pull-down button with automatic menu anchoring.
CNPullDownMenuDivider
A visual divider between pull-down menu items.
CNPullDownMenuEntry
Base type for entries in a CNPullDownButton menu.
CNPullDownMenuItem
A selectable item in a pull-down menu.
CNSearchBar
Legacy CNSearchBar class for backward compatibility
CNSearchConfig
Configuration for search integration in native components.
CNSheetDetent
Detent heights for resizable sheets (iOS only)
CNSheetInlineAction
An individual inline action button for sheets.
CNSheetInlineActions
A horizontal row of inline action buttons in a native sheet.
CNSheetItem
An item to display in a native sheet
CNSheetItemRow
A horizontal row of vertical-style items displayed side-by-side.
CNSymbol
Describes an SF Symbol to render natively.
CupertinoInputAccessory
Input Accessory for keyboard toolbars
CupertinoInteractiveKeyboard
Legacy CupertinoInteractiveKeyboard class for backward compatibility
HeightObserver
A widget that observes and reports changes to its child's height.
HeightObserverRenderObject
Render object that tracks height changes for a widget.
Navigation service for accessing context when needed
SFSymbols
Common SF Symbol mappings for standard navigation icons

Enums

BaseActionSheetActionStyle
Action style for action sheet actions (cross-platform)
BaseAlertActionStyle
Action style for alert actions (cross-platform)
BaseDialogActionType
Material 3 button type for dialog actions
BaseMode
Platform build mode
BaseToolbarAlignment
Toolbar middle alignment options
CNActionSheetButtonStyle
iOS-specific action sheet button style (internal use only)
CNAlertActionStyle
iOS-specific alert action style (internal use only)
CNAutocapitalizationType
Auto-capitalization type
CNAutocorrectionType
Auto-correction type
CNButtonStyle
Visual styles for CNButton and related controls.
CNKeyboardAppearance
Keyboard appearance
CNKeyboardType
Keyboard type
CNReturnKeyType
Return key type
CNSearchBarStyle
Search bar visual style
CNSpellCheckingType
Spell checking type
WidgetBuildMode
Widget actual build mode

Extensions

BottomNavigationBarItemNativeExtension on BottomNavigationBarItem
Extension to make it easier to add SF Symbol metadata to BottomNavigationBarItem

Properties

currentBaseMode → BaseMode
no setter
defaultBaseMode ↔ BaseMode?
Default runtime mode
getter/setter pair
isCupertinoMode → bool
build by Cupertino
no setter
isMaterialMode → bool
build by Material
no setter
withoutSplashOnCupertino ↔ bool
在cupertino模式下是否禁用水波纹
getter/setter pair

Functions

pushBaseRoute<T extends Object?>(BaseRoute<T> baseRoute, BuildContext context, {bool rootNavigator = false}) → Future<T?>
Navigator.push
pushBaseRouteAndRemoveUntil<T extends Object?>(BaseRoute<T> baseRoute, BuildContext context, RoutePredicate predicate, {bool rootNavigator = false}) → Future<T?>
Navigator.pushAndRemoveUntil
setBasePlatformMode({BasePlatformMode? basePlatformMode = const BasePlatformMode()}) → void
Must call this method before building baseApp set the platform
showBaseAlertDialog<T>(BaseAlertDialog alertDialog, BuildContext context, {bool barrierDismissible = true, Color? barrierColor = Colors.black54, String? barrierLabel, bool useSafeArea = true, bool useRootNavigator = true, RouteSettings? routeSettings}) → Future<T?>
showDialog

Typedefs

OnWidgetHeightChange = void Function(double height)
Callback function type for widget height changes.