A library that provides access to an API for getting and setting the screen brightness.
GitHub
npm
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.
-
npx expo install expo-brightness
If you are installing this in an existing React Native app, start by installing expo
in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.
Learn how to configure the native projects in the installation instructions in the expo-brightness
repository.
import { 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>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: '#fff',
alignItems: 'center',
justifyContent: 'center',
},
});
import * as Brightness from 'expo-brightness';
usePermissions(options)
Parameter | Type |
---|---|
options (optional) | PermissionHookOptions<object> |
[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]
Brightness.getBrightnessAsync()
Gets the current brightness level of the device's main screen.
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.
A promise that fulfils with an object of type PermissionResponse.
Brightness.getSystemBrightnessAsync()
Gets the global system screen brightness.
Promise<number>
A Promise
that is resolved with a number between 0
and 1
, inclusive, representing
the current system screen brightness.
Brightness.getSystemBrightnessModeAsync()
Gets the system brightness mode (e.g. whether or not the OS will automatically adjust the screen brightness depending on ambient light).
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.
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()
Returns a boolean specifying whether or not the current activity is using the system-wide brightness value.
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.
A promise that fulfils with an object of type PermissionResponse.
Brightness.restoreSystemBrightnessAsync()
Resets the brightness setting of the current activity to use the system-wide brightness value rather than overriding it.
Promise<void>
A Promise
that fulfils when the setting has been successfully changed.
Brightness.setBrightnessAsync(brightnessValue)
Parameter | Type | Description |
---|---|---|
brightnessValue | number | A number between |
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.
Promise<void>
A Promise
that fulfils when the brightness has been successfully set.
Brightness.setSystemBrightnessAsync(brightnessValue)
Parameter | Type | Description |
---|---|---|
brightnessValue | number | A number between |
Sets the global system screen brightness and changes the brightness mode to
MANUAL
. Requires SYSTEM_BRIGHTNESS
permissions.
Promise<void>
A Promise
that fulfils when the brightness has been successfully set.
Brightness.setSystemBrightnessModeAsync(brightnessMode)
Parameter | Type | Description |
---|---|---|
brightnessMode | BrightnessMode | One of |
Sets the system brightness mode.
Promise<void>
Deprecated Use
restoreSystemBrightnessAsync
method instead.
Brightness.useSystemBrightnessAsync()
Promise<void>
Brightness.addBrightnessListener(listener)
Parameter | Type | Description |
---|---|---|
listener | (event: BrightnessEvent) => void | A callback that is invoked when brightness (iOS) changes.
The callback is provided a single argument that is an object with a |
Subscribe to brightness (iOS) updates. The event fires whenever the power mode is toggled.
On web and android the event never fires.
EventSubscription
A Subscription
object on which you can call remove()
to unsubscribe from the listener.
PermissionResponse
An object obtained by permissions get and request functions.
PermissionResponse Properties
Name | Type | Description |
---|---|---|
canAskAgain | boolean | Indicates if user can be asked again for specific permission. If not, one should be directed to the Settings app in order to enable/disable the permission. |
expires | PermissionExpiration | Determines time when the permission expires. |
granted | boolean | A convenience boolean that indicates if the permission is granted. |
status | PermissionStatus | Determines the status of the permission. |
BrightnessEvent
Name | Type | Description |
---|---|---|
brightness | number | A number between |
PermissionExpiration
Literal Type: multiple types
Permission expiration time. Currently, all permissions are granted permanently.
Acceptable values are: 'never'
| number
PermissionHookOptions
Literal Type: multiple types
Acceptable values are: PermissionHookBehavior
| Options
AUTOMATIC
BrightnessMode.AUTOMATIC = 1
Mode in which the device OS will automatically adjust the screen brightness depending on the ambient light.
MANUAL
BrightnessMode.MANUAL = 2
Mode in which the screen brightness will remain constant and will not be adjusted by the OS.
UNDETERMINED
PermissionStatus.UNDETERMINED = "undetermined"
User hasn't granted or denied the permission yet.
ERR_BRIGHTNESS
An error occurred when getting or setting the app brightness.
ERR_BRIGHTNESS_MODE
An error occurred when getting or setting the system brightness mode. See the nativeError
property of the thrown error for more information.
ERR_BRIGHTNESS_PERMISSIONS_DENIED
An attempt to set the system brightness was made without the proper permissions from the user. The user did not grant SYSTEM_BRIGHTNESS
permissions.
ERR_BRIGHTNESS_SYSTEM
An error occurred when getting or setting the system brightness.
ERR_INVALID_ARGUMENT
An invalid argument was passed. Only BrightnessMode.MANUAL
or BrightnessMode.AUTOMATIC
are allowed.
You must add the following permissions to your app.json inside the expo.android.permissions
array.
Android Permission | Description |
---|---|
Allows an application to read or write the system settings. |
No permissions required.