use-notification

Show typed Web Notifications with permission handling.


Package	`@vizejs/composable/use-notification`
Own the source	`vize lib pull composable:use-notification`
Runtime exports	`useWebNotification`
Gzip budget	2304 B

Usage

import { useWebNotification } from "@vizejs/composable/use-notification";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useWebNotification`	system	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, desktop	`window`	`tryOnScopeDispose`

API

`useWebNotification`

Show typed Web Notifications with permission handling. show merges reactive defaults with per-call options, asks for permission first when it is still undecided (configurable), and resolves to a discriminated WebNotificationResult. Handlers registered with on apply to every notification this composable shows. The current notification is closed when the owning reactive scope stops. Server rendering: the API is never touched; permission is "unsupported" and supported is false.

function useWebNotification<Data = unknown>( options: UseWebNotificationOptions<Data> = {}, ): WebNotificationControls<Data>

const notify = useWebNotification<{ id: string }>({ defaults: { icon: "/icon.png" } });
notify.on("click", () => window.focus());
await notify.show("Build finished", { data: { id: "42" } });

Types

`NotificationOptionsLike`

Options accepted by the Notification constructor.

Member	Type	Description
`body`?	`string`	Body text.
`icon`?	`string`	Icon URL.
`badge`?	`string`	Monochrome badge URL for constrained surfaces.
`tag`?	`string`	Grouping tag; a new notification with the same tag replaces the old one.
`lang`?	`string`	BCP 47 language tag.
`dir`?	`"auto" \| "ltr" \| "rtl"`	Text direction.
`requireInteraction`?	`boolean`	Keep the notification visible until the user interacts with it.
`silent`?	`boolean \| null`	Suppress sounds and vibration.
`data`?	`Data`	Application data attached to the notification.

`NotificationLike`

Minimal Notification instance consumed by useWebNotification.

Member	Type	Description
`close`	`() => void`	Dismiss the notification.

`NotificationHost`

Minimal Notification constructor (with its static members).

Member	Type	Description
`permission`	`string`	Current permission.
`requestPermission`	`() => Promise<string>`	Ask the user for permission.

`WebNotificationDefaults`

Default notification content for useWebNotification.

Member	Type	Description
`body`?	`string`	Body text.
`icon`?	`string`	Icon URL.
`badge`?	`string`	Monochrome badge URL for constrained surfaces.
`tag`?	`string`	Grouping tag; a new notification with the same tag replaces the old one.
`lang`?	`string`	BCP 47 language tag.
`dir`?	`"auto" \| "ltr" \| "rtl"`	Text direction.
`requireInteraction`?	`boolean`	Keep the notification visible until the user interacts with it.
`silent`?	`boolean \| null`	Suppress sounds and vibration.
`data`?	`Data`	Application data attached to the notification.
`title`?	`string`	Default title.

`UseWebNotificationOptions`

Options for useWebNotification.

Member	Type	Description
`host`?	`MaybeRef<NotificationHost \| null \| undefined>`	Notification constructor for alternate runtimes and tests. A ref (not a getter) because the host itself is a constructor function.
`defaults`?	`MaybeRefOrGetter<WebNotificationDefaults<Data>>`	Reactive default title and options merged into every `show` call.
`requestPermissionOnShow`?	`boolean`	Request permission from `show` when it has not been decided yet.

`WebNotificationControls`

Reactive state and actions returned by useWebNotification.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the Notifications API is available.
`permission`	`Readonly<Ref<NotificationPermissionState>>`	Current permission state.
`notification`	`Readonly<ShallowRef<NotificationLike \| undefined>>`	Most recently shown notification, cleared when it closes.
`data`	`Readonly<ShallowRef<Data \| undefined>>`	Data attached to the current notification.
`requestPermission`	`() => Promise<NotificationPermissionState>`	Ask the user for permission.
`show`	`( title?: string, options?: NotificationOptionsLike<Data>, ) => Promise<WebNotificationResult>`	Show a notification, replacing the current one.
`close`	`() => void`	Close the current notification.
`on`	`( event: WebNotificationEvent, handler: (event: Event, notification: NotificationLike) => void, ) => () => void`	Subscribe to an event of every notification shown by this composable.