use-screen-details

Snapshot a ScreenDetailed into a plain object.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useScreenDetails, placeWindow, snapshotScreen } from "@vizejs/composable/use-screen-details";

Try it

Find a second screen

Discover connected screens to open speaker notes on another display.

Open the interactive example

What to observe: Find screens asks for permission where Window Management exists and lists the screens.

openOnScreen opens a window positioned on a chosen screen. Every example renders a neutral message until it mounts, so server and client markup match, and then explains what to do when the browser lacks the API.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useMounted } from "@vizejs/composable/use-mounted";
import { useScreenDetails } from "@vizejs/composable/use-screen-details";

const mounted = useMounted();
const { supported, isExtended, screens, request } = useScreenDetails();
</script>

<template>
  <div class="composable-example">
    <p>Open speaker notes on a second screen when one is connected.</p>
    <button type="button" :disabled="!mounted || !supported" @click="() => request()">
      Find screens
    </button>
    <ul aria-label="Screens">
      <li v-for="(screen, index) in screens" :key="screen.label || index">
        {{ screen.label || `Screen ${index + 1}` }}
      </li>
    </ul>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : !supported
          ? "Window Management is not available; open the notes in a new tab."
          : isExtended
            ? "A second screen is connected."
            : "One screen detected."
    }}</output>
  </div>
</template>

Runtime contract

API

snapshotScreen

Snapshot a ScreenDetailed into a plain object.

function snapshotScreen(screen: ScreenSnapshot): ScreenSnapshot

placeWindow

Compute absolute window geometry inside a screen's available area. Sizes are clamped to the available area; omitted offsets center the window.

function placeWindow( screen: ScreenArea, placement: WindowPlacementOptions = {}, ): WindowPlacement

useScreenDetails

Enumerate and target multiple screens with the Window Management API. isExtended is live from window.screen. request() asks for the window-management permission; once granted, screens and currentScreen stay current through screenschange, currentscreenchange, and per-screen change events. openOnScreen opens a window placed with placeWindow. Listeners are removed when the owning reactive scope stops; outside a scope call stop(). Server rendering: nothing is requested, supported and isExtended are false and screens is empty.

function useScreenDetails(options: UseScreenDetailsOptions = {}): ScreenDetailsControls

const { request, screens, openOnScreen } = useScreenDetails();
await request();
const external = screens.value.find((screen) => !screen.isPrimary);
if (external) openOnScreen("/slides", external, { features: "popup" });

Types

ScreenArea

Available (work) area of a screen in multi-screen coordinates.

ScreenSnapshot

Plain snapshot of a ScreenDetailed.

ScreenDetailedLike

Minimal ScreenDetailed.

ScreenDetailsLike

Minimal ScreenDetails.

ScreenDetailsHost

Capabilities used by useScreenDetails.

UseScreenDetailsOptions

Options for useScreenDetails.

WindowPlacementOptions

Desired window geometry relative to a screen's available area.

WindowPlacement

Absolute window geometry for window.open features or moveTo/resizeTo.

OpenOnScreenOptions

Options of ScreenDetailsControls.openOnScreen.

ScreenDetailsControls

Reactive state and actions returned by useScreenDetails.