Control screen brightness on iOS and Android.
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.
Full documentation available at: https://capgo.app/docs/plugins/brightness/
npm install @capgo/capacitor-brightness
npx cap syncFor 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+.
- iOS: iOS 15+ (uses UIScreen.brightness)
- Android: API 24+ (uses WindowManager for app brightness, Settings.System for system brightness)
getBrightness()setBrightness(...)getSystemBrightness()setSystemBrightness(...)getSystemBrightnessMode()setSystemBrightnessMode(...)isUsingSystemBrightness()restoreSystemBrightness()isAvailable()checkPermissions()requestPermissions()getPluginVersion()- Interfaces
- Type Aliases
- Enums
getBrightness() => Promise<GetBrightnessResult>Get the current brightness level of the device's main screen.
Returns: Promise<GetBrightnessResult>
Since: 8.0.0
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() => Promise<GetBrightnessResult>Get the system-wide screen brightness.
Returns: Promise<GetBrightnessResult>
Since: 8.0.0
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() => 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(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() => Promise<IsUsingSystemBrightnessResult>Check if the current activity is using the system-wide brightness value.
Returns: Promise<IsUsingSystemBrightnessResult>
Since: 8.0.0
restoreSystemBrightness() => Promise<void>Reset the brightness setting of the current activity to use the system-wide value.
Since: 8.0.0
isAvailable() => Promise<IsAvailableResult>Check if the Brightness API is available on the current device.
Returns: Promise<IsAvailableResult>
Since: 8.0.0
checkPermissions() => Promise<PermissionStatus>Check user's permissions for accessing system brightness.
Returns: Promise<PermissionStatus>
Since: 8.0.0
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() => Promise<GetPluginVersionResult>Get the native plugin version.
Returns: Promise<GetPluginVersionResult>
Since: 8.0.0
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 |
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 |
Result of getSystemBrightnessMode.
| Prop | Type | Description | Since |
|---|---|---|---|
mode |
BrightnessMode |
The current brightness mode. | 8.0.0 |
Options for setSystemBrightnessMode.
| Prop | Type | Description | Since |
|---|---|---|---|
mode |
BrightnessMode |
The brightness mode to set. Cannot be set to UNKNOWN. | 8.0.0 |
Result of isUsingSystemBrightness.
| Prop | Type | Description | Since |
|---|---|---|---|
isUsing |
boolean |
Whether the current activity is using the system-wide brightness value. | 8.0.0 |
Result of isAvailable.
| Prop | Type | Description | Since |
|---|---|---|---|
available |
boolean |
Whether the Brightness API is available on the current device. | 8.0.0 |
Permission status result.
| Prop | Type | Description | Since |
|---|---|---|---|
brightness |
PermissionState |
Whether the permission to modify system brightness is granted. | 8.0.0 |
Result of getPluginVersion.
| Prop | Type | Description | Since |
|---|---|---|---|
version |
string |
The native plugin version. | 8.0.0 |
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
| 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 |
