Capacitor Light Sensor Plugin

Capacitor plugin to read the device's ambient light sensor.

Features

The Capacitor Light Sensor plugin provides a complete solution for ambient light measurements in Capacitor apps. Here are some of the key features:

• 🌗 Illuminance: Read the ambient light level in lux.
• ⚡ Real-time measurements: Continuous light data with event listeners.
• 🖥️ Native: Supports Android.
• 📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
• 🔁 Up-to-date: Always supports the latest Capacitor version.
• 🤝 Compatibility: Works alongside the Screen Brightness plugin.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

The Light Sensor plugin is typically used to react to the lighting conditions around the device, for example:

• Adaptive theming: Switch between a light and dark theme based on the ambient light level.
• Brightness control: Combine the illuminance readings with the Screen Brightness plugin to adjust the screen brightness.
• Environment monitoring: Continuously measure the light level in a room using real-time measurement events.
• Reading comfort: Detect dark environments and suggest a more comfortable display mode to the user.

Compatibility

| Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | >=8.x.x | Active support |

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-light-sensor` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome/capacitor-light-sensor
npx cap sync

Android

Proguard

If you are using Proguard, you need to add the following rules to your proguard-rules.pro file:

-keep class io.capawesome.capacitorjs.plugins.** { *; }

iOS

iOS does not provide a public API to read the ambient light sensor, so the plugin is not implemented on this platform. The closest available signal is the screen brightness, which you can read using the Screen Brightness plugin.

Configuration

No configuration required for this plugin.

Usage

The following examples show how to check whether an ambient light sensor is available, read the current light level, and receive or stop continuous measurement updates.

Check if the light sensor is available

Check whether the device has an ambient light sensor before using the other methods. Only available on Android:

import { LightSensor } from '@capawesome/capacitor-light-sensor';

const isAvailable = async () => {
  const result = await LightSensor.isAvailable();
  return result.available;
};

Read the current light level

Get the most recent measurement from the ambient light sensor in lux. Only available on Android:

import { LightSensor } from '@capawesome/capacitor-light-sensor';

const getMeasurement = async () => {
  const measurement = await LightSensor.getMeasurement();
  console.log('Illuminance: ', measurement.illuminance);
};

Receive continuous measurements

Add a listener for the measurement event and start the measurement updates to receive real-time light data. Only available on Android:

import { LightSensor } from '@capawesome/capacitor-light-sensor';

const startMeasurementUpdates = async () => {
  await LightSensor.addListener('measurement', measurement => {
    console.log('Illuminance: ', measurement.illuminance);
  });
  await LightSensor.startMeasurementUpdates();
};

Stop receiving measurements

Stop the measurement updates and remove the listeners when you no longer need them:

import { LightSensor } from '@capawesome/capacitor-light-sensor';

const stopMeasurementUpdates = async () => {
  await LightSensor.stopMeasurementUpdates();
};

const removeAllListeners = async () => {
  await LightSensor.removeAllListeners();
};

API

• getMeasurement()
• isAvailable()
• startMeasurementUpdates()
• stopMeasurementUpdates()
• addListener('measurement', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

getMeasurement()

getMeasurement() => Promise<GetMeasurementResult>

Get the latest measurement.

This method returns the most recent measurement from the ambient light sensor.

Only available on Android.

Returns: Promise<Measurement>

Since: 0.1.0

isAvailable()

isAvailable() => Promise<IsAvailableResult>

Check if the ambient light sensor is available on the device.

Only available on Android.

Returns: Promise<IsAvailableResult>

Since: 0.1.0

startMeasurementUpdates()

startMeasurementUpdates() => Promise<void>

Start emitting measurement events.

Only available on Android.

Since: 0.1.0

stopMeasurementUpdates()

stopMeasurementUpdates() => Promise<void>

Stop emitting measurement events.

Only available on Android.

Since: 0.1.0

addListener('measurement', ...)

addListener(eventName: 'measurement', listenerFunc: (event: MeasurementEvent) => void) => Promise<PluginListenerHandle>

Called when a new measurement is available.

Only available on Android.

| Param | Type | | ------------------ | ----------------------------------------------------------------------- | | eventName | 'measurement' | | listenerFunc | (event: Measurement) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.1.0

Interfaces

Measurement

| Prop | Type | Description | Since | | ----------------- | ------------------- | ------------------------------------ | ----- | | illuminance | number | The ambient light level in lux (lx). | 0.1.0 |

IsAvailableResult

| Prop | Type | Description | Since | | --------------- | -------------------- | ------------------------------------------------------------ | ----- | | available | boolean | Whether the ambient light sensor is available on the device. | 0.1.0 |

PluginListenerHandle

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

Type Aliases

GetMeasurementResult

Measurement

MeasurementEvent

Measurement

FAQ

How is this plugin different from other similar plugins?

It reads the Android ambient light sensor in lux through a fully typed API, offering both a one-time reading and continuous real-time measurement events, plus an availability check so you can gracefully handle devices without the sensor. It pairs naturally with the Screen Brightness plugin for adaptive theming and brightness control, and is kept current with the latest Capacitor version. If a rough light signal is enough, screen brightness may cover it; if you need true illuminance values in lux, this plugin is built for exactly that.

Why is this plugin not available on iOS?

iOS does not provide a public API to read the ambient light sensor, so the plugin is not implemented on this platform. The closest available signal is the screen brightness, which you can read using the Screen Brightness plugin.

What unit are the measurements in?

The illuminance property of a measurement contains the ambient light level in lux (lx).

How do I know if the device has a light sensor?

Call the isAvailable() method, which returns whether the ambient light sensor is available on the device. It is recommended to check this before calling the other methods.

What is the difference between getMeasurement and the measurement event?

The getMeasurement() method returns the most recent measurement from the ambient light sensor as a one-time value. The measurement event, in combination with startMeasurementUpdates(), delivers continuous real-time measurements until you call stopMeasurementUpdates(). See the usage examples above.

Do I need any permissions or configuration on Android?

No permissions are required. However, if you are using Proguard, you need to add a keep rule for the plugin classes to your proguard-rules.pro file, as described in the Installation section.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

• Screen Brightness: Read and control the screen brightness.
• Proximity Sensor: Read the device's proximity sensor.
• Barometer: Obtain the static air pressure in hectopascals (hPa).
• Accelerometer: Capture the acceleration force along the x, y, and z axes.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.