Torch

The phone's flashlight — the LED beside the back camera, lit as a lamp: on and off, how bright, whether the device has one. From the torch plugin; it needs no permission. A light in a 3D scene (a player's flashlight, a car's headlight) is Light.spot() (light.md).

  • turn the phone's flashlight on and off with a button
  • set how bright the flashlight is
  • hide the flashlight button on a device that has none (Torch.available())
  • show that the flashlight went off when the system or another app turned it off (Torch.onChange)
  • tell the user why the flashlight did not light
  • turn the flashlight off when the screen closes

Platforms: iOS, Android; not on the web, in the web player, on desktop or in headless tests — check Torch.supported.

At a glance

TypeScript
// app.json: "plugins": { "torch": "*" }
const lit = signal(false)
const hasTorch = signal(false)

Torch.available().then(yes => { hasTorch.value = yes })    // false on the web, in the iOS simulator, on most tablets
Torch.onChange(state => { lit.value = state.on })           // the system or another app changed it

const toggle = async () => {
  try {
    lit.value = (await Torch.toggle()).on
  } catch (e) {
    toast(e.message === 'busy' ? 'The camera is using the flashlight' : 'The flashlight is not available')
  }
}

Router.init(UIScreen(
  UIColumn(() => [hasTorch.value
    ? UIButton(UIText(() => (lit.value ? 'Flashlight off' : 'Flashlight on')).style({ color: 'white' })).onClick(toggle)
    : UIText('This device has no flashlight').style({ color: 'gray' })]),
).style({ bgColor: 'black', p: 20, pt: 'safe-top', gap: 16 }))

Add the torch plugin to the app: app.json

The flashlight is the torch plugin: list it in the project's app.json — "plugins": { "torch": "*" }. The list is one for every platform: a plugin it does not name is not there, and the compile warns about one the app uses and does not list. The le.codes viewer app has the plugin whatever the list says. No permission, no usage string: lighting the torch does not open the camera on either platform. On Android the flash is declared not required, so the app installs on a device without one.

Turn the flashlight on and off: Torch.set, Torch.toggle

TypeScript
Torch.set(on: boolean, level?: number): Promise<TorchState>   // level 0..1, clamped; 0 = off; left out = the platform's default
Torch.toggle(): Promise<TorchState>                           // off → on at the level this app last lit it at; on → off
Torch.state(): Promise<TorchState>                            // never rejects; off where there is no torch

interface TorchState { on: boolean, level: number }           // level (0, 1] while lit (1 on a torch that does not dim), 0 when off

Both resolve with the state the torch is in after the call. set(false) turns it off whatever the level. state() asks the device: the torch may have changed since the app last set it.

TypeScript
const lightUp = async () => {
  const state = await Torch.set(true)              // full on iOS, the flash's default strength on Android
  console.log(state.on, state.level)
}
const lightDown = () => Torch.set(false)

Set how bright the flashlight is: level, info().dimmable

TypeScript
Torch.info(): Promise<TorchInfo>                   // never rejects

interface TorchInfo {
  available: boolean                               // the device has a torch the app can light
  dimmable: boolean                                // its brightness can be set
}

A level is a fraction of full brightness. iOS dims continuously, and a warm LED gives less than asked — the state says what it took. Android 13+ dims in the strength steps its flash has, where it has several, and the state reports the step it took. Every other device lights at its one brightness and reports level: 1; info().dimmable is false there.

TypeScript
const level = signal(1)

const brightness = async (wanted: number) => {
  const { dimmable } = await Torch.info()
  if (!dimmable) return                                    // one brightness: on or off only
  level.value = (await Torch.set(true, wanted)).level      // what the torch took: a warm LED, an Android step
}

UIRow(
  UIButton(UIText('Dim')).onClick(() => brightness(0.25)),
  UIButton(UIText('Bright')).onClick(() => brightness(1)),
).style({ gap: 12 })

Hide the flashlight button where there is none: Torch.supported, Torch.available()

TypeScript
Torch.supported: boolean                 // this host registered the "torch" service
Torch.available(): Promise<boolean>      // the device has a torch the app can light; never rejects

supported is false on the web, in the web player, in headless tests, on desktop and in a shell built without the plugin. available() is false there too, and also in the iOS simulator and on most tablets — the one to ask before showing a button. On a host without the service, info(), available() and state() answer "no torch, off" and set() / toggle() reject "unavailable": the same code the app already handles for a phone without a flash. Nothing throws there.

TypeScript
const hasTorch = signal(false)
Torch.available().then(yes => { hasTorch.value = yes })

UIColumn(() => [hasTorch.value
  ? UIButton(UIText('Flashlight')).onClick(() => Torch.toggle().catch(e => toast(e.message)))
  : UIText('No flashlight on this device')])

Tell the user why the flashlight did not light: the codes

set() and toggle() reject with a code as e.message:

code when
"unavailable" no torch (also every host without the service); iOS holds it back while the LED is too hot
"busy" Android: a camera has the flash — another app's, or a camera this app has open (CameraView, QRScanner)
"failed" anything else
TypeScript
const toggle = async () => {
  try {
    await Torch.toggle()
  } catch (e) {
    if (e.message === 'busy') toast('Close the camera to use the flashlight')
    else if (e.message === 'unavailable') toast('The flashlight is not available right now')
    else toast('The flashlight did not turn on')
  }
}

Follow what the system or another app does to it: Torch.onChange

TypeScript
Torch.onChange(listener: (state: TorchState) => void): () => void   // returns a function that stops listening

The torch is the device's, not the app's: another app, the camera or the system may change it — a warm LED makes iOS lower its level, then turn it off. onChange reports every change while the app listens, the app's own set() too; it is never called on a host without the service. Draw the button from it, not from what the app last asked.

TypeScript
const lit = signal(false)
const stop = Torch.onChange(state => { lit.value = state.on })
Torch.state().then(state => { lit.value = state.on })     // the torch may be lit already

Turn the flashlight off when the screen closes: onClose

Nothing turns the torch off for the app: it stays lit after the screen that lit it is gone, until the app, the user or the system turns it off. A screen that lights it turns it off when it closes.

TypeScript
const screen = UIScreen(
  UIButton(UIText('Flashlight')).onClick(() => Torch.toggle().catch(e => toast(e.message))),
).onClose(() => {
  Torch.set(false).catch(() => {})                 // nothing to turn off on a host without a torch
})

See also

  • camera-view.md — the camera preview and photos (no flash control of its own)
  • light.md — a flashlight inside a 3D scene: Light.spot()