win-screen-resolution

About

A NAPI Native C++ addon to get the current and all available screen resolution on Windows (DPI Aware).

Example

import { 
  getCurrentResolution, 
  getAvailableResolution 
} from "win-screen-resolution";

console.log(getCurrentResolution()); 
//{ width: 1920, height: 1080 }

console.log(getAvailableResolution());
/*
[
  { width: 1920, height: 1080 },
  { width: 1768, height: 992 },
  { width: 1680, height: 1050 },
  { width: 1600, height: 1024 },
  ...
]
*/

You may want the raw data which has more information such as the refresh rate:

import { 
  getCurrentDisplayMode, 
  getAvailableDisplayMode 
} from "win-screen-resolution";

console.log(getCurrentDisplayMode()); 
//{ width: 1920, height: 1080, hz: 60, scale: 100, color: 32 }

console.log(getAvailableDisplayMode());
/*
[
  { width: 640, height: 480, hz: 59, color: 32 },
  { width: 640, height: 480, hz: 60, color: 32 },
  { width: 640, height: 480, hz: 75, color: 32 },
  { width: 720, height: 480, hz: 60, color: 32 },
  ...
]
*/

Multi-monitor

import { 
  getActiveDisplays, 
  setPrimaryDisplay 
} from "win-screen-resolution";

const displays = getActiveDisplays();
console.log(displays);
/*
[{
    id: '\\\\.\\DISPLAY1',
    adapter: 'NVIDIA GeForce GTX 1060 6GB',
    monitor: 'LG ULTRAGEAR(DisplayPort)',
    primary: true,
    width: 2560,
    height: 1440,
    hz: 165,
    scale: 100,
    offset: { x: 0, y: 0 }
  },
  {
    id: '\\\\.\\DISPLAY5',
    adapter: 'Intel(R) HD Graphics 530',
    monitor: 'Dell U2417H (HDMI)',
    primary: false,
    width: 1920,
    height: 1080,
    hz: 59,
    scale: 100,
    offset: { x: 2560, y: 0 }
  }]
*/

//Change primary display
setPrimaryDisplay(displays[1].id); //by identifier
//OR
setPrimaryDisplay(1); //by index

Installation

npm install win-screen-resolution

🚀 x86, x64 and arm64 prebuilt binary provided.

Force compiling:

npm install win-screen-resolution --build-from-source

You will need C/C++ build tools and Python 3.x (node-gyp) to build this module.

⚠️ This package doesn't have any installation restrictions in its package.json file to facilitate multi-platform development; however, it is at the moment only designed to work on Windows.

API

⚠️ This module is only available as an ECMAScript module (ESM) starting with version 2.0.0.
Previous version(s) are CommonJS (CJS) with an ESM wrapper.

DPI Awareness

The following exports are DPI aware meaning that their results won't change with different DPI scalor factor. Please note that support for DPI awareness on Windows 7/8 was removed in 3.x. If you need it use previous version.

Named export

getCurrentDisplayMode(): object

Get the current primary display video mode as follows:

{
  width: number, //Horizontal resolution
  height: number, //Vertical resolution
  hz: number, //Refresh rate
  color: number, //Color depth in bits/pixel
  scale: number|object //DPI scale factor in %
}

❌ Will throw if not running Win10 or greater.

getAvailableDisplayMode(): object[]

Get all available video modes from the primary display as follows:

[
  {
    width: number, //Horizontal resolution
    height: number, //Vertical resolution
    hz: number, //Refresh rate
    color: number //Color depth in bits/pixel
  }
]

❌ Will throw if not running Win10 or greater.

getCurrentResolution(): object

Get the current primary display screen resolution as follows:

{
  width: number,
  height: number
}

This is a short hand to getCurrentDisplayMode().

❌ Will throw if not running Win10 or greater.

getAvailableResolution(): object[]

Get all available screen resolutions from the primary display as follows sorted from highest to lowest as follows:

[
  {
    width: number,
    height: number
  }
]

This is a short hand to getAvailableDisplayMode().

💡 Available screen resolution below 800x600 are ignored because of Windows 10 min display resolution requirement.

❌ Will throw if not running Win10 or greater.

getActiveDisplays(): object[]

List the current settings of every display devices attached to the desktop as follows:

[
  {
    id: string, //Device id
    adapter: string, //Adapter name
    monitor: string, //Monitor name
    primary: boolean,
    width: number, //Pixels X
    height: number, //Pixels Y
    hz: number, //Frequency
    scale: number|object, //DPI scale factor
    offset: { x: number, y: number } //Position in the Windows virtual screen¹
  }
]

¹Windows virtual screen

❌ Will throw if not running Win10 or greater.

setPrimaryDisplay(display: string|number): void

Switch the primary display to specified display.

If display is a string then the device id is assumed;
If it's a number then the array index is used.

Call getActiveDisplays() to list available displays.

⚠️ Please be carefull that the list of displays might have changed between the time you called getActiveDisplays() and setPrimaryDisplay(). Depending on your use case you might be better of using the device id to avoid this problem.

❌ Will throw on error.
❌ Will throw if not running Win10 or greater.