🔋 iOS Battery Indicator

A Flutter widget that replicates the native iOS battery indicator, including support for iOS 27 style and automatic system battery monitoring.

Language: English | 中文

✨ Features

Native iOS look & feel — faithfully reproduces the iOS battery icon with rounded superellipse shape and proper sizing.
Automatic system battery — reads battery level, charging state, and low-power mode from the device in real time when no manual value is supplied.
System event callbacks — onBatteryLevelChanged and onBatteryStateChanged notify the parent when system values change in auto mode.
Manual control — optionally pass batteryLevel, batteryState, and isInBatterySaveMode for demo or custom scenarios.
iOS 27 style — supports the new borderless design introduced in iOS 27, with automatic detection of the iOS version.
Charging bolt overlay — renders a bolt (⚡) glyph using the native Cupertino icon font when the battery is charging.
Cutout percentage — in normal discharging mode, the percentage text is punched through the fill using a cutout effect for a polished look.
Low battery warning — the indicator turns red when the battery level drops below a configurable threshold (10–30, defaults to 20).
Battery save mode — the track turns yellow when low-power mode is active.
Real-time save-mode monitoring — monitorBatterySaveMode polls Low Power Mode (auto mode only; poll interval configurable via saveModePollInterval, default 30s; supported on Android, iOS, macOS and Windows; not on web or other platforms).
Light / Dark mode — automatically adapts to the ambient Brightness, or force a specific brightness via the brightness property.
Smooth animations — animated fill level, color changes, charging bolt transitions, and crossfade between basic and percentage display. All animation durations are configurable via animationDuration.
Charging sound — optionally play the native iOS charging sound (connectedToPower) when entering the charging state in manual mode (iOS only).

🚀 Getting started

Install via pub.dev → pub.dev/packages/ios_battery_indicator/install

Live Demo — try it out online

⚙️ Platform setup

This package depends on battery_plus and device_info_plus. No additional configuration is required for iOS and macOS. For Android, ensure the android/app/build.gradle.kts targets API 21 or higher (the default Flutter template already satisfies this).

📖 Usage

🤖 Auto mode (system battery)

The simplest usage — the widget reads everything from the device:

IosBatteryIndicator();

You can configure how often the system battery level is polled (default 30s):

IosBatteryIndicator(
  batteryLevelPollInterval: const Duration(seconds: 15), // level poll interval (default 30s)
);

Battery percentage display is enabled by default.
Listen to Battery.onBatteryStateChanged for real-time state updates.
Automatically detect iOS 27+ and render the borderless style.

🎮 Manual control

Provide explicit values to bypass the system readings:

IosBatteryIndicator(
  batteryLevel: 80,
  batteryState: BatteryState.charging,
);

🎛️ Controlling display options

IosBatteryIndicator(
  showBatteryPercentage: false,  // hide the percentage number
  fontFeatures: const [.tabularFigures()], // default: monospaced digits (only effective when showBatteryPercentage is true)
  chargingWithBolt: false,      // hide the bolt when charging
);

🔊 Charging sound (iOS only)

When in manual mode, you can play the native iOS charging sound when the battery state is set to BatteryState.charging:

IosBatteryIndicator(
  batteryState: BatteryState.charging,
  playChargingSound: true, // play iOS charging sound
);

Note

This feature requires the ios_system_sound package and is only supported on iOS. It has no effect on the web or other platforms, and is ignored in auto mode (when batteryState is null).

🎨 Styling

IosBatteryIndicator(
  isIOS27Style: true,            // force iOS 27 borderless style
  brightness: Brightness.dark,   // force dark mode colors
  lowBatteryThreshold: 15,       // turn red when ≤ 15%
  animationDuration: const Duration(milliseconds: 500),  // slow down animations
);

📐 Sizing

Use height orwidth (mutually exclusive) to scale it:

IosBatteryIndicator(height: 36); // 36 logical pixels tall, width auto

IosBatteryIndicator(width: 40); // 40 logical pixels wide, height auto

📡 Callbacks

Receive real-time system battery updates when in auto mode:

IosBatteryIndicator(
  onBatteryLevelChanged: (level) => print('Battery: $level%'),
  onBatteryStateChanged: (state) => print('State: $state'),
);

Note

These callbacks only fire when batteryLevel / batteryState is null (system mode). When providing manual values, use your own state management instead.

🔋 Battery save mode monitoring

By default the system Low Power Mode is read only once when the widget initializes. To keep it in sync when the user toggles it at runtime, enable monitorBatterySaveMode — this only takes effect when isInBatterySaveMode is null (system mode). Note this is only supported on Android, iOS, macOS and Windows — it has no effect on web or other platforms:

IosBatteryIndicator(
  isInBatterySaveMode: null,      // read from the system
  monitorBatterySaveMode: true,   // re-poll periodically
  saveModePollInterval: const Duration(seconds: 10), // poll interval (default 30s)
);

Note

This has no effect when isInBatterySaveMode is explicitly provided.

🖌️ Custom theme

You can customize the colors by providing a BatteryIndicatorTheme via ThemeData.extensions:

MaterialApp(
  theme: ThemeData(
    extensions: [
      BatteryIndicatorTheme(
        bgColor: CupertinoColors.black.withValues(alpha: .3),
        dischargingTrackColor: CupertinoColors.black,
        chargingTrackColor: CupertinoColors.activeGreen,
        criticallyLowTrackColor: CupertinoColors.destructiveRed,
        saveModeTrackColor: CupertinoColors.systemYellow,
        contentColor: CupertinoColors.black,
        contentAntiColor: CupertinoColors.white,
      ),
    ],
  ),
  home: /* ... */,
);

For Cupertino apps, wrap the indicator in a Theme widget or use CupertinoThemeData extensions.

📚 API reference