useScreen

Hook to work with Screen Orientation API.

See: Screen Orientation API.

See: Window Management API.

Demo

INFO

The component shows screens information.

Loading demo…

Show source code

import { useScreen } from "../../../.."

export const UseScreen = () => {
	const [details] = useScreen(true);

	return <div style={{ textAlign: "left", padding: "0 1em", maxHeight: 300, overflow: "auto", border: "1px solid lightgray" }}>
		<p><strong>Current screen:</strong></p>
		<pre>{JSON.stringify(details.currentScreen, null, 2)}</pre>
		<p><strong>Screens:</strong></p>
		{
			details.screens?.map((el, index) => (
				<pre key={index}>{el.label}</pre>
			))
		}
	</div>
}

Types

ScreenDetail

Detailed information about a single screen, extending the standard Screen interface with additional properties available via the Window Management API.

Property	Type	Required	Description
availLeft	number \| undefined	✓	X-coordinate (left edge) of the available screen area — the area not occupied by the OS taskbar or dock. undefined when not available.
availTop	number \| undefined	✓	Y-coordinate (top edge) of the available screen area. undefined when not available.
devicePixelRatio	number \| undefined	✓	Ratio of physical pixels to CSS pixels for this screen. Higher values indicate high-DPI / Retina displays. undefined when not available via the Window Management API.
isInternal	boolean \| undefined	✓	true when this is a built-in screen (e.g. laptop display). false for external monitors. undefined when not available.
isPrimary	boolean \| undefined	✓	true when this is the operating system's primary/main screen. undefined when not available via the Window Management API.
label	string \| undefined	✓	Human-readable label for the screen as reported by the OS (e.g. "Built-in Retina Display", "LG UltraWide"). undefined when not available.
left	number \| undefined	✓	X-coordinate (left edge) of the total screen area in the multi-screen coordinate space. undefined when the Window Management API is not available.
top	number \| undefined	✓	Y-coordinate (top edge) of the total screen area in the multi-screen coordinate space. undefined when the Window Management API is not available.
orientation	{ type: OrientationType; angle: number; }	✓	Current orientation of the screen, including type and angle.

ScreenDetails

Aggregated screen information returned by useScreen.

Property	Type	Required	Description
currentScreen	ScreenDetail	✓	Details of the screen currently displaying the browser window.
screens	ScreenDetail[] \| undefined	✓	Details of all screens connected to the device. undefined when the Window Management API is unavailable or permission was denied.

ScreenDetailsEvt

Internal interface extending ScreenDetails for the Window Management API event target.

Property	Type	Required	Description
oncurrentscreenchange	((evt: Event) => void) \| null	✓	Called when the current screen changes (e.g. window moved to another display).
onscreenschange	((evt: Event) => void) \| null	✓	Called when the set of available screens changes (monitor connected/disconnected).

OrientationLockType

Screen orientation lock type supported by the Screen Orientation API. Pass one of these values to the lockOrientation function returned by useScreen.

export type OrientationLockType = "any" | "natural" | "landscape" | "portrait" | "portrait-primary" | "portrait-secondary" | "landscape-primary" | "landscape-secondary"

UseScreenProps

Parameters accepted by useScreen.

Property	Type	Required	Description
allScreen	boolean		When true, the hook requests access to the full multi-screen details via the Window Management API, populating per-screen properties such as availLeft, availTop, left, top, devicePixelRatio, isInternal, isPrimary, and label for each screen. Requires the "window-management" permission to be granted. When false or omitted, only the standard screen properties are populated and multi-screen fields are undefined.

UseScreenResult

Return value of useScreen.

Index	Type	Description
[0]	ScreenDetails	A reactive snapshot of the current screen details. Includes standard screen properties (width, height, availWidth, availHeight, colorDepth, pixelDepth, orientation) on currentScreen, plus extended per-screen properties when allScreen is true and the Window Management API is available.
[1]	(orientation: OrientationLockType) => Promise<void>	Requests a screen orientation lock, constraining the device to the specified {@link OrientationLockType} (e.g. "portrait-primary", "landscape"). Resolves when the lock is acquired. Rejects if the browser does not support orientation locking or if the request is denied.
[2]	() => void	Releases the current orientation lock, allowing the device to rotate freely again. No-op if no lock is currently held.