use-permission

Observe a browser permission reactively.


Package	`@vizejs/composable/use-permission`
Own the source	`vize lib pull composable:use-permission`
Runtime exports	`usePermission`
Gzip budget	2048 B

Usage

import { usePermission } from "@vizejs/composable/use-permission";

Runtime contract

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

API

`usePermission`

Observe a browser permission reactively. The permission is queried when the composable is created and whenever the reactive name/descriptor or host changes; the change event of the returned PermissionStatus keeps state current (for example after the user revokes camera access in the site settings). The subscription is removed when the name changes and when the owning reactive scope stops. Server rendering: no browser window exists, so nothing is queried and state stays at initialState ("unknown") with supported false. Unknown names (the browser rejects the query) report "unsupported". Inside a component the first query runs after mounting, so hydration renders initialState exactly like the server did.

function usePermission( name: MaybeRefOrGetter<WellKnownPermissionName | PermissionDescriptorLike>, options: UsePermissionOptions = {}, ): PermissionControls

const { state } = usePermission("camera");
const canUseCamera = computed(() => state.value === "granted");

Types

`PermissionDescriptorLike`

Descriptor passed to navigator.permissions.query.

Member	Type	Description
`name`	`WellKnownPermissionName`	Permission name.
`userVisibleOnly`?	`boolean`	Push: only user-visible notifications (required `true` by most browsers).
`sysex`?	`boolean`	MIDI: request system-exclusive message access.
`panTiltZoom`?	`boolean`	Camera: request pan-tilt-zoom control.
`allowWithoutGesture`?	`boolean`	Clipboard (Chromium): allow access without a user gesture.

`PermissionStatusLike`

Minimal PermissionStatus shape consumed by usePermission.

Member	Type	Description
`state`	`string`	Current state reported by the browser.

`PermissionsHost`

Minimal Permissions shape consumed by usePermission.

Member	Type	Description
`query`	`(descriptor: PermissionDescriptorLike) => Promise<PermissionStatusLike>`	Query one permission. Rejects (TypeError) for names the browser does not know. Declared with method syntax so the DOM `Permissions` object, whose descriptor names are a narrower union, satisfies this interface.

`UsePermissionOptions`

Options for usePermission.

Member	Type	Description
`host`?	`MaybeRefOrGetter<PermissionsHost \| null \| undefined>`	Permissions capability for alternate runtimes and tests.
`initialState`?	`PermissionQueryState`	State exposed before the first query settles and during server rendering.

`PermissionControls`

Reactive state returned by usePermission.

Member	Type	Description
`state`	`Readonly<Ref<PermissionQueryState>>`	Current permission state. `"unsupported"` means the Permissions API (or this permission name) is unavailable; `"unknown"` means no answer yet.
`supported`	`Readonly<Ref<boolean>>`	Whether a Permissions capability is attached.
`query`	`() => Promise<PermissionQueryState>`	Query the permission again and resubscribe to its changes.