QubicKit Web Components

@qubiq/web provides React hooks and headless UI primitives built on top of @qubiq/core. It helps dashboards, operations consoles, and governance tools embed live balances, tick info, and CCF proposal data without rewriting the plumbing each time.

Status: first toolkit release – API may evolve as we collect feedback from integrators.

Installation

bun add @qubiq/web @qubiq/core react react-dom

The package ships ESM output (Node 18+/Bun-ready) and expects React 18+ as a peer dependency.

Usage

import { BalanceCard, TickInfoCard, ProposalList, QubiQProvider } from "@qubiq/web";

export function Dashboard({ identity }: { identity: string }) {
  return (
    <QubiQProvider>
      <div className="grid">
        <BalanceCard identity={identity} pollIntervalMs={15_000} />
        <TickInfoCard pollIntervalMs={10_000} />
        <ProposalList status="active" pollIntervalMs={60_000} />
      </div>
    </QubiQProvider>
  );
}

All components and hooks accept an optional client prop. Pass your own LiveServiceClient if you don’t want to use the provider:

import { LiveServiceClient } from "@qubiq/core";
import { useTickInfo } from "@qubiq/web";

const client = new LiveServiceClient({ baseUrl: "https://api.qubic.org" });
const state = useTickInfo({ client });

Hooks

Prefer to build your own UI? Import the hooks directly:

• useLiveBalance – polls /v1/balances/:identity and returns the parsed BalanceRecord.
• useTickInfo – polls /v1/tick-info.
• useBlockHeight – watches /v1/block-height and exposes the latest height.
• useIdentityAssets – fetches issued/owned/possessed asset lists for a given identity.
• useCcfProposals – fetches the latest CCF proposals using the smart-contract helper from @qubiq/core.
• useContractFunctionCall – executes any smart contract function binding returned by useContractBinding.

Each hook exposes { data, loading, error, refresh, lastUpdated } so you can render custom states.

Provider & Contract Hooks

When you need smart contract helpers in React, wrap your app with the QubiQProvider. It wires up shared clients and the ContractToolkit from @qubiq/sdk, so your components can grab them via hooks. The provider also supplies the default LiveServiceClient for the hooks listed above.

import { QubiQProvider, useContractBinding, useContractFunctionCall } from "@qubiq/web";
import type { ContractName } from "@qubiq/sdk";

function App() {
  return (
    <QubiQProvider>
      <ProposalInspector />
    </QubiQProvider>
  );
}

function ProposalInspector() {
  const ccf = useContractBinding("ComputorControlledFund");
  const { data, loading } = useContractFunctionCall({
    binding: ccf,
    functionName: "GetProposal",
    params: { proposalIndex: 1 },
  });

  if (loading) return <p>Loading…</p>;
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

Available helpers:

• QubiQProvider / useQubiQClients – share configured Live/Archive/Query clients.
• useContractToolkit / useContractBinding – read contract metadata and bindings.
• useContractFunctionCall – call any contract function and track loading/error states.

Components

All components are “unstyled” headless cards. They output semantic markup with qubiq-* class names so you can attach your own design system or utility classes:

• BalanceCard
• TickInfoCard
• ProposalList

Pass render* props to override the default layout, or use the exported hooks with your own design entirely.

Development

bun install
bun run build

The build step runs tsc to emit dist/. Linting is handled via biome check src.

Next steps

Upcoming iterations will add chart-ready primitives, wallet connect helpers, and storybook examples once the core API stabilizes. Contributions and issue reports are welcome!