# win-screen-resolution

> Get the current and all available screen resolution on Windows

Latest version **4.0.0** (published 2024-11-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install win-screen-resolution
pnpm add win-screen-resolution
yarn add win-screen-resolution
bun add win-screen-resolution
```

## Health

**Score 45/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2024-11-10 |
| First published | 2020-08-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=22.11.0 |
| Dependencies | 4 |
| Unpacked size | 388.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 9 |
| Author | Anthony Beaumont |
| Maintainers | xan105 |
| Keywords | screen, resolution, windows, DPI, display, primary |

## Links

- npm: https://www.npmjs.com/package/win-screen-resolution
- Repository: https://github.com/xan105/node-win-screen-resolution
- Homepage: https://github.com/xan105/node-win-screen-resolution#readme
- Issues: https://github.com/xan105/node-win-screen-resolution/issues
- Funding: https://github.com/sponsors/xan105
- npm.io page: https://npm.io/package/win-screen-resolution

## Dependencies (4)

- [@xan105/is](https://npm.io/package/@xan105/is.md) ^2.10.1
- [@xan105/error](https://npm.io/package/@xan105/error.md) ^1.7.1
- [@xan105/addons](https://npm.io/package/@xan105/addons.md) ^2.1.1
- [node-addon-api](https://npm.io/package/node-addon-api.md) ^8.2.2

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 4.0.0 (latest) — 2024-11-10
- 3.0.2 — 2023-03-25
- 3.0.1 — 2023-03-22
- 3.0.0 — 2023-02-07
- 2.1.0 — 2022-12-23
- 2.0.3 — 2022-03-22
- 2.0.2 — 2022-03-03
- 2.0.0 — 2021-11-15
- 1.2.0 — 2021-07-04
- 1.1.0 — 2021-04-13
- 1.0.2 — 2021-04-07
- 1.0.1 — 2020-08-04

## README

About
=====

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

Example
=======

```js
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:

```js
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

```js
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.<br />
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:

```ts
{
  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: 

```ts
[
  {
    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:

```ts
{
  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:

```ts
[
  {
    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:

```ts
[
  {
    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](https://learn.microsoft.com/en-us/windows/win32/gdi/the-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;<br />
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.<br />
❌ Will throw if not running Win10 or greater.

---
_Source: https://npm.io/package/win-screen-resolution · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._