StackOne Hub Web Component

@stackone/hub ships a framework-agnostic custom element, <stackone-hub>, that you can drop into any HTML page or framework template. React and ReactDOM are bundled into the web-component build, so consumers don’t need React installed. Use the web component for any non-React stack, or when you want a single code path across multiple frameworks. For a native React app, the StackOne Hub (Native) is usually a better fit. It integrates with your React tree and lets you pass callbacks as props.

Quick start

Install and register

Install the package and register <stackone-hub>. The import is side-effecting. It registers <stackone-hub> on customElements.

Vanilla HTML
React
Vue 3
Svelte 5
Angular

Point a <script> tag at the IIFE bundle on a CDN. The script is side-effecting. It registers <stackone-hub> on customElements.

<script src="https://unpkg.com/@stackone/hub/dist/webcomponent.js"></script>

If you’d rather install via npm and bundle the script yourself, use the import '@stackone/hub/webcomponent' pattern shown in the other tabs.

If you’re starting fresh in React, the <StackOneHub> component is usually a better fit. It integrates with your React tree and lets you pass callbacks as props. Reach for the web component when you can’t add another copy of React to your bundle, or when you want the same code path as your non-React surfaces.

Install the package:

npm install @stackone/hub

yarn add @stackone/hub

pnpm add @stackone/hub

// src/main.tsx
import '@stackone/hub/webcomponent';
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

const root = document.getElementById('root');
if (!root) {
  throw new Error('#root element not found');
}
createRoot(root).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

Tell TypeScript that <stackone-hub> is a valid JSX tag:

declare global {
  // biome-ignore lint/style/noNamespace: JSX intrinsic-element augmentation requires namespace syntax.
  namespace JSX {
    interface IntrinsicElements {
      'stackone-hub': React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement> & {
          token?: string;
          mode?: string;
          'base-url'?: string;
          'app-url'?: string;
          'account-id'?: string;
          height?: string;
          theme?: string;
          'show-footer-links'?: boolean | string;
          'on-close-label'?: string;
        },
        HTMLElement
      >;
    }
  }
}

Install the package:

npm install @stackone/hub

yarn add @stackone/hub

pnpm add @stackone/hub

Vue’s template compiler treats unknown tags as Vue components by default. Mark stackone-hub as a custom element so it falls through to the DOM:

// vite.config.ts
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === 'stackone-hub',
        },
      },
    }),
  ],
});

// src/main.ts
import '@stackone/hub/webcomponent';
import { createApp } from 'vue';
import App from './App.vue';

createApp(App).mount('#app');

Svelte treats unknown tags as custom elements automatically. No extra config required.Install the package:

npm install @stackone/hub

yarn add @stackone/hub

pnpm add @stackone/hub

// src/main.ts
import '@stackone/hub/webcomponent';
import { mount } from 'svelte';
import App from './App.svelte';

const target = document.getElementById('app');
if (!target) {
  throw new Error('#app element not found');
}
mount(App, { target });

Install the package:

npm install @stackone/hub

yarn add @stackone/hub

pnpm add @stackone/hub

Add CUSTOM_ELEMENTS_SCHEMA to the component (or module) that uses <stackone-hub> so Angular accepts unknown tags as custom elements:

// src/app/app.component.ts
import { CUSTOM_ELEMENTS_SCHEMA, Component } from '@angular/core';

@Component({
  selector: 'app-root',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  templateUrl: './app.component.html',
})
export class AppComponent {}

// src/main.ts
import '@stackone/hub/webcomponent';
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent).catch((err) => console.error(err));

Get a session token from your backend

The Hub needs a connect session token to communicate with StackOne. Generate it server-side to keep your API key off the client.

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.

Mount and wire the Hub

Mount the element, set the token, and listen for events:

Vanilla HTML
React
Vue 3
Svelte 5
Angular

<stackone-hub id="hub" mode="integration-picker" height="600px"></stackone-hub>

<script type="module">
  const hub = document.getElementById('hub');
  const token = await retrieveConnectSessionToken();
  hub.setAttribute('token', token);

  hub.addEventListener('success', (event) => {
    console.log('Connected:', event.detail.id, event.detail.provider);
  });

  hub.addEventListener('close', () => {
    console.log('Closed');
  });
</script>

React 19 passes unknown props through as attributes, but events still need to be wired with addEventListener via a ref. React’s onSuccess={...} JSX shorthand does not fire on native DOM CustomEvents.

import { useEffect, useRef, useState } from 'react';

export default function App() {
  const [token, setToken] = useState('');
  const hubRef = useRef<HTMLElement>(null);

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

  useEffect(() => {
    const el = hubRef.current;
    if (!el) return;
    const onSuccess = (event: Event) => {
      const detail = (event as CustomEvent).detail;
      console.log('Connected:', detail.id, detail.provider);
    };
    const onClose = () => console.log('Closed');
    el.addEventListener('success', onSuccess);
    el.addEventListener('close', onClose);
    return () => {
      el.removeEventListener('success', onSuccess);
      el.removeEventListener('close', onClose);
    };
  }, []);

  return (
    <stackone-hub
      ref={hubRef}
      token={token || undefined}
      mode="integration-picker"
      height="600px"
    />
  );
}

Vue passes :prop="value" bindings through as HTML attributes when the tag is registered as a custom element. Vue’s @event shorthand does not fire on native DOM CustomEvents. Subscribe with addEventListener via a ref instead.

<script setup lang="ts">
import { onBeforeUnmount, onMounted, ref, useTemplateRef } from 'vue';

const token = ref('');
const hubRef = useTemplateRef<HTMLElement>('hub');

const onSuccess = (event: Event) => {
  const detail = (event as CustomEvent).detail;
  console.log('Connected:', detail.id, detail.provider);
};
const onClose = () => console.log('Closed');

onMounted(async () => {
  token.value = await retrieveConnectSessionToken();
  hubRef.value?.addEventListener('success', onSuccess);
  hubRef.value?.addEventListener('close', onClose);
});

onBeforeUnmount(() => {
  hubRef.value?.removeEventListener('success', onSuccess);
  hubRef.value?.removeEventListener('close', onClose);
});
</script>

<template>
  <stackone-hub
    ref="hub"
    :token="token"
    mode="integration-picker"
    height="600px"
  ></stackone-hub>
</template>

Svelte passes attribute bindings through directly. Its on:event shorthand does fire on native DOM CustomEvents, so <stackone-hub on:success={...} on:close={...}> works. The example below uses addEventListener via bind:this to keep the typing explicit.

<script lang="ts">
    let token = $state('');
    let hubEl: HTMLElement | undefined = $state();

    $effect(() => {
        retrieveConnectSessionToken().then((t) => {
            token = t;
        });
    });

    $effect(() => {
        if (!hubEl) return;
        const onSuccess = (event: Event) => {
            const detail = (event as CustomEvent).detail;
            console.log('Connected:', detail.id, detail.provider);
        };
        const onClose = () => console.log('Closed');
        hubEl.addEventListener('success', onSuccess);
        hubEl.addEventListener('close', onClose);
        return () => {
            hubEl?.removeEventListener('success', onSuccess);
            hubEl?.removeEventListener('close', onClose);
        };
    });
</script>

<stackone-hub
    bind:this={hubEl}
    {token}
    mode="integration-picker"
    height="600px"
></stackone-hub>

Bind attributes with [attr.name]="value" to keep them as attributes rather than Angular property bindings. Angular’s (event) template binding does fire on native DOM CustomEvents, so (success)="onSuccess($event)" works. The example below uses addEventListener via @ViewChild for explicit teardown in ngOnDestroy.

// src/app/app.component.ts
import {
  AfterViewInit,
  Component,
  CUSTOM_ELEMENTS_SCHEMA,
  ElementRef,
  OnDestroy,
  ViewChild,
} from '@angular/core';

@Component({
  selector: 'app-root',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <stackone-hub
      #hub
      [attr.token]="token || null"
      mode="integration-picker"
      height="600px"
    ></stackone-hub>
  `,
})
export class AppComponent implements AfterViewInit, OnDestroy {
  @ViewChild('hub') hubRef?: ElementRef<HTMLElement>;
  token = '';

  private onSuccess = (event: Event) => {
    const detail = (event as CustomEvent).detail;
    console.log('Connected:', detail.id, detail.provider);
  };
  private onClose = () => console.log('Closed');

  async ngAfterViewInit() {
    this.token = await retrieveConnectSessionToken();
    this.hubRef?.nativeElement.addEventListener('success', this.onSuccess);
    this.hubRef?.nativeElement.addEventListener('close', this.onClose);
  }

  ngOnDestroy() {
    this.hubRef?.nativeElement.removeEventListener('success', this.onSuccess);
    this.hubRef?.nativeElement.removeEventListener('close', this.onClose);
  }
}

Let users link their accounts

Your end-users now use the Hub to connect their accounts. Each successful link fires the success event with the linked account id — persist against your user — it’s the account ID you’ll use with every action call.You can also capture it server-side from the account.created webhook event.

Attributes

The <stackone-hub> element accepts these attributes. All scalar StackOneHub properties map to kebab-case HTML attributes:

Attribute	Type	Default	Description
`token`	string	—	Connect session token from your backend
`mode`	`integration-picker`	`integration-picker`	Hub mode
`base-url`	string	`https://api.stackone.com`	StackOne API base URL
`app-url`	string	`https://app.stackone.com`	StackOne App URL
`height`	string	`500px`	Component height
`theme`	`light` \| `dark` \| JSON object	`light`	Theme keyword or a JSON-encoded `PartialMalachiteTheme`
`account-id`	string	—	Pre-select a specific account to edit
`on-close-label`	string	`Close`	Custom label for the close button
`show-footer-links`	boolean attribute	`true`	Toggle footer visibility

Style Customization

Set the theme attribute to light or dark:

<stackone-hub theme="dark"></stackone-hub>

For custom theming, pass a PartialMalachiteTheme. Because HTML attributes are strings, use JSON.stringify(...) to encode the object first. The theme attribute receives a JSON-encoded PartialMalachiteTheme string, not an object:

Vanilla HTML
Angular

<stackone-hub id="hub"></stackone-hub>

<script type="module">
  const hub = document.getElementById('hub');
  hub.setAttribute(
    'theme',
    JSON.stringify({
      colors: {
        primary: {
          background: '#6366f1',
          foreground: '#ffffff',
        },
        card: {
          background: '#fafafa',
        },
      },
    })
  );
</script>

Bind the theme attribute like any other with [attr.theme], using a component property that holds a JSON-encoded PartialMalachiteTheme, the string produced by JSON.stringify(...), since attributes are strings, not objects:

@Component({
  selector: 'app-root',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <stackone-hub [attr.theme]="themeJson" height="600px"></stackone-hub>
  `,
})
export class AppComponent {
  themeJson = JSON.stringify({
    colors: {
      primary: {
        background: '#6366f1',
        foreground: '#ffffff',
      },
      card: {
        background: '#fafafa',
      },
    },
  });
}

For a keyword theme, bind a plain string (themeJson = 'dark') or set the attribute directly (theme="dark").

See the @stackone/hub repository for full theme options.

Events

Callbacks are dispatched as native DOM CustomEvents on the host element with bubbles: true and composed: true.

Event	`event.detail`
`success`	`{ id: string; provider: string }`
`close`	`undefined`

Framework-emitted event shorthands behave differently from native DOM CustomEvents. React’s onSuccess={...} and Vue’s @event do not fire on them. Subscribe with addEventListener via a ref. Svelte’s on:event and Angular’s (event) do fire on them.

Next steps

Call Actions

With the account linked, call its actions from your product over the Agent SDK, MCP, A2A, or RPC/HTTP.

Embed Overview

Return to the end-to-end embedding journey.

​Quick start

​Attributes

​Style Customization

​Events

​Next steps

Call Actions

Embed Overview

Quick start

Attributes

Style Customization

Events

Next steps