Introduction to Mutations in TanStack Query
TanStack Query (formerly React Query) revolutionized how developers handle server state in React applications. While the library's useQuery hook handles data fetching with elegant simplicity, the useMutation hook provides a powerful abstraction for server-side modifications--creating, updating, or deleting data on your API endpoints.
Unlike queries, which are identified by unique keys and can be cached and reused across components, mutations are typically one-off operations triggered by user actions like form submissions, button clicks, or API calls that modify server state. The useMutation hook gives you fine-grained control over the mutation lifecycle, including loading states, error handling, and automatic cache updates.
For teams building custom web applications, mastering mutations is essential for creating responsive user experiences where server interactions feel instantaneous.
When to Use useMutation
The useMutation hook is the appropriate choice when your application needs to send data to the server that will create, modify, or remove resources:
- Form submissions for user registration or profile updates
- Creating or editing advertising campaigns
- Updating bid strategies or budget allocations
- Deleting records or cancelling actions
- Any operation that triggers a POST, PUT, PATCH, or DELETE HTTP request
Fundamentals of the useMutation Hook
The useMutation hook returns a mutation object containing state variables and methods to execute and control the mutation process.
Basic Syntax and Return Values
Primary return values from useMutation:
- mutate - Triggers the mutation synchronously
- mutateAsync - Returns a promise for sequential operations
- isPending - Boolean indicating the mutation is executing
- isError - Boolean signaling the mutation failed
- isSuccess - Boolean indicating successful completion
- data - Contains the response from the server
- error - Contains the error object on failure
The Mutation Function
The mutation function is the async function responsible for communicating with your API. It receives any variables passed during execution and should return the expected response data.
const createCampaign = useMutation({
mutationFn: (newCampaign) =>
fetch('/api/campaigns', {
method: 'POST',
body: JSON.stringify(newCampaign),
headers: { 'Content-Type': 'application/json' }
}).then(res => res.json()),
onSuccess: (data) => {
// Handle successful campaign creation
}
});
// Trigger the mutation
createCampaign.mutate({ name: 'New Campaign', budget: 1000 });
The mutation function should handle both success and error scenarios internally or rely on the callback parameters for lifecycle management. Throwing an error from the mutation function will trigger the onError callback and set isError to true.
The onSuccess Callback Pattern
The onSuccess callback is one of the most powerful features of TanStack Query's mutation system. This function executes after a successful mutation, providing an ideal opportunity for cache invalidation, state updates, and side effects.
Why onSuccess Matters for Cache Synchronization
When you modify server data through a mutation, the cached data managed by TanStack Query becomes stale. The onSuccess callback provides the perfect hook point to invalidate relevant queries:
const createCampaign = useMutation({
mutationFn: createCampaignAPI,
onSuccess: (newCampaign) => {
// Invalidate the campaigns list to refetch with new data
queryClient.invalidateQueries({ queryKey: ['campaigns'] });
// Show success notification
toast.success('Campaign created successfully');
// Reset form or redirect
form.resetFields();
}
});
Implementing Cache Invalidation
The invalidation pattern uses query keys to identify which cached data to refresh. You can invalidate specific queries by exact key match or use wildcards to invalidate entire categories of queries.
Advanced invalidation patterns include:
- Invalidating multiple query keys simultaneously
- Conditionally invalidating based on mutation variables
- Using the invalidateQueries return value to await the refetch completion
For complex workflows involving multiple related data updates, consider how AI-powered automation solutions can help coordinate these operations at scale.
Error Handling with onError and onSettled
Robust applications must handle mutation failures gracefully. TanStack Query provides dedicated callbacks for error scenarios and guaranteed cleanup operations.
The onError Callback
The onError callback executes when the mutation function throws an error or returns a rejected promise:
const updateCampaign = useMutation({
mutationFn: updateCampaignAPI,
onError: (error, variables, context) => {
// Display user-friendly error message
toast.error(error.message || 'Failed to update campaign');
// Rollback optimistic updates if needed
if (context?.previousCampaign) {
queryClient.setQueryData(
['campaign', variables.id],
context.previousCampaign
);
}
}
});
The onSettled Callback
The onSettled callback runs after the mutation completes, regardless of success or failure:
const saveCampaign = useMutation({
mutationFn: saveCampaignAPI,
onSettled: (data, error, variables, context) => {
// Always re-enable the submit button
setIsSubmitting(false);
// Close loading indicators
hideLoadingOverlay();
}
});
Combining Callbacks for Comprehensive Handling
A well-structured mutation typically uses all three callbacks--onSuccess, onError, and onSettled--for clear separation of concerns. The onSuccess handler handles cache invalidation and success-specific logic. The onError handler manages failure scenarios with appropriate feedback. The onSettled handler ensures cleanup occurs regardless of outcome.
Best Practices for Mutation Implementation
Managing Loading States Effectively
- Disable form submissions during isPending to prevent duplicate submissions
- Show inline loading indicators for the affected UI elements
- Preserve the submit button label during loading to maintain context
Optimistic Updates for Improved UX
Optimistic updates enhance user experience by immediately reflecting expected changes in the UI before receiving server confirmation:
const updateCampaign = useMutation({
mutationFn: updateCampaignAPI,
onMutate: async (newData) => {
// Cancel outgoing refetches
await queryClient.cancelQueries({ queryKey: ['campaign', newData.id] });
// Snapshot previous value
const previousCampaign = queryClient.getQueryData(['campaign', newData.id]);
// Optimistically update
queryClient.setQueryData(['campaign', newData.id], newData);
return { previousCampaign };
},
onError: (err, newData, context) => {
// Rollback on error
queryClient.setQueryData(['campaign', newData.id], context.previousCampaign);
}
});
Proper Cache Invalidation Strategies
Cache invalidation requires balance between data freshness and unnecessary network requests. Consider the relationships between your data entities when designing invalidation strategies. For complex applications, establish clear naming conventions for query keys that reflect their scope and content.
When building custom web applications with TanStack Query, these patterns form the foundation for creating reliable, responsive user interfaces.
Practical Examples and Code Patterns
Basic Post Request Pattern
const createCampaign = useMutation({
mutationFn: (campaignData) =>
fetch('/api/campaigns', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(campaignData)
}).then(res => res.json()),
onSuccess: (newCampaign) => {
queryClient.invalidateQueries({ queryKey: ['campaigns'] });
navigate(`/campaigns/${newCampaign.id}`);
}
});
// Usage in component
<button
onClick={() => createCampaign.mutate({ name: 'Test', budget: 500 })}
disabled={createCampaign.isPending}
>
{createCampaign.isPending ? 'Creating...' : 'Create Campaign'}
</button>
Update Operations with Cache Management
const updateCampaign = useMutation({
mutationFn: ({ id, ...updates }) =>
fetch(`/api/campaigns/${id}`, {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(updates)
}).then(res => res.json()),
onSuccess: (data, variables) => {
// Invalidate list and update detail cache
queryClient.invalidateQueries({ queryKey: ['campaigns'] });
queryClient.setQueryData(['campaign', variables.id], data);
}
});
Delete Operations and List Management
const deleteCampaign = useMutation({
mutationFn: (id) =>
fetch(`/api/campaigns/${id}`, { method: 'DELETE' }),
onSuccess: (data, id) => {
// Remove from list cache
queryClient.setQueryData(['campaigns'], (old) =>
old?.filter(campaign => campaign.id !== id)
);
queryClient.invalidateQueries({ queryKey: ['campaigns'] });
toast.success('Campaign deleted');
}
});
Advanced Patterns and Considerations
Using mutateAsync for Sequential Operations
The mutateAsync function returns a promise, enabling sequential mutation workflows:
const createCampaign = useMutation({
mutationFn: createCampaignAPI
});
const attachAssets = useMutation({
mutationFn: attachAssetsAPI
});
// Sequential operations
async function setupCampaign(campaignData, assets) {
try {
const campaign = await createCampaign.mutateAsync(campaignData);
await attachAssets.mutateAsync({ campaignId: campaign.id, assets });
navigate(`/campaigns/${campaign.id}`);
} catch (error) {
toast.error('Campaign setup failed');
}
}
Mutation Retry and Configuration
TanStack Query allows configuration of retry behavior for mutations. For non-idempotent operations, consider setting retry to a low value or zero.
Testing Mutation Components
Effective tests verify that mutations call the correct API endpoint, handle errors appropriately, and execute callbacks with correct parameters. Testing libraries can trigger the mutation and verify both the API call and the callback execution.
Conclusion
TanStack Query's useMutation hook provides a robust foundation for server-side data mutations in React applications. Understanding the onSuccess, onError, and onSettled callbacks enables sophisticated post-mutation workflows, while proper cache invalidation strategies ensure your UI reflects current server state.
The patterns covered here--basic mutation execution, callback-based side effects, optimistic updates, and cache management--form the foundation for building reliable data-driven applications. Whether you're managing advertising campaigns, handling user submissions, or building any application that modifies server state, these concepts translate directly to better user experiences and more maintainable code.
For teams looking to implement these patterns in production applications, our web development services can help you build robust React applications with proper state management. Additionally, our AI automation solutions can extend these patterns to coordinate complex workflows across multiple systems.
Sources
- TanStack Query Mutations Guide - The authoritative source for useMutation hook, onSuccess patterns, and error handling
- DEV Community: TanStack React Query Crash Course - Comprehensive tutorial covering mutations, optimistic updates, and practical examples