Unverified Commit 9480f67d authored by Jiwon Choi's avatar Jiwon Choi Committed by GitHub

Document catchError for the Pages Router (#97748)

Supersedes https://github.com/vercel/next.js/pull/91848

`catchError` works in both the App Router and Pages Router, but its API
reference only documented the App Router behavior. This adds a Pages
Router reference backed by the same canonical document and scopes the
content that differs between routers.

The Pages Router examples use `reset()` because `retry()` is App
Router-only, omit App Router-only navigation behavior, and use Pages
Router component paths. The existing App Router guidance and shared API
reference remain unchanged.

<!-- NEXT_JS_LLM -->
parent 6df5c456
......@@ -8,6 +8,8 @@ related:
- app/api-reference/file-conventions/error
---
<AppOnly>
The `catchError` function creates a component that wraps its children in an error boundary. It provides a programmatic alternative to the [`error.js`](/docs/app/api-reference/file-conventions/error) file convention, enabling component-level error recovery anywhere in your component tree.
Compared to a custom React error boundary, `catchError` is designed to work with Next.js out of the box:
......@@ -54,6 +56,51 @@ function ErrorFallback(props, { error, retry }) {
export default catchError(ErrorFallback)
```
</AppOnly>
<PagesOnly>
The `catchError` function creates a component that wraps its children in an error boundary. It provides a programmatic alternative to writing a [custom React error boundary class](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary), enabling component-level error recovery anywhere in your component tree.
Compared to a custom React error boundary, `catchError` is designed to work with Next.js out of the box:
- **Built-in error recovery** — `reset()` re-renders the error boundary's children, letting users recover from errors without a full page reload.
- **Client navigation handling** — The error state automatically clears when you do a client navigation to a different route.
```tsx filename="components/custom-error-boundary.tsx" switcher
import { catchError, type ErrorInfo } from 'next/error'
function ErrorFallback(props: { title: string }, { error, reset }: ErrorInfo) {
return (
<div>
<h2>{props.title}</h2>
<p>{error.message}</p>
<button onClick={() => reset()}>Try again</button>
</div>
)
}
export default catchError(ErrorFallback)
```
```jsx filename="components/custom-error-boundary.js" switcher
import { catchError } from 'next/error'
function ErrorFallback(props, { error, reset }) {
return (
<div>
<h2>{props.title}</h2>
<p>{error.message}</p>
<button onClick={() => reset()}>Try again</button>
</div>
)
}
export default catchError(ErrorFallback)
```
</PagesOnly>
## Reference
### Parameters
......@@ -71,6 +118,8 @@ A function that renders the error UI when an error is caught. It receives two ar
- `props` — The props passed to the wrapper component (excluding `children`).
- `errorInfo` — An object containing information about the error:
<AppOnly>
| Property | Type | Description |
| -------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `error` | [`Error`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error) | The error instance that was caught. |
......@@ -79,6 +128,17 @@ A function that renders the error UI when an error is caught. It receives two ar
The `fallback` function must be a Client Component (or defined in a `'use client'` module).
</AppOnly>
<PagesOnly>
| Property | Type | Description |
| -------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `error` | [`Error`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error) | The error instance that was caught. |
| `reset` | `() => void` | Resets the error state and re-renders the error boundary's children. |
</PagesOnly>
### Returns
`catchError` returns a React component that:
......@@ -89,10 +149,12 @@ The `fallback` function must be a Client Component (or defined in a `'use client
## Examples
### Client Component
### Basic usage
Define a fallback and use the returned component to wrap parts of your UI:
<AppOnly>
```tsx filename="app/some-component.tsx" switcher
import ErrorWrapper from '../custom-error-boundary'
......@@ -109,8 +171,32 @@ export default function Component({ children }) {
}
```
</AppOnly>
<PagesOnly>
```tsx filename="components/some-component.tsx" switcher
import ErrorWrapper from './custom-error-boundary'
export default function Component({ children }: { children: React.ReactNode }) {
return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}
```
```jsx filename="components/some-component.js" switcher
import ErrorWrapper from './custom-error-boundary'
export default function Component({ children }) {
return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}
```
</PagesOnly>
### Recovering from errors
<AppOnly>
Use `retry()` to prompt the user to recover from the error. When called, the function re-fetches and re-renders the error boundary's children. If successful, the fallback is replaced with the re-rendered result.
In most cases, use `retry()` instead of `reset()`. The `reset()` function only clears the error state and re-renders without re-fetching, which means it won't recover from Server Component errors.
......@@ -151,6 +237,46 @@ function ErrorFallback(props, { error, retry, reset }) {
export default catchError(ErrorFallback)
```
</AppOnly>
<PagesOnly>
Use `reset()` to prompt the user to recover from the error. When called, the function clears the error state and re-renders the error boundary's children.
```tsx filename="components/custom-error-boundary.tsx" switcher
import { catchError, type ErrorInfo } from 'next/error'
function ErrorFallback(props: {}, { error, reset }: ErrorInfo) {
return (
<div>
<p>{error.message}</p>
<button onClick={() => reset()}>Try again</button>
</div>
)
}
export default catchError(ErrorFallback)
```
```jsx filename="components/custom-error-boundary.js" switcher
import { catchError } from 'next/error'
function ErrorFallback(props, { error, reset }) {
return (
<div>
<p>{error.message}</p>
<button onClick={() => reset()}>Try again</button>
</div>
)
}
export default catchError(ErrorFallback)
```
</PagesOnly>
<AppOnly>
### Server-rendered error fallback
You can pass server-rendered content as a prop to display data-driven fallback UI. This works by rendering a Server Component as a `React.ReactNode` prop that the fallback displays when an error is caught.
......@@ -216,6 +342,14 @@ export default function Component({ children }) {
> - Props passed to the wrapper component are forwarded to the fallback function, making it easy to create reusable error UIs with different configurations.
> - You don't need to wrap `error.js` default exports with `catchError`. The [`error.js`](/docs/app/api-reference/file-conventions/error) file convention already renders inside a built-in error boundary provided by Next.js.
</AppOnly>
<PagesOnly>
> **Good to know**: Props passed to the wrapper component are forwarded to the fallback function, making it easy to create reusable error UIs with different configurations.
</PagesOnly>
## Version History
| Version | Changes |
......
---
title: catchError
description: API Reference for the catchError function.
source: app/api-reference/functions/catchError
---
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment