React Hooks

The trellis/react package exposes standard React hooks for binding Trellis queries directly to your component state. These hooks manage WebSocket subscriptions automatically, meaning your UI is always perfectly in sync with the underlying causal graph.

Setup

Wrap your application or component tree in the <TrellisProvider> constructor.

import { TrellisProvider } from "trellis/react";

export function App() {
  return (
    <TrellisProvider url="ws://localhost:3000" apiKey="dev-key">
      <Dashboard />
    </TrellisProvider>
  );
}

Hooks API

useTrellis()

Returns the underlying TrellisClient instance from the nearest provider context.

useEntity<T>(id)

Fetches a specific entity by its graph ID and auto-refreshes when new causal ops modify it. Returns: { data: T | null, loading, error, refetch }

useEntities<T>(type, opts?)

Standard list query for fetching an array of entities by type, keeping them synced. Returns: { data: T[], total, loading, error, refetch }

useQuery<T>(eql)

Provides raw TQL execution capabilities wrapped in a reactive hook hook. It automatically calls client.subscribe(eql, callback) underneath the hood and cleans up on unmount. Returns: { data: T[], loading, error }

useMutation()

Exposes CRUD actions that apply optimistic updates to the local React cache before sending the corresponding ops up to the server. Returns: { create, update, delete, loading, error }