sorokit-ui

React component library for Stellar.

Drop-in UI primitives for wallet connection, transaction flows,
account display, and Soroban contract interaction — powered by sorokit-core.

Part of the sorokit ecosystem.

---

Overview

sorokit-ui is the React layer of the sorokit ecosystem. It provides ready-to-use components that connect directly to sorokit-core — so you can add wallet connection, balance display, payment flows, and Soroban contract interaction to your app without building any of the wiring yourself.

All components are unstyled by default and accept a className prop, making them compatible with Tailwind, CSS Modules, or any styling approach you already use.

---

Table of Contents

• Installation
• Quick Start
• Provider Setup
• Components
• Hooks
• Styling
• Theming
• Networks
• Design Principles
• License

---

Installation

npm install sorokit-ui sorokit-core @creit.tech/stellar-wallets-kit

Both sorokit-core and @creit.tech/stellar-wallets-kit are required peer dependencies.

---

Quick Start

Wrap your app in SorokitProvider, then use components anywhere in the tree:

import {
  SorokitProvider,
  ConnectWalletButton,
  AccountBalance,
} from "sorokit-ui";

function App() {
  return (
    <SorokitProvider network="testnet">
      <ConnectWalletButton />
      <AccountBalance />
    </SorokitProvider>
  );
}

---

Provider Setup

SorokitProvider initialises a sorokit-core client and makes it available to all child components via context.

import { SorokitProvider } from "sorokit-ui";

<SorokitProvider
  network="testnet" // "mainnet" | "testnet" | "futurenet"
  horizonUrl="https://..." // optional: override Horizon URL
  rpcUrl="https://..." // optional: override Soroban RPC URL
>
  {children}
</SorokitProvider>;

---

Components

The package ships a broad set of reusable UI building blocks for wallets, accounts, transactions, Soroban flows, and shared layout primitives.

Category	Component	Purpose
Wallet	WalletConnectButton	Connect or disconnect a Stellar wallet with a ready-to-use button.
Wallet	AddressDisplay	Render and format a wallet or account address.
Account	AccountCard	Display account summary information in a compact card.
Account	BalanceList	Present the connected account's balances in a list.
Account	AssetBadge	Show an asset code and related badge styling.
Account	ClaimableBalanceCard	Display claimable balance details in a card.
Transactions	TransactionHistory	Show recent account transactions.
Transactions	TransactionPanel	Manage transaction submission and status details.
Transactions	FeeEstimator	Estimate fees for a proposed transaction.
Transactions	QRCode	Render a QR code for addresses or payment requests.
Transactions	ErrorBoundary	Catch rendering errors and show a fallback state.
Network	NetworkBanner	Display the active network context.
Network	NetworkSwitcher	Let users switch between Stellar networks.
Soroban	SorobanPanel	Provide a full Soroban contract interaction experience.
Soroban	SorobanInvokeButton	Trigger a contract invocation from a button.
Soroban	ContractEventFeed	Stream and display contract events.
Layout	Sidebar	Render app navigation in a sidebar shell.
Layout	TopBar	Render a top navigation bar.
UI Primitives	Badge	Small status or label badge primitive.
UI Primitives	Button	Flexible button primitive.
UI Primitives	Card	Surface container primitive.
UI Primitives	Input	Text input primitive.
UI Primitives	Separator	Horizontal divider primitive.
UI Primitives	Skeleton	Loading placeholder primitive.

For upgrade notes and release history, see CHANGELOG.md.

---

Hooks

If you need the underlying client or wallet state directly, hooks are available:

import { useSorokit, useWallet, useAccount, useTransaction } from "sorokit-ui";

// Access the raw sorokit-core client
const { client } = useSorokit();

// Wallet state and connect/disconnect actions
const { publicKey, connected, connect, disconnect } = useWallet();

// Account data for the connected wallet
const { balances, loading, error } = useAccount();

// Build and submit transactions
const { buildPayment, submit, status } = useTransaction();

refreshAccount

Re-fetches the connected account data and balances. Useful when the user expects their balance to have changed (e.g. after receiving a payment) without disconnecting and reconnecting.

const { refreshAccount, isLoadingAccount } = useSorokit();

// Await the refresh to know when it has completed
await refreshAccount();

refreshAccount returns a Promise<void> that resolves once both getAccount and getBalances have settled. isLoadingAccount is true while the request is in flight.

All hooks must be used inside a SorokitProvider. When used outside one, useSorokit returns safe no-op defaults rather than throwing, so components render in a neutral disconnected state.

---

Tailwind CSS Setup

sorokit-ui is styled with Tailwind CSS v4. To use the library in your own Tailwind project:

1. Import the CSS file

@import "sorokit-ui/style.css";

This imports the pre-built component styles, design tokens (surfaces, text, borders, brand colors), and all custom utility classes (bg-surface, text-ink, border-line, etc.).

2. Scan library files in your Tailwind config

If you are using Tailwind's JIT engine (Tailwind v3 with tailwind.config.js) or the automatic content detection in Tailwind v4, you may need to configure @source directives or the content glob to pick up class names used inside the library:

/* Tailwind v4 — add to your main CSS file */
@import "tailwindcss";
@source "../node_modules/sorokit-ui";

For Tailwind v3, add to tailwind.config.js:

module.exports = {
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/sorokit-ui/dist/**/*.{js,mjs}",
  ],
};

3. Verify theme tokens

The library exposes CSS custom properties on :root (see Theming below). Override any token to customise the appearance:

:root {
  --color-brand: #replac3;
  --color-surface: #ffffff;
  --color-ink: #1a1a1a;
}

---

Styling

Components are unstyled by default. Every component accepts a className prop:

// Tailwind
<ConnectWalletButton className="rounded-lg bg-indigo-600 px-4 py-2 text-white" />

// CSS Modules
<AccountBalance className={styles.balance} />

To apply a consistent base style across all components, pass a classNames map to the provider:

<SorokitProvider
  network="testnet"
  classNames={{
    connectButton: "rounded-lg bg-indigo-600 px-4 py-2 text-white",
    accountBalance: "font-mono text-sm text-gray-700",
  }}
>
  {children}
</SorokitProvider>

---

Theming

sorokit-ui ships with a dark-first design token system defined in src/index.css. All components reference semantic CSS custom properties rather than hardcoded colours, so consumer apps can adapt the library to light mode or a custom brand palette by overriding tokens on :root.

Token categories

Category	Examples	Utility classes
Surfaces	--color-base, --color-surface, --color-surface-2	bg-base, bg-surface, bg-surface-2
Text	--color-ink, --color-ink-2, --color-ink-3	text-ink, text-ink-2, text-ink-3
Borders	--color-line, --color-line-2	border-line, border-line-2
Brand	--color-brand, --color-brand-hover	bg-brand, text-brand
State	--color-success-bg, --color-error-bg	bg-success-dim, bg-error-dim
QR canvas	--color-qr-canvas-bg, --color-qr-canvas-fg	—

Light mode adaptation

Override tokens in your app's global stylesheet. The library uses color-scheme: dark by default; switch to light by overriding surface and ink tokens and setting color-scheme: light:

:root {
  color-scheme: light;

  --color-base: #ffffff;
  --color-surface: #f5f5f5;
  --color-surface-2: #ebebeb;
  --color-ink: #1a1a1a;
  --color-ink-2: #666666;
  --color-ink-3: #999999;
  --color-line: #e0e0e0;

  /* QR codes: white background works in light mode by default */
  --color-qr-canvas-bg: #ffffff;
  --color-qr-canvas-fg: #0d0d0d;
}

You can also respect the OS preference with prefers-color-scheme:

@media (prefers-color-scheme: light) {
  :root {
    color-scheme: light;
    --color-base: #ffffff;
    /* …other light tokens */
  }
}

Component-level overrides

QRCode accepts canvasBackground and canvasForeground props for per-instance control. All other components accept className for local overrides.

---

Networks

// Development
<SorokitProvider network="testnet">

// Production
<SorokitProvider network="mainnet">

// Bleeding edge
<SorokitProvider network="futurenet">

// Self-hosted infrastructure
<SorokitProvider
  network="mainnet"
  horizonUrl="https://my-horizon.example.com"
  rpcUrl="https://my-rpc.example.com"
>

---

Design Principles

Composable — every component does one thing. Combine them freely; there are no required groupings or wrapper hierarchies beyond the provider.

Unstyled by default — no opinion about your design system. Bring Tailwind, CSS Modules, styled-components, or plain CSS.

Powered by sorokit-core — all network logic lives in sorokit-core. Components are thin UI wrappers — no duplicated Stellar logic, no diverging behaviour between the SDK and the UI layer.

No-throw, all the way down — error states are props and hook return values, never unhandled exceptions.

---

Contributing

Pull requests are welcome. For significant changes, please open an issue first to discuss what you'd like to change.

See CONTRIBUTING.md for detailed development guidelines, code style, and the PR process.

---

Publishing to npm

This package is now public ("private": false in package.json). To publish a new version:

1. Update the version in package.json
2. Update CHANGELOG.md with changes
3. Create a GitHub release with tag v{version}
4. CI automatically publishes to npm

Requires NPM_TOKEN secret in GitHub repository settings.

---

License

MIT