Hook
useOptimisticTransaction
Manages optimistic transaction state with confirmation and rollback handling.
Installation
terminal
$npx shadcn@latest add https://uxdotsol.xyz/r/use-optimistic-transaction.jsonUsage
use-optimistic-transaction.tsx
"use client"; import { useOptimisticTransaction } from "@/hooks/use-optimistic-transaction"; type UsdcPaymentProps = { currentBalance: number; amount: number; sendPayment: () => Promise<string>; confirmPayment: (signature: string) => Promise<void>;}; export function UsdcPayment({ currentBalance, amount, sendPayment, confirmPayment,}: UsdcPaymentProps) { const payment = useOptimisticTransaction({ initialState: { balance: currentBalance }, apply: (state) => ({ balance: state.balance - amount }), transaction: sendPayment, confirm: confirmPayment, }); async function pay() { try { await payment.run(); } catch { // The balance is rolled back and the hook exposes the error. } } return ( <section> <p>USDC balance: {payment.state.balance.toFixed(2)}</p> <button disabled={payment.isPending} onClick={pay}> {payment.isPending ? "Confirming payment..." : `Pay ${amount} USDC`} </button> {payment.status === "rolled-back" ? ( <p role="alert">Payment failed. Your displayed balance was restored.</p> ) : null} </section> );}Options
| Name | Type | Default | Description |
|---|---|---|---|
| initialState | TState | required | Initial UI state controlled by the hook. |
| transaction | () => Promise<TResult> | required | Async transaction or send+confirm operation. |
| apply | (state: TState) => TState | required | Creates the optimistic state. |
| rollback | (previousState, error) => TState | previousState | Restores or adjusts state after failure. |
| confirm | (result: TResult) => Promise<unknown> | undefined | Optional post-send confirmation step. |
Functions
| Name | Type | Default | Description |
|---|---|---|---|
| run | (override?: Partial<Options>) => Promise<TResult> | - | Applies optimistic state, runs transaction, confirms, and rolls back on failure. |
| reset | (nextState?: TState) => void | initialState | Resets hook state and clears result/error. |
| setState | Dispatch<SetStateAction<TState>> | - | Direct state setter for controlled UI updates. |
Types
| Name | Type | Default | Description |
|---|---|---|---|
| OptimisticTransactionStatus | 'idle' | 'optimistic' | 'confirming' | 'confirmed' | 'rolled-back' | - | Current optimistic transaction phase. |
Returns
| Name | Type | Default | Description |
|---|---|---|---|
| state / status | TState / OptimisticTransactionStatus | initialState / 'idle' | Current UI state and transaction phase. |
| error / result | unknown / TResult | null | null | Failure cause or transaction result. |
| isPending | boolean | false | True during optimistic or confirming phases. |