Introduction

After iOS SDK updates or Flutter framework upgrades, certain Cupertino widgets become deprecated as Apple changes their design guidelines and Flutter aligns with new patterns. CupertinoScaffold (from the cupertino_icons or community packages) and similar deprecated widgets cause build warnings or runtime issues. Understanding the replacement pattern ensures your app maintains a native iOS feel while staying compatible with the latest Flutter and iOS versions.

Symptoms

  • Build warnings:
  • `
  • 'CupertinoScaffold' is deprecated and shouldn't be used.
  • Use CupertinoPageScaffold instead.
  • `
  • Or:
  • `
  • Warning: CupertinoNavigationBar transition behavior changed in iOS 17.
  • `
  • Navigation transitions look incorrect after iOS update
  • Tab bar behaves differently on iOS 17+
  • Console:
  • `
  • flutter: The behavior of CupertinoPageRoute changed in Flutter 3.16
  • `

Common Causes

  • Using community cupertino_scaffold package that is no longer maintained
  • Flutter framework updating Cupertino widgets to match new iOS design
  • iOS 17+ changes to navigation bar translucency
  • CupertinoTabScaffold API changes in newer Flutter versions
  • Breaking changes in cupertino_icons package

Step-by-Step Fix

  1. 1.Replace deprecated CupertinoScaffold with CupertinoPageScaffold:
  2. 2.```dart
  3. 3.// BEFORE (deprecated)
  4. 4.CupertinoScaffold(
  5. 5.body: CustomScrollView(
  6. 6.slivers: [
  7. 7.CupertinoSliverNavigationBar(
  8. 8.largeTitle: const Text('Home'),
  9. 9.),
  10. 10.SliverList(
  11. 11.delegate: SliverChildBuilderDelegate(
  12. 12.(context, index) => ListTile(title: Text('Item $index')),
  13. 13.),
  14. 14.),
  15. 15.],
  16. 16.),
  17. 17.)

// AFTER (current) CupertinoPageScaffold( navigationBar: CupertinoNavigationBar( middle: const Text('Home'), // iOS 17+ automatically handles translucency ), child: ListView.builder( itemCount: 20, itemBuilder: (context, index) => CupertinoListTile( title: Text('Item $index'), ), ), ) ```

  1. 1.Update CupertinoTabScaffold usage:
  2. 2.```dart
  3. 3.// AFTER - correct modern usage
  4. 4.CupertinoTabScaffold(
  5. 5.tabBar: CupertinoTabBar(
  6. 6.items: const [
  7. 7.BottomNavigationBarItem(
  8. 8.icon: Icon(CupertinoIcons.home),
  9. 9.label: 'Home',
  10. 10.),
  11. 11.BottomNavigationBarItem(
  12. 12.icon: Icon(CupertinoIcons.settings),
  13. 13.label: 'Settings',
  14. 14.),
  15. 15.],
  16. 16.),
  17. 17.tabBuilder: (context, index) {
  18. 18.return CupertinoTabView(
  19. 19.builder: (context) {
  20. 20.return CupertinoPageScaffold(
  21. 21.child: Center(child: Text('Tab $index')),
  22. 22.);
  23. 23.},
  24. 24.);
  25. 25.},
  26. 26.);
  27. 27.`
  28. 28.Update cupertino_icons package:
  29. 29.```yaml
  30. 30.# pubspec.yaml
  31. 31.dependencies:
  32. 32.cupertino_icons: ^1.0.8 # Latest version with all iOS 17+ icons
  33. 33.`
  34. 34.Handle iOS 17+ navigation bar changes:
  35. 35.```dart
  36. 36.CupertinoNavigationBar(
  37. 37.backgroundColor: CupertinoTheme.of(context)
  38. 38..barBackgroundColor
  39. 39..withOpacity(0.8),
  40. 40.// New in Flutter 3.16+ - automatically adapts to iOS version
  41. 41.transitionBetweenRoutes: true,
  42. 42.heroTag: 'home-nav-bar',
  43. 43.)
  44. 44.`
  45. 45.If using community cupertino_scaffold package, remove it:
  46. 46.```bash
  47. 47.# Remove the deprecated package
  48. 48.flutter pub remove cupertino_scaffold

# Use built-in Cupertino widgets instead flutter pub add cupertino_icons ```

  1. 1.Test on physical iOS device:
  2. 2.```bash
  3. 3.flutter run -d <device-id>
  4. 4.# Verify navigation transitions match native iOS behavior
  5. 5.# Test pull-to-dismiss, swipe-to-go-back, etc.
  6. 6.`

Prevention

  • Follow Flutter release notes for Cupertino widget changes
  • Test on physical iOS devices after Flutter upgrades
  • Avoid community Cupertino packages that duplicate built-in widgets
  • Use flutter build ios --analyze-size to verify no deprecated code
  • Monitor deprecation warnings in flutter analyze output
  • Check Flutter GitHub for migration guides when major versions change