Cupertino widgets are Flutter widgets that mimic the native iOS design system. They follow Apple's Human Interface Guidelines and visually resemble UIKit components used in iOS apps.
Examples include:
CupertinoButtonCupertinoSwitchCupertinoNavigationBarCupertinoTabScaffoldCupertinoDatePicker
They are part of the Flutter SDK and live in the cupertino library.
They matter when you care about platform authenticity. iOS users expect different visuals and interactions than Android users, especially for navigation bars, switches, and dialogs.
Using Cupertino widgets helps Flutter apps feel less "cross-platform" and more native on iOS.
Cupertino widgets are not native iOS views. They are rendered by Flutter itself (Skia), just like Material widgets. This means:
- no platform channels
- consistent behavior across iOS versions
- predictable performance
Animations, paddings, and scroll physics are tuned to feel "iOS-native".
Cupertino widgets should be used when a Flutter app needs to strictly follow iOS design principles.
They are particularly useful if the application is iOS-only or when replacing an existing native iOS app and aiming to preserve a familiar look and feel. Cupertino widgets provide native-like controls and navigation patterns, such as:
- Sliding page transitions
- iOS-style switches
- Pickers
- Tab bars
These elements help ensure consistency with the Apple Human Interface Guidelines (HIG).
Cupertino widgets are also appropriate when targeting users who expect a highly iOS-native experience, for example in:
In these domains, users are often sensitive to platform-specific UI patterns.
It is also possible to mix Cupertino widgets inside a MaterialApp. Wrapping the entire app in CupertinoApp is not required. For example, developers can use:
CupertinoButtonCupertinoSwitch
on selected screens while continuing to use Material components elsewhere.
Cupertino widgets are not ideal when an app is cross-platform and aims to maintain a consistent visual language across iOS and Android.
Using Cupertino widgets across multiple screens in such cases can lead to:
- Duplicated layouts
- Increased complexity when maintaining separate Material and Cupertino variants
They should also be avoided when platform-specific design is not required or when strictly following Apple Human Interface Guidelines is not a priority. In these situations, using Material or custom widgets helps:
- Keep a simpler, unified codebase.
- Reduce maintenance overhead.
- Avoid unexpected behavior on Android.
Overusing Cupertino widgets can also complicate:
- Responsive layouts
- Theming
- Testing
This is because the application must handle subtle differences in rendering and interaction patterns between Cupertino and Material widgets.
Common mistakes to avoid
Common issues when using Cupertino widgets usually come from misunderstandings about how they interact with the Flutter ecosystem.
- Thinking
CupertinoApp is required to use Cupertino widgets. - Mixing
CupertinoPageScaffold and expecting Material features like FAB. - Seeing yellow underlined text when using
Text without a Material ancestor (Solution: wrap content in Material or provide DefaultTextStyle). - Overusing Cupertino widgets in cross-platform apps.
Best practices
Using Cupertino widgets effectively requires selective and intentional usage:
- Mix Cupertino widgets inside
MaterialApp when needed. - Use
CupertinoPageScaffold only if you fully commit to iOS structure. - Be explicit about text styles when not using Material.
- Prefer adaptive widgets when possible.
Alternatives
Depending on the use case, other approaches may be more appropriate than relying solely on Cupertino widgets:
- Adaptive widgets (
Switch.adaptive, CircularProgressIndicator.adaptive) - Material widgets with iOS theming
- Custom design system built on core Flutter widgets
Cupertino widgets are best used selectively, not as a blanket replacement for Material.
