You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A **react hook** for using error boundaries in your functional components.
8
10
9
-
It lets you keep track of the error state of child components, by wrapping them in a provided `ErrorBoundary` component.
11
+
It lets you keep track of the error state of child components, by wrapping them in the provided `ErrorBoundary` component.
10
12
11
-
:warning: Read more about error boundaries and their intended use in the [React documentation](https://reactjs.org/docs/error-boundaries.html), this will only catch errors when rendering your children!
13
+
:warning: Read more about error boundaries and their intended use in the [React documentation](https://reactjs.org/docs/error-boundaries.html), this will only catch errors during the render phase!
12
14
13
15
### Installation
14
16
15
17
```bash
16
18
npm i use-error-boundary
17
19
```
18
20
21
+
```bash
22
+
yarn add use-error-boundary
23
+
```
24
+
19
25
### Breaking changes in `2.x`
20
26
21
-
If you are upgrading from version `1.x` please make sure you are not using the `errorInfo` object.
22
-
The hook itself and the `renderError` callback no longer provide this object.
27
+
While upgrading from version `1.x` make sure you are not using the `errorInfo` object.
28
+
The hook and the `renderError` callback no longer provide this object.
23
29
24
-
For advanced use, please refer to [Custom handling of error and errorInfo](#custom-handling-of-error-and-errorinfo).
30
+
For advanced use, please refer to [Custom handling of error and errorInfo](#handling-error-and-errorinfo-outside-of-markup).
25
31
26
32
## Examples and usage
27
33
@@ -34,28 +40,30 @@ import { useErrorBoundary } from "use-error-boundary"
34
40
importuseErrorBoundaryfrom"use-error-boundary"
35
41
```
36
42
37
-
Please read more info on the [returned properties](#returned-properties) by the hook.
43
+
Learn more about the [properties that are returned](#returned-properties).
38
44
39
45
```javascript
40
46
constMyComponent= () => {
41
47
42
48
const {
43
49
ErrorBoundary,
44
50
didCatch,
45
-
error
51
+
error,
52
+
reset
46
53
} =useErrorBoundary()
47
54
48
-
...
55
+
//...
49
56
50
57
}
51
58
```
52
59
53
-
### Use without render props
60
+
### Usage without render props
54
61
55
-
Wrap your components in the provided `ErrorBoundary`,
56
-
if it catches an error the hook provides you with the changed state and the boundary Component will render nothing. So you have to handle rendering some error display yourself.
62
+
Wrap your components in the provided `ErrorBoundary`.
63
+
When it catches an error the hook provides you the changed error-state and the boundary Component will render nothing.
64
+
You have to handle rendering some error display yourself.
57
65
58
-
If you want the boundary to also render your error display, you can [use it with render props](#use-with-render-props)
66
+
You can get the ErrorBoundary component to render your custom error display by [using the `renderError` render-prop.](#use-with-render-props)
59
67
60
68
```javascript
61
69
constJustRenderMe= () => {
@@ -79,13 +87,13 @@ const MyComponent = () => {
79
87
}
80
88
```
81
89
82
-
### Use with render props
90
+
### Usage with render props
83
91
84
-
Optionally, you can pass a `render` and `renderError` function to render the components to display errors in the boundary itself:
92
+
Optionally, you can pass a `render` and `renderError` function to render your UI and error-state inside the boundary.
85
93
86
94
```javascript
87
95
/**
88
-
* The renderError function also passes the error and errorInfo, so that you can display it using
96
+
* The renderError function also passes the error, so that you can display it using
89
97
* render props.
90
98
*/
91
99
return (
@@ -96,9 +104,9 @@ return (
96
104
)
97
105
```
98
106
99
-
## Custom handling of `error` and `errorInfo`
107
+
## Handling `error` and `errorInfo` outside of markup
100
108
101
-
The hook now accepts an `options` object that you can pass a `onDidCatch` callback that gets called when the ErrorBoundary catches an error.
109
+
The hook now accepts an `options` object that you can pass a `onDidCatch` callback that gets called when the ErrorBoundary catches an error. Use this for logging or reporting of errors.
|`ErrorBoundary`| React Component | Special error boundary component that provides state changes to the hook. <br>:warning:**You need to use this as the error boundary! Otherwise, the state will not update when errors are caught!** <br> The ErrorBoundary is **guaranteed referential equality** across rerenders. |
118
-
|`didCatch`| Boolean |`true` if an error has been caught |
119
-
|`error`| Error Object or `null`| The error caught by the Boundary |
123
+
### `ErrorBoundary`
124
+
`Type: React Component`
125
+
126
+
127
+
Special error boundary component that provides state changes to the hook.
128
+
129
+
:warning:**You need to use this as the error boundary! Otherwise, the state will not update when errors are caught!**
130
+
131
+
The ErrorBoundary is **guaranteed referential equality** across rerenders and only updates after a reset.
132
+
133
+
### `didCatch`
134
+
`Type: boolean`
135
+
136
+
The error state, `true` if an error has ben caught.
137
+
138
+
139
+
### `error`
140
+
`Type: any | null`
141
+
142
+
The error caught by the boundary, or `null`.
143
+
144
+
### `reset`
145
+
`Type: function`
146
+
147
+
Function the reset the error state.
148
+
Forces react to recreate the boundary by creating a new ErrorBoundary
149
+
150
+
Your boundary can now catch errors again.
120
151
121
152
If you are searching for the `errorInfo` property, please read [Breaking Changes in 2.x](#breaking-changes-in-2x).
122
153
123
-
## Why should I use this?
154
+
## Why should I use this hook?
124
155
125
156
React does not provide a way to catch errors within the same functional component and you have to handle that in a class Component with special lifecycle methods.
126
-
If you are new to ErrorBoundaries, I recommend implementing this yourself!
127
157
128
-
This packages purpose is to provide an easy drop in replacement for projects that are being migrated to hooks and to pull the error presentation out of the boundary itself by putting it on the same level you are catching the errors.
158
+
If you are new to ErrorBoundaries, building this yourself is a good way to get started!
159
+
160
+
This packages purpose is to provide an easy drop in replacement for projects that are being migrated to hooks.
161
+
162
+
This also pulls the error presentation out of the error boundary, and on the same level you are handling errors.
0 commit comments