React

Use the <stackone-hub> custom element from @stackone/hub directly in JSX. This is the right choice if you can’t add another copy of React to your bundle, or if you want the same code path as your non-React surfaces.

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 need the framework-agnostic build.

Install the package

npm install @stackone/hub

yarn add @stackone/hub

pnpm add @stackone/hub

The import is side-effecting — it registers <stackone-hub> on customElements.

// 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>,
);

Type the element for JSX

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
      >;
    }
  }
}

Get a session token from your backend

Add the element and listen for events

React 19 passes unknown props through as attributes, but events still need to be wired with addEventListener via a ref — React doesn’t synthesize custom DOM events.

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"
    />
  );
}

Attribute reference

All scalar StackOneHub props map to kebab-case HTML attributes — see the vanilla guide for the full table.

Events

Native DOM CustomEvents on the element:

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

React’s onSuccess={...} JSX shorthand does not fire on native DOM CustomEvents — React doesn’t synthesize custom DOM events. Subscribe with addEventListener via a ref instead.

Next steps

Backend setup

Generate session tokens from your backend.

React component path

Use <StackOneHub> instead, with native React props.

Quickstart

Connect Tools

Dashboard

Build Connectors

Attribute reference

Events

Next steps

Backend setup

React component path

​Attribute reference

​Events

​Next steps

Backend setup

React component path

Attribute reference

Events

Next steps