Callbacks Overview
Every generated composable supports four local lifecycle callbacks.
Execution flow
text
onRequest -> request -> onSuccess or onError -> onFinishThe wrappers call them in this order:
onRequestbefore the request is sentonSuccesswhen the request resolves successfullyonErrorwhen the request failsonFinishafter success or error
Quick example
ts
useFetchGetPetById(
{
path: { petId: 123 },
},
{
onRequest: ({ url }) => {
console.log('Fetching from:', url)
},
onSuccess: (pet) => {
console.log('Loaded:', pet.name)
},
onError: (error) => {
console.error('Failed:', error.message)
},
onFinish: ({ success }) => {
console.log('Request complete:', success)
},
}
)What each callback is for
onRequest
Runs before the request and can return request modifications.
Use it for:
- Adding headers
- Adjusting body or query values
- Request logging
- Starting loading or tracing state
onSuccess
Runs after a successful request.
Use it for:
- Success toasts
- Navigation
- Updating stores
- Analytics
onError
Runs when the request throws or returns an error response.
Use it for:
- Error toasts
- Redirecting on
401 - Logging
- Retry orchestration
onFinish
Runs after success or error and receives { data, error, success }.
Use it for:
- Cleanup
- Hiding loading UI
- Completion metrics
- Shared success or error finalization
Additive behavior
Local callbacks do not replace Nuxt's normal composable state. For example, onError can run and the composable error ref is still updated.
Global callbacks are a separate layer and run before local ones unless disabled or suppressed.
Guarantees
onRequestcan returnheaders,body, orquerymodificationsonSuccessreceives transformed data afterpickandtransformonErrorreceives the thrown error object from the underlying requestonFinishreceives{ data, error, success }