React Hooks Reference

@gillsdk/react provides a comprehensive set of React hooks for interacting with the Solana blockchain. All hooks are built on top of TanStack Query, providing automatic caching, background refetching, and error handling.

Hook Categories

Client Management

Hooks for managing and accessing the Solana client connection:

useSolanaClient - Get the current Solana client
useUpdateSolanaClient - Update the Solana client

Data Fetching

Hooks for fetching data from the Solana blockchain:

useAccount - Get account info and data
useBalance - Get an account's balance
useLatestBlockhash - Get the latest blockhash
useSignatureStatuses - Get the statuses of signatures
useSignaturesForAddress - Get signatures for an address
useProgramAccounts - Get all accounts owned by a program
useTokenMint - Get a token mint account
useTokenAccount - Get a token account

Transaction Handling

Hooks for sending and managing transactions (coming soon):

useSendTransaction - Send transactions with automatic confirmation
useSimulateTransaction - Simulate transactions before sending

Common Hook Options

All data fetching hooks in @gillsdk/react accept standard TanStack Query options:

interface HookOptions {
  // Query key for caching
  queryKey?: QueryKey;

  // How often to refetch in milliseconds
  refetchInterval?: number;

  // Whether to refetch on window focus
  refetchOnWindowFocus?: boolean;

  // Whether to refetch on reconnect
  refetchOnReconnect?: boolean;

  // Time in milliseconds before data is considered stale
  staleTime?: number;

  // Time in milliseconds to keep data in cache
  cacheTime?: number;

  // Whether to enable the query
  enabled?: boolean;

  // Retry configuration
  retry?: boolean | number | RetryConfig;
}

Common Return Values

All data fetching hooks return a consistent shape based on TanStack Query:

interface HookResult<T> {
  // The fetched data - hooks return specific field names like `account`, `balance`, etc. instead of generic `data`
  account?: T; // or balance, signatures, etc. depending on the hook

  // Loading state
  isLoading: boolean;
  isFetching: boolean;

  // Error state
  isError: boolean;
  error: Error | null;

  // Success state
  isSuccess: boolean;

  // Refetch function
  refetch: () => void;

  // Query status
  status: "loading" | "error" | "success" | "idle";
}

Error Handling

All hooks provide built-in error handling. You can handle errors at the component level:

function MyComponent() {
  const { balance, isError, error } = useBalance({
    address: "...",
  });

  if (isError) {
    return <div>Error: {error?.message}</div>;
  }

  // ... rest of component
}

Or configure global error handling through TanStack Query:

import { QueryClient } from "@tanstack/react-query";

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      onError: (error) => {
        console.error("Query error:", error);
        // Handle error globally
      },
    },
  },
});

Performance Tips

Use staleTime wisely - Set appropriate stale times to reduce unnecessary refetches
Enable queries conditionally - Use the enabled option to prevent unnecessary queries
Batch requests - Multiple hooks can share the same query key to deduplicate requests
Implement pagination - For large datasets, use pagination parameters

TypeScript Support

All hooks are fully typed with TypeScript. Import types from gill for complete type safety:

import type { Address, Lamports } from "gill";
import { useBalance } from "@gillsdk/react";

function Balance({ address }: { address: Address }) {
  const { balance } = useBalance({ address });
  // balance is typed as `Lamports | undefined`
}

Hook Categories

Client Management

Data Fetching

Transaction Handling

Common Hook Options

Common Return Values

Error Handling

Performance Tips

TypeScript Support

Client Management Hooks

Data Fetching Hooks

Transaction Hooks

On this page