UX.SOL

Hook

useTransactionStatus

Tracks a Solana transaction signature and exposes confirmation state.

Installation

terminal
$npx shadcn@latest add https://uxdotsol.xyz/r/use-transaction-status.json

Usage

use-transaction-status.tsx
"use client";
 
import type { Connection } from "@solana/web3.js";
import { useTransactionStatus } from "@/hooks/use-transaction-status";
 
export function PaymentReceipt({
connection,
signature,
}: {
connection: Connection;
signature: string;
}) {
const transaction = useTransactionStatus({
client: connection,
signature,
commitment: "confirmed",
cluster: "mainnet-beta",
});
 
return (
<section aria-live="polite">
<h2>Payment receipt</h2>
<p>Status: {transaction.status}</p>
{transaction.status === "failed" || transaction.status === "expired" ? (
<button onClick={transaction.retry}>Check again</button>
) : null}
{transaction.explorerLink ? (
<a href={transaction.explorerLink} target="_blank" rel="noreferrer">
View transaction
</a>
) : null}
</section>
);
}

Options

NameTypeDefaultDescription
signaturestringundefinedTransaction signature to watch.
timeoutMsnumber90000Time before the hook reports an expired status.
clientConnection | KitRpcLikeundefinedRPC client used for subscription and status polling.
pollIntervalMsnumber2000Polling interval used alongside or instead of subscriptions.
cluster / explorer / explorerUrlstring'mainnet-beta' / 'solscan' / undefinedExplorer link controls.

Types

NameTypeDefaultDescription
TransactionStatusState'idle' | 'pending' | 'confirmed' | 'finalized' | 'failed' | 'expired'-Clean UI state for a watched signature.

Returns

NameTypeDefaultDescription
statusTransactionStatusState'idle'Current signature state.
confirmations / confirmationStatusnumber | null / string | nullnullRPC confirmation details when available.
errorSignatureResult['err'] | Error | nullnullFailure or timeout error.
explorerLink / isPending / isTerminalstring | null / boolean / booleannull / false / falseConvenience values for rendering status UI.