use-push-subscription

Manage a Web Push subscription.


Package	`@vizejs/composable/use-push-subscription`
Own the source	`vize lib pull composable:use-push-subscription`
Runtime exports	`usePushSubscription`
Gzip budget	2560 B

Usage

import { usePushSubscription } from "@vizejs/composable/use-push-subscription";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`usePushSubscription`	networking	experimental	deterministic-fallback	caller-managed	none	web, desktop	`window`	`tryOnScopeDispose`

API

`usePushSubscription`

Manage a Web Push subscription. Uses the push manager of options.registration, or of navigator.serviceWorker.ready by default. The existing subscription is loaded when the registration becomes known; subscribe accepts the VAPID key as a base64url string. json is the snapshot to send to a push server. Nothing needs cleanup; pending results are ignored after the owning reactive scope stops. Server rendering: nothing is read, supported is false and the subscription is null. Inside a component the host is resolved after mounting, so hydration renders this server state first.

function usePushSubscription( options: UsePushSubscriptionOptions = {}, ): PushSubscriptionControls

const push = usePushSubscription();
const enable = async () => {
  await push.subscribe({ applicationServerKey: VAPID_PUBLIC_KEY });
  await fetch("/api/push", { method: "POST", body: JSON.stringify(push.json.value) });
};

Types

`PushSubscriptionJsonLike`

JSON form of a push subscription (PushSubscription.toJSON()).

Member	Type	Description
`endpoint`?	`string \| undefined`	Push service endpoint.
`expirationTime`?	`number \| null \| undefined`	Expiration time in epoch milliseconds, if any.
`keys`?	`Readonly<Record<string, string>> \| undefined`	Base64url-encoded keys (`p256dh`, `auth`).

`PushSubscriptionLike`

Minimal PushSubscription consumed by usePushSubscription.

Member	Type	Description
`endpoint`	`string`	Push service endpoint.
`expirationTime`	`number \| null`	Expiration time in epoch milliseconds, if any.
`toJSON`	`() => PushSubscriptionJsonLike`	Serialize for a server.
`unsubscribe`	`() => Promise<boolean>`	Cancel the subscription.

`PushManagerSubscribeOptions`

Options forwarded to PushManager.subscribe.

Member	Type	Description
`applicationServerKey`	`BufferSource`	VAPID public key bytes.
`userVisibleOnly`	`boolean`	Only user-visible notifications.

`PushManagerLike`

Minimal PushManager consumed by usePushSubscription.

Member	Type	Description
`subscribe`	`(options: PushManagerSubscribeOptions) => Promise<PushSubscriptionLike>`	Create (or return the existing) subscription.
`getSubscription`	`() => Promise<PushSubscriptionLike \| null>`	Current subscription, if any.
`permissionState`	`(options?: { readonly userVisibleOnly?: boolean }) => Promise<PushPermissionState>`	Permission state for push.

`PushRegistrationLike`

Registration-like owner of a push manager.

Member	Type	Description
`pushManager`	`PushManagerLike`	The registration's push manager.

`UsePushSubscriptionOptions`

Options for usePushSubscription.

Member	Type	Description
`registration`?	`MaybeRefOrGetter<PushRegistrationLike \| null \| undefined>`	Service worker registration owning the push manager. `null` while it is not known yet.
`immediate`?	`boolean`	Load the existing subscription as soon as a registration is known.

`PushSubscribeOptions`

Arguments of PushSubscriptionControls.subscribe.

Member	Type	Description
`applicationServerKey`	`string \| BufferSource`	VAPID public key as a base64url string or raw bytes.
`userVisibleOnly`?	`boolean`	Only user-visible notifications (required by most browsers).

`PushSubscriptionSnapshot`

Serializable snapshot of the current subscription.

Member	Type	Description
`endpoint`	`string`	Push service endpoint.
`expirationTime`	`number \| null`	Expiration time in epoch milliseconds, or `null`.
`keys`	`Readonly<Record<string, string>>`	Base64url-encoded keys (`p256dh`, `auth`).

`PushSubscriptionControls`

Reactive state and actions returned by usePushSubscription.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the Push API is available.
`subscription`	`Readonly<ShallowRef<PushSubscriptionLike \| null>>`	Current subscription, or `null`.
`json`	`ComputedRef<PushSubscriptionSnapshot \| null>`	JSON snapshot of the current subscription, or `null`.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure, cleared by the next successful action.
`subscribe`	`(options: PushSubscribeOptions) => Promise<PushSubscriptionLike \| null>`	Subscribe to push messages. Rejects with a tagged `TypeError` when the key string is not valid base64url.
`unsubscribe`	`() => Promise<boolean>`	Cancel the current subscription.
`refresh`	`() => Promise<PushSubscriptionLike \| null>`	Re-read the existing subscription.
`permissionState`	`( userVisibleOnly?: boolean, ) => Promise<PushPermissionState \| "unsupported">`	Query the push permission state.