getBrightness

Info

getBrightness queries the current screen brightness through WMI (Windows Management Instrumentation). It returns a BrightnessInfo object containing the brightness percentage and display metadata, or null if no WMI-compatible display is available. This is a synchronous one-shot read — it does not subscribe to changes.

Signature

function getBrightness(): BrightnessInfo | null;

Usage

Call getBrightness when you need to read the current screen brightness — for example, to display the value in a UI slider, log the state, or decide whether to adjust brightness based on ambient conditions. Because this is a synchronous one-shot query, it does not reflect external changes made after the call returns. For real-time monitoring, use BrightnessMonitor instead.

Tips

If you only need the brightness value once at startup or on demand, getBrightness is the simplest choice. If you need to react to every brightness change (e.g. hardware buttons, OS adjustments), prefer BrightnessMonitor for event-driven tracking without polling overhead.

Return Value

Returns a BrightnessInfo object, or null if brightness cannot be read (e.g. no WMI-compatible display, or the query failed).

The BrightnessInfo object has the following shape:

Property	Type	Description
currentBrightness	number	Current brightness percentage (0–100)
levels	number[] | null	Array of brightness levels supported by the display, or null if unavailable
instanceName	string | null	WMI monitor instance name, or null if unavailable

Warning

The return value can be null. Systems without WMI-compatible displays (e.g. some desktop monitors connected via HDMI/DP) will return null. Always check for null before accessing properties on the result.

Example

TypeScript

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

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

if (info) {
  // Brightness is a percentage from 0 to 100
  console.log(`Current brightness: ${info.currentBrightness}%`);
  // Log the supported brightness levels (if available)
  if (info.levels) {
    console.log(`Supported levels: ${info.levels.join(', ')}`);
  }
} else {
  // No WMI-compatible display found or query failed
  console.log('Unable to read brightness');
}

JavaScript

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

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

if (info) {
  // Brightness is a percentage from 0 to 100
  console.log(`Current brightness: ${info.currentBrightness}%`);
  // Log the supported brightness levels (if available)
  if (info.levels) {
    console.log(`Supported levels: ${info.levels.join(', ')}`);
  }
} else {
  // No WMI-compatible display found or query failed
  console.log('Unable to read brightness');
}

Notes

Note

This function performs a synchronous WMI query. While the call is fast on most systems, avoid calling it in a tight loop; cache the result and re-query only when needed, or use BrightnessMonitor for continuous tracking.

Note

External brightness changes made by the OS, hardware buttons, or other applications are not reflected until you call getBrightness again. This function reads a snapshot, not a live subscription.

Tips

The levels and instanceName fields may be null on some hardware even when currentBrightness is available. Guard against null on each field individually if you plan to use them.

Danger Avoidance

Caution

Do not assume the return value is always non-null. Systems without WMI-compatible displays (e.g. some desktop monitors connected via HDMI/DP) will return null. Always guard against null before accessing properties like currentBrightness, or your application will crash with a TypeError.

Caution

Do not poll getBrightness in a rapid loop (e.g. setInterval with < 500ms). Each call triggers a WMI query which involves COM initialization and system-level IPC. Excessive polling can cause high CPU usage and WMI provider contention. Use BrightnessMonitor for event-driven brightness tracking instead.