@groundstate/react

React hooks and components for building local-first apps with @groundstate.

Installation

# npm
npm install @groundstate/react @groundstate/crdt

# yarn
yarn add @groundstate/react @groundstate/crdt

# pnpm
pnpm add @groundstate/react @groundstate/crdt

Peer dependency: React 18+

Quick Start

import { GroundstateProvider, useDoc, useField, usePresence } from '@groundstate/react';
import { Doc, Field, List } from '@groundstate/crdt';

const schema = { title: Field(''), tags: List<string>() };

function App() {
  return (
    <GroundstateProvider doc={Doc(schema)} sync={syncEngine}>
      <TodoEditor />
    </GroundstateProvider>
  );
}

function TodoEditor() {
  const doc = useDoc();
  const [title, setTitle] = useField(doc, 'title');
  const { peers } = usePresence();

  return (
    <div>
      <input value={title} onChange={(e) => setTitle(e.target.value)} />
      <p>{peers.length} peer(s) online</p>
    </div>
  );
}

API Highlights

Provider

• GroundstateProvider -- Context provider that supplies the document and sync engine
• GroundstateContext -- Raw React context for advanced use cases
• useGroundstate() -- Access the provider context directly

Hooks

• useDoc() -- Subscribe to the full document, re-renders on any change
• useField(doc, path) -- Subscribe to a single field with a setter
• usePresence() -- Track peer presence (cursors, selections, names)
• useSyncStatus() -- Monitor sync connection state and progress
• useConflicts() -- Access detected conflicts for manual resolution

Components

• ConflictResolver -- Drop-in UI component for resolving conflicts interactively

Documentation

See the full documentation for complete API reference.

License

MIT