Getting Started

Copy a setup prompt with the install steps and the full markdown guide for this plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-light-sensor`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/light-sensor/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Install

bun add @capgo/capacitor-light-sensor
bunx cap sync

Import

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

API Overview

`isAvailable`

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

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

const { available } = await LightSensor.isAvailable();

`start`

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

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

await LightSensor.start({ updateInterval: 500 });

`stop`

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

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

await LightSensor.stop();

`checkPermissions`

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.

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

const status = await LightSensor.checkPermissions();

`requestPermissions`

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

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

const status = await LightSensor.requestPermissions();

Type Reference

`IsAvailableResult`

Result indicating whether the sensor is available.

export interface IsAvailableResult {
  /**
   * Whether the light sensor is available on this device.
   * Always false on iOS as the light sensor API is not available.
   *
   * @since 0.0.1
   */
  available: boolean;
}

`StartOptions`

Options for starting the light sensor listener.

export interface StartOptions {
  /**
   * 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.
   *
   * @default 200
   * @since 0.0.1
   */
  updateInterval?: number;
}

`LightSensorCallback`

Callback function for light sensor updates.

export type LightSensorCallback = (measurement: LightSensorMeasurement) => void;

`PermissionStatus`

Result of a permission request or check.

export interface PermissionStatus {
  /**
   * Whether the high sampling rate sensor permission is granted.
   * On Android 12+, this permission is required for update intervals below 200ms.
   *
   * @since 0.0.1
   */
  highSamplingRate: 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';
}

`VersionResult`

Plugin version information.

export interface VersionResult {
  /**
   * The current version of the plugin.
   *
   * @since 0.0.1
   */
  version: string;
}

`LightSensorMeasurement`

A single light sensor measurement.

export interface LightSensorMeasurement {
  /**
   * Ambient light level in lux (lx).
   *
   * @since 0.0.1
   */
  illuminance: number;

  /**
   * Timestamp of the measurement in seconds since epoch.
   *
   * @since 0.0.1
   */
  timestamp: number;
}

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.