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 · usePermissionEditor
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.tsfor implementation details