> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# @appsignal/react

## Installation

### With npm or yarn

Add the `@appsignal/react` and `@appsignal/javascript` packages to your `package.json`. Then, run `npm install`/`yarn install`.

You can also add these packages to your `package.json` on the command line:

<CodeGroup>
  ```sh Shell theme={null}
  yarn add @appsignal/javascript @appsignal/react
  npm install @appsignal/javascript @appsignal/react
  ```
</CodeGroup>

<Tip>
  You can also use the React integration with React Native and Expo.
</Tip>

### With JSPM.io import maps

Using the [JSPM.io import map generator](https://generator.jspm.io/), you can generate an import map for your application's dependencies.

Add `@appsignal/javascript` and `@appsignal/react` to the dependencies list in the generator, then add the generated import map and ES module shims to your application's code.

### With `rails-importmap`

Use the following command to add these packages to your Rails application's import maps:

<CodeGroup>
  ```sh Shell theme={null}
  ./bin/importmap pin @appsignal/javascript @appsignal/react
  ```
</CodeGroup>

## Usage

You must pass the AppSignal client instance as the `instance` prop. In addition, the following props can optionally be passed to both the `ErrorBoundary` and `LegacyBoundary` components:

| Prop name  | Description                                                                                                                                                                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action`   | The action name for which to show errors reported by this boundary. We recommend using the name of the component.                                                                                                                                          |
| `tags`     | An object containing the tags to set for errors reported by this boundary.                                                                                                                                                                                 |
| `fallback` | A function that optionally takes the error as an argument, and returns a fallback component to use when rendering fails.                                                                                                                                   |
| `override` | A function that takes the error span, and optionally the error itself, as arguments, and returns a modified span. Only called when an error is reported. Use it to [set tags, params or breadcrumbs](/front-end/span#updating-a-span) on the error sample. |

When using `tags`, `fallback` or `override`, use `useMemo` (or `useCallback` for `fallback` and `override`) to memoize the values. This will prevent unnecessary re-renders.

### Error Boundary

If you are using React v16 or higher, you can use the `ErrorBoundary` component to catch errors from anywhere in the child component tree.

<CodeGroup>
  ```jsx JavaScript theme={null}
  import React from "react";
  import ReactDOM from "react-dom";
  import { appsignal } from "./appsignal";
  import { ErrorBoundary } from "@appsignal/react";

  const FallbackComponent = () => (
    <div>Uh oh! There was an error :(</div>
  );

  const App = () => (
    const tags = useMemo(() => ({ tag: "value" }), []);
    const fallback = useCallback((error) => <FallbackComponent />, []);
    const override = useCallback((span, error) => {
      span.setParams({ customParams: "123" });
      return span
    }, []);

    <ErrorBoundary
      instance={appsignal}
      action="App"
      tags={tags}
      override={override}
      fallback={fallback}
    >
      { /* Child components here */ }
    </ErrorBoundary>
  );

  ReactDOM.render(<App />, document.getElementById("root"));
  ```
</CodeGroup>

### Legacy Boundary

<Warning>
  The API that this component uses is unstable at this point in React's
  development. We offer this component as a means to support those running React
  v15, but do not guarantee its reliablity. You are encouraged to use the
  `ErrorBoundary` whenever possible.
</Warning>

The `LegacyBoundary` works in almost exactly the same way as the `ErrorBoundary`:

<CodeGroup>
  ```jsx JavaScript theme={null}
  import React from "react";
  import ReactDOM from "react-dom";
  import { appsignal } from "./appsignal";
  import { LegacyBoundary } from "@appsignal/react";

  const FallbackComponent = () => (
    <div>Uh oh! There was an error :(</div>
  );

  const App = () => (
    const tags = useMemo(() => ({ tag: "value" }), []);
    const fallback = useCallback((error) => <FallbackComponent />, []);
    const override = useCallback((span, error) => {
      span.setParams({ customParams: "123" });
      return span
    }, []);

    <LegacyBoundary
      instance={appsignal}
      action="App"
      tags={tags}
      fallback={fallback}
      override={override}
    >
      { /* Child components here */ }
    </LegacyBoundary>
  );

  ReactDOM.render(<App />, document.getElementById("root"));
  ```
</CodeGroup>