Spaces

A space is an instance of an ECHO database which can be replicated by a number of peers.

This section describes how to create, join, and invite peers to ECHO Spaces in react.

Creating spaces

To create a space, call the client.echo.createSpace() API:

createSpace([meta])

Creates a new space.

Returns: Promise<Space>

Arguments:

meta: PropertiesProps

import React from 'react';
import { createRoot } from 'react-dom/client';
import { ClientProvider, useClient } from '@dxos/react-client';

export const App = () => {
  const client = useClient();
  return (
    <button
      onClick={async () => {
        const space = await client.createSpace();
      }}
    ></button>
  );
};

const root = createRoot(document.getElementById('root')!);
root.render(
  <ClientProvider>
    <App />
  </ClientProvider>
);

Obtaining a Space reactively

These hooks are available from package @dxos/react-client and re-render reactively.

useSpace([spaceKey])

Get a specific Space using its key. Returns undefined when no spaceKey is available. Requires a ClientProvider somewhere in the parent tree.

Returns: undefined | Space

Arguments:

spaceKey: PublicKeyLike

useSpaces(options)

Get all Spaces available to current user. Requires a ClientProvider somewhere in the parent tree. By default, only ready spaces are returned.

Returns: Space[]

Arguments:

options: UseSpacesParams

useOrCreateFirstSpace()

Returns the first space in the current spaces array. If none exist, undefined will be returned at first, then the hook will re-run and return a space once it has been created. Requires a ClientProvider somewhere in the parent tree.

Returns: Space

Arguments: none

Example

import React from 'react';
import { createRoot } from 'react-dom/client';
import {
  ClientProvider,
  Space,
  useQuery,
  useSpace,
  useSpaces
} from '@dxos/react-client';

export const App = () => {
  // Usually space IDs are in the URL like in params.spaceKey.
  const space1 = useSpace('<space_key_goes_here>');
  
  // Get all spaces.
  const spaces = useSpaces();
  const space2: Space | undefined = spaces[0]; // Spaces may be an empty list.
  
  // Get objects from the space as an array of JS objects.
  const objects = useQuery(space2);

  return <>{objects.length}</>;
};

const root = createRoot(document.getElementById('root')!);
root.render(
  <ClientProvider>
    <App />
  </ClientProvider>
);

Joining spaces

See the platform overview describing the general process of joining peers to a space.

In react the package @dxos/react-appkit offers components that implement the entire join flow. See how to include DXOS UI packages in your project, or use one of the DXOS application templates which have DXOS UI pre-configured.

Tip

To implement invitation flows manually, see the TypeScript API about joining spaces.

The pre-built space join flow is contained in the SpacesPage component for react. This is designed to be a panel or a full-screen page.

SpacesPage

• Lists spaces.
• Allows joining spaces with an invite code.
• Allows creating spaces.
• Supports navigating to a space by clicking it.

import React from 'react';
import { createRoot } from 'react-dom/client';
import { ClientProvider } from '@dxos/react-client';
import { SpacesPage } from '@dxos/react-appkit';

export const App = () => {
  // typically you would put this on a specific route like /spaces
  return (
    <SpacesPage
      spacePath="/spaces/:space" // how to navigate to a specific space
      onSpaceCreate={() => {
        // handle the event that the user clicks "create space"
        // this is where you can initialize the space with new objects
      }}
    />
  );
};

const root = createRoot(document.getElementById('root')!);
root.render(
  <ClientProvider>
    <App />
  </ClientProvider>
);

See a more detailed example in the Tasks application sample.

Learn more about the other react UI Components available from DXOS.