use-permission

Observe a browser permission reactively.

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 { usePermission } from "@vizejs/composable/use-permission";

Try it

Adapt to a permission state

Read a permission state without prompting and adapt the interface to it.

Open the interactive example

What to observe: The message reflects whether location is allowed, blocked or not decided yet, and updates if the reader changes it in site settings.

usePermission only reads the state; the API that needs the permission is what prompts. 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 { usePermission } from "@vizejs/composable/use-permission";

const mounted = useMounted();
const { state, supported } = usePermission("geolocation");
</script>

<template>
  <div class="composable-example">
    <p>
      Explain a location feature differently depending on whether the reader already allowed it.
    </p>
    <output aria-live="polite">{{
      !mounted
        ? "Checking permissions…"
        : !supported
          ? "This browser cannot report permission states."
          : state === "granted"
            ? "Location is allowed; nearby venues load automatically."
            : state === "denied"
              ? "Location is blocked; search for a venue instead."
              : "Location: we will ask when you look for nearby venues."
    }}</output>
  </div>
</template>

Runtime contract

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.

PermissionStatusLike

Minimal PermissionStatus shape consumed by usePermission.

PermissionsHost

Minimal Permissions shape consumed by usePermission.

UsePermissionOptions

Options for usePermission.

PermissionControls

Reactive state returned by usePermission.