@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;       // 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

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.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());

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