svelte-visibility-change

Detect browser page visibility changes using the Page Visibility API

Use this utility component and action to listen to browser page visibility changes.

The visibility state of a page can either be visible or hidden.

Use cases

make a network request when the browser tab is focused
play/pause audio when the browser tab is focused/blurred
pause expensive background computations when the tab is blurred

Installation

# yarn
yarn add -D svelte-visibility-change

# npm
npm i -D svelte-visibility-change

# pnpm
pnpm i -D svelte-visibility-change

Usage

Basic

Bind to the state prop to determine if the current tab is currently visible or hidden.

In the following example, switch to a different tab in the same browser window. The page title should change from "visible" to "hidden."

<script>
  import VisibilityChange from "svelte-visibility-change";

  let state; /** "visible" | "hidden" */

  $: if (typeof window !== "undefined") {
    document.title = state;
  }
</script>

<VisibilityChange bind:state />

visible / hidden

You can also bind to the boolean visible and hidden props.

<script>
  import VisibilityChange from "svelte-visibility-change";

  let visible; /** boolean */
  let hidden; /** boolean */
</script>

<VisibilityChange bind:visible bind:hidden />

`on:visible` / `on:hidden`

An alternative to binding to props is to listen to the on:visible and on:hidden dispatched events.

<script>
  import VisibilityChange from "svelte-visibility-change";

  let events = [];
</script>

<VisibilityChange
  on:visible={() => (events = [...events, "on:visible"])}
  on:hidden={() => (events = [...events, "on:hidden"])}
/>

{events.join(", ")}

`on:change`

This component dispatches an on:change event whenever a visibilitychange event occurs.

Note: unlike on:visible, this event only fires when the page visibility changes after the component has mounted.

<VisibilityChange
  on:change={({ detail }) => {
    console.log(detail.state); // "visible" | "hidden"
    console.log(detail.visible); // boolean
    console.log(detail.hidden); // boolean
  }}
/>

`visibilityChange` action

An alternative to the VisibilityChange component is the visibilityChange action.

The action only dispatches a "change" event with the same event.detail signature.

<script>
  import { visibilityChange } from "svelte-visibility-change";
</script>

<div
  use:visibilityChange
  on:visibilitychange={({ detail }) => {
    console.log(detail.state); // "visible" | "hidden"
    console.log(detail.visible); // boolean
    console.log(detail.hidden); // boolean
  }}
/>

API

Props

Name	Type	Default value
state	`"visible"` or `"hidden"`	`undefined`
visible	`boolean`	`false`
hidden	`boolean`	`false`

Dispatched Events

on:visible: fired if the page is visible
on:hidden: fired if the page visibility is hidden
on:change: fired when a page visibility event occurs, after the initial mount

TypeScript

Svelte version 3.31 or greater is required to use this component with TypeScript.

Changelog

CHANGELOG.md

License

MIT