use-push-subscription

Manage a Web Push subscription.

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 { usePushSubscription } from "@vizejs/composable/use-push-subscription";

Try it

Subscribe to schedule alerts

Subscribe to push messages from your server with a service worker registration.

Open the interactive example

What to observe: Subscribe to alerts creates a subscription once a service worker is registered; send its JSON to your server.

Pass registration from useServiceWorker. The key in the example is a placeholder for your VAPID public key. 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 { usePushSubscription } from "@vizejs/composable/use-push-subscription";

const mounted = useMounted();
// Pass your service worker registration, for example from useServiceWorker().
const { supported, subscription, subscribe, unsubscribe } = usePushSubscription({
  immediate: false,
});
const vapidPublicKey =
  "BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U";
</script>

<template>
  <div class="composable-example">
    <p>Subscribe to schedule-change alerts sent by your server.</p>
    <div class="example-actions">
      <button
        type="button"
        :disabled="!mounted || !supported || subscription !== null"
        @click="() => subscribe({ applicationServerKey: vapidPublicKey, userVisibleOnly: true })"
      >
        Subscribe to alerts
      </button>
      <button type="button" :disabled="!subscription" @click="() => unsubscribe()">
        Unsubscribe
      </button>
    </div>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : supported
          ? subscription
            ? "Subscribed to alerts."
            : "Not subscribed."
          : "Push messages are not available in this browser."
    }}</output>
  </div>
</template>

Runtime contract

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()).

PushSubscriptionLike

Minimal PushSubscription consumed by usePushSubscription.

PushManagerSubscribeOptions

Options forwarded to PushManager.subscribe.

PushManagerLike

Minimal PushManager consumed by usePushSubscription.

PushRegistrationLike

Registration-like owner of a push manager.

UsePushSubscriptionOptions

Options for usePushSubscription.

PushSubscribeOptions

Arguments of PushSubscriptionControls.subscribe.

PushSubscriptionSnapshot

Serializable snapshot of the current subscription.

PushSubscriptionControls

Reactive state and actions returned by usePushSubscription.