Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/metonym/svelte-visibility-change
Detect browser page visibility changes using the Page Visibility API
https://github.com/metonym/svelte-visibility-change
blur browser-tab focus page-visibility svelte svelte-component typescript visibility-change
Last synced: about 2 months ago
JSON representation
Detect browser page visibility changes using the Page Visibility API
- Host: GitHub
- URL: https://github.com/metonym/svelte-visibility-change
- Owner: metonym
- License: mit
- Created: 2021-07-18T21:42:19.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2023-06-13T17:14:21.000Z (over 1 year ago)
- Last Synced: 2024-10-14T08:43:41.419Z (2 months ago)
- Topics: blur, browser-tab, focus, page-visibility, svelte, svelte-component, typescript, visibility-change
- Language: TypeScript
- Homepage: https://metonym.github.io/svelte-visibility-change
- Size: 193 KB
- Stars: 22
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# svelte-visibility-change
[![NPM][npm]][npm-url]
> Detect browser page visibility changes using the [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/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
- check for app UI updates when the tab is focused
- play/pause audio when the tab is focused/blurred
- pause expensive background computations when the tab is blurred
Try it in the [Svelte REPL](https://svelte.dev/repl/a4b8bdb782514baaa7fa1cb26313b303).
---
## Installation
```sh
# 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."
```svelte
import VisibilityChange from "svelte-visibility-change";
let state; /** "visible" | "hidden" */
$: if (typeof window !== "undefined") {
document.title = state;
}
```
### visible / hidden
You can also bind to the boolean `visible` and `hidden` props.
```svelte no-eval
import VisibilityChange from "svelte-visibility-change";
let visible; /** boolean */
let hidden; /** boolean */
```
### `on:visible` / `on:hidden`
An alternative to binding to props is to listen to the `on:visible` and `on:hidden` dispatched events.
```svelte
import VisibilityChange from "svelte-visibility-change";
let events = [];
(events = [...events, "on:visible"])}
on:hidden={() => (events = [...events, "on:hidden"])}
/>
{events.join(", ")}
```
### `on:change`
This component dispatches an `on:change` event whenever a [visibilitychange](https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilitychange_event) event occurs.
**Note:** unlike `on:visible`, this event only fires when the page visibility changes _after the component has mounted._
```svelte no-eval
{
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.
```svelte no-eval
import { visibilityChange } from "svelte-visibility-change";
{
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](CHANGELOG.md)
## License
[MIT](LICENSE)
[npm]: https://img.shields.io/npm/v/svelte-visibility-change.svg?style=for-the-badge&color=%23ff3e00
[npm-url]: https://npmjs.com/package/svelte-visibility-change