@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/

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 |