# File upload
A file is just part of a point's input. Declare a schema field as a file
(`z.file()`, `z.instanceof(File)`, …), put a real `File` into the input on the
client, and the loader gets that `File` back on the server. Point0 assembles the
`multipart/form-data` request itself — there is no separate upload API.
```tsx
import { root } from '@/lib/root'
import * as z from 'zod'
export const ideaCreateMutation = root.lets
.mutation()
.input(
z.object({
title: z.string().min(1),
image: z.file().optional(), // a file field, just like any other input field
}),
)
.loader(async ({ input }) => {
// on the server, input.image is a real File (a Blob subclass)
const imageBase64 = input.image
? Buffer.from(await input.image.arrayBuffer()).toString('base64')
: undefined
const idea = await prisma.idea.create({
data: { title: input.title, image: imageBase64 },
})
return { idea }
})
.mutation()
```
On the client you fill that field from an `` and pass it like
any other value:
```tsx
const mutation = ideaCreateMutation.useMutation()
const [image, setImage] = useState(undefined)
// setImage(e.target.files?.[0] || undefined)} />
await mutation.mutateAsync({ title, image })
// the loader's input.image is a File with .name, .type, .size, .arrayBuffer() intact
```
(This is the canonical `examples/basic` flow — `src/lib/idea.ts` declares the
field, `src/pages/idea-create-update.tsx` wires the ``.)
## What counts as a file
A file field is any schema field that holds a `File` or a `Blob`. How you
declare it depends on your validation library:
```tsx
z.file() // zod
z.instanceof(File) // zod, also detected
v.file() // valibot
Type.String({ format: 'binary' }) // typebox
type({ file: 'File' }) // arktype
```
The schema only validates the value and feeds [OpenAPI](openapi) (see below). It
does **not** decide whether the request is multipart — that switch is made at
runtime, on the actual value.
## How the request is encoded
The body format is chosen by looking at the input value, not the schema. If the
input contains any `File` or `Blob` anywhere, the whole body is sent as
`multipart/form-data`; otherwise it's JSON.
```tsx
mutation.mutate({ title: 'x', image: someFile }) // → multipart/form-data
mutation.mutate({ title: 'x' }) // → application/json (no file present)
```
A few consequences worth knowing:
- **Detection is recursive.** A file nested deep in the input
(`{ profile: { avatar: File } }`, `{ files: [File, File] }`) still triggers
multipart — the detector walks arrays and plain objects.
- **Don't set `Content-Type` yourself.** On the multipart branch Point0 sets no
`Content-Type` header, so the runtime fills in
`multipart/form-data; boundary=…` automatically. Setting it by hand breaks the
boundary.
- **You never think about flattening — the framework does it.** Declare your
input with any nesting you like; on the multipart branch Point0 flattens it to
bracket-notation keys (`profile[avatar]`, `files[0]`) with
[`@1gr14/flat`](https://1gr14.dev/flat) before sending, and the server
unflattens it back into the original shape for the loader. The `File`/`Blob`
parts are appended raw; every other field is `JSON.stringify`'d into its form
part. Nothing about this is your concern — it folds and unfolds under the
hood.
- **The loader gets a genuine `File`.** Its `name`, `type`, `size`, and
`arrayBuffer()` all survive the round-trip — proven by
`packages/engine/tests/mutation.test.tsx` ("with file loader").
## Where the file lands on the server
The loader reads the file from the same place it reads the rest of the input —
which depends on the point type:
```tsx
// mutation: file is in input
.loader(async ({ input }) => { input.image /* the File */ })
// action: file is in body
.loader(async ({ body }) => { body.image /* the File */ })
```
Send files with a [mutation](mutation) (or an [action](action)), not a
[query](query). A query's input has to be serializable into a cache key, and a
`File` has no sensible serialization there — sending bytes to read data isn't
what a query is for. Uploading is a write, so it belongs on a mutation.
[Pages](page) and [layouts](layout) are `GET` and carry no body, so they never
take a file upload either.
## Mutations
The hero example above is a mutation — the common case. The file is part of
`.input`, you fill it on the client, the server loader consumes it. See
[Mutation](mutation) for the rest of the mutation surface.
## Actions
An [action](action) puts the file in `.body` instead of `.input`, and the loader
reads it from `body`:
```tsx
export const uploadAction = root.lets
.action('POST', '/api/upload')
.body(z.object({ file: z.file() }))
.loader(async ({ body }) => {
const bytes = await body.file.arrayBuffer()
return { size: bytes.byteLength }
})
.action()
```
An action can also take a ready-made `FormData` as its body directly, bypassing
the schema-driven assembly — useful when you already hold a `FormData` (e.g.
from a `