@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

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;       // required borrowed ccc.Client
connector.wallet;       // connected ccc.Wallet | undefined
connector.signer;       // ccc.SignerInfo | undefined

connector.disconnect(); // disconnect the current wallet
connector.addEventListener("select-client", (event) => {
  connector.client = (event as ccc.SelectClientEvent).client;
});

The Web Component requires and only borrows its client; it never creates or disposes one. Assign a client before adding the element to the document, keep its owner alive for as long as the element may use it, and dispose the owner from your application lifecycle. Network and fee-rate selections emit a composed, bubbling select-client event; the application decides whether to feed its candidate Client back through the client property.

Select a transaction fee rate

The connected-wallet view includes a Fee Rate entry above Manage, so applications do not need to provide a separate trigger. It opens the selector inside the same modal and offers economy, auto, and custom rates. Selections apply immediately; use the back button to return to the connected-wallet view. For now, the selection is retained by the connector UI only.

Usage in plain HTML

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

      const connector = document.createElement("ccc-connector");
      const clientOwner = ccc.ClientPublicTestnet.open();
      connector.client = clientOwner.value;
      connector.style.cssText = "display: none; z-index: 999;";

      window.addEventListener(
        "pagehide",
        () => void clientOwner.dispose(),
        { once: true },
      );

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

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

      connector.addEventListener("select-client", (event) => {
        connector.client = event.client;
      });

      connector.addEventListener("willUpdate", () => {
        if (connector.signer) {
          connector.signer.signer.getRecommendedAddress().then((addr) => {
            document.getElementById("address").textContent = addr;
          });
        }
      });

      // `client` must be assigned before the element is connected.
      document.body.append(connector);
    </script>
  </head>
  <body>
    <button id="open-btn">Connect Wallet</button>
    <p id="address"></p>

  </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.createElement(
  "ccc-connector",
) as ccc.WebComponentConnector;
const clientOwner = ccc.ClientPublicTestnet.open();
connector.client = clientOwner.value; // The Connector borrows it.

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

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

// The Connector requests changes; the application controls the Client.
connector.addEventListener("select-client", (event) => {
  connector.client = (event as ccc.SelectClientEvent).client;
});

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

// `client` must be assigned before the element is connected.
document.body.append(connector);

// Once the Connector can no longer use this Client, the caller releases it:
// await clientOwner.dispose();

Styling with CSS custom properties

Set CSS custom properties on <ccc-connector> to theme the built-in UI. The Web Component consumes the variables listed below; the defaults shown are the light theme supplied by @ckb-ccc/connector-react.

Custom property	React default	Controls
`--background`	`#fff`	Dialog and input base background
`--divider`	`#eee`	Dividers and separators
`--btn-primary`	`#f8f8f8`	Primary button background
`--btn-primary-hover`	`#efeeee`	Primary button hover and selected background
`--btn-secondary`	`#ddd`	Secondary pill button background
`--btn-secondary-hover`	`#ccc`	Secondary pill button hover background
`--btn-color`	`color` (`#1e1e1e`)	Button text, SVG icon, and embedded input text
`--btn-color-hover`	`--btn-color`	Button content on hover or when selected
`--icon-primary`	`#1E1E1E`	Primary icons
`--icon-secondary`	`#666666`	Secondary icons
`--tip-color`	`#666`	Supporting and tip text
`--tip-color-hover`	`--tip-color`	Interactive tip text on hover or when selected

The connector's regular text inherits the standard CSS color property. When omitted, --btn-color also inherits color, --btn-color-hover falls back to --btn-color, and --tip-color-hover falls back to --tip-color.

<ccc-connector
  style="
    color: #e6eef2;
    --background: #11181c;
    --divider: #28343a;
    --btn-primary: #171d21;
    --btn-primary-hover: #5bcefa;
    --btn-color: #e6eef2;
    --btn-color-hover: #070a0c;
    --tip-color: #76858d;
    --tip-color-hover: #31515f;
  "
></ccc-connector>

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.

@ckb-ccc/connector

On this page