`useNexusAction`

useNexusAction is a client-side hook that wraps a Server Action. It provides state management (isPending, result, error) and lifecycle callbacks, making it easier to handle server-side logic triggered from the client.

Import


import { useNexusAction } from 'next-nexus/client';

Core Concepts

When to Use

useNexusAction is ideal when you have logic that must run on the server (e.g., accessing a database directly, using server-only secrets) and you want to call it from a client component like a standard function. It’s a lighter-weight alternative to useNexusMutation when you don’t need to model the operation as a formal API endpoint with a definition.

State Management

The hook tracks the execution of the Server Action, providing isPending, result, and error states, which simplifies building responsive UIs.

Signature

Parameters

serverAction: (...args: TArgs) => Promise<TResult> — The Server Action function itself.
options?: An optional object to configure lifecycle callbacks.

Return Value

An object containing:

execute: (...args: TArgs) => void — A fire-and-forget function to trigger the action.
executeAsync: (...args: TArgs) => Promise<TResult> — A function that returns a promise, allowing you to await the action’s result.
isPending: boolean
result: TResult | undefined
error: Error | null
reset: () => void

Options

onStart?: (...args: TArgs) => void | Promise<void>
onSuccess?: (result: TResult, ...args: TArgs) => void | Promise<void>
onError?: (error: Error, ...args: TArgs) => void | Promise<void>
onSettled?: (result?: TResult, error?: Error, ...args: TArgs) => void | Promise<void>

Example

In this example, a Server Action is used to update a product name. The useNexusAction hook manages the pending state for the button.


'use client'
import { useNexusAction } from 'next-nexus/client'
import { revalidateServerTags } from 'next-nexus'
import { revalidateClientTags } from 'next-nexus/client'
 
// Assume this action is in a separate file, e.g., app/actions.ts
async function updateProductNameAction(id: string, name: string) {
  'use server'
  // ... database logic to update the product name
  await revalidateServerTags(['products', `product:${id}`]);
  return { success: true, newName: name };
}
 
export function UpdateProductName({ productId }: { productId: string }) {
  const { execute, isPending } = useNexusAction(updateProductNameAction, {
    onSuccess: (data) => {
      revalidateClientTags(['products', `product:${productId}`]);
      alert(`Product name updated to ${data.newName}`);
    }
  });
 
  return (
    <button onClick={() => execute(productId, 'New Name')} disabled={isPending}>
      {isPending ? 'Updating…' : 'Update Name'}
    </button>
  );
}

See also