Installation

pnpm dlx uselab@latest add use-web-lock

Usage

import { useWebLock } from "@/hooks/use-web-lock"
 
export function SyncOwner() {
  const { isLocked, acquire, release } = useWebLock("background-sync")
 
  return (
    <div className="space-y-2">
      <button onClick={() => void acquire()} disabled={isLocked}>
        Become sync owner
      </button>
      <button onClick={release} disabled={!isLocked}>
        Release ownership
      </button>
    </div>
  )
}

API Reference

useWebLock(name, options?)

Parameters

Return value

The hook returns an object { isSupported, isLocked, error, acquire, release }:

Options

interface UseWebLockOptions {
  mode?: "exclusive" | "shared"
  ifAvailable?: boolean
  steal?: boolean
  onAcquire?: (lock: { name: string; mode: "exclusive" | "shared" }) => void
  onRelease?: () => void
}

• mode: Lock mode to request. Defaults to "exclusive".
• ifAvailable: Return immediately when the lock is not available instead of waiting.
• steal: Request the lock aggressively when supported by the browser.
• onAcquire: Runs when the lock is granted.
• onRelease: Runs when the lock is released.

Notes

• This hook is a strong fit for cross-tab leader election, single-writer background sync, and mutation coordination.
• Lock support is not universal, so high-value workflows should still have a fallback strategy.
• Use stable lock names that map cleanly to the shared resource you are protecting.