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

# StackOne Hub (React)

> Embed the native React `<StackOneHub>` component to let end-users connect their accounts

The **StackOne Hub** (`@stackone/hub`) is a native React `<StackOneHub>` component that renders directly in your React tree. It offers filtering, search, detailed error messages, and full theming support. It is the **recommended** way to implement the Hub.

## Quick start

<Steps>
  <Step title="Install the package">
    <CodeGroup>
      ```bash npm theme={null}
      npm install @stackone/hub
      ```

      ```bash yarn theme={null}
      yarn add @stackone/hub
      ```

      ```bash pnpm theme={null}
      pnpm add @stackone/hub
      ```
    </CodeGroup>
  </Step>

  <Step title="Get a session token from your backend">
    The Hub needs a [connect session token](/embed/connect-session) to securely communicate with StackOne. This token must be generated server-side to keep your API key secure.

    ```typescript theme={null}
    async function retrieveConnectSessionToken() {
      const response = await fetch('/api/stackone/connect-session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ username: 'jane@example.com' }),
      });
      const { token } = await response.json();
      return token;
    }
    ```

    To route the session through a specific **connector profile** (when a provider has more than one), pass its `connector_profile_id` when creating the session. See [Target a specific connector profile](/embed/connect-session#target-a-specific-connector-profile).
  </Step>

  <Step title="Add the component">
    ```tsx theme={null}
    import { StackOneHub } from "@stackone/hub";
    import { useEffect, useState } from "react";

    function ConnectorPage() {
      const [token, setToken] = useState<string>();

      useEffect(() => {
        retrieveConnectSessionToken().then(setToken);
      }, []);

      if (!token) return <div>Loading...</div>;

      return (
        <StackOneHub
          token={token}
          onSuccess={(account) => {
            console.log('Connected:', account.id, account.provider);
          }}
          onCancel={() => console.log('Cancelled')}
          onClose={() => console.log('Closed')}
        />
      );
    }
    ```
  </Step>

  <Step title="Let users link their accounts">
    Your end-users now use the Hub to connect their accounts. Each successful link fires `onSuccess` with the linked account id — persist against your user — it's the account ID you'll use with every [action call](/embed/call-actions/overview).

    You can also capture it server-side from the `account.created` [webhook event](/embed/handle-account-events).
  </Step>
</Steps>

## Properties

The `StackOneHub` component accepts these properties:

| Property | Type | Default | Description |
| - | - | - | - |
| `token` | `string` | — | Connect session token from your backend |
| `mode` | `'integration-picker'` | `'integration-picker'` | Hub mode |
| `accountId` | `string` | — | Pre-select a specific account to edit |
| `baseUrl` | `string` | `'https://api.stackone.com'` | StackOne API base URL |
| `appUrl` | `string` | `'https://app.stackone.com'` | StackOne App URL |
| `height` | `string` | `'500px'` | Component height |
| `theme` | `'light' \| 'dark' \| PartialMalachiteTheme` | `'light'` | Theme configuration |
| `showFooterLinks` | `boolean` | `true` | Show footer links |
| `onSuccess` | `(account: { id: string; provider: string }) => void` | — | Called when account is connected |
| `onCancel` | `() => void` | — | Called when user cancels |
| `onClose` | `() => void` | — | Called when hub closes |
| `onCloseLabel` | `string` | `'Close'` | Custom label for the close button on the success screen |

```tsx theme={null}
import { StackOneHub } from "@stackone/hub";

<StackOneHub
  token={sessionToken}
  mode="integration-picker"
  height="600px"
  theme="dark"
  showFooterLinks={false}
  onSuccess={(account) => {
    console.log(`Connected ${account.provider} with ID ${account.id}`);
  }}
  onCancel={() => console.log('User cancelled')}
  onClose={() => console.log('Hub closed')}
  onCloseLabel="Done"
/>
```

<Tip>
  Use `onSuccess` to update your UI or trigger backend syncs. Use `onClose` as a cleanup handler that always runs.
</Tip>

## Theming

The Hub supports full theming with the `theme` property:

```tsx theme={null}
<StackOneHub
  token={token}
  theme="dark"  // or "light"
/>
```

For custom theming, pass a `PartialMalachiteTheme` object:

```tsx theme={null}
<StackOneHub
  token={token}
  theme={{
    colors: {
      primary: {
        background: '#6366f1',
        foreground: '#ffffff',
      },
      card: {
        background: '#fafafa',
      },
    },
  }}
/>
```

See the [@stackone/hub repository](https://github.com/StackOneHQ/hub) for full theme options.

<Note>
  For non-React stacks, use the [web components](/embed/account-linking/stackone-hub-web-component) build (`<stackone-hub>`). For the older hook API, see [@stackone/react-hub](https://www.npmjs.com/package/@stackone/react-hub) on npm.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Call Actions" icon="code" href="/embed/call-actions/overview">
    With the account linked, call its actions from your product over the Agent SDK, MCP, A2A, or RPC/HTTP.
  </Card>

  <Card title="Embed Overview" icon="map" href="/embed/getting-started">
    Return to the end-to-end embedding journey.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.