Getting Started

Install

bun add @capgo/capacitor-brightness
bunx cap sync

Import

import { CapgoBrightness } from '@capgo/capacitor-brightness';

API Overview

getBrightness

Get the current brightness level of the device’s main screen.

import { CapgoBrightness } from '@capgo/capacitor-brightness';

await CapgoBrightness.getBrightness();

setBrightness

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.

import { CapgoBrightness } from '@capgo/capacitor-brightness';

await CapgoBrightness.setBrightness({} as SetBrightnessOptions);

getSystemBrightness

Get the system-wide screen brightness.

import { CapgoBrightness } from '@capgo/capacitor-brightness';

await CapgoBrightness.getSystemBrightness();

setSystemBrightness

Set the system-wide screen brightness. Requires WRITE_SETTINGS permission on Android. This also changes the brightness mode to MANUAL.

import { CapgoBrightness } from '@capgo/capacitor-brightness';

await CapgoBrightness.setSystemBrightness({} as SetBrightnessOptions);

getSystemBrightnessMode

Get the current system brightness mode (automatic or manual). Requires WRITE_SETTINGS permission on Android.

import { CapgoBrightness } from '@capgo/capacitor-brightness';

await CapgoBrightness.getSystemBrightnessMode();

setSystemBrightnessMode

Set the system brightness mode (automatic or manual). Requires WRITE_SETTINGS permission on Android.

import { CapgoBrightness } from '@capgo/capacitor-brightness';

await CapgoBrightness.setSystemBrightnessMode({} as SetBrightnessModeOptions);

isUsingSystemBrightness

Check if the current activity is using the system-wide brightness value.

import { CapgoBrightness } from '@capgo/capacitor-brightness';

await CapgoBrightness.isUsingSystemBrightness();

restoreSystemBrightness

Reset the brightness setting of the current activity to use the system-wide value.

import { CapgoBrightness } from '@capgo/capacitor-brightness';

await CapgoBrightness.restoreSystemBrightness();

isAvailable

Check if the Brightness API is available on the current device.

import { CapgoBrightness } from '@capgo/capacitor-brightness';

await CapgoBrightness.isAvailable();

checkPermissions

Check user’s permissions for accessing system brightness.

import { CapgoBrightness } from '@capgo/capacitor-brightness';

await CapgoBrightness.checkPermissions();

requestPermissions

Request permissions for accessing system brightness. On Android, this opens the system settings to grant WRITE_SETTINGS permission.

import { CapgoBrightness } from '@capgo/capacitor-brightness';

await CapgoBrightness.requestPermissions();

Type Reference

GetBrightnessResult

Result of getBrightness or getSystemBrightness.

export interface GetBrightnessResult {
  /**
   * The brightness value from 0 to 1.
   * 0 is the minimum brightness, 1 is the maximum brightness.
   *
   * @since 8.0.0
   */
  brightness: number;
}

SetBrightnessOptions

Options for setBrightness or setSystemBrightness.

export interface SetBrightnessOptions {
  /**
   * The brightness value from 0 to 1.
   * 0 is the minimum brightness, 1 is the maximum brightness.
   *
   * @since 8.0.0
   */
  brightness: number;
}

GetBrightnessModeResult

Result of getSystemBrightnessMode.

export interface GetBrightnessModeResult {
  /**
   * The current brightness mode.
   *
   * @since 8.0.0
   */
  mode: BrightnessMode;
}

SetBrightnessModeOptions

Options for setSystemBrightnessMode.

export interface SetBrightnessModeOptions {
  /**
   * The brightness mode to set.
   * Cannot be set to UNKNOWN.
   *
   * @since 8.0.0
   */
  mode: BrightnessMode;
}

IsUsingSystemBrightnessResult

Result of isUsingSystemBrightness.

export interface IsUsingSystemBrightnessResult {
  /**
   * Whether the current activity is using the system-wide brightness value.
   *
   * @since 8.0.0
   */
  isUsing: boolean;
}

IsAvailableResult

Result of isAvailable.

export interface IsAvailableResult {
  /**
   * Whether the Brightness API is available on the current device.
   *
   * @since 8.0.0
   */
  available: boolean;
}

PermissionStatus

Permission status result.

export interface PermissionStatus {
  /**
   * Whether the permission to modify system brightness is granted.
   *
   * @since 8.0.0
   */
  brightness: PermissionState;
}

GetPluginVersionResult

Result of getPluginVersion.

export interface GetPluginVersionResult {
  /**
   * The native plugin version.
   *
   * @since 8.0.0
   */
  version: string;
}

BrightnessMode

The brightness mode.

export enum BrightnessMode {
  /**
   * The brightness mode is unknown.
   *
   * @since 8.0.0
   */
  UNKNOWN = 0,
  /**
   * The brightness is automatically adjusted by the system.
   *
   * @since 8.0.0
   */
  AUTOMATIC = 1,
  /**
   * The brightness is manually set by the user.
   *
   * @since 8.0.0
   */
  MANUAL = 2,
}

PermissionState

Permission state.

export type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.