🔋 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.
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();

Battery percentage display is enabled by default.
Poll the system battery level every 30 seconds.
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
  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.

🖌️ Custom theme

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

MaterialApp(
  theme: ThemeData(
    extensions: [
      BatteryIndicatorTheme(
        bgColor: Colors.grey.withValues(alpha: .3),
        dischargingTrackColor: Colors.blue,
        contentColor: Colors.blue,
        contentAntiColor: Colors.white,
      ),
    ],
  ),
  home: /* ... */,
);

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

📚 API reference