inertiajs-use-api

A React hook for calling JSON API endpoints from Inertia.js apps. Like Inertia's useForm, but for plain JSON routes — with optional piping of responses back into Inertia page props.

const api = useApi<{ name: string }, User[]>({ name: "" });

// Pipe the response straight into page.props.users (client-side, no roundtrip):
await api.get("/api/users", { intoProp: "users" });

// Or trigger a partial reload from the server:
await api.post("/users", { reloadProps: ["users", "stats"] });

Features

• useForm-style ergonomics — data, errors, processing, cancel, and lifecycle callbacks for plain JSON routes
• Inertia prop integration — pipe responses into page.props client-side (intoProp) or trigger a partial reload (reloadProps)
• Pluggable error parsing — adapt any backend's validation envelope into a flat { field: message } map
• Pluggable toast hooks — wire your notification system once at boot
• XSRF out of the box — reads Laravel's XSRF-TOKEN cookie by default, fully overridable
• AbortSignal-aware — cancel a single call or all in-flight requests for the hook
• Zero runtime dependencies — native fetch under the hood, only react and @inertiajs/core as peers
• Strongly typed — generic over form shape and response shape

Table of Contents

• Requirements
• Installation
• Quick Start
• Inertia Prop Integration
  • intoProp — client-side write
  • reloadProps — server roundtrip
  • Choosing between them
• Configuration
• API Reference
• AI Coding Assistant Skill
• Contributing
• Security
• License

Requirements

• React 18 or 19
• @inertiajs/core 2 or 3

Installation

npm install inertiajs-use-api

Quick Start

import { useApi } from "inertiajs-use-api";

type Form = { name: string; email: string };
type User = { id: number; name: string; email: string };

function CreateUserForm() {
  const api = useApi<Form, User>({ name: "", email: "" });

  const submit = async (e: React.FormEvent) => {
    e.preventDefault();
    try {
      const user = await api.post("/api/users", {
        successToast: "User created",
        reloadProps: ["users"],
      });
      // user is the typed response body
    } catch {
      // ApiError thrown — api.errors is populated
    }
  };

  return (
    <form onSubmit={submit}>
      <input
        value={api.data.name}
        onChange={(e) => api.setData("name", e.target.value)}
      />
      {api.errors.name && <span>{api.errors.name}</span>}
      <button disabled={api.processing}>Create</button>
    </form>
  );
}

Why

Inertia's built-in router and useForm are great for navigating between Inertia pages, but they expect Inertia responses. For plain JSON API routes (/api/*), you typically drop down to fetch and lose the ergonomics — processing flag, field errors, abort, lifecycle callbacks, etc.

useApi gives you that ergonomics back, and lets you pipe responses into Inertia page props when you want them to live in usePage() alongside server-rendered data.

Inertia Prop Integration

intoProp — write the response into page.props client-side

Uses router.replaceProp under the hood (no server roundtrip). The data flows straight into usePage().props.

import { useApi } from "inertiajs-use-api";
import { usePage } from "@inertiajs/react";

function UserList() {
  const api = useApi<{}, User[]>({});

  useEffect(() => {
    api.get("/api/users", { intoProp: "users" });
  }, []);

  const { users } = usePage<{ users: User[] }>().props;
  return <ul>{users?.map((u) => <li key={u.id}>{u.name}</li>)}</ul>;
}

You can also map a single response into multiple props:

await api.get("/api/dashboard", {
  intoProp: (res) => ({ users: res.users, stats: res.stats }),
});

reloadProps — refresh props from the server

Uses router.reload({ only }). The server is the source of truth.

await api.post("/api/users", { reloadProps: ["users", "stats"] });

Pass extra options via reloadOptions (anything Inertia's ReloadOptions accepts, except only):

await api.post("/api/users", {
  reloadProps: "users",
  reloadOptions: { preserveScroll: true },
});

Choosing between them

Use intoProp when…	Use reloadProps when…
The API endpoint already returns the data you want in props.	The server computes the props (auth filters, scoping…).
You want to avoid an extra HTTP request.	You want server-side validation of what the user sees.
You're piping into client-only state.	You want Inertia's normal partial-reload semantics.

Configuration

Configure the library once at app boot — the hook reads from a global config so calls stay terse.

// app.tsx
import { configureUseApi } from "inertiajs-use-api";

configureUseApi({
  // Optional base URL for relative paths
  baseUrl: "/",

  // Parse your backend's error envelope into a flat { field: message } map
  parseErrors: (body) => {
    const errs = (body as { errors?: Record<string, string[] | string> }).errors ?? {};
    const flat: Record<string, string> = {};
    for (const [k, v] of Object.entries(errs)) {
      flat[k] = Array.isArray(v) ? v[0]! : String(v);
    }
    return flat;
  },

  // Extract a human-readable message (used as the default error toast text)
  parseMessage: (body) => (body as { message?: string }).message ?? null,

  // Wire your toast/notification system
  onSuccessToast: (toast) => fireToast({ type: "success", message: toast as string }),
  onErrorToast: (toast) => fireToast({ type: "error", message: toast as string }),

  // Optional: inspect every response body (e.g. to extract a server-side toast envelope)
  onResponse: (body, status, ok) => {
    const alerts = (body as { toastAlerts?: ToastMessage[] })?.toastAlerts;
    if (alerts?.length) fireToasts(alerts);
  },
});

Config reference

Option	Type	Default
baseUrl	string	undefined
defaultHeaders	Record<string, string>	undefined
getXsrfToken	() => string | null	reads XSRF-TOKEN cookie
xsrfHeaderName	string	"X-XSRF-TOKEN"
parseErrors	(body, status) => Record<string, string>	returns {}
parseMessage	(body, status) => string | null	returns null
onSuccessToast	(toast: unknown) => void	no-op
onErrorToast	(toast: unknown) => void	no-op
onResponse	(body, status, ok) => void	no-op

API Reference

useApi<TForm, TResponse>(initialData?)

Returns an object with:

Field	Type
data	TForm
setData	(field | partial, value?) => void
errors	Partial<Record<keyof TForm | string, string>>
hasErrors	boolean
processing	boolean
response	TResponse | null
wasSuccessful	boolean
status	number | null
reset	() => void
clearErrors	() => void
cancel	() => void — aborts all in-flight requests for this hook
submit	(method, url, options?) => Promise<TResponse>
get/post/put/patch/delete	(url, options?) => Promise<TResponse>

SubmitOptions

Option	Type	Notes
data	Partial<TForm>	Overrides the hook's data body
params	Record<string, string | number | boolean | null | undefined>	Query string. null/undefined values are skipped
headers	Record<string, string>	Merged on top of defaults
signal	AbortSignal	Aborting it (or calling cancel()) aborts the request
intoProp	string | (response) => Record<string, unknown>	Writes into page.props via router.replaceProp
reloadProps	string | string[]	After success, triggers router.reload({ only })
reloadOptions	Omit<ReloadOptions, "only">	Extra options forwarded to router.reload
successToast	unknown	Forwarded to onSuccessToast
errorToast	unknown | false	Forwarded to onErrorToast. false suppresses the toast for this call
onBefore	() => void
onSuccess	(response: TResponse) => void
onError	(errors, raw, status) => void
onFinish	() => void	Always called

ApiError

Thrown on non-2xx responses.

import { ApiError } from "inertiajs-use-api";

try {
  await api.post("/api/users");
} catch (e) {
  if (e instanceof ApiError) {
    console.log(e.status, e.message, e.body);
  }
}

Notes

• The hook uses native fetch and reads/writes Inertia state only when you ask it to (intoProp, reloadProps).
• @inertiajs/react is not a peer dep — only @inertiajs/core is. Use whichever Inertia adapter your app uses to read updated props.
• All in-flight requests for a given hook share processing and can be cancelled together via cancel().

AI Coding Assistant Skill

This package ships an Anthropic Skill at the package root so coding agents (Claude Code, Claude.ai) can use the library correctly without needing to grep through source.

The skill covers when to reach for useApi vs useForm, the intoProp vs reloadProps decision, the one-time configureUseApi wiring an app needs, and common Laravel/XSRF gotchas.

To install it for Claude Code:

mkdir -p ~/.claude/skills/inertiajs-use-api
cp node_modules/inertiajs-use-api/SKILL.md ~/.claude/skills/inertiajs-use-api/SKILL.md

Or symlink it so it stays in sync with package upgrades:

ln -s "$PWD/node_modules/inertiajs-use-api/SKILL.md" ~/.claude/skills/inertiajs-use-api/SKILL.md

Contributors hacking on the library itself should read AGENTS.md — picked up automatically by Cursor, Windsurf, Cline, and similar in-repo agents.

Contributing

Contributions are welcome! Please see the documents below before getting started.

• Contributing Guide — setup, workflow, commit conventions, and PR process
• Code of Conduct — expectations for participation in this project

Security

• Security Policy — how to report a vulnerability privately

License

The MIT License (MIT). Please see License File for more information.