# Connection UI (DidConnect)

The `DidConnect` component is a pre-built, comprehensive UI solution for handling various decentralized identity (DID) connection flows. It provides a user-friendly interface for actions like login, authentication, and profile requests, supporting multiple connection methods out-of-the-box.

It serves as the visual centerpiece of the `@arcblock/did-connect-react` library, abstracting away the complexity of session management and real-time status updates. The component displays a QR code for DID Wallet users and offers alternative login options such as social logins (OAuth) and passwordless authentication (Passkeys).

Before using `DidConnect`, ensure you have wrapped your application with the [`SessionProvider`](./core-components-session-provider.md) to manage the overall session state.

## Basic Usage

To use `DidConnect`, you need to import it and provide a few essential props. The component is typically controlled by a state variable that determines its visibility.

```jsx DID Connect Example icon=logos:react
import React, { useState } from 'react';
import axios from 'axios';
import DidConnect from '@arcblock/did-connect-react/lib/Connect';

function App() {
  const [isConnectOpen, setConnectOpen] = useState(false);

  const handleClose = () => setConnectOpen(false);
  const handleSuccess = () => {
    // Handle successful login, e.g., redirect the user
    window.location.href = '/profile';
  };

  return (
    <div>
      <button onClick={() => setConnectOpen(true)}>Login with DID</button>
      {isConnectOpen && (
        <DidConnect
          action="login"
          checkFn={axios.get}
          onClose={handleClose}
          onSuccess={handleSuccess}
          messages={{
            title: 'Scan to Sign In',
            scan: 'Scan QR code with your DID Wallet',
            confirm: 'Confirm login on your DID Wallet',
            success: 'You have successfully signed in!',
          }}
        />
      )}
    </div>
  );
}

export default App;
```

In this example, clicking the "Login with DID" button sets the `isConnectOpen` state to `true`, which renders the `DidConnect` component as a modal dialog. The `checkFn` prop is crucial, as it's the function the component uses to poll for the session status from your backend.

## How It Works

The `DidConnect` component orchestrates the entire user authentication flow, from displaying connection options to handling the final success or error state. The following diagram illustrates this flow:

<!-- DIAGRAM_IMAGE_START:flowchart:4:3:1765962229 -->
![Connection UI (DidConnect)](assets/diagram/did-connect-diagram-0.jpg)
<!-- DIAGRAM_IMAGE_END -->

## Component Props

The `DidConnect` component is highly configurable through its props. Below is a detailed list of the available options.

### Core Configuration

These props are essential for setting up the component's basic functionality.

<x-field-group>
  <x-field data-name="action" data-type="string" data-required="true">
    <x-field-desc markdown>Defines the purpose of the connection, such as `login`, `claim`, `sign`, etc. This string is passed to your backend to determine the required actions.</x-field-desc>
  </x-field>
  <x-field data-name="checkFn" data-type="function" data-required="true">
    <x-field-desc markdown>The function used to poll the backend for session status updates. It should be a function that makes an API request, like `axios.get`.</x-field-desc>
  </x-field>
  <x-field data-name="baseUrl" data-type="string" data-default="''">
    <x-field-desc markdown>The base URL for the API endpoints. If your API is on a different domain, specify it here.</x-field-desc>
  </x-field>
  <x-field data-name="prefix" data-type="string" data-default="/api/did">
    <x-field-desc markdown>The URL prefix for the DID Connect API endpoints on your backend.</x-field-desc>
  </x-field>
</x-field-group>

### Behavior Control

These props control how the connection process behaves.

<x-field-group>
  <x-field data-name="enabledConnectTypes" data-type="string[]" data-default='["web", "mobile", ...]'>
    <x-field-desc markdown>An array of strings specifying which connection methods to display. Possible values include `web`, `mobile`, `github`, `google`, `apple`, `passkey`, etc.</x-field-desc>
  </x-field>
  <x-field data-name="passkeyBehavior" data-type="'none' | 'both' | 'only-existing' | 'only-new'" data-default="'none'">
    <x-field-desc markdown>Controls the behavior of Passkey authentication. `none` disables it, `both` allows creating new passkeys and using existing ones, `only-existing` restricts to existing passkeys, and `only-new` forces new passkey creation.</x-field-desc>
  </x-field>
  <x-field data-name="allowWallet" data-type="boolean" data-default="true">
    <x-field-desc markdown>If `false`, the QR code and mobile wallet connection options will be hidden.</x-field-desc>
  </x-field>
  <x-field data-name="autoConnect" data-type="boolean" data-default="true">
    <x-field-desc markdown>If `true`, the component will automatically try to use a previously established connection from the same device.</x-field-desc>
  </x-field>
  <x-field data-name="forceConnected" data-type="boolean | string" data-default="true">
    <x-field-desc markdown>If `true`, a user must connect with the same DID they are already logged in with. If a DID string is provided, the user must connect with that specific DID.</x-field-desc>
  </x-field>
  <x-field data-name="saveConnect" data-type="boolean" data-default="true">
    <x-field-desc markdown>If `true`, the successful connection information is saved locally for future `autoConnect` attempts.</x-field-desc>
  </x-field>
  <x-field data-name="useSocket" data-type="boolean" data-default="true">
    <x-field-desc markdown>If `true`, attempts to use a WebSocket for real-time status updates, falling back to polling if a connection cannot be established.</x-field-desc>
  </x-field>
</x-field-group>

### UI Customization

Customize the appearance and text of the `DidConnect` component.

<x-field-group>
  <x-field data-name="mode" data-type="'dialog' | 'drawer' | 'page'" data-default="'dialog'">
    <x-field-desc markdown>Determines how the component is displayed. `dialog` shows it as a centered modal, `drawer` as a bottom sheet (on mobile), and `page` embeds it directly into the document flow.</x-field-desc>
  </x-field>
  <x-field data-name="messages" data-type="object">
    <x-field-desc markdown>An object to customize the text displayed in the UI.</x-field-desc>
    <x-field data-name="title" data-type="string" data-desc="The main title at the top."></x-field>
    <x-field data-name="scan" data-type="string" data-desc="The instructional text below the title."></x-field>
    <x-field data-name="confirm" data-type="string" data-desc="Text shown after the QR code is scanned."></x-field>
    <x-field data-name="success" data-type="string | ReactNode" data-desc="Message displayed upon successful connection."></x-field>
    <x-field data-name="error" data-type="string" data-desc="Message displayed on error."></x-field>
  </x-field>
  <x-field data-name="hideCloseButton" data-type="boolean" data-default="false">
    <x-field-desc markdown>If `true`, the close button (X) in the top-right corner is hidden.</x-field-desc>
  </x-field>
  <x-field data-name="extraContent" data-type="ReactNode" data-default="null">
    <x-field-desc markdown>Allows you to inject a custom React component or element into the UI, typically appearing below the main title/description.</x-field-desc>
  </x-field>
  <x-field data-name="customItems" data-type="ReactNode[]" data-default="[]">
    <x-field-desc markdown>An array of custom React nodes to be added to the list of connection methods.</x-field-desc>
  </x-field>
  <x-field data-name="disableSwitchApp" data-type="boolean" data-default="false">
    <x-field-desc markdown>If you are using Federated Login, this prop prevents users from switching between different applications in the group during the login process.</x-field-desc>
  </x-field>
  <x-field data-name="webWalletUrl" data-type="string">
    <x-field-desc markdown>The URL of the web-based DID Wallet to be used for the "Connect with Web Wallet" option. Defaults to the official ArcBlock web wallet.</x-field-desc>
  </x-field>
</x-field-group>

### Callbacks

Functions that are called at different stages of the connection lifecycle.

<x-field-group>
  <x-field data-name="onClose" data-type="function" data-required="true">
    <x-field-desc markdown>Callback function that is executed when the user closes the `DidConnect` dialog (e.g., by clicking the close button or outside the modal).</x-field-desc>
  </x-field>
  <x-field data-name="onSuccess" data-type="function" data-required="true">
    <x-field-desc markdown>Callback function that is executed upon a successful connection. The session data is passed as an argument.</x-field-desc>
  </x-field>
  <x-field data-name="onError" data-type="function">
    <x-field-desc markdown>Callback function that is executed when an error occurs during the process. The error object or message is passed as an argument.</x-field-desc>
  </x-field>
  <x-field data-name="onRecreateSession" data-type="function">
    <x-field-desc markdown>A callback function that is invoked when the session needs to be reset, for example, after a timeout or when the user manually cancels and retries.</x-field-desc>
  </x-field>
</x-field-group>

## Next Steps

With a solid understanding of the `DidConnect` component, you can now build robust authentication experiences. For more programmatic control over the connection UI, explore the [`useConnect` hook](./hooks-use-connect.md), which allows you to open and close the `DidConnect` modal from anywhere in your application.
