The practical cordova-plugin-brightness alternative for a Capacitor app is @capgo/capacitor-brightness. It replaces cordova.plugins.brightness callbacks with CapgoBrightness promises for values from 0 to 1, documents iOS and Android behavior in definitions.ts, and exposes Android system brightness APIs that the Cordova plugin never shipped. This guide lists npm facts, install steps, usage, and an API map for your Cordova to Capacitor move.
Why leave cordova-plugin-brightness in Capacitor
cordova-plugin-brightness on npm is version 0.2.0. The registry modified timestamp is 13 June 2022. The npm repository URL points to mgcrea/cordova-plugin-brightness.
The www/brightness.js bridge exposes cordova.plugins.brightness with:
setBrightness(value, success, error)with float 0 to 1getBrightness(success, error)where success may return -1 for system defaultsetKeepScreenOn(value, success, error)on the same plugin object
In a Capacitor codebase the Cordova module still routes through cordova.exec and bundles screen wake with brightness even when you only need one concern.
@capgo/capacitor-brightness latest on npm is 8.0.26 with a modified date of 12 November 2026. src/definitions.ts documents getBrightness, setBrightness, getSystemBrightness, setSystemBrightness, getSystemBrightnessMode, setSystemBrightnessMode, restoreSystemBrightness, and requestPermissions for Android WRITE_SETTINGS. Capgo ships fixes on an open source cadence where a human still reviews, tests and merges 50+ pull requests daily.
Install
bun add @capgo/capacitor-brightness
bunx cap sync
On Android, setSystemBrightness needs the user to grant modify system settings. Call requestPermissions() and handle denied before you change system wide brightness.
Usage example
import { CapgoBrightness } from '@capgo/capacitor-brightness';
export async function dimForNightMode() {
const { brightness } = await CapgoBrightness.getBrightness();
console.log('current', brightness);
await CapgoBrightness.setBrightness({ brightness: 0.2 });
}
Migrating from Cordova to Capacitor
// Before (Cordova)
var brightness = cordova.plugins.brightness;
brightness.setBrightness(0.75, success, error);
brightness.getBrightness(success, error);
// After (Capacitor)
import { CapgoBrightness } from '@capgo/capacitor-brightness';
await CapgoBrightness.setBrightness({ brightness: 0.75 });
const { brightness } = await CapgoBrightness.getBrightness();
console.log(brightness);
// Before (Cordova wake lock on brightness plugin)
cordova.plugins.brightness.setKeepScreenOn(true, success, error);
// After (Capacitor, dedicated plugin)
import { KeepAwake } from '@capgo/capacitor-keep-awake';
await KeepAwake.keepAwake();
API mapping table
cordova-plugin-brightness (cordova.plugins.brightness) |
@capgo/capacitor-brightness |
|---|---|
setBrightness(value, success, error) |
setBrightness({ brightness: value }) with 0 to 1 |
getBrightness(success, error) |
getBrightness() returns { brightness } (no -1 sentinel; use restoreSystemBrightness on Android) |
setKeepScreenOn(true, ...) |
Use @capgo/capacitor-keep-awake keepAwake() |
| Not in Cordova | getSystemBrightness, setSystemBrightness, getSystemBrightnessMode, setSystemBrightnessMode |
| Not in Cordova | isUsingSystemBrightness, restoreSystemBrightness, checkPermissions, requestPermissions |
| Cordova plugin install | bun add @capgo/capacitor-brightness plus bunx cap sync |
Links and next steps
- Plugin docs: https://capgo.app/docs/plugins/brightness/
- Marketing page: /plugins/capacitor-brightness/
- npm: https://www.npmjs.com/package/@capgo/capacitor-brightness
- GitHub: https://github.com/Cap-go/capacitor-brightness/
- Cordova upstream: https://github.com/mgcrea/cordova-plugin-brightness
- Keep awake: /plugins/capacitor-keep-awake/ and keep awake plugin docs
Brightness changes ship in the native binary. Use Capgo Build for store builds, then tune reader or kiosk screens with Capgo live updates where the logic stays in JavaScript. For the full platform move, read the Cordova to Capacitor migration guide.