Brightness

An API to get and set screen brightness.

On Android, there is a global system-wide brightness setting, and each app has its own brightness setting that can optionally override the global setting. It is possible to set either of these values with this API. On iOS, the system brightness setting cannot be changed programmatically; instead, any changes to the screen brightness will persist until the device is locked or powered off.

Platform Compatibility

Android Device	Android Emulator	iOS Device	iOS Simulator	Web

Installation

Terminal

→ expo install expo-brightness

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

Usage

import React, { useEffect } from 'react';
import { StyleSheet, View, Text } from 'react-native';
import * as Brightness from 'expo-brightness';

export default function App() {
  useEffect(() => {
    (async () => {
      const { status } = await Brightness.requestPermissionsAsync();
      if (status === 'granted') {
        Brightness.setSystemBrightnessAsync(1);
      }
    })();
  }, []);

  return (
    <View style={styles.container}>
      <Text>Brightness Module Example</Text>
    </View>
  );
}

%%placeholder-start%%const styles = StyleSheet.create({ ... }); %%placeholder-end%%const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
});

API

import * as Brightness from 'expo-brightness';

Hooks

`usePermissions`

Arguments

Name	Type	Description
options (optional)	`PermissionHookOptions<object>`	-

Check or request permissions to modify the system brightness. This uses both requestPermissionAsync and getPermissionsAsync to interact with the permissions.

Example

const [status, requestPermission] = Brightness.usePermissions();

Returns

[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]

Methods

`Brightness.getBrightnessAsync()`

Gets the current brightness level of the device's main screen.

Returns

Promise<number>

A Promise that fulfils with a number between 0 and 1, inclusive, representing the current screen brightness.

`Brightness.getPermissionsAsync()`

Checks user's permissions for accessing system brightness.

Returns

Promise<PermissionResponse>

A promise that fulfils with an object of type PermissionResponse.

`Brightness.getSystemBrightnessAsync()`

Android Only

Gets the global system screen brightness.

Returns

Promise<number>

A Promise that is resolved with a number between 0 and 1, inclusive, representing the current system screen brightness.

`Brightness.getSystemBrightnessModeAsync()`

Android Only

Gets the system brightness mode (e.g. whether or not the OS will automatically adjust the screen brightness depending on ambient light).

Returns

Promise<BrightnessMode>

A Promise that fulfils with a BrightnessMode. Requires SYSTEM_BRIGHTNESS permissions.

`Brightness.isAvailableAsync()`

Returns whether the Brightness API is enabled on the current device. This does not check the app permissions.

Returns

Promise<boolean>

Async boolean, indicating whether the Brightness API is available on the current device. Currently this resolves true on iOS and Android only.

`Brightness.isUsingSystemBrightnessAsync()`

Android Only

Returns a boolean specifying whether or not the current activity is using the system-wide brightness value.

Returns

Promise<boolean>

A Promise that fulfils with true when the current activity is using the system-wide brightness value, and false otherwise.

`Brightness.requestPermissionsAsync()`

Asks the user to grant permissions for accessing system brightness.

Returns

Promise<PermissionResponse>

A promise that fulfils with an object of type PermissionResponse.

`Brightness.setBrightnessAsync(brightnessValue)`

Arguments

Name	Type	Description
brightnessValue	`number`	A number between `0` and `1`, inclusive, representing the desired screen brightness.

Sets the current screen brightness. On iOS, this setting will persist until the device is locked, after which the screen brightness will revert to the user's default setting. On Android, this setting only applies to the current activity; it will override the system brightness value whenever your app is in the foreground.

Returns

Promise<void>

A Promise that fulfils when the brightness has been successfully set.

`Brightness.setSystemBrightnessAsync(brightnessValue)`

Android Only

Arguments

Name	Type	Description
brightnessValue	`number`	A number between `0` and `1`, inclusive, representing the desired screen brightness.

WARNING: This method is experimental.

Sets the global system screen brightness and changes the brightness mode to MANUAL. Requires SYSTEM_BRIGHTNESS permissions.

Returns

Promise<void>

A Promise that fulfils when the brightness has been successfully set.

`Brightness.setSystemBrightnessModeAsync(brightnessMode)`

Android Only

Arguments

Name	Type	Description
brightnessMode	`BrightnessMode`	One of `BrightnessMode.MANUAL` or `BrightnessMode.AUTOMATIC`. The system brightness mode cannot be set to `BrightnessMode.UNKNOWN`.

Sets the system brightness mode.

Returns

Promise<void>

`Brightness.useSystemBrightnessAsync()`

Android Only

Resets the brightness setting of the current activity to use the system-wide brightness value rather than overriding it.

Returns

Promise<void>

A Promise that fulfils when the setting has been successfully changed.

Types

`PermissionExpiration`

Acceptable values are: 'never', number.

`PermissionHookOptions`

Acceptable values are: PermissionHookBehavior, Options.

Interfaces

`PermissionResponse`

Name	Type	Description
canAskAgain	`boolean`	-
expires	`PermissionExpiration`	-
granted	`boolean`	-
status	`PermissionStatus`	-

Enums

`BrightnessMode`

UNKNOWN - Means that the current brightness mode cannot be determined.
BrightnessMode.UNKNOWN ＝ 0
AUTOMATIC - Mode in which the device OS will automatically adjust the screen brightness depending on the ambient light.
BrightnessMode.AUTOMATIC ＝ 1
MANUAL - Mode in which the screen brightness will remain constant and will not be adjusted by the OS.
BrightnessMode.MANUAL ＝ 2

`PermissionStatus`

DENIED
PermissionStatus.DENIED ＝ "denied"
GRANTED
PermissionStatus.GRANTED ＝ "granted"
UNDETERMINED
PermissionStatus.UNDETERMINED ＝ "undetermined"