feat: add custom error and success states to txn button

.changeset/real-dolphins-drive.md

@@ -0,0 +1,5 @@
+---
+'@coinbase/onchainkit': patch
+---
+
+- **feat**: Added ability to customize error and success states for TransactionButton. By @abcrane123 #1460

src/transaction/components/TransactionButton.test.tsx

@@ -30,6 +30,7 @@ describe('TransactionButton', () => {
     (useShowCallsStatus as Mock).mockReturnValue({
       showCallsStatus: vi.fn(),
     });
+    vi.clearAllMocks();
   });
 
   it('renders correctly', () => {
@@ -74,6 +75,70 @@ describe('TransactionButton', () => {
     expect(text).toBeInTheDocument();
   });
 
+  it('renders custom error text when error exists', () => {
+    const mockErrorFunc = vi.fn();
+    (useTransactionContext as Mock).mockReturnValue({
+      lifecycleStatus: { statusName: 'init', statusData: null },
+      errorMessage: 'blah blah',
+      isLoading: false,
+      address: '123',
+      transactions: [{}],
+    });
+    render(
+      <TransactionButton
+        text="Transact"
+        errorOverride={{
+          text: 'oops',
+          onClick: mockErrorFunc,
+        }}
+      />,
+    );
+    const text = screen.getByText('oops');
+    expect(text).toBeInTheDocument();
+    const button = screen.getByTestId('ockTransactionButton_Button');
+    fireEvent.click(button);
+    expect(mockErrorFunc).toHaveBeenCalled();
+  });
+
+  it('should call custom error handler when error exists', () => {
+    const mockErrorFunc = vi.fn();
+    (useTransactionContext as Mock).mockReturnValue({
+      lifecycleStatus: { statusName: 'init', statusData: null },
+      errorMessage: 'blah blah',
+      isLoading: false,
+      address: '123',
+      transactions: [{}],
+    });
+    render(
+      <TransactionButton
+        text="Transact"
+        errorOverride={{
+          text: 'oops',
+          onClick: mockErrorFunc,
+        }}
+      />,
+    );
+    const button = screen.getByTestId('ockTransactionButton_Button');
+    fireEvent.click(button);
+    expect(mockErrorFunc).toHaveBeenCalled();
+  });
+
+  it('should recall onSubmit when error exists and no custom handler provided', () => {
+    const mockOnSubmit = vi.fn();
+    (useTransactionContext as Mock).mockReturnValue({
+      lifecycleStatus: { statusName: 'init', statusData: null },
+      errorMessage: 'blah blah',
+      isLoading: false,
+      address: '123',
+      transactions: [{}],
+      onSubmit: mockOnSubmit,
+    });
+    render(<TransactionButton text="Transact" />);
+    const button = screen.getByTestId('ockTransactionButton_Button');
+    fireEvent.click(button);
+    expect(mockOnSubmit).toHaveBeenCalled();
+  });
+
   it('should have disabled attribute when isDisabled is true', () => {
     const { getByRole } = render(
       <TransactionButton disabled={true} text="Submit" />,
@@ -116,6 +181,43 @@ describe('TransactionButton', () => {
     expect(showCallsStatus).toHaveBeenCalledWith({ id: '456' });
   });
 
+  it('should render custom success text when it exists', () => {
+    const showCallsStatus = vi.fn();
+    (useShowCallsStatus as Mock).mockReturnValue({ showCallsStatus });
+    (useTransactionContext as Mock).mockReturnValue({
+      lifecycleStatus: { statusName: 'init', statusData: null },
+      receipt: '123',
+      transactionId: '456',
+    });
+    render(
+      <TransactionButton text="Transact" successOverride={{ text: 'yay' }} />,
+    );
+    const button = screen.getByText('yay');
+    fireEvent.click(button);
+    expect(showCallsStatus).toHaveBeenCalledWith({ id: '456' });
+  });
+
+  it('should call custom success handler when it exists', () => {
+    const mockSuccessHandler = vi.fn();
+    (useTransactionContext as Mock).mockReturnValue({
+      lifecycleStatus: { statusName: 'init', statusData: null },
+      receipt: '123',
+      transactionId: '456',
+    });
+    render(
+      <TransactionButton
+        text="Transact"
+        successOverride={{
+          text: 'yay',
+          onClick: mockSuccessHandler,
+        }}
+      />,
+    );
+    const button = screen.getByText('yay');
+    fireEvent.click(button);
+    expect(mockSuccessHandler).toHaveBeenCalledWith('123');
+  });
+
   it('should enable button when not in progress, not missing props, and not waiting for receipt', () => {
     (useTransactionContext as Mock).mockReturnValue({
       isLoading: false,

src/transaction/components/TransactionButton.tsx

@@ -12,6 +12,8 @@ export function TransactionButton({
   className,
   disabled = false,
   text: buttonText = 'Transact',
+  errorOverride,
+  successOverride,
 }: TransactionButtonReact) {
   const {
     chainId,
@@ -50,41 +52,69 @@ export function TransactionButton({
     transactionId,
   });
 
+  const { errorText, successText } = useMemo(() => {
+    const successText = successOverride?.text
+      ? successOverride?.text
+      : 'View transaction';
+
+    const errorText = errorOverride?.text ? errorOverride?.text : 'Try again';
+
+    return { successText, errorText };
+  }, [errorOverride, successOverride]);
+
+  const successHandler = useCallback(() => {
+    if (successOverride?.onClick && receipt) {
+      return successOverride?.onClick?.(receipt);
+    }
+    // SW will have txn id so open in wallet
+    if (receipt && transactionId) {
+      return showCallsStatus({ id: transactionId });
+    }
+    // EOA will not have txn id so open in explorer
+    const chainExplorer = getChainExplorer(accountChainId);
+    return window.open(
+      `${chainExplorer}/tx/${transactionHash}`,
+      '_blank',
+      'noopener,noreferrer',
+    );
+  }, [
+    accountChainId,
+    successOverride,
+    showCallsStatus,
+    transactionId,
+    transactionHash,
+    receipt,
+  ]);
+
+  const errorHandler = useCallback(() => {
+    if (errorOverride?.onClick) {
+      return errorOverride?.onClick?.();
+    }
+    // if no custom logic, retry submit
+    return onSubmit();
+  }, [errorOverride, onSubmit]);
+
   const buttonContent = useMemo(() => {
     // txn successful
     if (receipt) {
-      return 'View transaction';
+      return successText;
     }
     if (errorMessage) {
-      return 'Try again';
+      return errorText;
     }
     return buttonText;
-  }, [buttonText, errorMessage, receipt]);
+  }, [errorText, buttonText, successText, errorMessage, receipt]);
 
   const handleSubmit = useCallback(() => {
-    // SW will have txn id so open in wallet
-    if (receipt && transactionId) {
-      showCallsStatus({ id: transactionId });
-      // EOA will not have txn id so open in explorer
-    } else if (receipt) {
-      const chainExplorer = getChainExplorer(accountChainId);
-      window.open(
-        `${chainExplorer}/tx/${transactionHash}`,
-        '_blank',
-        'noopener,noreferrer',
-      );
+    if (receipt) {
+      successHandler();
+    } else if (errorMessage) {
+      errorHandler();
+      // if no receipt or error, submit txn
     } else {
-      // if no receipt, submit txn
       onSubmit();
     }
-  }, [
-    accountChainId,
-    onSubmit,
-    receipt,
-    showCallsStatus,
-    transactionHash,
-    transactionId,
-  ]);
+  }, [errorMessage, errorHandler, onSubmit, receipt, successHandler]);
 
   return (
     <button

src/transaction/types.ts

@@ -15,6 +15,11 @@ import type {
 
 export type Call = { to: Hex; data?: Hex; value?: bigint };
 
+type TransactionButtonOverride = {
+  text?: string;
+  onClick?: (receipt?: TransactionReceipt) => void;
+};
+
 /**
  * List of transaction lifecycle statuses.
  * The order of the statuses loosely follows the transaction lifecycle.
@@ -71,6 +76,8 @@ export type TransactionButtonReact = {
   className?: string; // An optional CSS class name for styling the button component.
   disabled?: boolean; // A optional prop to disable the submit button
   text?: string; // An optional text to be displayed in the button component.
+  errorOverride?: TransactionButtonOverride; // Optional overrides for text and onClick handler in error state (default is resubmit txn)
+  successOverride?: TransactionButtonOverride; // Optional overrides for text and onClick handler in success state (default is view txn on block explorer)
 };
 
 export type TransactionContextType = {