https://github.com/Cap-go/capacitor-brightness
Capacitor plugin for controlling screen brightness on iOS and Android
https://github.com/Cap-go/capacitor-brightness
capacitor capacitor-plugin
Last synced: about 1 month ago
JSON representation
Capacitor plugin for controlling screen brightness on iOS and Android
- Host: GitHub
- URL: https://github.com/Cap-go/capacitor-brightness
- Owner: Cap-go
- License: mpl-2.0
- Created: 2026-01-04T17:06:15.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-02-04T02:20:48.000Z (about 1 month ago)
- Last Synced: 2026-02-04T14:26:30.331Z (about 1 month ago)
- Topics: capacitor, capacitor-plugin
- Language: Java
- Homepage: https:/capgo.app
- Size: 164 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-capacitor - Brightness - Control screen brightness on iOS and Android. ([Capgo plugins](https://capgo.app/) / Device & Sensors)
README
# @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
```bash
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`:
```xml
```
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()`](#getbrightness)
* [`setBrightness(...)`](#setbrightness)
* [`getSystemBrightness()`](#getsystembrightness)
* [`setSystemBrightness(...)`](#setsystembrightness)
* [`getSystemBrightnessMode()`](#getsystembrightnessmode)
* [`setSystemBrightnessMode(...)`](#setsystembrightnessmode)
* [`isUsingSystemBrightness()`](#isusingsystembrightness)
* [`restoreSystemBrightness()`](#restoresystembrightness)
* [`isAvailable()`](#isavailable)
* [`checkPermissions()`](#checkpermissions)
* [`requestPermissions()`](#requestpermissions)
* [`getPluginVersion()`](#getpluginversion)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
* [Enums](#enums)
### getBrightness()
```typescript
getBrightness() => Promise
```
Get the current brightness level of the device's main screen.
**Returns:** Promise<GetBrightnessResult>
**Since:** 8.0.0
--------------------
### setBrightness(...)
```typescript
setBrightness(options: SetBrightnessOptions) => Promise
```
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()
```typescript
getSystemBrightness() => Promise
```
Get the system-wide screen brightness.
**Returns:** Promise<GetBrightnessResult>
**Since:** 8.0.0
--------------------
### setSystemBrightness(...)
```typescript
setSystemBrightness(options: SetBrightnessOptions) => Promise
```
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()
```typescript
getSystemBrightnessMode() => Promise
```
Get the current system brightness mode (automatic or manual).
Requires WRITE_SETTINGS permission on Android.
**Returns:** Promise<GetBrightnessModeResult>
**Since:** 8.0.0
--------------------
### setSystemBrightnessMode(...)
```typescript
setSystemBrightnessMode(options: SetBrightnessModeOptions) => Promise
```
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()
```typescript
isUsingSystemBrightness() => Promise
```
Check if the current activity is using the system-wide brightness value.
**Returns:** Promise<IsUsingSystemBrightnessResult>
**Since:** 8.0.0
--------------------
### restoreSystemBrightness()
```typescript
restoreSystemBrightness() => Promise
```
Reset the brightness setting of the current activity to use the system-wide value.
**Since:** 8.0.0
--------------------
### isAvailable()
```typescript
isAvailable() => Promise
```
Check if the Brightness API is available on the current device.
**Returns:** Promise<IsAvailableResult>
**Since:** 8.0.0
--------------------
### checkPermissions()
```typescript
checkPermissions() => Promise
```
Check user's permissions for accessing system brightness.
**Returns:** Promise<PermissionStatus>
**Since:** 8.0.0
--------------------
### requestPermissions()
```typescript
requestPermissions() => Promise
```
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()
```typescript
getPluginVersion() => Promise
```
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 |