HTTP Requests

Available since:@inertiajs/core:3.0.0

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.

<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.

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 at the hook level or on a per-request basis.

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.

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.

<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.

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.

<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.

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.

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: (response) => {
    /*...*/
  },
  onError: (errors) => {
    /*...*/
  },
  onCancel: () => {
    /*...*/
  },
  onFinish: () => {
    /*...*/
  },
})

You may return false from onBefore to cancel the request.

Precognition

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

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.

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')