From 93718e3f54ab356cf513bbfb537d5a2d1f7c414b Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Mon, 25 May 2026 11:04:08 +0200 Subject: [PATCH 1/2] Clarify event handler error docs --- README.md | 22 ++++----- lib/components/ErrorBoundary.tsx | 2 +- public/generated/docs/ErrorBoundary.json | 2 +- .../examples/AsyncUserCodeErrors.json | 2 +- public/generated/search-index.json | 16 +++---- public/generated/search-records.json | 10 ++-- public/generated/site-map.json | 10 ++-- src/App.tsx | 4 +- src/routes/AsyncUserCodeErrorsRoute.tsx | 10 ++-- src/routes/examples/AsyncUserCodeErrors.tsx | 46 +++++++++++++++---- 10 files changed, 76 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index b4ab449..3a06140 100644 --- a/README.md +++ b/README.md @@ -69,9 +69,9 @@ Error boundaries do not catch errors thrown during: - Errors thrown in the error boundary itself - Async code that runs after rendering, like `setTimeout` callbacks or unresolved promises -## Async errors +## Event handler and async errors -For async errors: +For event handler errors and async callback errors: - Use `useErrorBoundary` to pass caught errors to the nearest boundary. - In React 19, `useTransition` Actions can be an alternative: errors thrown from a function passed to the returned `startTransition` function are caught by the nearest boundary. @@ -82,26 +82,26 @@ For async errors: import { useTransition } from "react"; import { ErrorBoundary } from "react-error-boundary"; -function UserProfileContainer({ username }: { username: string }) { +function AddCommentContainer() { return ( - Could not load profile

}> - + Could not add comment

}> + ); } -function UserProfile({ username }: { username: string }) { +function AddCommentButton() { const [isPending, startTransition] = useTransition(); - function loadProfile() { + function handleClick() { startTransition(async () => { - await fetchUserProfile(username); + await addComment(); }); } return ( - ); } @@ -123,7 +123,7 @@ Does not catch errors thrown during: - Errors thrown in the error boundary itself - Async code that runs after rendering, like `setTimeout` callbacks or unresolved promises -Async errors: +Event handler and async errors: - Use `useErrorBoundary` to pass caught errors to the nearest boundary - In React 19, errors thrown from a function passed to the `startTransition` function returned by `useTransition` diff --git a/lib/components/ErrorBoundary.tsx b/lib/components/ErrorBoundary.tsx index bf0d7d0..fc35eed 100644 --- a/lib/components/ErrorBoundary.tsx +++ b/lib/components/ErrorBoundary.tsx @@ -31,7 +31,7 @@ const initialState: ErrorBoundaryState = { * - Errors thrown in the error boundary itself * - Async code that runs after rendering, like `setTimeout` callbacks or unresolved promises * - * Async errors: + * Event handler and async errors: * * - Use `useErrorBoundary` to pass caught errors to the nearest boundary * - In React 19, errors thrown from a function passed to the `startTransition` function returned by `useTransition` diff --git a/public/generated/docs/ErrorBoundary.json b/public/generated/docs/ErrorBoundary.json index 03e4164..8d2cdb7 100644 --- a/public/generated/docs/ErrorBoundary.json +++ b/public/generated/docs/ErrorBoundary.json @@ -10,7 +10,7 @@ "content": "

Does not catch errors thrown during:

\n
    \n
  • Server side rendering
    • \n
  • Event handlers
    • \n
  • Errors thrown in the error boundary itself
    • \n
  • Async code that runs after rendering, like setTimeout callbacks or unresolved promises
    • \n
\n" }, { - "content": "

Async errors:

\n" + "content": "

Event handler and async errors:

\n" }, { "content": "
    \n
  • Use useErrorBoundary to pass caught errors to the nearest boundary
    • \n
  • In React 19, errors thrown from a function passed to the startTransition function returned by useTransition\nare caught by the nearest boundary
    • \n
\n" diff --git a/public/generated/examples/AsyncUserCodeErrors.json b/public/generated/examples/AsyncUserCodeErrors.json index 94bdb03..813926a 100644 --- a/public/generated/examples/AsyncUserCodeErrors.json +++ b/public/generated/examples/AsyncUserCodeErrors.json @@ -1,3 +1,3 @@ { - "html": "
import { useErrorBoundary } from \"react-error-boundary\";
\n
 
\n
function UserProfile({ username }: { username: string }) {
\n
const { showBoundary } = useErrorBoundary();
\n
 
\n
async function loadProfile() {
\n
try {
\n
await fetchUserProfile(username);
\n
} catch (error) {
\n
showBoundary(error);
\n
}
\n
}
\n
 
\n
return <button onClick={loadProfile}>Load profile</button>;
\n
}
" + "html": "
import { useEffect } from \"react\";
\n
import { ErrorBoundary, useErrorBoundary } from \"react-error-boundary\";
\n
 
\n
function UserProfileContainer({ username }: { username: string }) {
\n
return (
\n
<ErrorBoundary
\n
fallback={<p>Could not load profile</p>}
\n
resetKeys={[username]}
\n
>
\n
<UserProfile username={username} />
\n
</ErrorBoundary>
\n
);
\n
}
\n
 
\n
function UserProfile({ username }: { username: string }) {
\n
const { showBoundary } = useErrorBoundary();
\n
 
\n
useEffect(() => {
\n
let cancelled = false;
\n
 
\n
fetchUserProfile(username).then(
\n
(response) => {
\n
if (!cancelled) {
\n
// Set data in state and re-render
\n
}
\n
},
\n
(error) => {
\n
if (!cancelled) {
\n
showBoundary(error);
\n
}
\n
},
\n
);
\n
 
\n
return () => {
\n
cancelled = true;
\n
};
\n
}, [showBoundary, username]);
\n
 
\n
return null;
\n
}
" } \ No newline at end of file diff --git a/public/generated/search-index.json b/public/generated/search-index.json index 0a6d63d..c37b9b3 100644 --- a/public/generated/search-index.json +++ b/public/generated/search-index.json @@ -37,8 +37,8 @@ "n": 0.5 }, "2": { - "v": " Getting started with react-error-boundary React components and utils for managing runtime errors. Supports all React renderers (including React DOM and React Native). This package is built on top of React error boundaries, so it follows React's rules for what errors are caught. Error boundaries catch errors thrown while rendering the tree below them. This means that it can't catch errors during: Server side rendering Event handlers Errors thrown in the error boundary itself Async code that runs after rendering, like setTimeout callbacks or unresolved promises For async errors: Use useErrorBoundary to pass caught errors to the nearest boundary. Learn more. In React 19, errors thrown from a function passed to the startTransition function returned by useTransition are caught by the nearest boundary. Learn more. Installation Begin by installing the library from NPM: npm install react-error-boundary TypeScript definitions are included within the published dist folder. Support Here are some ways to support this project: Become a GitHub sponsor Buy me a coffee ", - "n": 0.079 + "v": " Getting started with react-error-boundary React components and utils for managing runtime errors. Supports all React renderers (including React DOM and React Native). This package is built on top of React error boundaries, so it follows React's rules for what errors are caught. Error boundaries catch errors thrown while rendering the tree below them. This means that it can't catch errors during: Server side rendering Event handlers Errors thrown in the error boundary itself Async code that runs after rendering, like setTimeout callbacks or unresolved promises For event handler errors and async callback errors: Use useErrorBoundary to pass caught errors to the nearest boundary. Learn more. In React 19, errors thrown from a function passed to the startTransition function returned by useTransition are caught by the nearest boundary. Learn more. Installation Begin by installing the library from NPM: npm install react-error-boundary TypeScript definitions are included within the published dist folder. Support Here are some ways to support this project: Become a GitHub sponsor Buy me a coffee ", + "n": 0.078 } } }, @@ -114,16 +114,16 @@ "i": 5, "$": { "0": { - "v": "Async user code errors", - "n": 0.5 + "v": "Event handler and async errors", + "n": 0.447 }, "1": { "v": "Examples", "n": 1 }, "2": { - "v": " Examples Async user code errors React handles errors thrown while rendering the tree below an error boundary. Errors thrown in event handlers, or after async code has run, will not be caught by an error boundary automatically. For async work outside of Actions, catch the error yourself and pass it to the nearest boundary with useErrorBoundary: In React 19, useTransition Actions can be an alternative: errors thrown from a function passed to the returned startTransition function are caught by the nearest boundary. Learn more. import { useErrorBoundary } from \"react-error-boundary\" ; \n \n function UserProfile ( { username } : { username : string } ) { \n const { showBoundary } = useErrorBoundary ( ) ; \n \n async function loadProfile ( ) { \n try { \n await fetchUserProfile ( username ) ; \n } catch ( error ) { \n showBoundary ( error ) ; \n } \n } \n \n return < button onClick = { loadProfile } > Load profile ; \n } ", - "n": 0.076 + "v": " Examples Event handler and async errors React handles errors thrown while rendering the tree below an error boundary. Errors thrown in event handlers, or after async code has run, will not be caught by an error boundary automatically. For async callback errors, like errors thrown after an Effect starts loading data, catch the error yourself and pass it to the nearest boundary with useErrorBoundary. You can use the same pattern for event handler errors: In React 19, useTransition Actions can be an alternative: errors thrown from a function passed to the returned startTransition function are caught by the nearest boundary. Learn more. import { useEffect } from \"react\" ; \n import { ErrorBoundary , useErrorBoundary } from \"react-error-boundary\" ; \n \n function UserProfileContainer ( { username } : { username : string } ) { \n return ( \n < ErrorBoundary \n fallback = { < p > Could not load profile } \n resetKeys = { [ username ] } \n > \n < UserProfile username = { username } /> \n \n ) ; \n } \n \n function UserProfile ( { username } : { username : string } ) { \n const { showBoundary } = useErrorBoundary ( ) ; \n \n useEffect ( ( ) => { \n let cancelled = false ; \n \n fetchUserProfile ( username ) . then ( \n ( response ) => { \n if ( ! cancelled ) { \n // Set data in state and re-render \n } \n } , \n ( error ) => { \n if ( ! cancelled ) { \n showBoundary ( error ) ; \n } \n } , \n ) ; \n \n return ( ) => { \n cancelled = true ; \n } ; \n } , [ showBoundary , username ] ) ; \n \n return null ; \n } ", + "n": 0.056 } } }, @@ -173,7 +173,7 @@ "n": 1 }, "2": { - "v": " API ErrorBoundary component props A reusable React error boundary component.\nWrap this component around other React components to \"catch\" errors and render a fallback UI.\n Catches errors thrown while rendering the tree below it.\n Does not catch errors thrown during:\n\nServer side rendering\nEvent handlers\nErrors thrown in the error boundary itself\nAsync code that runs after rendering, like setTimeout callbacks or unresolved promises\n\n Async errors:\n \nUse useErrorBoundary to pass caught errors to the nearest boundary\nIn React 19, errors thrown from a function passed to the startTransition function returned by useTransition\nare caught by the nearest boundary\n\n The component provides several ways to render a fallback: fallback, fallbackRender, and FallbackComponent.\nRefer to the documentation to determine which is best for your application.\n This is a client component. You can only pass props to it that are serializable or use it in files that have a \"use client\"; directive.\n Optional props fallback ? : ReactNode Static content to render in place of an error if one is thrown.\n < ErrorBoundary fallback = { < div className = \"text-red\" > Something went wrong } /> FallbackComponent ? : ComponentType < FallbackProps > React component responsible for returning a fallback UI based on a thrown value.\n < ErrorBoundary FallbackComponent = { Fallback } /> fallbackRender ? : ( props : FallbackProps ) => ReactNode Render prop function responsible for returning a fallback UI based on a thrown value.\n < ErrorBoundary fallbackRender = { ( { error , resetErrorBoundary } ) => < div > ... } /> onError ? : ( error : unknown , info : ErrorInfo ) => void Optional callback to enable e.g. logging error information to a server.\n\n error Value that was thrown; typically an instance of Error \n info React \"component stack\" identifying where the error was thrown\n\n onReset ? : ( details : { reason : \"imperative-api\" ; args : unknown [ ] ; } | { reason : \"keys\" ; prev : unknown [ ] ; next : unknown [ ] ; } ) => void Optional callback to be notified when an error boundary is reset so React can retry the failed render.\n resetKeys ? : unknown [ ] When changed, these keys will reset a triggered error boundary.\nThis can be useful when an error condition may be tied to some specific state (that can be uniquely identified by key).\nSee the documentation for examples of how to use this prop.\n ", + "v": " API ErrorBoundary component props A reusable React error boundary component.\nWrap this component around other React components to \"catch\" errors and render a fallback UI.\n Catches errors thrown while rendering the tree below it.\n Does not catch errors thrown during:\n\nServer side rendering\nEvent handlers\nErrors thrown in the error boundary itself\nAsync code that runs after rendering, like setTimeout callbacks or unresolved promises\n\n Event handler and async errors:\n \nUse useErrorBoundary to pass caught errors to the nearest boundary\nIn React 19, errors thrown from a function passed to the startTransition function returned by useTransition\nare caught by the nearest boundary\n\n The component provides several ways to render a fallback: fallback, fallbackRender, and FallbackComponent.\nRefer to the documentation to determine which is best for your application.\n This is a client component. You can only pass props to it that are serializable or use it in files that have a \"use client\"; directive.\n Optional props fallback ? : ReactNode Static content to render in place of an error if one is thrown.\n < ErrorBoundary fallback = { < div className = \"text-red\" > Something went wrong } /> FallbackComponent ? : ComponentType < FallbackProps > React component responsible for returning a fallback UI based on a thrown value.\n < ErrorBoundary FallbackComponent = { Fallback } /> fallbackRender ? : ( props : FallbackProps ) => ReactNode Render prop function responsible for returning a fallback UI based on a thrown value.\n < ErrorBoundary fallbackRender = { ( { error , resetErrorBoundary } ) => < div > ... } /> onError ? : ( error : unknown , info : ErrorInfo ) => void Optional callback to enable e.g. logging error information to a server.\n\n error Value that was thrown; typically an instance of Error \n info React \"component stack\" identifying where the error was thrown\n\n onReset ? : ( details : { reason : \"imperative-api\" ; args : unknown [ ] ; } | { reason : \"keys\" ; prev : unknown [ ] ; next : unknown [ ] ; } ) => void Optional callback to be notified when an error boundary is reset so React can retry the failed render.\n resetKeys ? : unknown [ ] When changed, these keys will reset a triggered error boundary.\nThis can be useful when an error condition may be tied to some specific state (that can be uniquely identified by key).\nSee the documentation for examples of how to use this prop.\n ", "n": 0.05 } } @@ -237,7 +237,7 @@ "n": 0.707 }, "2": { - "v": " Common questions Why didn't the boundary catch my error? This package is built on top of React error boundaries, so it follows React's rules for what errors are caught. Error boundaries catch errors thrown while rendering the tree below them. This means that it can't catch errors during: Server side rendering Event handlers Errors thrown in the error boundary itself Async code that runs after rendering, like setTimeout callbacks or unresolved promises For async errors: Use useErrorBoundary to pass caught errors to the nearest boundary. Learn more. In React 19, errors thrown from a function passed to the startTransition function returned by useTransition are caught by the nearest boundary. Learn more. ErrorBoundary cannot be used as a JSX component This error can be caused by a version mismatch between react and @types/react. To fix this, ensure that both match exactly. For NPM, you may need to use an override: { \n \"overrides\" : { \n \"@types/react\" : \"17.0.60\" \n } \n } Yarn has a similar mechanism called a resolution: { \n \"resolutions\" : { \n \"@types/react\" : \"17.0.60\" \n } \n } Unable to resolve path to module 'react-error-boundary' The version 6.0 release of this library switched to ESM-only to better work with modern JavaScript tooling. If your project uses a framework or runtime that does not yet support ES Modules (like Expo or Hermes) then you should use version 5 of this library. There are no major API differences between these two versions other than ESM support. ", + "v": " Common questions Why didn't the boundary catch my error? This package is built on top of React error boundaries, so it follows React's rules for what errors are caught. Error boundaries catch errors thrown while rendering the tree below them. This means that it can't catch errors during: Server side rendering Event handlers Errors thrown in the error boundary itself Async code that runs after rendering, like setTimeout callbacks or unresolved promises For event handler errors and async callback errors: Use useErrorBoundary to pass caught errors to the nearest boundary. Learn more. In React 19, errors thrown from a function passed to the startTransition function returned by useTransition are caught by the nearest boundary. Learn more. ErrorBoundary cannot be used as a JSX component This error can be caused by a version mismatch between react and @types/react. To fix this, ensure that both match exactly. For NPM, you may need to use an override: { \n \"overrides\" : { \n \"@types/react\" : \"17.0.60\" \n } \n } Yarn has a similar mechanism called a resolution: { \n \"resolutions\" : { \n \"@types/react\" : \"17.0.60\" \n } \n } Unable to resolve path to module 'react-error-boundary' The version 6.0 release of this library switched to ESM-only to better work with modern JavaScript tooling. If your project uses a framework or runtime that does not yet support ES Modules (like Expo or Hermes) then you should use version 5 of this library. There are no major API differences between these two versions other than ESM support. ", "n": 0.063 } } diff --git a/public/generated/search-records.json b/public/generated/search-records.json index 75d5739..4c3345c 100644 --- a/public/generated/search-records.json +++ b/public/generated/search-records.json @@ -1,7 +1,7 @@ [ { "path": "/", - "text": " Getting started with react-error-boundary React components and utils for managing runtime errors. Supports all React renderers (including React DOM and React Native). This package is built on top of React error boundaries, so it follows React's rules for what errors are caught. Error boundaries catch errors thrown while rendering the tree below them. This means that it can't catch errors during: Server side rendering Event handlers Errors thrown in the error boundary itself Async code that runs after rendering, like setTimeout callbacks or unresolved promises For async errors: Use useErrorBoundary to pass caught errors to the nearest boundary. Learn more. In React 19, errors thrown from a function passed to the startTransition function returned by useTransition are caught by the nearest boundary. Learn more. Installation Begin by installing the library from NPM: npm install react-error-boundary TypeScript definitions are included within the published dist folder. Support Here are some ways to support this project: Become a GitHub sponsor Buy me a coffee ", + "text": " Getting started with react-error-boundary React components and utils for managing runtime errors. Supports all React renderers (including React DOM and React Native). This package is built on top of React error boundaries, so it follows React's rules for what errors are caught. Error boundaries catch errors thrown while rendering the tree below them. This means that it can't catch errors during: Server side rendering Event handlers Errors thrown in the error boundary itself Async code that runs after rendering, like setTimeout callbacks or unresolved promises For event handler errors and async callback errors: Use useErrorBoundary to pass caught errors to the nearest boundary. Learn more. In React 19, errors thrown from a function passed to the startTransition function returned by useTransition are caught by the nearest boundary. Learn more. Installation Begin by installing the library from NPM: npm install react-error-boundary TypeScript definitions are included within the published dist folder. Support Here are some ways to support this project: Become a GitHub sponsor Buy me a coffee ", "title": "Getting started with react-error-boundary" }, { @@ -31,8 +31,8 @@ { "path": "/examples/async-user-code-errors", "section": "Examples", - "text": " Examples Async user code errors React handles errors thrown while rendering the tree below an error boundary. Errors thrown in event handlers, or after async code has run, will not be caught by an error boundary automatically. For async work outside of Actions, catch the error yourself and pass it to the nearest boundary with useErrorBoundary: In React 19, useTransition Actions can be an alternative: errors thrown from a function passed to the returned startTransition function are caught by the nearest boundary. Learn more. import { useErrorBoundary } from \"react-error-boundary\" ; \n \n function UserProfile ( { username } : { username : string } ) { \n const { showBoundary } = useErrorBoundary ( ) ; \n \n async function loadProfile ( ) { \n try { \n await fetchUserProfile ( username ) ; \n } catch ( error ) { \n showBoundary ( error ) ; \n } \n } \n \n return < button onClick = { loadProfile } > Load profile ; \n } ", - "title": "Async user code errors" + "text": " Examples Event handler and async errors React handles errors thrown while rendering the tree below an error boundary. Errors thrown in event handlers, or after async code has run, will not be caught by an error boundary automatically. For async callback errors, like errors thrown after an Effect starts loading data, catch the error yourself and pass it to the nearest boundary with useErrorBoundary. You can use the same pattern for event handler errors: In React 19, useTransition Actions can be an alternative: errors thrown from a function passed to the returned startTransition function are caught by the nearest boundary. Learn more. import { useEffect } from \"react\" ; \n import { ErrorBoundary , useErrorBoundary } from \"react-error-boundary\" ; \n \n function UserProfileContainer ( { username } : { username : string } ) { \n return ( \n < ErrorBoundary \n fallback = { < p > Could not load profile } \n resetKeys = { [ username ] } \n > \n < UserProfile username = { username } /> \n \n ) ; \n } \n \n function UserProfile ( { username } : { username : string } ) { \n const { showBoundary } = useErrorBoundary ( ) ; \n \n useEffect ( ( ) => { \n let cancelled = false ; \n \n fetchUserProfile ( username ) . then ( \n ( response ) => { \n if ( ! cancelled ) { \n // Set data in state and re-render \n } \n } , \n ( error ) => { \n if ( ! cancelled ) { \n showBoundary ( error ) ; \n } \n } , \n ) ; \n \n return ( ) => { \n cancelled = true ; \n } ; \n } , [ showBoundary , username ] ) ; \n \n return null ; \n } ", + "title": "Event handler and async errors" }, { "path": "/examples/transition-errors", @@ -49,7 +49,7 @@ { "path": "/api/error-boundary-props", "section": "API", - "text": " API ErrorBoundary component props A reusable React error boundary component.\nWrap this component around other React components to \"catch\" errors and render a fallback UI.\n Catches errors thrown while rendering the tree below it.\n Does not catch errors thrown during:\n\nServer side rendering\nEvent handlers\nErrors thrown in the error boundary itself\nAsync code that runs after rendering, like setTimeout callbacks or unresolved promises\n\n Async errors:\n \nUse useErrorBoundary to pass caught errors to the nearest boundary\nIn React 19, errors thrown from a function passed to the startTransition function returned by useTransition\nare caught by the nearest boundary\n\n The component provides several ways to render a fallback: fallback, fallbackRender, and FallbackComponent.\nRefer to the documentation to determine which is best for your application.\n This is a client component. You can only pass props to it that are serializable or use it in files that have a \"use client\"; directive.\n Optional props fallback ? : ReactNode Static content to render in place of an error if one is thrown.\n < ErrorBoundary fallback = { < div className = \"text-red\" > Something went wrong } /> FallbackComponent ? : ComponentType < FallbackProps > React component responsible for returning a fallback UI based on a thrown value.\n < ErrorBoundary FallbackComponent = { Fallback } /> fallbackRender ? : ( props : FallbackProps ) => ReactNode Render prop function responsible for returning a fallback UI based on a thrown value.\n < ErrorBoundary fallbackRender = { ( { error , resetErrorBoundary } ) => < div > ... } /> onError ? : ( error : unknown , info : ErrorInfo ) => void Optional callback to enable e.g. logging error information to a server.\n\n error Value that was thrown; typically an instance of Error \n info React \"component stack\" identifying where the error was thrown\n\n onReset ? : ( details : { reason : \"imperative-api\" ; args : unknown [ ] ; } | { reason : \"keys\" ; prev : unknown [ ] ; next : unknown [ ] ; } ) => void Optional callback to be notified when an error boundary is reset so React can retry the failed render.\n resetKeys ? : unknown [ ] When changed, these keys will reset a triggered error boundary.\nThis can be useful when an error condition may be tied to some specific state (that can be uniquely identified by key).\nSee the documentation for examples of how to use this prop.\n ", + "text": " API ErrorBoundary component props A reusable React error boundary component.\nWrap this component around other React components to \"catch\" errors and render a fallback UI.\n Catches errors thrown while rendering the tree below it.\n Does not catch errors thrown during:\n\nServer side rendering\nEvent handlers\nErrors thrown in the error boundary itself\nAsync code that runs after rendering, like setTimeout callbacks or unresolved promises\n\n Event handler and async errors:\n \nUse useErrorBoundary to pass caught errors to the nearest boundary\nIn React 19, errors thrown from a function passed to the startTransition function returned by useTransition\nare caught by the nearest boundary\n\n The component provides several ways to render a fallback: fallback, fallbackRender, and FallbackComponent.\nRefer to the documentation to determine which is best for your application.\n This is a client component. You can only pass props to it that are serializable or use it in files that have a \"use client\"; directive.\n Optional props fallback ? : ReactNode Static content to render in place of an error if one is thrown.\n < ErrorBoundary fallback = { < div className = \"text-red\" > Something went wrong } /> FallbackComponent ? : ComponentType < FallbackProps > React component responsible for returning a fallback UI based on a thrown value.\n < ErrorBoundary FallbackComponent = { Fallback } /> fallbackRender ? : ( props : FallbackProps ) => ReactNode Render prop function responsible for returning a fallback UI based on a thrown value.\n < ErrorBoundary fallbackRender = { ( { error , resetErrorBoundary } ) => < div > ... } /> onError ? : ( error : unknown , info : ErrorInfo ) => void Optional callback to enable e.g. logging error information to a server.\n\n error Value that was thrown; typically an instance of Error \n info React \"component stack\" identifying where the error was thrown\n\n onReset ? : ( details : { reason : \"imperative-api\" ; args : unknown [ ] ; } | { reason : \"keys\" ; prev : unknown [ ] ; next : unknown [ ] ; } ) => void Optional callback to be notified when an error boundary is reset so React can retry the failed render.\n resetKeys ? : unknown [ ] When changed, these keys will reset a triggered error boundary.\nThis can be useful when an error condition may be tied to some specific state (that can be uniquely identified by key).\nSee the documentation for examples of how to use this prop.\n ", "title": "ErrorBoundary component props" }, { @@ -72,7 +72,7 @@ }, { "path": "/common-questions", - "text": " Common questions Why didn't the boundary catch my error? This package is built on top of React error boundaries, so it follows React's rules for what errors are caught. Error boundaries catch errors thrown while rendering the tree below them. This means that it can't catch errors during: Server side rendering Event handlers Errors thrown in the error boundary itself Async code that runs after rendering, like setTimeout callbacks or unresolved promises For async errors: Use useErrorBoundary to pass caught errors to the nearest boundary. Learn more. In React 19, errors thrown from a function passed to the startTransition function returned by useTransition are caught by the nearest boundary. Learn more. ErrorBoundary cannot be used as a JSX component This error can be caused by a version mismatch between react and @types/react. To fix this, ensure that both match exactly. For NPM, you may need to use an override: { \n \"overrides\" : { \n \"@types/react\" : \"17.0.60\" \n } \n } Yarn has a similar mechanism called a resolution: { \n \"resolutions\" : { \n \"@types/react\" : \"17.0.60\" \n } \n } Unable to resolve path to module 'react-error-boundary' The version 6.0 release of this library switched to ESM-only to better work with modern JavaScript tooling. If your project uses a framework or runtime that does not yet support ES Modules (like Expo or Hermes) then you should use version 5 of this library. There are no major API differences between these two versions other than ESM support. ", + "text": " Common questions Why didn't the boundary catch my error? This package is built on top of React error boundaries, so it follows React's rules for what errors are caught. Error boundaries catch errors thrown while rendering the tree below them. This means that it can't catch errors during: Server side rendering Event handlers Errors thrown in the error boundary itself Async code that runs after rendering, like setTimeout callbacks or unresolved promises For event handler errors and async callback errors: Use useErrorBoundary to pass caught errors to the nearest boundary. Learn more. In React 19, errors thrown from a function passed to the startTransition function returned by useTransition are caught by the nearest boundary. Learn more. ErrorBoundary cannot be used as a JSX component This error can be caused by a version mismatch between react and @types/react. To fix this, ensure that both match exactly. For NPM, you may need to use an override: { \n \"overrides\" : { \n \"@types/react\" : \"17.0.60\" \n } \n } Yarn has a similar mechanism called a resolution: { \n \"resolutions\" : { \n \"@types/react\" : \"17.0.60\" \n } \n } Unable to resolve path to module 'react-error-boundary' The version 6.0 release of this library switched to ESM-only to better work with modern JavaScript tooling. If your project uses a framework or runtime that does not yet support ES Modules (like Expo or Hermes) then you should use version 5 of this library. There are no major API differences between these two versions other than ESM support. ", "title": "Common questions" }, { diff --git a/public/generated/site-map.json b/public/generated/site-map.json index 5911508..0b4270b 100644 --- a/public/generated/site-map.json +++ b/public/generated/site-map.json @@ -1,7 +1,7 @@ [ { "path": "/", - "text": " React components and utils for managing runtime errors. Supports all React renderers (including React DOM and React Native). This package is built on top of React error boundaries, so it follows React's rules for what errors are caught. Error boundaries catch errors thrown while rendering the tree below them. This means that it can't catch errors during: Server side rendering Event handlers Errors thrown in the error boundary itself Async code that runs after rendering, like setTimeout callbacks or unresolved promises For async errors: Use useErrorBoundary to pass caught errors to the nearest boundary. Learn more. In React 19, errors thrown from a function passed to the startTransition function returned by useTransition are caught by the nearest boundary. Learn more. Installation Begin by installing the library from NPM: npm install react-error-boundary TypeScript definitions are included within the published dist folder. Support Here are some ways to support this project: Become a GitHub sponsor Buy me a coffee ", + "text": " React components and utils for managing runtime errors. Supports all React renderers (including React DOM and React Native). This package is built on top of React error boundaries, so it follows React's rules for what errors are caught. Error boundaries catch errors thrown while rendering the tree below them. This means that it can't catch errors during: Server side rendering Event handlers Errors thrown in the error boundary itself Async code that runs after rendering, like setTimeout callbacks or unresolved promises For event handler errors and async callback errors: Use useErrorBoundary to pass caught errors to the nearest boundary. Learn more. In React 19, errors thrown from a function passed to the startTransition function returned by useTransition are caught by the nearest boundary. Learn more. Installation Begin by installing the library from NPM: npm install react-error-boundary TypeScript definitions are included within the published dist folder. Support Here are some ways to support this project: Become a GitHub sponsor Buy me a coffee ", "title": "Getting started with react-error-boundary" }, { @@ -31,8 +31,8 @@ { "path": "/examples/async-user-code-errors", "section": "Examples", - "text": " React handles errors thrown while rendering the tree below an error boundary. Errors thrown in event handlers, or after async code has run, will not be caught by an error boundary automatically. For async work outside of Actions, catch the error yourself and pass it to the nearest boundary with useErrorBoundary: In React 19, useTransition Actions can be an alternative: errors thrown from a function passed to the returned startTransition function are caught by the nearest boundary. Learn more. import { useErrorBoundary } from \"react-error-boundary\";\n \nfunction UserProfile({ username }: { username: string }) {\n const { showBoundary } = useErrorBoundary();\n \n async function loadProfile() {\n try {\n await fetchUserProfile(username);\n } catch (error) {\n showBoundary(error);\n }\n }\n \n return ;\n} ", - "title": "Async user code errors" + "text": " React handles errors thrown while rendering the tree below an error boundary. Errors thrown in event handlers, or after async code has run, will not be caught by an error boundary automatically. For async callback errors, like errors thrown after an Effect starts loading data, catch the error yourself and pass it to the nearest boundary with useErrorBoundary. You can use the same pattern for event handler errors: In React 19, useTransition Actions can be an alternative: errors thrown from a function passed to the returned startTransition function are caught by the nearest boundary. Learn more. import { useEffect } from \"react\";\nimport { ErrorBoundary, useErrorBoundary } from \"react-error-boundary\";\n \nfunction UserProfileContainer({ username }: { username: string }) {\n return (\n Could not load profile

}\n resetKeys={[username]}\n >\n \n \n );\n}\n \nfunction UserProfile({ username }: { username: string }) {\n const { showBoundary } = useErrorBoundary();\n \n useEffect(() => {\n let cancelled = false;\n \n fetchUserProfile(username).then(\n (response) => {\n if (!cancelled) {\n // Set data in state and re-render\n }\n },\n (error) => {\n if (!cancelled) {\n showBoundary(error);\n }\n },\n );\n \n return () => {\n cancelled = true;\n };\n }, [showBoundary, username]);\n \n return null;\n} ", + "title": "Event handler and async errors" }, { "path": "/examples/transition-errors", @@ -49,7 +49,7 @@ { "path": "/api/error-boundary-props", "section": "API", - "text": " A reusable React error boundary component.\nWrap this component around other React components to \"catch\" errors and render a fallback UI.\n Catches errors thrown while rendering the tree below it.\n Does not catch errors thrown during:\n\nServer side rendering\nEvent handlers\nErrors thrown in the error boundary itself\nAsync code that runs after rendering, like setTimeout callbacks or unresolved promises\n\n Async errors:\n \nUse useErrorBoundary to pass caught errors to the nearest boundary\nIn React 19, errors thrown from a function passed to the startTransition function returned by useTransition\nare caught by the nearest boundary\n\n The component provides several ways to render a fallback: fallback, fallbackRender, and FallbackComponent.\nRefer to the documentation to determine which is best for your application.\n This is a client component. You can only pass props to it that are serializable or use it in files that have a \"use client\"; directive.\n Optional props fallback?: ReactNode Static content to render in place of an error if one is thrown.\n < ErrorBoundary fallback = { < div className = \"text-red\" > Something went wrong } /> FallbackComponent?: ComponentType React component responsible for returning a fallback UI based on a thrown value.\n < ErrorBoundary FallbackComponent = { Fallback } /> fallbackRender?: (props: FallbackProps) => ReactNode Render prop function responsible for returning a fallback UI based on a thrown value.\n < ErrorBoundary fallbackRender = { ( { error , resetErrorBoundary } ) => < div > ... } /> onError?: (error: unknown, info: ErrorInfo) => void Optional callback to enable e.g. logging error information to a server.\n\n error Value that was thrown; typically an instance of Error \n info React \"component stack\" identifying where the error was thrown\n\n onReset?: (details: { reason: \"imperative-api\"; args: unknown[]; } | { reason: \"keys\"; prev: unknown[]; next: unknown[]; }) => void Optional callback to be notified when an error boundary is reset so React can retry the failed render.\n resetKeys?: unknown[] When changed, these keys will reset a triggered error boundary.\nThis can be useful when an error condition may be tied to some specific state (that can be uniquely identified by key).\nSee the documentation for examples of how to use this prop.\n ", + "text": " A reusable React error boundary component.\nWrap this component around other React components to \"catch\" errors and render a fallback UI.\n Catches errors thrown while rendering the tree below it.\n Does not catch errors thrown during:\n\nServer side rendering\nEvent handlers\nErrors thrown in the error boundary itself\nAsync code that runs after rendering, like setTimeout callbacks or unresolved promises\n\n Event handler and async errors:\n \nUse useErrorBoundary to pass caught errors to the nearest boundary\nIn React 19, errors thrown from a function passed to the startTransition function returned by useTransition\nare caught by the nearest boundary\n\n The component provides several ways to render a fallback: fallback, fallbackRender, and FallbackComponent.\nRefer to the documentation to determine which is best for your application.\n This is a client component. You can only pass props to it that are serializable or use it in files that have a \"use client\"; directive.\n Optional props fallback?: ReactNode Static content to render in place of an error if one is thrown.\n < ErrorBoundary fallback = { < div className = \"text-red\" > Something went wrong } /> FallbackComponent?: ComponentType React component responsible for returning a fallback UI based on a thrown value.\n < ErrorBoundary FallbackComponent = { Fallback } /> fallbackRender?: (props: FallbackProps) => ReactNode Render prop function responsible for returning a fallback UI based on a thrown value.\n < ErrorBoundary fallbackRender = { ( { error , resetErrorBoundary } ) => < div > ... } /> onError?: (error: unknown, info: ErrorInfo) => void Optional callback to enable e.g. logging error information to a server.\n\n error Value that was thrown; typically an instance of Error \n info React \"component stack\" identifying where the error was thrown\n\n onReset?: (details: { reason: \"imperative-api\"; args: unknown[]; } | { reason: \"keys\"; prev: unknown[]; next: unknown[]; }) => void Optional callback to be notified when an error boundary is reset so React can retry the failed render.\n resetKeys?: unknown[] When changed, these keys will reset a triggered error boundary.\nThis can be useful when an error condition may be tied to some specific state (that can be uniquely identified by key).\nSee the documentation for examples of how to use this prop.\n ", "title": "ErrorBoundary component props" }, { @@ -72,7 +72,7 @@ }, { "path": "/common-questions", - "text": " Why didn't the boundary catch my error? This package is built on top of React error boundaries, so it follows React's rules for what errors are caught. Error boundaries catch errors thrown while rendering the tree below them. This means that it can't catch errors during: Server side rendering Event handlers Errors thrown in the error boundary itself Async code that runs after rendering, like setTimeout callbacks or unresolved promises For async errors: Use useErrorBoundary to pass caught errors to the nearest boundary. Learn more. In React 19, errors thrown from a function passed to the startTransition function returned by useTransition are caught by the nearest boundary. Learn more. ErrorBoundary cannot be used as a JSX component This error can be caused by a version mismatch between react and @types/react. To fix this, ensure that both match exactly. For NPM, you may need to use an override: {\n \"overrides\": {\n \"@types/react\": \"17.0.60\"\n }\n} Yarn has a similar mechanism called a resolution: {\n \"resolutions\": {\n \"@types/react\": \"17.0.60\"\n }\n} Unable to resolve path to module 'react-error-boundary' The version 6.0 release of this library switched to ESM-only to better work with modern JavaScript tooling. If your project uses a framework or runtime that does not yet support ES Modules (like Expo or Hermes) then you should use version 5 of this library. There are no major API differences between these two versions other than ESM support. ", + "text": " Why didn't the boundary catch my error? This package is built on top of React error boundaries, so it follows React's rules for what errors are caught. Error boundaries catch errors thrown while rendering the tree below them. This means that it can't catch errors during: Server side rendering Event handlers Errors thrown in the error boundary itself Async code that runs after rendering, like setTimeout callbacks or unresolved promises For event handler errors and async callback errors: Use useErrorBoundary to pass caught errors to the nearest boundary. Learn more. In React 19, errors thrown from a function passed to the startTransition function returned by useTransition are caught by the nearest boundary. Learn more. ErrorBoundary cannot be used as a JSX component This error can be caused by a version mismatch between react and @types/react. To fix this, ensure that both match exactly. For NPM, you may need to use an override: {\n \"overrides\": {\n \"@types/react\": \"17.0.60\"\n }\n} Yarn has a similar mechanism called a resolution: {\n \"resolutions\": {\n \"@types/react\": \"17.0.60\"\n }\n} Unable to resolve path to module 'react-error-boundary' The version 6.0 release of this library switched to ESM-only to better work with modern JavaScript tooling. If your project uses a framework or runtime that does not yet support ES Modules (like Expo or Hermes) then you should use version 5 of this library. There are no major API differences between these two versions other than ESM support. ", "title": "Common questions" }, { diff --git a/src/App.tsx b/src/App.tsx index 69f4cbd..f7febee 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -29,7 +29,7 @@ export default function App() { Error logging - Async user code errors + Events and async functions Transition errors @@ -93,7 +93,7 @@ const clientSideWarning = ( unresolved promises -
For async errors:
+
For event handler errors and async callback errors:
  • Use useErrorBoundary to pass caught errors to the nearest diff --git a/src/routes/AsyncUserCodeErrorsRoute.tsx b/src/routes/AsyncUserCodeErrorsRoute.tsx index 6c12469..eaaa139 100644 --- a/src/routes/AsyncUserCodeErrorsRoute.tsx +++ b/src/routes/AsyncUserCodeErrorsRoute.tsx @@ -4,16 +4,18 @@ import { html } from "../../public/generated/examples/AsyncUserCodeErrors.json"; export default function AsyncUserCodeErrorsRoute() { return ( -
    +
    React handles errors thrown while rendering the tree below an error boundary. Errors thrown in event handlers, or after async code has run, will not be caught by an error boundary automatically.
    - For async work outside of Actions, catch the error yourself and pass it - to the nearest boundary with{" "} - useErrorBoundary: + For async callback errors, like errors thrown after an Effect starts + loading data, catch the error yourself and pass it to the nearest + boundary with{" "} + useErrorBoundary. You can + use the same pattern for event handler errors:
    In React 19, useTransition Actions can be an alternative: diff --git a/src/routes/examples/AsyncUserCodeErrors.tsx b/src/routes/examples/AsyncUserCodeErrors.tsx index ccb81cb..5d5a88b 100644 --- a/src/routes/examples/AsyncUserCodeErrors.tsx +++ b/src/routes/examples/AsyncUserCodeErrors.tsx @@ -1,21 +1,47 @@ -import { useErrorBoundary } from "react-error-boundary"; +import { useEffect } from "react"; +import { ErrorBoundary, useErrorBoundary } from "react-error-boundary"; + +function UserProfileContainer({ username }: { username: string }) { + return ( + Could not load profile

    } + resetKeys={[username]} + > + +     + ); +} function UserProfile({ username }: { username: string }) { const { showBoundary } = useErrorBoundary(); - async function loadProfile() { - try { - await fetchUserProfile(username); - } catch (error) { - showBoundary(error); - } - } + useEffect(() => { + let cancelled = false; + + fetchUserProfile(username).then( + (response) => { + if (!cancelled) { + // Set data in state and re-render + response; // hidden + } + }, + (error) => { + if (!cancelled) { + showBoundary(error); + } + }, + ); + + return () => { + cancelled = true; + }; + }, [showBoundary, username]); - return ; + return null; } // -export { UserProfile }; +export { UserProfileContainer }; async function fetchUserProfile(_: string) {} From 2b6c9321ae2cb1975d086114dd5fc660240faf47 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Mon, 25 May 2026 15:15:22 +0200 Subject: [PATCH 2/2] Address review: simpler example, shorter nav label --- .../examples/AsyncUserCodeErrors.json | 2 +- src/App.tsx | 2 +- src/routes/examples/AsyncUserCodeErrors.tsx | 21 ++++++------------- 3 files changed, 8 insertions(+), 17 deletions(-) diff --git a/public/generated/examples/AsyncUserCodeErrors.json b/public/generated/examples/AsyncUserCodeErrors.json index 813926a..03cb33f 100644 --- a/public/generated/examples/AsyncUserCodeErrors.json +++ b/public/generated/examples/AsyncUserCodeErrors.json @@ -1,3 +1,3 @@ { - "html": "
    import { useEffect } from \"react\";
    \n
    import { ErrorBoundary, useErrorBoundary } from \"react-error-boundary\";
    \n
     
    \n
    function UserProfileContainer({ username }: { username: string }) {
    \n
    return (
    \n
    <ErrorBoundary
    \n
    fallback={<p>Could not load profile</p>}
    \n
    resetKeys={[username]}
    \n
    >
    \n
    <UserProfile username={username} />
    \n
    </ErrorBoundary>
    \n
    );
    \n
    }
    \n
     
    \n
    function UserProfile({ username }: { username: string }) {
    \n
    const { showBoundary } = useErrorBoundary();
    \n
     
    \n
    useEffect(() => {
    \n
    let cancelled = false;
    \n
     
    \n
    fetchUserProfile(username).then(
    \n
    (response) => {
    \n
    if (!cancelled) {
    \n
    // Set data in state and re-render
    \n
    }
    \n
    },
    \n
    (error) => {
    \n
    if (!cancelled) {
    \n
    showBoundary(error);
    \n
    }
    \n
    },
    \n
    );
    \n
     
    \n
    return () => {
    \n
    cancelled = true;
    \n
    };
    \n
    }, [showBoundary, username]);
    \n
     
    \n
    return null;
    \n
    }
    " + "html": "
    import { useEffect } from \"react\";
    \n
    import { ErrorBoundary, useErrorBoundary } from \"react-error-boundary\";
    \n
     
    \n
    function UserProfileContainer({ username }: { username: string }) {
    \n
    return (
    \n
    <ErrorBoundary
    \n
    fallback={<p>Could not load profile</p>}
    \n
    resetKeys={[username]}
    \n
    >
    \n
    <UserProfile username={username} />
    \n
    </ErrorBoundary>
    \n
    );
    \n
    }
    \n
     
    \n
    function UserProfile({ username }: { username: string }) {
    \n
    const { showBoundary } = useErrorBoundary();
    \n
     
    \n
    useEffect(() => {
    \n
    fetchGreeting(username).then(
    \n
    (response) => {
    \n
    // Set data in state and re-render ...
    \n
    },
    \n
    (error) => {
    \n
    // Show error boundary
    \n
    showBoundary(error);
    \n
    },
    \n
    );
    \n
    }, [showBoundary, username]);
    \n
     
    \n
    return null;
    \n
    }
    " } \ No newline at end of file diff --git a/src/App.tsx b/src/App.tsx index f7febee..4f71e11 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -29,7 +29,7 @@ export default function App() { Error logging - Events and async functions + Events & async Transition errors diff --git a/src/routes/examples/AsyncUserCodeErrors.tsx b/src/routes/examples/AsyncUserCodeErrors.tsx index 5d5a88b..643aa93 100644 --- a/src/routes/examples/AsyncUserCodeErrors.tsx +++ b/src/routes/examples/AsyncUserCodeErrors.tsx @@ -16,25 +16,16 @@ function UserProfile({ username }: { username: string }) { const { showBoundary } = useErrorBoundary(); useEffect(() => { - let cancelled = false; - - fetchUserProfile(username).then( + fetchGreeting(username).then( (response) => { - if (!cancelled) { - // Set data in state and re-render - response; // hidden - } + // Set data in state and re-render ... + response; // hidden }, (error) => { - if (!cancelled) { - showBoundary(error); - } + // Show error boundary + showBoundary(error); }, ); - - return () => { - cancelled = true; - }; }, [showBoundary, username]); return null; @@ -44,4 +35,4 @@ function UserProfile({ username }: { username: string }) { export { UserProfileContainer }; -async function fetchUserProfile(_: string) {} +async function fetchGreeting(_: string) {}