use-display-media

Capture a screen, window, or tab with getDisplayMedia.

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 { useDisplayMedia } from "@vizejs/composable/use-display-media";

Try it

Share a screen

Capture a screen or window and preview the stream.

Open the interactive example

What to observe: Share a screen opens the browser's picker; the preview shows the shared screen until Stop sharing.

enabled can be a ref to start and stop capture reactively. Stopping ends every track. 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 { computed, ref, watchEffect } from "vue";
import { useDisplayMedia } from "@vizejs/composable/use-display-media";
import { useMounted } from "@vizejs/composable/use-mounted";

const mounted = useMounted();
const preview = ref<HTMLVideoElement | null>(null);
const { supported, stream, status, start, stop } = useDisplayMedia({ video: true });
const sharing = computed(() => stream.value !== undefined);
watchEffect(() => {
  if (preview.value) preview.value.srcObject = (stream.value as MediaStream | undefined) ?? null;
});
</script>

<template>
  <div class="composable-example">
    <p>Share a screen or window into a recording preview.</p>
    <div class="example-actions">
      <button type="button" :disabled="!mounted || !supported || sharing" @click="() => start()">
        Share a screen
      </button>
      <button type="button" :disabled="!sharing" @click="() => stop()">Stop sharing</button>
    </div>
    <video ref="preview" autoplay muted playsinline aria-label="Screen preview"></video>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : supported
          ? `Screen capture: ${status}`
          : "Screen capture is not available in this browser."
    }}</output>
  </div>
</template>

Runtime contract

API

useDisplayMedia

Capture a screen, window, or tab with getDisplayMedia. Shares the stream lifecycle of useMediaStream (from use-user-media): classified failures ("permission-denied" when the user dismisses the picker), latest-wins requests, and automatic return to "idle" when the user ends sharing from the browser UI (every track ended). Tracks are stopped when the owning reactive scope stops. Server rendering: nothing is captured; status is "idle" and supported is false.

function useDisplayMedia(options: UseDisplayMediaOptions = {}): MediaStreamControls

const screen = useDisplayMedia({ audio: true });
const share = () => screen.start();

Types

DisplayMediaHost

Minimal MediaDevices consumed by useDisplayMedia.

UseDisplayMediaOptions

Options for useDisplayMedia.