React

import { HaloProvider, useIdentity } from '@dxos/halo-react';

@dxos/halo-react reads HALO from React components. Each hook follows one @dxos/halo stream and re-renders when it emits, so a component shows the current identity, devices or members without subscribing itself.

Set up the provider

HaloProvider takes the HALO services as an Effect Context. Build it from a Client with the adapter’s makeIdentityService and makeSpaceService, and wrap the part of the app that uses the hooks.

import * as Context from 'effect/Context';
import { Identity, Space } from '@dxos/halo';
import { makeIdentityService, makeSpaceService } from '@dxos/halo-adapter-client';
import { HaloProvider } from '@dxos/halo-react';

const services = Context.empty().pipe(
  Context.add(Identity.Service, makeIdentityService(client)),
  Context.add(Space.Service, makeSpaceService(client)),
);

export const App = () => (
  <HaloProvider services={services}>
    <Profile />
  </HaloProvider>
);

The identity

useIdentity returns the identity, or undefined before one exists. It has the current value on the first render. useDevices and useCredentials return the identity’s devices and credentials.

import { useCredentials, useDevices, useIdentity } from '@dxos/halo-react';

export const Profile = () => {
  const identity = useIdentity();
  const devices = useDevices();
  const credentials = useCredentials();
  if (!identity) {
    return <p>No identity yet.</p>;
  }

  const recovery = credentials.filter((c) => c.recovery && !c.recovery.revoked);
  return (
    <p>
      {identity.displayName} on {devices.length} devices, with {recovery.length}{' '}
      recovery credentials.
    </p>
  );
};

Spaces and members

useSpaces returns the spaces that are ready; pass { all: true } for every space. useSpace finds one by id, and useMembers returns a space’s members.

import { useMembers, useSpace, useSpaces } from '@dxos/halo-react';
import { type SpaceId } from '@dxos/keys';

export const SpaceList = () => {
  const spaces = useSpaces();
  return (
    <ul>
      {spaces.map((space) => (
        <li key={space.id}>
          <Members spaceId={space.id} />
        </li>
      ))}
    </ul>
  );
};

export const Members = ({ spaceId }: { spaceId: SpaceId }) => {
  const space = useSpace(spaceId);
  const members = useMembers(spaceId);
  return (
    <>
      {space?.name}:{' '}
      {members.map((member) => member.displayName ?? member.did).join(', ')}
    </>
  );
};

Invitations

Start a flow with Space.share or Identity.share, run as an Effect with the same services. useInvitationFlow follows the flow: its latest event and its code. It needs no provider, since a flow carries what it needs. useSpaceInvitations and useHaloInvitations list the flows this device has open.

import * as Effect from 'effect/Effect';
import { useState } from 'react';
import { Invitation, Space } from '@dxos/halo';
import { useHaloInvitations, useInvitationFlow, useSpaceInvitations } from '@dxos/halo-react';
import { type SpaceId } from '@dxos/keys';

export const Invite = ({ spaceId }: { spaceId: SpaceId }) => {
  const [flow, setFlow] = useState<Invitation.Flow>();
  const { event, code } = useInvitationFlow(flow);

  const share = () =>
    Effect.runPromise(
      Space.share(spaceId, { authMethod: 'shared-secret' }).pipe(
        Effect.provide(services),
      ),
    ).then(setFlow);

  if (!flow) {
    return <button onClick={share}>Invite</button>;
  }
  return (
    <p>
      Code: {code}
      {event?._tag === 'readyForAuthentication' && ` Auth: ${event.authCode}`}
    </p>
  );
};

// Every flow this device has open, for a space or for the identity.
export const OpenInvitations = ({ spaceId }: { spaceId: SpaceId }) => {
  const forSpace = useSpaceInvitations(spaceId);
  const forDevices = useHaloInvitations();
  return (
    <p>
      {forSpace.length} space and {forDevices.length} device invitations open.
    </p>
  );
};

Hooks at a glance

Hook	Returns
useIdentity	The identity, or undefined
useDevices useCredentials	The identity’s devices and credentials
useSpaces useSpace	Spaces, and one space by id
useMembers	A space’s members
useContacts	Everyone you share a space with, once each
useSpaceInvitations useHaloInvitations	Open space and device invitations
useInvitationFlow	One flow’s latest event and code

Related

• Identity, Space and Invitation
• The contact book in the learning path is built on HaloProvider and these hooks.