> ## 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>