@apideck/vault-react/README.md

React hook for the Apideck Vault component.

# Vault React

A React hook to easily embed [Apideck Vault](https://www.apideck.com/products/vault) in any React application.

<img src="https://user-images.githubusercontent.com/8850410/208065819-716c6e02-98c9-4df5-b687-e5acd1e3c4e5.png" width="100%" />

**Vault React** | [Vault Vue](https://github.com/apideck-libraries/vue-vault) | [Vault JS](https://github.com/apideck-libraries/vault-js)

## Installation

### Package

```sh
npm install @apideck/vault-react
```

## Prerequisites

Before opening the Vault modal with `@apideck/vault-react`, you need to create a Vault session from your backend using the Vault API or one of our [SDKs](https://docs.apideck.com/sdks). Find out more in the [docs](https://docs.apideck.com/apis/vault/reference#operation/sessionsCreate).

## Usage

Pass the JWT you got from the Vault session to the `open` function to open the Vault modal.

```tsx
import { useVault } from '@apideck/vault-react';

function App() {
  const { open } = useVault();

  return (
    <button onClick={() => open({ token: 'REPLACE_WITH_SESSION_TOKEN' })}>
      Open Vault
    </button>
  );
}

export default App;
```

If you want to only show integrations for a single Unified API, you can do that by passing the `unifiedApi` prop. If you want to open Vault for only a single integration, you can provide the `serviceId` prop.

```tsx
import { useVault } from '@apideck/vault-react';

function App() {
  const { open } = useVault();

  return (
    <button
      onClick={() =>
        open({
          token: 'REPLACE_WITH_SESSION_TOKEN',
          unifiedApi: 'file-storage',
          serviceId: 'dropbox',
        })
      }
    >
      Open Vault
    </button>
  );
}

export default App;
```

If you want to get notified when the modal opens and closes, you can provide the `onReady` and `onClose` options. You can also provide the `onConnectionChange` and `onConnectionDelete` options to get notified when the state of a connection changes or gets deleted.

```tsx
import { useVault } from '@apideck/vault-react';

function App() {
  const { open, close } = useVault();

  function onClose() {
    console.log('close!');
  }

  function onReady() {
    console.log('ready!');
  }

  function onConnectionChange(connection: Connection) {
    console.log('changed!', connection);
    if (connection.state === 'callable') {
      close();
    }
  }

  function onConnectionDelete(connection: Connection) {
    console.log('ready!', connection);
  }

  return (
    <button
      onClick={() =>
        open({
          token: 'REPLACE_WITH_SESSION_TOKEN',
          onReady,
          onClose,
          onConnectionChange,
          onConnectionDelete,
        })
      }
    >
      Open Vault
    </button>
  );
}

export default App;
```

If you want to open a specific view you can pass the `initialView` prop. The available views are `settings`, `configurable-resources`, and `custom-mapping`.

```js
import { useVault } from '@apideck/vault-react';

function App() {
  const { open, close } = useVault();

  return (
    <button
      onClick={() =>
        open({
          token: 'REPLACE_WITH_SESSION_TOKEN',
          unifiedApi: 'accounting',
          serviceId: 'quickbooks',
          initialView: 'custom-mapping',
        })
      }
    >
      Open Vault
    </button>
  );
}
```

If you want to open vault in a specific language you can pass a locale. The available locales are `en` (default), `nl`, `de`, `fr`, and `es`.

```js
import { useVault } from '@apideck/vault-react';

function App() {
  const { open, close } = useVault();

  return (
    <button
      onClick={() =>
        open({
          token: 'REPLACE_WITH_SESSION_TOKEN',
          locale: 'nl',
        })
      }
    >
      Open Vault
    </button>
  );
}
```

If you want to show the language switch at the bottom you can provide the `showLanguageSwitch` prop.

```js
import { useVault } from '@apideck/vault-react';

function App() {
  const { open, close } = useVault();

  return (
    <button
      onClick={() =>
        open({
          token: 'REPLACE_WITH_SESSION_TOKEN',
          locale: 'nl',
          showLanguageSwitch: true,
        })
      }
    >
      Open Vault
    </button>
  );
}
```