Gear-JS React Hooks

Table of Contents

- Description
- Installation
- Getting started
- Context Hooks
- Balance Hooks
- Derive Hooks
- Voucher Hooks
- Sails Hooks

Description

A React library that provides hooks used across Gear applications.

This package provides ready-to-use hooks for interacting with the @gear-js/api, managing accounts and wallets, formatting balances, querying on-chain state, handling program transactions, and working with vouchers and staking.

Designed to simplify dApp development, these hooks abstract away low-level details and provide a consistent, declarative interface for common blockchain operations, including real-time subscriptions, state management, and user notifications.

Installation

$3

``sh
npm install @gear-js/react-hooks
`

$3

`sh
yarn add @gear-js/react-hooks
`

$3

`sh
pnpm add @gear-js/react-hooks
`

Peer Dependencies

This package requires several peer dependencies to be installed in your project:

- @gear-js/api
- @polkadot/api
- @tanstack/react-query
- sails-js

> Note:
> We recommend not installing peer dependencies explicitly if your package manager can resolve them automatically. However, if you have to fix version conflicts, or if you want to use functionality from these libraries directly in your project, you should install them explicitly.
> Please refer to the peerDependencies section in the package.json for the required versions.

Getting started

To use the hooks, wrap your application with the required providers. Each provider is described below.

QueryClientProvider (TanStack Query)

Wrap your app with QueryClientProvider from TanStack Query to enable query and mutation management.

For more details on setting up TanStack Query, see the TanStack Query documentation.

$3

- client (required): An instance of QueryClient.

$3

`jsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

{/ ... /};
`

ApiProvider

Provides Gear API context to the app.

$3

- initialArgs (required): ProviderArgs — Arguments for the API provider. Determines how the API connection is established.
- WsProviderArgs: { endpoint: string | string[]; autoConnectMs?: number | false; headers?: Record; timeout?: number; } — Connects via JSON-RPC. endpoint is the node address or addresses. autoConnectMs sets the auto-reconnect interval. headers and timeout are optional connection options.
- ScProviderArgs: { spec: string; sharedSandbox?: ScProvider; } — Connects via Light Client. spec is the specification string. sharedSandbox allows sharing a sandbox instance.

$3

`jsx
import { ApiProvider } from '@gear-js/react-hooks';

{/ ... /};
`

AccountProvider

Provides account and wallet context to the app.

$3

- appName (required): string — The name of your application. The value provided here will be displayed in the wallet app or extension.

$3

`jsx
import { AccountProvider } from '@gear-js/react-hooks';

{/ ... /};
`

AlertProvider

Provides alert context for notifications and messages.

$3

- template (required): ComponentType — The component to use as the alert template. Defines how alerts are rendered in your app.
- containerClassName (optional): string — Custom class name for the alert container. Use this to style or position the alert area.

$3

`jsx
import { AlertProvider } from '@gear-js/react-hooks';

import { AlertTemplate } from './alert-template';

{/ ... /};
`

Combine all providers at the root of your app:

`jsx









`

Usage Example

As simple as it is, here's a quick example:

`jsx
import { ProgramMetadata } from '@gear-js/api';
import { useReadFullState } from '@gear-js/react-hooks';

function State() {
const programId = '0x...';
const metadataHex = '0x...';
const payload = null;

const { state } = useReadFullState(programId, ProgramMetadata.from(METADATA_HEX), payload);

return

export { State };
`

Context Hooks

useApi

Provides access to the Gear API instance, allowing you to interact with the blockchain, check if the API is ready, and switch networks programmatically.

$3

None.

$3

- api (GearApi | undefined): The current Gear API instance, or undefined if not yet connected.
- isApiReady (boolean): Indicates whether the API is fully initialized and ready to use.
- switchNetwork ((args: ProviderArgs) => Promise): Function to switch the network provider.

$3

`jsx
import { useApi } from '@gear-js/react-hooks';

function ApiStatus() {
const { api, isApiReady, switchNetwork } = useApi();

if (!isApiReady) return

- wallets (Wallets | undefined): An object containing all detected wallets and their accounts, or undefined if not yet loaded.
- account (Account | undefined): The currently selected account, or undefined if not logged in.
- isAnyWallet (boolean): Indicates whether any wallet extension is available.
- isAccountReady (boolean): Indicates whether wallet and account information has been loaded.
- login ((account: Account) => void): Function to log in with a specific account.
- logout (() => void): Function to log out the current account.

$3

`jsx
import { useAccount } from '@gear-js/react-hooks';

function AccountInfo() {
const { wallets, account, isAnyWallet, isAccountReady, login, logout } = useAccount();

if (!isAccountReady) return

- info ((content: ReactNode, options?: TemplateAlertOptions) => string): Show an info alert.
- error ((content: ReactNode, options?: TemplateAlertOptions) => string): Show an error alert.
- success ((content: ReactNode, options?: TemplateAlertOptions) => string): Show a success alert.
- loading ((content: ReactNode, options?: TemplateAlertOptions) => string): Show a loading alert.
- update ((alertId: string, content: ReactNode, options?: Partial) => void): Update an existing alert by its ID.
- remove ((alertId: string) => void): Remove an alert by its ID.

$3

`jsx
import { useAccount, useAlert } from '@gear-js/react-hooks';

function AlertButtons() {
const alert = useAlert();

const handleSuccessClick = () => {
alert.success('Success alert!');
};

const handleErrorClick = () => {
alert.error('Error alert!');
};

return (


Provides utilities for formatting and converting balances and gas values according to the current chain's decimals and token unit. Use this hook when you need to display user-friendly balances, convert between raw and formatted values, or transform gas calculation values. This hook is based on api.registry.chainDecimals, api.registry.chainTokens, and api.valuePerGas.

> Note:
> This hook uses the BigNumber.js library under the hood. If you are not sure, all values returned as BigNumber instances should be converted or used in calculations only with BigNumber methods — using them as regular JavaScript numbers is not safe and may lead to precision errors.

$3

None.

$3

- balanceMultiplier (BigNumber): Multiplier for converting between raw and formatted balances.
- decimals (number): Number of decimals for the current chain.
- getChainBalanceValue ((value: string | number) => BigNumber): Converts a formatted value to the raw chain balance.
- getFormattedBalanceValue ((value: string | number) => BigNumber): Converts a raw chain balance to a formatted value.
- getFormattedBalance ((balance: BN | string | number) => { value: string, unit: string }): Formats a balance for display, returning the value and unit.
- getChainGasValue ((value: string | number) => BigNumber): Converts a formatted gas value to the raw chain gas value.
- getFormattedGasValue ((value: string | number) => BigNumber): Converts a raw chain gas value to a formatted value.

$3

`jsx
import { useApi, useBalanceFormat } from '@gear-js/react-hooks';

const RAW_BALANCE = 1_000_000_000_000n;

function BalanceDisplay({ balance }) {
const { isApiReady } = useApi();

const { getFormattedBalance } = useBalanceFormat();
const formattedBalance = isApiReady ? getFormattedBalance(RAW_BALANCE) : undefined;

if (!formattedBalance) return Loading...;

return (

{formattedBalance.value} {formattedBalance.unit}

);
}
`

useBalance

Retrieves and subscribes to the total balance of a given account address, allowing you to display or react to the overall balance in your application. This hook is based on api.balance.findOut and api.gearEvents.subscribeToBalanceChanges.

> Note:
> This hook returns the account's total balance as a single value, not its individual components (such as free, reserved, or misc frozen balances). On Substrate-based chains, the balance type is a composite structure; to access specific fields like free balance, use the useDeriveBalancesAll.

$3

- address (string | undefined): The account address to fetch and subscribe to the balance for.

$3

- balance (Balance | undefined): The current total balance of the account, or undefined if not yet loaded.
- isBalanceReady (boolean): Indicates whether the balance has been successfully loaded.

$3

`jsx
import { useBalance } from '@gear-js/react-hooks';

type Props = {
address: string | undefined;
}

function Balance({ address }: Props) {
const { balance, isBalanceReady } = useBalance(address);

if (!isBalanceReady) return

Retrieves and subscribes to all balance components (transferable, reserved, misc frozen, etc.) for a given account address, providing a full breakdown of the account's balance as returned by Substrate's derive API. Use this hook when you need to display or react to specific balance fields, such as transferable or reserved balance, rather than the total. This hook is based on api.derive.balances.all.

$3

- address (string | undefined): The account address to fetch and subscribe to the balance breakdown for.
- watch (boolean, optional): If true, subscribes to balance changes and updates automatically. Default is false.
- query (QueryParameters, optional): Additional query options for TanStack Query.

$3

- TanStack Query UseQueryResult with DeriveBalancesAll data.

$3

`jsx
import { useDeriveBalancesAll } from '@gear-js/react-hooks';

function BalanceBreakdown({ address }) {
const { data, isLoading } = useDeriveBalancesAll({ address });

if (isLoading) return

Retrieves and subscribes to staking information for a given account address, including staking ledger, nominations, rewards, and more, as provided by Substrate's derive API. Use this hook when you need to display or react to staking-related data for an account. This hook is based on api.derive.staking.account.

$3

- address (string | undefined): The account address to fetch and subscribe to staking information for.
- watch (boolean, optional): If true, subscribes to staking changes and updates automatically. Default is false.
- query (QueryParameters, optional): Additional query options for TanStack Query.

$3

- TanStack Query UseQueryResult with DeriveStakingAccount data.

$3

`jsx
import { useDeriveStakingAccount } from '@gear-js/react-hooks';

function StakingInfo({ address }) {
const { data, isLoading } = useDeriveStakingAccount({ address });

if (isLoading) return

Retrieves details for a specific voucher associated with a given account address. Use this hook when you need to display or react to voucher information for a user. This hook is based on api.voucher.getDetails.

$3

- voucherId (HexString | undefined): The voucher ID to fetch details for.
- accountAddress (string | undefined): The account address to fetch the voucher for.

$3

- voucher (IVoucherDetails | undefined): The voucher details, or undefined if not yet loaded.
- isVoucherReady (boolean): Indicates whether the voucher details have been successfully loaded.

$3

`jsx
import { useVoucher } from '@gear-js/react-hooks';

function VoucherInfo({ voucherId, accountAddress }) {
const { voucher, isVoucherReady } = useVoucher(voucherId, accountAddress);

if (!isVoucherReady) return

Retrieves all voucher details for a given account address, optionally filtered by a specific program ID. Use this hook when you need to display or react to all vouchers associated with a user. This hook is based on api.voucher.getAllForAccount.

$3

- accountAddress (string | undefined): The account address to fetch vouchers for.
- programId (HexString, optional): The program ID to filter vouchers by. If omitted, returns all vouchers for the account.

$3

- vouchers (Record | undefined): An object mapping voucher IDs to their details, or undefined if not yet loaded.
- isEachVoucherReady (boolean): Indicates whether the vouchers have been successfully loaded.

$3

`jsx
import { useVouchers } from '@gear-js/react-hooks';

function VouchersList({ accountAddress, programId }) {
const { vouchers, isEachVoucherReady } = useVouchers(accountAddress, programId);

if (!isEachVoucherReady) return

- programId (string): The program ID to connect to.
- idl (string): The program's interface definition language (IDL) as a string.
- query (QueryParameters, optional): Additional query options for TanStack Query.

$3

- TanStack Query UseQueryResult with Sails instance data.

$3

`jsx
import { useSails } from '@gear-js/react-hooks';

const PROGRAM_ID = '0x...';
const IDL = '...';

function SailsInfo() {
const { data: sails } = useSails({
programId: PROGRAM_ID,
idl: IDL,
});

if (!sails) return

- library (Program): The generated program library (e.g., Program from your codegen output).
- id (string): The program ID to connect to.
- query (QueryParameters, optional): Additional query options for TanStack Query.

$3

- TanStack Query UseQueryResult with Program instance data.

$3

`jsx
import { useProgram } from '@gear-js/react-hooks';
import { Program } from './lib';

function ProgramInfo() {
const { data: program } = useProgram({
library: Program,
id: '0x...',
});

if (!program) return

export { ProgramInfo };
`

useSendProgramTransaction

Returns a mutation to sign and send a transaction to a program with minimal effort. Use this hook to interact with a program's service and function, to handle signing, sending, and response management.

$3

- program (Program): The program instance returned by useProgram.
- serviceName (string): The name of the service to call.
- functionName (string): The name of the function to call within the service.

$3

- sendTransactionAsync (function): A function to sign and send the transaction. Accepts an object with:
- args (TFunctionArgs[]): Arguments for the function call.
- account (AccountParameters, optional): Account options to sign the transaction. Defaults to the connected account.
- value (bigint, optional): Value to send with the transaction. Defaults to 0.
- gasLimit (bigint | CalculateGasParameters, optional): Gas limit for the transaction. If not provided, calculated automatically.
- voucherId (HexString, optional): Voucher ID to use for the transaction. If not provided, the transaction will be sent without a voucher.
- awaitFinalization (boolean, optional): Flag indicating whether to wait for the transaction to be finalized. By default, if not specified, the transaction will be processed at the inBlock status.

$3

`jsx
import { useProgram, useSendProgramTransaction } from '@gear-js/react-hooks';
import { Program } from './lib';

function SendTransaction() {
const { data: program } = useProgram({
library: Program,
id: '0x...',
});

const { sendTransactionAsync } = useSendProgramTransaction({
program,
serviceName: 'service',
functionName: 'function',
});

const handleClick = async () => {
const { response } = await sendTransactionAsync({
args: ['arg', 'anotherArg'],
});

console.log('response: ', response);
};

return (

Send Transaction

);
}

export { SendTransaction };
`

Or in combination with usePrepareProgramTransaction:

`jsx
import { useProgram, usePrepareProgramTransaction, useSendProgramTransaction } from '@gear-js/react-hooks';
import { Program } from './lib';

function SendPreparedTransaction() {
const { data: program } = useProgram({
library: Program,
id: '0x...',
});

const { prepareTransactionAsync } = usePrepareProgramTransaction({
program,
serviceName: 'service',
functionName: 'function',
});

const { sendTransactionAsync } = useSendProgramTransaction({
program,
serviceName: 'service',
functionName: 'function',
});

const handleClick = async () => {
const { transaction, fee } = await prepareTransactionAsync({
args: ['arg', 'anotherArg'],
});

console.log('fee: ', fee);

const { response } = await sendTransactionAsync({ transaction });

console.log('response: ', response);
};

return (

Prepare and Send Transaction

);
}

export { SendPreparedTransaction };
`

usePrepareProgramTransaction

Returns a mutation that retrieves the intermediate transaction state. This can be useful for eagerly obtaining values such as gasLimit, extrinsic, and transactionFee, which are essential for providing a better UX.
For example, it can be used to perform validation checks before sending the transaction.

$3

- program (Program): The program instance returned by useProgram.
- serviceName (string): The name of the service to call.
- functionName (string): The name of the function to call within the service.

$3

- prepareTransactionAsync (function): A function to prepare the transaction. Accepts an object with:
- args (TFunctionArgs[]): Arguments for the function call.
- account (AccountParameters, optional): Account options to sign the transaction. Defaults to the connected account.
- value (bigint, optional): Value to send with the transaction. Defaults to 0.
- gasLimit (bigint | CalculateGasParameters, optional): Gas limit for the transaction. If not provided, calculated automatically.
- voucherId (HexString, optional): Voucher ID to use for the transaction.

$3

`jsx
import { useProgram, usePrepareProgramTransaction } from '@gear-js/react-hooks';
import { Program } from './lib';

function LogTransactionFeeButton() {
const { data: program } = useProgram({
library: Program,
id: '0x...',
});

const { prepareTransactionAsync } = usePrepareProgramTransaction({
program,
serviceName: 'service',
functionName: 'function',
});

const handleClick = async () => {
const { fee } = await prepareTransactionAsync({
args: ['arg', 'anotherArg'],
});

console.log('fee: ', fee);
};

return (

Log Transaction Fee

);
}

export { LogTransactionFeeButton };
`

useProgramQuery

Returns a query with the program's state for a given service and function. Use this hook to read state from a program, optionally subscribing to state changes.

$3

- program (Program): The program instance returned by useProgram.
- serviceName (string): The name of the service to query.
- functionName (string): The name of the function to query.
- args (TFunctionArgs[]): Arguments for the function call.
- originAddress (HexString, optional): Account address of the query. Defaults to the connected account.
- value (bigint, optional): Value of the query.
- gasLimit (bigint, optional): Gas limit of the query. Defaults to block maximum gas limit.
- atBlock (HexString, optional): The block hash to query at. Defaults to the latest block.
- watch (boolean, optional): If true, subscribes to state changes. Default is false.
- query (QueryParameters, optional): Additional query options for TanStack Query.

$3

- TanStack Query UseQueryResult with the function's return data.

$3

`jsx
import { useProgram, useProgramQuery } from '@gear-js/react-hooks';
import { Program } from './lib';

function State() {
const { data: program } = useProgram({
library: Program,
id: '0x...',
});

const { data } = useProgramQuery({
program,
serviceName: 'service',
functionName: 'function',
args: ['arg', 'anotherArg'],
});

return

- program (Program): The program instance returned by useProgram.
- serviceName (string): The name of the service to subscribe to.
- functionName (string): The name of the function to subscribe to.
- onData (function): Callback function to handle event data.

$3

None.

$3

`jsx
import { useProgram, useProgramEvent } from '@gear-js/react-hooks';
import { Routing } from './pages';
import { Program } from './lib';

function App() {
const { data: program } = useProgram({
library: Program,
id: '0x...',
});

useProgramEvent({
program,
serviceName: 'service',
functionName: 'function',
onData: (data) => console.log(data),
});

return (


export { App };
``