Skip to content

docs(react): add reference page for useTransform #2087

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mixelburg wants to merge 1 commit into
base: main
Choose a base branch
from
+61 −0
Open

docs(react): add reference page for useTransform #2087

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions docs/framework/react/reference/functions/useTransform.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
---
id: useTransform
title: useTransform
---

# Function: useTransform()

```ts
function useTransform(
fn: (formBase: AnyFormApi) => AnyFormApi,
deps?: unknown[],
): (data: unknown) => unknown;
```

A hook used in SSR meta-framework adapters (TanStack Start, Next.js, Remix) to merge server-returned form state with the client-side form instance.

Pass the result directly to the `transform` option of `useForm`. Under the hood it is a stable `useCallback` wrapper, so it only recreates the transform function when `deps` change.

## Parameters

### fn

`(formBase: AnyFormApi) => AnyFormApi`

A function that receives the base form API and returns a transformed form API. Typically calls `mergeForm(baseForm, serverState)` to layer server validation errors or default values on top of the client form.
Comment on lines +21 to +25
Copy link

@coderabbitai coderabbitai bot Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Verify that mergeForm is exported from adapter packages

# Search for mergeForm exports in adapter packages
echo "=== Searching for mergeForm in react-form-start ==="
fd -t f -e ts -e tsx . packages/react-form-start --exec rg -n "export.*mergeForm"

echo -e "\n=== Searching for mergeForm in react-form-nextjs ==="
fd -t f -e ts -e tsx . packages/react-form-nextjs --exec rg -n "export.*mergeForm"

echo -e "\n=== Searching for mergeForm in react-form-remix ==="
fd -t f -e ts -e tsx . packages/react-form-remix --exec rg -n "export.*mergeForm"

echo -e "\n=== Searching for mergeForm definition ==="
rg -n "function mergeForm|const mergeForm|export.*mergeForm" --type ts

Repository: TanStack/form

Length of output: 387

Clarify the import source for mergeForm in the documentation.

The description references mergeForm(baseForm, serverState) but does not specify where to import it from. mergeForm is exported from @tanstack/form-core, not from the adapter packages. Update the documentation to clearly indicate the correct import source to prevent user confusion.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/framework/react/reference/functions/useTransform.md` around lines 21 -
25, The docs mention calling mergeForm(baseForm, serverState) but don't state
its import source; update the useTransform documentation to explicitly note that
mergeForm is exported from `@tanstack/form-core` (e.g., "import { mergeForm } from
'@tanstack/form-core'") and clarify that it is not provided by adapter packages,
referencing the function name mergeForm and the hook useTransform to help locate
the text to change.


### deps?

`unknown[]`

Dependency array for the callback, identical to `useCallback`'s second argument. Include any reactive values referenced inside `fn`.

## Returns

`(data: unknown) => unknown`

A stable transform function suitable for the `transform` option of `useForm`.

## Example

```ts
import { mergeForm, useForm, useTransform } from '@tanstack/react-form-start'

// serverState comes from a loader / action / server function
const form = useForm({
...formOpts,
transform: useTransform(
(baseForm) => mergeForm(baseForm, serverState),
[serverState],
),
})
```

## Notes

- This hook is exported from the meta-framework adapter packages (`@tanstack/react-form-start`, `@tanstack/react-form-nextjs`, `@tanstack/react-form-remix`), not from `@tanstack/react-form` itself.
- For a full SSR integration example see the [React Meta-Framework Usage guide](../guides/ssr.md).

## Defined in

[packages/react-form-nextjs/src/useTransform.ts](https://github.com/TanStack/form/blob/main/packages/react-form-nextjs/src/useTransform.ts)