@capgo/capacitor-brightness

@capgo/capacitor-brightness

➡️ Get Instant updates for your App with Capgo

Missing a feature? We'll build the plugin for you 💪

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

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-brightness` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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