Headless React bindings for Stellar applications: connection state, cached reads, explicit contract invocations, existing transaction pipelines, events and SEPs.
The React package is a 0.x preview. React
19.1+ in the 19.x line and TanStack Query 5.87+ in the 5.x line are supported.
The app owns its configuration, wallet SDKs and signing authority.
ColibriQueryProvider can own the query cache or reuse the
application cache. See installation for
the current package versions.
Follow installation and provider setup.
The complete TSX balance example uses
ColibriQueryProvider and displays a funded account’s
balance.
See common workflows and convenience APIs for complete provider, wallet and combined signing setup. Granular APIs remain available.
Import runtime features from their documented subpaths. The root contains only configuration, provider, connection hooks and integration errors. Shared type exports are erased from JavaScript.
Keep full clients and their plugins with useContract, read through a generated helper or an ABI spec, and invoke only from explicit user actions. useWalletContractInvoke fills missing transaction source and signers from the connected wallet; explicit overrides remain available. Contract and pipeline recipes explain transaction configuration, simulation and event subscriptions.
- XLM:
{ kind: "xlm" }. - Classic issued asset:
{ kind: "classic", code, issuer }. - SEP-41 token, including a SAC:
{ kind: "sep41", contractId }.
Classic account/trustline reads use G-addresses. SEP-41 balances accept G or C addresses; muxed attribution belongs to the transaction destination, not a separate balance. A C-address does not imply an Ed25519 signing capability.
The package composes existing Colibri support: SEP-1
discovery, SEP-10/45 WebAuth, SEP-41
tokens and event values, SEP-33 SVG identicons and optional
SEP-53 message signing.
SEP-1 anchor URLs are advertisements; this package does not
implement SEP-6/12/24/31/38 services. Existing Core
SEP-11 asset helpers remain available through
@colibri/core/assets without a redundant React hook for pure work.
Use one config per application and separate configs per server request. Queries and caching explains network scopes, freshness, mutation retries and serialization. Wallets and sessions explains authority changes, memory-only credentials and cleanup. Event subscriptions have their own shared observer lifecycle.
Connection SSR snapshots are disconnected and session SSR snapshots are
anonymous. Render ordinary query/mutation error states and handle connection
Promise rejections at the user-action boundary. React errors have dedicated
subclasses, such as
ReactNetworkMismatchError,
within the ColibriReactError
family. Use instanceof or stable
React error codes for integration failures;
existing Core and wallet errors retain their identity.