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

# React SDK

> Microapp authentication for React apps.

The Auth SDK for React enables you to authenticate users using React-specific features.

## Getting Started

### 1. Install the SDK

Install the SDK with your preferred package manager.

<CodeGroup>
  ```bash npm theme={null}
  npm install @microapp-io/react
  ```

  ```bash yarn theme={null}
  yarn add @microapp-io/react
  ```

  ```bash pnpm theme={null}
  pnpm add @microapp-io/react
  ```
</CodeGroup>

### 2. Wrap Your App with the Provider

In order for your microapp to have access to auth features, it needs to be wrapped in the `AuthProvider` component:

```tsx theme={null}
import { AuthProvider } from "@microapp-io/react";

function App() {
  return <AuthProvider>{/* Your microapp code here */}</AuthProvider>;
}
```

For local development, we recommend using the `sandbox` feature on the `AuthProvider` component to return mocked users:

```tsx theme={null}
import { AuthProvider } from "@microapp-io/react";

const sandbox = {
  enabled: process.env.NODE_ENV !== "production",
  user: {
    id: "1",
    email: "hi@microapp.io",
    pictureUrl: "https://example.com/avatar.png",
  },
};

function App() {
  return (
    <AuthProvider sandbox={sandbox}>
      {/* Your microapp code here */}
    </AuthProvider>
  );
}
```

<Warning>
  The `sandbox` prop should only be used for local development. Do not use it in
  production.
</Warning>

### 3. Use the `useAuth` Hook

The `useAuth` hook returns all of the auth data and methods available to your microapp. It returns the following type:

```typescript theme={null}
type Auth = {
  isAuthenticated: boolean;
  isLoading: boolean;
  user?: {
    id: string;
    email: string;
    pictureUrl: string;
  };
  error?: Error;
  refresh: () => void;
  requestLogin: () => void;
};
```

### 4. Prompt the User to Log In

You can prompt the user to log in by calling the `requestLogin` method.

```tsx theme={null}
import { useAuth } from '@microapp-io/react';

function Home() {
  const { requestLogin } = useAuth();

  return (
    <button onClick={() => requestLogin()}>Log In</button>
  );
}
```

### 5. Get Notified when the Authenticated User Changes

You can get notified when the authenticated user changes passing a callback on Auth initialization

```tsx theme={null}
  import { useAuth } from '@microapp-io/react';

  function Home() {
    const { requestLogin } = useAuth({
      onChange: (user) => console.log('Auth user changed', user),
    });

    requestLogin();
  }
```

### 6. Example Usage

Here is an example of how you can use the `useAuth` hook in your microapp:

```tsx theme={null}
import { useAuth } from "@microapp-io/react";

function Home() {
  const {
    isAuthenticated,
    isLoading,
    user,
    error,
    requestLogin,
  } = useAuth({
    onChange: (user) => console.log('Auth user changed', user),
  });

  if (isLoading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>Error: {error.message}</p>;
  }

  if (!isAuthenticated) {
    return <button onClick={() => requestLogin()}>Log In</button>;
  }
}
```