@capgo/capacitor-brightness

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()
• setBrightness(...)
• getSystemBrightness()
• setSystemBrightness(...)
• getSystemBrightnessMode()
• setSystemBrightnessMode(...)
• isUsingSystemBrightness()
• restoreSystemBrightness()
• isAvailable()
• checkPermissions()
• requestPermissions()
• getPluginVersion()
• Interfaces
• Type Aliases
• Enums

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 |