@capgo/capacitor-brightness
May 11, 2026 · View on GitHub
Control screen brightness on iOS and Android.
Why Capacitor Brightness?
The only Capacitor plugin providing complete brightness control for both iOS and Android:
- App-level brightness - Control brightness for your activity without affecting system settings
- System-level brightness - Modify the global device brightness (Android)
- Auto/Manual mode - Switch between automatic and manual brightness modes (Android)
- Permission handling - Built-in support for WRITE_SETTINGS permission flow
- Cross-platform - Consistent API across iOS and Android
Essential for reading apps, video players, camera apps, and any app needing screen brightness control.
Documentation
Full documentation available at: https://capgo.app/docs/plugins/brightness/
Compatibility
| Plugin version | Capacitor compatibility | Maintained |
|---|---|---|
| v8.*.* | v8.*.* | ✅ |
| v7.*.* | v7.*.* | On demand |
| v6.*.* | v6.*.* | ❌ |
| v5.*.* | v5.*.* | ❌ |
Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
Install
npm install @capgo/capacitor-brightness
npx cap sync
Android Configuration
For Android, if you want to modify the system brightness (not just the app brightness), you need to add the WRITE_SETTINGS permission to your AndroidManifest.xml:
<uses-permission android:name="android.permission.WRITE_SETTINGS" />
Note: This permission requires user confirmation through system settings on Android 6.0+.
Requirements
- iOS: iOS 15+ (uses UIScreen.brightness)
- Android: API 24+ (uses WindowManager for app brightness, Settings.System for system brightness)
API
getBrightness()
getBrightness() => Promise<GetBrightnessResult>
Get the current brightness level of the device's main screen.
Returns: Promise<GetBrightnessResult>
Since: 8.0.0
setBrightness(...)
setBrightness(options: SetBrightnessOptions) => Promise<void>
Set the brightness level of the device's main screen.
On iOS, the brightness will persist until the device is locked. On Android, the brightness only applies to the current activity.
| Param | Type | Description |
|---|---|---|
options | SetBrightnessOptions | - The brightness options. |
Since: 8.0.0
getSystemBrightness()
getSystemBrightness() => Promise<GetBrightnessResult>
Get the system-wide screen brightness.
Returns: Promise<GetBrightnessResult>
Since: 8.0.0
setSystemBrightness(...)
setSystemBrightness(options: SetBrightnessOptions) => Promise<void>
Set the system-wide screen brightness. Requires WRITE_SETTINGS permission on Android. This also changes the brightness mode to MANUAL.
| Param | Type | Description |
|---|---|---|
options | SetBrightnessOptions | - The brightness options. |
Since: 8.0.0
getSystemBrightnessMode()
getSystemBrightnessMode() => Promise<GetBrightnessModeResult>
Get the current system brightness mode (automatic or manual). Requires WRITE_SETTINGS permission on Android.
Returns: Promise<GetBrightnessModeResult>
Since: 8.0.0
setSystemBrightnessMode(...)
setSystemBrightnessMode(options: SetBrightnessModeOptions) => Promise<void>
Set the system brightness mode (automatic or manual). Requires WRITE_SETTINGS permission on Android.
| Param | Type | Description |
|---|---|---|
options | SetBrightnessModeOptions | - The brightness mode options. |
Since: 8.0.0
isUsingSystemBrightness()
isUsingSystemBrightness() => Promise<IsUsingSystemBrightnessResult>
Check if the current activity is using the system-wide brightness value.
Returns: Promise<IsUsingSystemBrightnessResult>
Since: 8.0.0
restoreSystemBrightness()
restoreSystemBrightness() => Promise<void>
Reset the brightness setting of the current activity to use the system-wide value.
Since: 8.0.0
isAvailable()
isAvailable() => Promise<IsAvailableResult>
Check if the Brightness API is available on the current device.
Returns: Promise<IsAvailableResult>
Since: 8.0.0
checkPermissions()
checkPermissions() => Promise<PermissionStatus>
Check user's permissions for accessing system brightness.
Returns: Promise<PermissionStatus>
Since: 8.0.0
requestPermissions()
requestPermissions() => Promise<PermissionStatus>
Request permissions for accessing system brightness. On Android, this opens the system settings to grant WRITE_SETTINGS permission.
Returns: Promise<PermissionStatus>
Since: 8.0.0
getPluginVersion()
getPluginVersion() => Promise<GetPluginVersionResult>
Get the native plugin version.
Returns: Promise<GetPluginVersionResult>
Since: 8.0.0
Interfaces
GetBrightnessResult
Result of getBrightness or getSystemBrightness.
| Prop | Type | Description | Since |
|---|---|---|---|
brightness | number | The brightness value from 0 to 1. 0 is the minimum brightness, 1 is the maximum brightness. | 8.0.0 |
SetBrightnessOptions
Options for setBrightness or setSystemBrightness.
| Prop | Type | Description | Since |
|---|---|---|---|
brightness | number | The brightness value from 0 to 1. 0 is the minimum brightness, 1 is the maximum brightness. | 8.0.0 |
GetBrightnessModeResult
Result of getSystemBrightnessMode.
| Prop | Type | Description | Since |
|---|---|---|---|
mode | BrightnessMode | The current brightness mode. | 8.0.0 |
SetBrightnessModeOptions
Options for setSystemBrightnessMode.
| Prop | Type | Description | Since |
|---|---|---|---|
mode | BrightnessMode | The brightness mode to set. Cannot be set to UNKNOWN. | 8.0.0 |
IsUsingSystemBrightnessResult
Result of isUsingSystemBrightness.
| Prop | Type | Description | Since |
|---|---|---|---|
isUsing | boolean | Whether the current activity is using the system-wide brightness value. | 8.0.0 |
IsAvailableResult
Result of isAvailable.
| Prop | Type | Description | Since |
|---|---|---|---|
available | boolean | Whether the Brightness API is available on the current device. | 8.0.0 |
PermissionStatus
Permission status result.
| Prop | Type | Description | Since |
|---|---|---|---|
brightness | PermissionState | Whether the permission to modify system brightness is granted. | 8.0.0 |
GetPluginVersionResult
Result of getPluginVersion.
| Prop | Type | Description | Since |
|---|---|---|---|
version | string | The native plugin version. | 8.0.0 |
Type Aliases
PermissionState
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
Enums
BrightnessMode
| Members | Value | Description | Since |
|---|---|---|---|
UNKNOWN | 0 | The brightness mode is unknown. | 8.0.0 |
AUTOMATIC | 1 | The brightness is automatically adjusted by the system. | 8.0.0 |
MANUAL | 2 | The brightness is manually set by the user. | 8.0.0 |