@capgo/capacitor-brightness

Read and set screen brightness from your Capacitor app, for example to brighten the screen while a QR code or ticket is shown. On Android you can also control system brightness and its automatic mode.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-brightness in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-brightness to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• App brightness: getBrightness() and setBrightness() for the current screen on iOS and Android.
• System brightness: getSystemBrightness() and setSystemBrightness() on Android.
• Brightness mode: getSystemBrightnessMode() and setSystemBrightnessMode() switch between automatic and manual on Android.
• Restore: restoreSystemBrightness() hands control back to the system, isUsingSystemBrightness() checks the current state.
• Permissions: checkPermissions() and requestPermissions() for Android system settings access.
• Platforms: iOS and Android. System brightness and mode are Android only. Not available on web.

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

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.

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.

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.

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.

SetBrightnessOptions

Options for setBrightness or setSystemBrightness.

GetBrightnessModeResult

Result of getSystemBrightnessMode.

SetBrightnessModeOptions

Options for setSystemBrightnessMode.

IsUsingSystemBrightnessResult

Result of isUsingSystemBrightness.

IsAvailableResult

Result of isAvailable.

PermissionStatus

Permission status result.

GetPluginVersionResult

Result of getPluginVersion.

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Enums

BrightnessMode