@capgo/capacitor-light-sensor

Capacitor plugin for accessing the device's ambient light sensor.

Why Capacitor Light Sensor?

- Real Ambient Light Data: Get accurate light level readings in lux
- Efficient Sensor Access: Uses native Android sensor APIs for optimal performance
- Configurable Update Intervals: Control how often you receive sensor updates
- Battery Conscious: Start and stop the sensor as needed to conserve battery
- TypeScript Support: Full type definitions for a great developer experience

Platform Support

| Platform | Support |
|----------|---------|
| Android | ✅ Full support via TYPE_LIGHT sensor |
| iOS | ❌ Not available (no public API) |
| Web | ❌ Not available |

Compatibility

| Plugin version | Capacitor compatibility | Maintained |
| -------------- | ----------------------- | ---------- |
| v8.\.\ | v8.\.\ | ✅ |
| v7.\.\ | v7.\.\ | On demand |
| v6.\.\ | v6.\.\ | ❌ |
| v5.\.\ | v5.\.\ | ❌ |

> Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Installation

``bash
npm install @capgo/capacitor-light-sensor
npx cap sync
`

Requirements

$3

- Minimum SDK: 24 (Android 7.0)
- Target SDK: 36
- Device must have a light sensor (most Android phones do)

$3

For update intervals below 200ms on Android 12 and above, add this permission to your AndroidManifest.xml:

`xml

`

Usage

`typescript
import { LightSensor } from '@capgo/capacitor-light-sensor';

// Check if sensor is available
const { available } = await LightSensor.isAvailable();

if (available) {
// Start listening with 500ms update interval
await LightSensor.start({ updateInterval: 500 });

// Add listener for sensor data
const handle = await LightSensor.addListener('lightSensorChange', (data) => {
console.log(Light level: ${data.illuminance} lux);
console.log(Timestamp: ${data.timestamp});
});

// Later, stop the sensor
await LightSensor.stop();
await handle.remove();
}
`

Light Level Reference

| Lux Value | Condition |
|-----------|-----------|
| 0.0001 | Moonless, overcast night |
| 0.27-1 | Full moon on a clear night |
| 3.4 | Dark limit of civil twilight |
| 50 | Family living room |
| 80 | Office hallway |
| 100 | Very dark overcast day |
| 400 | Sunrise/sunset on clear day |
| 1,000 | Overcast day |
| 10,000-25,000 | Full daylight (indirect) |
| 32,000-100,000 | Direct sunlight |

API

* isAvailable()
* start(...)
* stop()
* addListener('lightSensorChange', ...)
* removeAllListeners()
* checkPermissions()
* requestPermissions()
* getPluginVersion()
* Interfaces
* Type Aliases




Capacitor plugin for accessing the device's ambient light sensor.

$3

`typescript
isAvailable() => Promise
`

Check if the light sensor is available on the current device.
You should always check sensor availability before attempting to use it.

Returns: Promise<IsAvailableResult>

Since: 0.0.1

--------------------




$3

`typescript
start(options?: StartOptions | undefined) => Promise
`

Start listening to light sensor updates.
This will begin sensor measurements at the specified interval.
Use addListener to receive the sensor data.

| Param | Type | Description |
| ------------- | ----------------------------------------------------- | -------------------------------------- |
| options | StartOptions | - Configuration options for the sensor |

Since: 0.0.1

--------------------




$3

`typescript
stop() => Promise
`

Stop listening to light sensor updates.
This will stop the sensor and conserve battery.

Since: 0.0.1

--------------------




$3

`typescript
addListener(eventName: 'lightSensorChange', listenerFunc: LightSensorCallback) => Promise
`

Add a listener for light sensor change events.
The listener will be called whenever new sensor data is available.

| Param | Type | Description |
| ------------------ | ------------------------------------------------------------------- | ------------------------------------------ |
| eventName | 'lightSensorChange' | - Must be 'lightSensorChange' |
| listenerFunc | LightSensorCallback | - Callback function to receive sensor data |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

--------------------




$3

`typescript
removeAllListeners() => Promise
`

Remove all listeners for light sensor events.

Since: 0.0.1

--------------------




$3

`typescript
checkPermissions() => Promise
`

Check the current permission status for high sampling rate sensors.
On Android 12+, the HIGH_SAMPLING_RATE_SENSORS permission is required
for sensor update intervals below 200ms.

Returns: Promise<PermissionStatus>

Since: 0.0.1

--------------------




$3

`typescript
requestPermissions() => Promise
`

Request permission for high sampling rate sensors.
On Android 12+, this requests the HIGH_SAMPLING_RATE_SENSORS permission.

Returns: Promise<PermissionStatus>

Since: 0.0.1

--------------------




$3

`typescript
getPluginVersion() => Promise
`

Get the current version of the plugin.

Returns: Promise<VersionResult>

Since: 0.0.1

--------------------




$3


#### IsAvailableResult

Result indicating whether the sensor is available.

| Prop | Type | Description | Since |
| --------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------- | ----- |
| available | boolean | Whether the light sensor is available on this device. Always false on iOS as the light sensor API is not available. | 0.0.1 |


#### StartOptions

Options for starting the light sensor listener.

| Prop | Type | Description | Default | Since |
| -------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | ----- |
| updateInterval | number | The desired interval between sensor updates in milliseconds. On Android 12+, there's a minimum interval of 200ms unless the app has the HIGH_SAMPLING_RATE_SENSORS permission. | 200 | 0.0.1 |


#### PluginListenerHandle

| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |


#### LightSensorMeasurement

A single light sensor measurement.

| Prop | Type | Description | Since |
| ----------------- | ------------------- | ---------------------------------------------------- | ----- |
| illuminance | number | Ambient light level in lux (lx). | 0.0.1 |
| timestamp | number | Timestamp of the measurement in seconds since epoch. | 0.0.1 |


#### PermissionStatus

Result of a permission request or check.

| Prop | Type | Description | Since |
| ---------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| highSamplingRate | 'prompt' \| 'prompt-with-rationale' \| 'granted' \| 'denied' | Whether the high sampling rate sensor permission is granted. On Android 12+, this permission is required for update intervals below 200ms. | 0.0.1 |


#### VersionResult

Plugin version information.

| Prop | Type | Description | Since |
| ------------- | ------------------- | ---------------------------------- | ----- |
| version` | string | The current version of the plugin. | 0.0.1 |

$3

#### LightSensorCallback

Callback function for light sensor updates.

(measurement: LightSensorMeasurement): void

Contributing

See CONTRIBUTING.md for details on how to contribute to this plugin.

License

MPL-2.0

Credits

This SDK has been inspired by Expo light sensor.