HTTP Requests

Not every request needs to trigger an Inertia page visit. For calls to an external API or fetching data from a non-Inertia endpoint, the useHttp hook provides the same developer experience as useForm, but for standalone HTTP requests.

Basic Usage

The useHttp hook accepts initial data and returns reactive state along with methods for making HTTP requests.

VueReactSvelte

<script setup>
import { useHttp } from '@inertiajs/vue3'

const http = useHttp({
    query: '',
})

function search() {
    http.get('/api/search', {
        onSuccess: (response) => {
            console.log(response)
        },
    })
}
</script>

<template>
    <input v-model="http.query" @input="search" />
    <div v-if="http.processing">Searching...</div>
</template>

Unlike router visits, useHttp requests do not trigger page navigation or interact with Inertia’s page lifecycle. They are plain HTTP requests that return JSON responses.

Submitting Data

The hook provides get, post, put, patch, and delete convenience methods. A generic submit method is also available for dynamic HTTP methods.

VueReactSvelte

http.get(url, options)
http.post(url, options)
http.put(url, options)
http.patch(url, options)
http.delete(url, options)
http.submit(method, url, options)

Each method returns a Promise that resolves with the parsed JSON response data. TypeScript users may type the request data and response.

VueReactSvelte

const response = await http.post('/api/comments', {
    onError: (errors) => {
        console.log(errors)
    },
})

Multiple Requests

Each useHttp instance tracks its own processing, errors, and other reactive state. When making independent requests, you may create a separate instance for each one so their states don’t collide.

VueReactSvelte

const search = useHttp({ query: '' })
const upload = useHttp({ file: null })

Reactive State

The useHttp hook exposes the same reactive properties as useForm:

Property	Type	Description
errors	object	Validation errors keyed by field name
hasErrors	boolean	Whether validation errors exist
processing	boolean	Whether a request is in progress
progress	object | null	Upload progress with percentage and total
wasSuccessful	boolean	Whether the last request was successful
recentlySuccessful	boolean	true for two seconds after a successful request
isDirty	boolean	Whether the data differs from its defaults

Validation Errors

When a request returns a 422 status code, the hook automatically parses validation errors and makes them available through the errors property.

VueReactSvelte

<script setup>
import { useHttp } from '@inertiajs/vue3'

const http = useHttp({
    name: '',
    email: '',
})

function save() {
    http.post('/api/users')
}
</script>

<template>
    <input v-model="http.name" />
    <div v-if="http.errors.name">{{ http.errors.name }}</div>

    <input v-model="http.email" />
    <div v-if="http.errors.email">{{ http.errors.email }}</div>

    <button @click="save" :disabled="http.processing">Save</button>
</template>

Displaying All Errors

By default, validation errors are simplified to the first error message for each field. You may chain withAllErrors() to receive all error messages as arrays, which is useful for fields with multiple validation rules.

VueReactSvelte

const http = useHttp({
    name: '',
    email: '',
}).withAllErrors()

// http.errors.name === ['Name is required.', 'Name must be at least 3 characters.']

The same method is available on the useForm helper and the <Form> component.

File Uploads

When the data includes files, the hook automatically sends the request as multipart/form-data. Upload progress is available through the progress property.

VueReactSvelte

<script setup>
import { useHttp } from '@inertiajs/vue3'

const http = useHttp({
    file: null,
})

function upload() {
    http.post('/api/uploads')
}
</script>

<template>
    <input type="file" @change="http.file = $event.target.files[0]" />
    <progress v-if="http.progress" :value="http.progress.percentage" max="100" />
    <button @click="upload" :disabled="http.processing">Upload</button>
</template>

Cancelling Requests

You may cancel an in-progress request using the cancel() method.

VueReactSvelte

http.cancel()

Optimistic Updates

The useHttp hook supports optimistic updates via the optimistic() method. The callback receives the current data and should return a partial update to apply immediately.

VueReactSvelte

http.optimistic((data) => ({
    likes: data.likes + 1,
})).post('/api/likes')

The update is applied synchronously. If the request fails, the data is rolled back to its previous state.

Event Callbacks

Each submit method accepts an options object with lifecycle callbacks:

http.post('/api/users', {
    onBefore: () => { ... },
    onStart: () => { ... },
    onProgress: (progress) => { ... },
    onSuccess: (data, response) => { ... },
    onError: (errors) => { ... },
    onHttpException: (response) => { ... },
    onNetworkError: (error) => { ... },
    onCancel: () => { ... },
    onFinish: () => { ... },
})

You may return false from onBefore to cancel the request.

Accessing the HTTP response

The onSuccess callback receives the parsed response data as its first argument and the HTTP response object as its second argument. The response object contains status, data, and headers properties, which is useful when you need to inspect the status code or response headers.

http.post('/api/users', {
    onSuccess: (data, response) => {
        console.log(response.status) // 200, 201, etc.
    },
})

HTTP exceptions

The onHttpException callback fires when the server returns a non-422 HTTP error, such as a 500 or 403. The callback receives the HTTP response object, giving you access to the status code, response body, and headers.

http.post('/api/users', {
    onHttpException: (response) => {
        console.log(response.status) // 500, 403, etc.
        console.log(response.data)   // Response body
    },
})

Network errors

The onNetworkError callback fires when the request fails due to a network issue, such as when the user loses their internet connection. The callback receives the Error object.

http.post('/api/users', {
    onNetworkError: (error) => {
        console.log(error.message)
    },
})

Precognition

The useHttp hook supports Laravel Precognition for real-time validation. Enable it by chaining withPrecognition() with the HTTP method and validation endpoint.

VueReactSvelte

import { useHttp } from '@inertiajs/vue3'

const http = useHttp({
    name: '',
    email: '',
}).withPrecognition('post', '/api/users')

Once enabled, the validate(), touch(), touched(), valid(), and invalid() methods become available, working identically to form precognition.

History State

You may persist data and errors in browser history state by providing a remember key as the first argument.

VueReactSvelte

const http = useHttp('SearchData', {
    query: '',
})

You may exclude sensitive fields from being stored in history state using the dontRemember() method.

const http = useHttp('Login', {
    email: '',
    token: '',
}).dontRemember('token')