DIDSpaceConnect
The DIDSpaceConnect component renders a button that initiates a connection or reconnection to a DID Space. It encapsulates the necessary authentication flows, providing a straightforward way for developers to integrate DID Space connectivity into their applications.
This component supports two primary connection methods:
- Wallet-based Connection: The user connects their DID Wallet, which provides the necessary credentials to authorize the connection to their DID Space.
- Gateway-based Connection: The user provides the URL of their DID Space Gateway directly to establish a connection.
Connection Flow#
The component manages the user interaction flow for both connection methods. The diagram below illustrates the simplified process.
Props#
The DIDSpaceConnect component accepts the following props. It also forwards any other props to the underlying Material-UI Button component.
Prop | Type | Description |
|---|---|---|
|
| Optional. If provided, the component automatically saves the |
|
| Optional, defaults to |
|
| Optional. The DID of the space to reconnect to. Required when |
|
| Optional. The URL of the space gateway to reconnect to. Required when |
|
| Optional. Advanced options to customize the authentication request, such as |
|
| Optional, defaults to |
|
| Optional. Custom content to display inside the connection button. Defaults to "Connect with Wallet". |
|
| Optional. Callback function executed on a successful connection. It receives the |
|
| Optional. Callback function executed when an error occurs during the connection process. |
onSuccess Callback Details#
The onSuccess callback is central to handling the connection result. It receives an object with the following properties:
spaceGateway: An object containing details of the connected DID Space. See the DIDSpaceGateway type definition for its structure.response: The raw response object from the authentication request.decrypt: A function that can be used to decrypt encrypted fields from theresponse.
Usage Scenarios#
1. Connecting to a Specific DID Space#
This is the most basic use case. The component is used to establish a connection, and the resulting spaceGateway object is handled manually within the onSuccess callback. This is useful when you need to manage the connection state yourself, for instance, by storing it in a local state or sending it to a backend.
import { DIDSpaceConnect, type DIDSpaceGateway } from '@blocklet/did-space-react';
import Toast from '@arcblock/ux/lib/Toast';
export default function ConnectDemo() {
const handleSuccess = async ({ spaceGateway }: { spaceGateway: DIDSpaceGateway }) => {
try {
// You can now use the spaceGateway object
console.log('Connected to DID Space:', spaceGateway.name);
console.log('Endpoint:', spaceGateway.endpoint);
// e.g., store it in local state or send to a server
Toast.success(`Successfully connected to ${spaceGateway.name}`);
} catch (error) {
console.error('Failed to process connection:', error);
Toast.error('An error occurred after connection.');
}
};
const handleError = (error: Error) => {
console.error('Connection failed:', error);
Toast.error(error.message || 'Connection failed.');
};
return <DIDSpaceConnect onSuccess={handleSuccess} onError={handleError} />;
}2. Linking DID Space to a User Account#
For applications that have a user authentication system (e.g., using @arcblock/did-connect-react), you can pass the session object to the component. Upon successful connection, DIDSpaceConnect will automatically persist the spaceGateway details to the user's session and refresh it. This simplifies state management, as the connection information becomes part of the user's session data, accessible via session.user.didSpace.
import { DIDSpaceConnect } from '@blocklet/did-space-react';
import { useSessionContext } from '@blocklet/did-connect-react/lib/Session';
export default function SessionConnectDemo() {
const session = useSessionContext();
// No need for a custom onSuccess handler if you just want to save to session
return <DIDSpaceConnect session={session} />;
}3. Reconnecting to a Specific DID Space#
A common use case for reconnect is to allow users to re-establish a connection that has become disconnected. This can be integrated directly into the DIDSpaceConnection component's action prop, providing a seamless user experience.
In the example below, the action prop of DIDSpaceConnection checks the connection status. If the status is DISCONNECTED, it renders a DIDSpaceConnect button in reconnect mode. Clicking this button will directly initiate the reconnection process for that specific DID Space.
import { DIDSpaceConnection, DIDSpaceConnect, DIDSpaceStatus, type DIDSpaceGateway } from '@blocklet/did-space-react';
import { useSessionContext } from '@arcblock/did-connect-react/lib/Session';
export default function ReconnectDemo() {
const session = useSessionContext();
// Assume didSpace holds the previously connected space's information
const didSpace: DIDSpaceGateway | undefined = session.user?.didSpace;
if (!didSpace) {
return <DIDSpaceConnect session={session} />;
}
return (
<DIDSpaceConnection
endpoint={didSpace.endpoint}
action={({ spaceStatus, refresh }) => {
// If disconnected, and we have the necessary info, show reconnect button
if (spaceStatus === DIDSpaceStatus.DISCONNECTED && didSpace.did && didSpace.url) {
return (
<DIDSpaceConnect
reconnect
session={session}
spaceDid={didSpace.did}
spaceGatewayUrl={didSpace.url}
onSuccess={async () => {
// After a successful reconnect, refresh the connection status display
await refresh();
}}
variant="contained"
size="small"
>
Reconnect
</DIDSpaceConnect>
);
}
// Return null or other actions for different statuses
return null;
}}
/>
);
}After establishing a connection, you will likely want to display the details of the connected DID Space. Proceed to the DIDSpaceConnection documentation to learn how to use the display card component.