> ## Documentation Index
> Fetch the complete documentation index at: https://ckbfans.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# connector-react

> React Provider, useCcc hook, and useSigner hook for wallet connection in CKB apps.

`@ckb-ccc/connector-react` is the recommended integration layer for React and Next.js applications. It provides a context `Provider`, a `useCcc` hook that exposes the full connector state, and a `useSigner` hook that returns the active signer whenever a wallet is connected.

## Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @ckb-ccc/connector-react
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @ckb-ccc/connector-react
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @ckb-ccc/connector-react
    ```
  </Tab>
</Tabs>

```typescript theme={null}
import { ccc } from "@ckb-ccc/connector-react";
```

## Provider

Wrap your application (or the subtree that needs wallet access) with `ccc.Provider`. It renders the wallet selection modal and makes the connector context available to all descendant components.

```tsx theme={null}
import { ccc } from "@ckb-ccc/connector-react";

export function App() {
  return (
    <ccc.Provider>
      <YourApp />
    </ccc.Provider>
  );
}
```

### Props

<Note>
  All props are optional except `children`.
</Note>

| Prop                | Type                                                                   | Description                                                                  |
| ------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `children`          | `ReactNode`                                                            | The component subtree that can access the connector context.                 |
| `name`              | `string`                                                               | Display name shown in the connector UI for your application.                 |
| `icon`              | `string`                                                               | URL of your application icon shown in the connector UI.                      |
| `defaultClient`     | `ccc.Client`                                                           | Override the default CKB client. Defaults to `ClientPublicTestnet`.          |
| `clientOptions`     | `{ icon?: string; client: ccc.Client; name: string }[]`                | List of named network clients users can switch between.                      |
| `preferredNetworks` | `ccc.NetworkPreference[]`                                              | Networks to prioritise when multiple signers are available.                  |
| `signerFilter`      | `(signerInfo: ccc.SignerInfo, wallet: ccc.Wallet) => Promise<boolean>` | Async predicate to hide specific signers from the UI.                        |
| `signersController` | `ccc.SignersController`                                                | Provide a custom signers controller, bypassing the built-in filter logic.    |
| `hideMark`          | `boolean`                                                              | Hide the CCC watermark in the connector modal.                               |
| `connectorProps`    | `HTMLAttributes<{}>`                                                   | Additional HTML attributes forwarded to the connector web component element. |

## useCcc

`useCcc()` returns the full connector context. Call it inside any component that is a descendant of `ccc.Provider`.

```tsx theme={null}
import { ccc } from "@ckb-ccc/connector-react";

function ConnectButton() {
  const { open, disconnect, wallet, signerInfo, client } = ccc.useCcc();

  if (signerInfo) {
    return (
      <div>
        <p>Connected: {wallet?.name}</p>
        <button onClick={disconnect}>Disconnect</button>
      </div>
    );
  }

  return <button onClick={open}>Connect wallet</button>;
}
```

### Return value

| Property     | Type                           | Description                                                                    |
| ------------ | ------------------------------ | ------------------------------------------------------------------------------ |
| `isOpen`     | `boolean`                      | Whether the connector modal is currently visible.                              |
| `open`       | `() => void`                   | Open the wallet selection modal.                                               |
| `close`      | `() => void`                   | Close the wallet selection modal.                                              |
| `disconnect` | `() => void`                   | Disconnect the currently connected wallet.                                     |
| `setClient`  | `(client: ccc.Client) => void` | Switch to a different CKB client at runtime.                                   |
| `client`     | `ccc.Client`                   | The active CKB client instance.                                                |
| `wallet`     | `ccc.Wallet \| undefined`      | The connected wallet metadata, or `undefined` when no wallet is connected.     |
| `signerInfo` | `ccc.SignerInfo \| undefined`  | The active signer info (contains `.signer`), or `undefined` when disconnected. |

<Warning>
  Calling `useCcc()` outside of a `ccc.Provider` subtree throws an error. Make sure every component that uses this hook is wrapped by the provider.
</Warning>

## useSigner

`useSigner()` is a convenience hook that returns the active `ccc.Signer` directly. It returns `undefined` while no wallet is connected.

```tsx theme={null}
import { ccc } from "@ckb-ccc/connector-react";

function SendButton() {
  const signer = ccc.useSigner();

  async function sendCkb() {
    if (!signer) return;

    const { script: toLock } = await ccc.Address.fromString(
      "ckb1...",
      signer.client,
    );
    const tx = ccc.Transaction.from({
      outputs: [{ lock: toLock, capacity: ccc.fixedPointFrom("100") }],
    });
    await tx.completeInputsByCapacity(signer);
    await tx.completeFeeBy(signer);
    const txHash = await signer.sendTransaction(tx);
    console.log("Sent:", txHash);
  }

  return (
    <button onClick={sendCkb} disabled={!signer}>
      Send 100 CKB
    </button>
  );
}
```

## Full example

The following example shows a minimal React app that connects a wallet and sends CKB.

```tsx theme={null}
"use client"; // Required for Next.js App Router

import { ccc } from "@ckb-ccc/connector-react";

function WalletControls() {
  const { open, disconnect, wallet, signerInfo } = ccc.useCcc();
  const signer = ccc.useSigner();

  async function handleSend() {
    if (!signer) return;
    const { script: toLock } = await ccc.Address.fromString(
      "ckb1qzda0cr08m85hc8jlnfp3gp88t7re8he4qkd3he97k2tfe4ckb...",
      signer.client,
    );
    const tx = ccc.Transaction.from({
      outputs: [{ lock: toLock, capacity: ccc.fixedPointFrom("100") }],
    });
    await tx.completeInputsByCapacity(signer);
    await tx.completeFeeBy(signer);
    const txHash = await signer.sendTransaction(tx);
    alert(`Sent! TX: ${txHash}`);
  }

  return (
    <div>
      {signerInfo ? (
        <>
          <p>Connected via {wallet?.name}</p>
          <button onClick={handleSend}>Send 100 CKB</button>
          <button onClick={disconnect}>Disconnect</button>
        </>
      ) : (
        <button onClick={open}>Connect wallet</button>
      )}
    </div>
  );
}

export default function App() {
  return (
    <ccc.Provider>
      <WalletControls />
    </ccc.Provider>
  );
}
```

<Tip>
  In Next.js App Router, add `"use client"` to any file that imports from `@ckb-ccc/connector-react`. The `Provider` and hooks use React context and browser APIs that are not available in server components.
</Tip>