@ckb-ccc/connector

@ckb-ccc/connector provides a native Web Component that renders CCC's wallet-selection UI without requiring any JavaScript framework. It is the foundation that @ckb-ccc/connector-react is built on top of.

When to use this package

Use @ckb-ccc/connector when you need wallet connectivity in a plain HTML page, vanilla JS project, or a framework that is not React. If you are building a React application, prefer @ckb-ccc/connector-react which wraps this package with React bindings.

Installation

@ckb-ccc/connector npm downloads per week

npm install @ckb-ccc/connector

yarn add @ckb-ccc/connector

pnpm add @ckb-ccc/connector

The `WebComponentConnector` class

The central export is ccc.WebComponentConnector — the underlying custom element class. When you register the element and add it to the DOM, it renders the wallet picker UI.

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

// The connector element
const connector: ccc.WebComponentConnector;

connector.client;       // current ccc.Client
connector.wallet;       // connected ccc.Wallet | undefined
connector.signer;       // ccc.SignerInfo | undefined

connector.disconnect(); // disconnect the current wallet
connector.setClient(newClient); // switch networks

Usage in plain HTML

<!doctype html>
<html>
  <head>
    <script type="module">
      import { ccc } from "https://esm.sh/@ckb-ccc/connector";

      const connector = document.getElementById("ccc-connector");

      document.getElementById("open-btn").addEventListener("click", () => {
        connector.style.display = "";
      });

      connector.addEventListener("close", () => {
        connector.style.display = "none";
      });

      connector.addEventListener("willUpdate", () => {
        if (connector.signer) {
          connector.signer.signer.getRecommendedAddress().then((addr) => {
            document.getElementById("address").textContent = addr;
          });
        }
      });
    </script>
  </head>
  <body>
    <button id="open-btn">Connect Wallet</button>
    <p id="address"></p>

    <ccc-connector
      id="ccc-connector"
      style="display: none; z-index: 999;"
    ></ccc-connector>
  </body>
</html>

Usage with a bundler (vanilla JS/TS)

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

// The custom element is auto-registered when you import the package.
const connector = document.querySelector("ccc-connector") as ccc.WebComponentConnector;

// Show the wallet picker
connector.style.display = "";

// Listen for events
connector.addEventListener("close", () => {
  connector.style.display = "none";
});

connector.addEventListener("willUpdate", () => {
  console.log("Connected wallet:", connector.wallet?.name);
  console.log("Signer:", connector.signer);
});

// Switch to mainnet
connector.setClient(new ccc.ClientPublicMainnet());

Comparison with `@ckb-ccc/connector-react`

Feature	`@ckb-ccc/connector`	`@ckb-ccc/connector-react`
Framework	None (Web Component)	React
Integration style	DOM events	`Provider` + `useCcc()` hook
State management	Manual DOM listeners	React context, reactive
Peer dependency	—	`react >= 16`

@ckb-ccc/connector-react uses @lit/react to wrap this Web Component. All wallet integrations (JoyID, MetaMask, Nostr, BTC wallets, etc.) are wired through the same underlying connector element.