React

By the end of this page you will know how the tutorial app’s components get their data, and why they re-render when any peer changes it.

Before you start

The learning path builds the app’s ECHO code in plain TypeScript: its types, its add and update functions, and its queries. This guide covers the React layer on top, which @dxos/react-client connects to ECHO.

Two rules decide when a component re-renders:

• A hook subscribes the component to what it returns. useQuery re-renders when the query’s results change, and useObject when the object changes.
• Reading a field of an ECHO object during render subscribes to nothing. A component that reads person.name straight off the object does not re-render when the name changes.

1. Install the React client. @dxos/react-client wraps @dxos/client in a provider and hooks. Configure the bundler as in Installation.

   pnpm

   pnpm add @dxos/react-client

   npm

   npm install --save @dxos/react-client

   yarn

   yarn add @dxos/react-client

2. Provide the client. ClientProvider gives the hooks below it a client. The app opens its client and space with openContacts from Installation, and renders one provider per peer.

   /** One peer's copy of the app: the provider gives the hooks below it the peer's client. */
   export const PeerApp = ({ client, space, stage }: { client: Client; space: Space; stage: Stage }) => (
     <ClientProvider client={client}>
       <Contacts space={space} stage={stage} />
     </ClientProvider>
   );
   
   

3. Query the space. useQuery takes a database and a query, here the app’s queries from Querying. It returns the current results and re-renders the component when they change.

     // Each list is a live query: it re-renders when a record is added, changed by any peer, or removed.
     const allOrganizations = useQuery(space.db, organizations);
     const allPeople = useQuery(space.db, people);
     const allEvents = useQuery(space.db, events);
   
   

   A query returns the same live object for an id every time, so a renamed record leaves the results array as it was. The app’s list reads its labels with useLabels, which re-renders the list when a label changes.

4. Show a record. useObject returns a snapshot of the object and re-renders the component when the object changes. The form’s title reads the record’s name through it.

   /** The record's name, re-rendered whenever any peer renames it. */
   const RecordTitle = ({ record }: { record: Obj.Unknown }) => {
     const [snapshot] = useObject(record);
     const label = 'title' in snapshot ? snapshot.title : 'name' in snapshot ? snapshot.name : undefined;
     return <h3 className='text-lg font-medium'>{String(label ?? '')}</h3>;
   };
   
   

   Caution

   Read fields through the snapshot from useObject. A field read straight off the ECHO object shows its value at render time, and the component does not re-render when the field changes.

5. Edit with a form built from the schema. Form.Root from @dxos/react-ui-form takes the type’s schema, so a new field in the schema is a new field in the form. A reference field lists the records of the type it points at.

     /** The options a reference field offers: the records of its target type, by label. */
     const getOptions = useCallback<NonNullable<RefFieldDataProps['getOptions']>>(
       (results) =>
         [...results]
           .sort((a, b) => (Entity.getLabel(a) ?? '').localeCompare(Entity.getLabel(b) ?? ''))
           .map((result) => {
             const target = types.find((type) => Type.getTypename(type) === Entity.getTypename(result));
             return {
               id: Entity.getURI(result),
               label: Entity.getLabel(result) ?? result.id,
               ...(target && { icon: getTypeIcon(target)?.icon }),
             };
           }),
       [],
     );
   
     const useRefType = useCallback<NonNullable<RefFieldDataProps['useType']>>(
       (_db, typeUri) => types.find((type) => String(typeUri).includes(Type.getTypename(type))) ?? recordType,
       [recordType],
     );
   
   

   On save, the form hands back its values, and the app writes them with the functions from Mutating objects.

     const handleSave = useCallback(
       (next: Record<string, unknown>) => {
         if (record) {
           updateRecord(record, next);
           onDone?.();
           return;
         }
   
         // A reference field reports the URI of its choice; the record behind it is what the add functions take.
         const resolve = (value: unknown) =>
           Ref.isRef(value) ? records.find((candidate) => Entity.getURI(candidate) === value.uri) : undefined;
         if (recordType === Person) {
           const employer = resolve(next.employer);
           addPerson(db, {
             name: String(next.name ?? ''),
             email: optional(next.email),
             employer: employer && Obj.instanceOf(Organization, employer) ? employer : undefined,
           });
         } else if (recordType === Event) {
           addEvent(db, {
             title: String(next.title ?? ''),
             description: optional(next.description),
             attendees: (Array.isArray(next.attendees) ? next.attendees : [])
               .map(resolve)
               .filter((candidate) => candidate !== undefined)
               .filter((candidate) => Obj.instanceOf(Person, candidate)),
           });
         } else {
           addOrganization(db, { name: String(next.name ?? ''), website: optional(next.website) });
         }
         onDone?.();
       },
       [db, record, records, recordType, onDone],
     );
   
   

Try it

The app with every piece in place: lists, the table and the graph are all useQuery, and the form is useObject and Form.Root.

Configure the provider

Show a fallback

fallback renders while the client initializes.

const Loading = () => <div>Loading…</div>;

const WithFallback = () => (
  <ClientProvider types={[Task]} fallback={Loading}>
    <Tasks />
  </ClientProvider>
);

Pass your own client

Create the client yourself to use it outside React too.

const client = new Client({ types: [Task] });

const WithClient = () => (
  <ClientProvider client={client}>
    <Tasks />
  </ClientProvider>
);

Pass a config

config takes a function that returns a Config, built from the same sources as in Configure the client.

const WithConfig = () => (
  <ClientProvider types={[Task]} config={async () => new Config(Local(), Defaults())}>
    <Tasks />
  </ClientProvider>
);

What you can do now

You can provide a client to a React app, query a space from a component, show a record that re-renders on every change, and edit records with a form built from their schema. The Tasks sample is another complete app built this way.

Next

Spaces and databases: what a space is, and how peers join one.