setBrightness

Info

setBrightness is a function that sets the screen brightness to a specified percentage via Windows WMI (Windows Management Instrumentation). It accepts a value from 0 to 100 and returns a boolean indicating whether the brightness was applied successfully. This is the primary write API in the brightness-helper plugin, complementing the read-only getBrightness function.

Signature

function setBrightness(brightness: number): boolean

Parameters

Parameter	Type	Description
brightness	number	Target brightness percentage (0--100). Values outside this range are clamped by the WMI provider.

Return Value

Returns true if the brightness was set successfully, false otherwise. A false return typically means the display device is not accessible or WMI failed to apply the change.

Warning

Always check the return value before assuming the brightness changed. A false result does not throw -- it silently signals failure. Use getBrightness afterward to confirm the actual brightness if certainty is required.

Usage

Call setBrightness whenever you need to change the screen brightness programmatically -- for example in response to a user slider adjustment, a time-of-day schedule, or an ambient light sensor reading. The change takes effect immediately and persists until the next call or until the system enters sleep.

Tips

After calling setBrightness, verify the result by calling getBrightness and checking the currentBrightness field. This is especially important in automated scripts where the user cannot visually confirm the change.

Tips

If you need to restore the original brightness later (e.g. on app exit), read it with getBrightness before overwriting and save the value. There is no built-in restore mechanism.

Example

TypeScript

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

// Save the current brightness before changing it
const original = getBrightness();
const savedBrightness = original ? original.currentBrightness : null;

// Set brightness to 75%
const success = setBrightness(75);

// Log whether the brightness change succeeded
console.log(success ? 'Brightness updated' : 'Failed to set brightness');

// Verify by reading the current brightness back
const info = getBrightness();
if (info) {
  // currentBrightness is a percentage from 0 to 100
  console.log(`Now at: ${info.currentBrightness}%`);
}

// Later, restore the original brightness if it was saved
if (savedBrightness !== null) {
  setBrightness(savedBrightness);
}

JavaScript

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

// Save the current brightness before changing it
const original = getBrightness();
const savedBrightness = original ? original.currentBrightness : null;

// Set brightness to 75%
const success = setBrightness(75);

// Log whether the brightness change succeeded
console.log(success ? 'Brightness updated' : 'Failed to set brightness');

// Verify by reading the current brightness back
const info = getBrightness();
if (info) {
  // currentBrightness is a percentage from 0 to 100
  console.log(`Now at: ${info.currentBrightness}%`);
}

// Later, restore the original brightness if it was saved
if (savedBrightness !== null) {
  setBrightness(savedBrightness);
}

Notes

Note

Brightness changes are applied immediately and persist until the next change or system sleep. There is no built-in "restore to previous value" mechanism -- if you need to restore the original brightness, read it with getBrightness before overwriting.

Note

The brightness parameter accepts whole numbers. Fractional values will be truncated by the underlying WMI provider.

Note

This function operates through WMI (WmiMonitorBrightnessMethods), which requires the application to run with sufficient privileges. On some systems, brightness control may not work if the WMI provider is unavailable or the display driver does not expose brightness methods.

Danger Avoidance

Caution

Setting brightness to 0 will turn the screen completely dark, making it very difficult to interact with the application or adjust the value back. Always enforce a sensible minimum (e.g. 5--10) in your UI when offering user-controlled brightness sliders.

Caution

Do not call setBrightness in a tight loop (e.g. on every mouse-move event of a slider). Rapidly issuing WMI brightness commands can cause visual flickering and may temporarily freeze the display. Debounce calls to at most one per 50--100 ms.