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
// 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
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 offBoth 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.
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
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.
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()
Torch.supported: boolean // this host registered the "torch" service
Torch.available(): Promise<boolean> // the device has a torch the app can light; never rejectssupported 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.
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 |
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
Torch.onChange(listener: (state: TorchState) => void): () => void // returns a function that stops listeningThe 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.
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 alreadyTurn 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.
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()