BrightnessInfo

Info

BrightnessInfo is a data structure returned by the getBrightness function. It contains the current screen brightness percentage, an optional list of supported brightness levels, and the display monitor's instance name. You never construct this object yourself — it comes from querying the system's WMI brightness provider.

Interface Introduction

You encounter BrightnessInfo whenever you call getBrightness(). The returned object tells you the brightness right now, which discrete levels the display supports (if reported by hardware), and which physical monitor the data came from. If no compatible WMI display is found, getBrightness() returns null instead.

export interface BrightnessInfo {
  /** Current brightness percentage (0-100) */
  currentBrightness: number;
  /** Display-supported brightness levels (0-100), null if unavailable */
  levels: number[] | null;
  /** Display monitor instance name, null if unavailable */
  instanceName: string | null;
}

Usage

Call getBrightness() to receive a BrightnessInfo object or null. The currentBrightness field is always populated when the object is non-null. The levels and instanceName fields may be null depending on the display hardware and WMI support.

Use currentBrightness for quick checks

If you only need the current brightness value, access currentBrightness directly — no need to inspect the other fields. The value is always a whole number between 0 and 100 inclusive.

import { getBrightness } from '@eisland/windows-brightness-helper';

// Receive a BrightnessInfo object or null
const info = getBrightness();

Properties

Property	Type	Description
currentBrightness	number	Current brightness percentage (0-100)
levels	number[] | null	Supported brightness levels (0-100), null if unavailable
instanceName	string | null	Display monitor instance name, null if unavailable

levels may be empty or null

The levels field is null when the display does not report its supported brightness steps through WMI. Even when non-null, the array may be empty on certain hardware. Always guard before calling array methods like .length or .includes().

Use instanceName to identify the monitor

On multi-monitor setups, instanceName lets you distinguish which physical display the brightness data belongs to. Store it if you need to correlate brightness queries across sessions.

Example

TypeScript

import { getBrightness } from '@eisland/windows-brightness-helper';

// Query the current screen brightness
const info = getBrightness();

// getBrightness() returns null when no WMI-compatible display is found
if (info) {
  // currentBrightness is a whole number from 0 to 100
  console.log(`Brightness: ${info.currentBrightness}%`);

  // levels lists discrete steps the display supports; may be null
  if (info.levels) {
    console.log(`Supported levels: ${info.levels.join(', ')}`);
  }

  // instanceName identifies the physical monitor; may be null
  if (info.instanceName) {
    console.log(`Monitor: ${info.instanceName}`);
  }
} else {
  // No WMI-compatible display detected
  console.log('Brightness info unavailable');
}

JavaScript

const { getBrightness } = require('@eisland/windows-brightness-helper');

// Query the current screen brightness
const info = getBrightness();

// getBrightness() returns null when no WMI-compatible display is found
if (info) {
  // currentBrightness is a whole number from 0 to 100
  console.log(`Brightness: ${info.currentBrightness}%`);

  // levels lists discrete steps the display supports; may be null
  if (info.levels) {
    console.log(`Supported levels: ${info.levels.join(', ')}`);
  }

  // instanceName identifies the physical monitor; may be null
  if (info.instanceName) {
    console.log(`Monitor: ${info.instanceName}`);
  }
} else {
  // No WMI-compatible display detected
  console.log('Brightness info unavailable');
}

Notes

Multiple displays

If the system has multiple monitors, getBrightness() returns brightness data for the primary WMI-compatible display. The instanceName field identifies which monitor the data belongs to. Use BrightnessMonitor to track changes on the same display.

WMI dependency

BrightnessInfo data comes from Windows WMI (WmiMonitorBrightness). Systems where WMI is disabled or where the display driver does not expose brightness data through WMI will always return null from getBrightness().

Combining with setBrightness

After reading currentBrightness from a BrightnessInfo object, you can pass a new value to setBrightness to adjust the screen. The value range is the same 0-100 scale used by currentBrightness.

Danger Avoidance

Do not assume getBrightness() always returns a value

getBrightness() returns null when no WMI-compatible display is detected — this happens with external monitors connected via non-WMI interfaces, virtual displays, or systems with WMI disabled. Accessing .currentBrightness on null throws a TypeError. Always check for null before reading any property.

Do not mutate the returned object

The BrightnessInfo object returned by getBrightness() is meant to be read-only. Mutating its properties has no effect on the actual screen brightness and may cause confusion if the object is referenced elsewhere. Use setBrightness to change brightness.