BrowserBeginnerSSR-safehooks/browser/usePermission.ts

usePermission

Permissions API status.

Import

TypeScript
import { usePermission } from '@/hooks';

API

Signature

usePermission(name) → { state, isLoading, query }

When to use

Use usePermission instead of re-implementing the same pattern in multiple components.

SSR / Next.js

Returns defaults on the server; hydrates on the client.

Live playground

Edit the example and see it run against the real @/hooks package in this app.

Live playgroundEdit · run with real @/hooks · usePermission
Editor
function MicPerm() {
  const { state, isLoading } = usePermission('microphone');
  return <p>{isLoading ? '…' : state}</p>;
}
Preview

Implementation source

Full library source for usePermission — copy into your project when you are not installing a package yet.

hooks/browser/usePermission.ts
import { useCallback, useEffect, useState } from 'react';
import { hasNavigator, isBrowser } from '../utility/isBrowser';
import type { PermissionNameCompatible } from '../types';

export type PermissionStateValue =
  | PermissionState
  | 'prompt'
  | 'granted'
  | 'denied'
  | 'unsupported';

/** Permission Status API wrapper. */
export function usePermission(
  name: PermissionNameCompatible,
): {
  state: PermissionStateValue;
  isLoading: boolean;
  query: () => Promise<PermissionStateValue>;
} {
  const [state, setState] = useState<PermissionStateValue>('prompt');
  const [isLoading, setIsLoading] = useState(true);

  const query = useCallback(async () => {
    if (!isBrowser() || !hasNavigator() || !navigator.permissions?.query) {
      setState('unsupported');
      setIsLoading(false);
      return 'unsupported' as const;
    }
    try {
      setIsLoading(true);
      const status = await navigator.permissions.query({
        name: name as PermissionName,
      });
      setState(status.state);
      setIsLoading(false);
      return status.state;
    } catch {
      setState('unsupported');
      setIsLoading(false);
      return 'unsupported' as const;
    }
  }, [name]);

  useEffect(() => {
    let status: PermissionStatus | null = null;
    let cancelled = false;

    const run = async () => {
      if (!isBrowser() || !hasNavigator() || !navigator.permissions?.query) {
        if (!cancelled) {
          setState('unsupported');
          setIsLoading(false);
        }
        return;
      }
      try {
        status = await navigator.permissions.query({
          name: name as PermissionName,
        });
        if (cancelled) return;
        setState(status.state);
        setIsLoading(false);
        const onChange = () => setState(status!.state);
        status.addEventListener('change', onChange);
        return () => status?.removeEventListener('change', onChange);
      } catch {
        if (!cancelled) {
          setState('unsupported');
          setIsLoading(false);
        }
      }
    };

    let cleanup: (() => void) | undefined;
    run().then((c) => {
      if (typeof c === 'function') cleanup = c;
    });

    return () => {
      cancelled = true;
      cleanup?.();
    };
  }, [name]);

  return { state, isLoading, query };
}

Copy-paste example

usePermission.example.tsx
'use client';

import { usePermission } from '@/hooks';

export function MicPerm() {
  const { state, isLoading } = usePermission('microphone');
  return <p>{isLoading ? '…' : state}</p>;
}

Production checklist

  • Called only from Client Components or other custom hooks
  • Type parameters filled in (e.g. useFetch<User[]>)
  • Tip: Values are safe during SSR (defaults). Gate layout-dependent UI with useMounted when needed.
  • Source of truth: open hooks/browser/usePermission.ts for implementation details