Module @automerge/automerge-repo-react-hooks - v1.1.0

React Hooks for Automerge Repo

These hooks are provided as helpers for using Automerge in your React project.


This hook is used to load a document based on the URL hash, for example //myapp/#documentId=[document ID]. It can also load the document ID from localStorage, or create a new document if none is specified.

useLocalAwareness & useRemoteAwareness

These hooks implement ephemeral awareness/presence, similar to Yjs Awareness. They allow temporary state to be shared, such as cursor positions or peer online/offline status.

Ephemeral messages are replicated between peers, but not saved to the Automerge doc, and are used for temporary updates that will be discarded.


Use RepoContext to set up react context for an Automerge repo. Use useRepo to lookup the repo from context. Most hooks depend on RepoContext being available.


Return a document & updater fn, by ID.


Return a handle, by ID.

Example usage

App Setup

import React, { StrictMode } from "react"
import ReactDOM from "react-dom/client"

import { Repo, DocCollection } from "@automerge/automerge-repo"

import { BroadcastChannelNetworkAdapter } from "@automerge/automerge-repo-network-broadcastchannel"

import App, { RootDocument } from "./App.js"
import { RepoContext } from "@automerge/automerge-repo-react-hooks"

// eslint-disable-next-line @typescript-eslint/no-unused-vars
const sharedWorker = new SharedWorker(
new URL("./shared-worker.js", import.meta.url),
{ type: "module", name: "@automerge/automerge-repo-shared-worker" }

async function getRepo(): Promise<DocCollection> {
return await Repo({
network: [
new BroadcastChannelNetworkAdapter(),
sharePolicy: peerId => peerId.includes("shared-worker"),

const initFunction = (d: RootDocument) => {
d.items = []

const queryString = // Returns:'?q=123'

// Further parsing:
const params = new URLSearchParams(queryString)
const hostname = params.get("host") || ""

getRepo().then(repo => {
useBootstrap(repo, initFunction).then(rootDoc => {
const rootElem = document.getElementById("root")
if (!rootElem) {
throw new Error("The 'root' element wasn't found in the host HTML doc.")
const root = ReactDOM.createRoot(rootElem)
<RepoContext.Provider value={repo}>
<App rootDocumentId={rootDoc.documentId} />



Type Aliases



Generated using TypeDoc