Brightness

App and system screen brightness

One.Brightness reads and writes the screen brightness: an app-level override on both platforms, plus the system brightness and mode on Android. Reach for it for video players, barcode scanners, and night modes that need the screen brighter or dimmer than the user’s setting.

On iOS app brightness reads and writes UIScreen on the main thread. On Android it sets the activity window attribute, while the system family reads and writes Settings.System. On web reads resolve 1, effects do nothing, permissions read denied, and listeners never fire.

Usage

import { useEffect } from 'react'
import { One } from 'one'

function useFullBrightness() {
  useEffect(() => {
    async function boost() {
      const initial = await One.Brightness.get()
      await One.Brightness.set(1)
      return initial
    }
    const initial = boost()
    return () => {
      void initial.then((value) => One.Brightness.set(value))
    }
  }, [])
}

Saving the starting value and restoring it on unmount leaves the user’s brightness exactly as it was. Out-of-range values throw synchronously.

How it works

get and set move a number from 0 to 1. On iOS the setting persists until the device locks. On Android it applies to the current activity while the app is in the foreground. addListener receives { brightness } and fires on iOS only; the iOS simulator never posts brightness notifications for programmatic sets, so listeners stay quiet there while get still reads back every set.

The getSystem family is Android only. getSystem reads the global brightness, setSystem writes it and switches the mode to manual, getSystemMode resolves unknown, automatic, or manual, setSystemMode switches between manual and automatic, isUsingSystem reports whether the activity follows the system value, and restoreSystem drops the app override. On iOS these resolve the app value or the matching empty value (unknown mode, always using system) and change nothing.

System writes need the Android write-settings grant. Permissions resolve a granted, denied, or undetermined status with granted and can-ask-again flags; on iOS they resolve granted with no prompt. requestPermissions opens the system settings screen, so read the grant back when the app resumes. The manifest must also declare WRITE_SETTINGS, which prebuild does not stamp yet: grant it from the settings screen, or on dev builds with adb. Without the declaration and the grant, setSystem and setSystemMode reject with E_BRIGHTNESS_PERMISSIONS.

API reference

Platform differences

Limits and gotchas

• Restore what you set. App brightness outlives the screen on iOS until the device locks. Save the starting value and write it back.
• System writes need two things. The manifest declaration plus the user grant; either missing rejects the call.
• Read the grant on resume. The settings screen leaves your app, so the promise result may predate the user’s choice. Re-read on return.
• Simulator listeners stay quiet. iOS never posts the notification there. Prove event flows on hardware.
• The mode setter takes two modes. Unknown is read-only; only manual and automatic can be written.

Examples

import { useEffect } from 'react'
import { One } from 'one'

function useScannerBrightness() {
  useEffect(() => {
    async function boost() {
      const initial = await One.Brightness.get()
      await One.Brightness.set(1)
      return initial
    }
    const initial = boost()
    return () => {
      void initial.then((value) => One.Brightness.set(value))
    }
  }, [])
}

Full brightness helps the camera freeze barcodes in dim aisles. The cleanup restores the exact prior value even when the screen unmounts mid-boost.

import { useEffect } from 'react'
import { One } from 'one'

function useNightDim(night: boolean) {
  useEffect(() => {
    if (!night) return
    async function dim() {
      const initial = await One.Brightness.get()
      await One.Brightness.set(0.2)
      return initial
    }
    const initial = dim()
    return () => {
      void initial.then((value) => One.Brightness.set(value))
    }
  }, [night])
}

Tying the effect to the night flag restores brightness the moment night mode turns off or the screen unmounts, whichever comes first.