@athenaintel/react

React SDK for building AI-powered chat applications with the Athena platform.

Installation

npm install @athenaintel/react

If you use the PropelAuth-specific provider from @athenaintel/react/auth, also install:

npm install @propelauth/react

Quick Start

import { AthenaProvider, AthenaChat, Toolkits } from '@athenaintel/react';
import '@athenaintel/react/styles.css';

function App() {
  return (
    <AthenaProvider
      config={{ apiKey: 'your-api-key' }}
      tools={[Toolkits.DOCUMENT, Toolkits.WEB_SEARCH]}
    >
      <AthenaChat />
    </AthenaProvider>
  );
}

Provider Config

<AthenaProvider config={{ environment: 'staging' }}>
  <AthenaChat />
</AthenaProvider>

<AthenaProvider
  config={{
    apiUrl: 'https://sync.example.com/api/chat',
    backendUrl: 'https://api.example.com',
    appUrl: 'https://app.example.com',
  }}
>
  <AthenaChat />
</AthenaProvider>

config accepts apiKey, token, apiUrl, backendUrl, appUrl, trustedParentOrigins, and environment. Top-level apiKey, token, apiUrl, backendUrl, appUrl, and environment props remain supported as compatibility aliases, but config is now the preferred API.

If config.appUrl is omitted, the provider resolves it from the parent bridge or from the matching Athena environment defaults. Known Athena staging and production apiUrl and backendUrl values automatically fall back to the corresponding frontend origin.

Use trustedParentOrigins when the SDK runs inside an iframe on a private-cloud or custom parent domain and you want to explicitly allow postMessage auth/config from that parent.

Authentication

Same-origin SSO defaults

import { AthenaSSOProvider } from '@athenaintel/react/auth';
import { AthenaChat, AthenaProvider } from '@athenaintel/react';

function App() {
  return (
    <AthenaSSOProvider>
      <AthenaProvider enableThreadList>
        <AthenaChat />
      </AthenaProvider>
    </AthenaSSOProvider>
  );
}

By default, AthenaSSOProvider uses same-origin SSO endpoints:

• /api/sso/userinfo
• /api/sso/initiate
• /api/sso/logout

This makes the SSO URLs optional when your frontend is reverse-proxied with the backend.

Cross-origin SSO backend

import { AthenaSSOProvider } from '@athenaintel/react/auth';

<AthenaSSOProvider ssoBaseUrl="https://api.example.com">
  <AthenaProvider
    config={{
      backendUrl: 'https://api.example.com/api/assistant-ui',
      apiUrl: 'https://sync.example.com/api/chat',
      trustedParentOrigins: ['https://app.example.com'],
    }}
    enableThreadList
  >
    <AthenaChat />
  </AthenaProvider>
</AthenaSSOProvider>

If you need full control, ssoUserInfoUrl, ssoLoginUrl, and ssoLogoutUrl remain available as explicit overrides.

Citation Links

When you render chat inside <AthenaLayout>, Athena citation links (app.athenaintel.com/dashboard/spaces?...) now open the referenced asset in the SDK asset pane by default instead of navigating away.

If your host app wants different behavior, configure linkClicks on <AthenaProvider> or use useAthenaLinkClickHandler() inside a custom message renderer. The hook runs for every rendered link; only Athena citation links are intercepted by default.

import { useMemo } from 'react';
import { AthenaChat, AthenaLayout, AthenaProvider } from '@athenaintel/react';

function App() {
  const linkClicks = useMemo(
    () => ({
      onClick: (link) => {
        if (link.kind !== 'athena-citation' || !link.openInAssetPanel) {
          return false;
        }

        console.log('Citation clicked:', link.citation?.assetId);
        link.openInAssetPanel();
        return true;
      },
    }),
    [],
  );

  return (
    <AthenaProvider linkClicks={linkClicks}>
      <AthenaLayout>
        <AthenaChat />
      </AthenaLayout>
    </AthenaProvider>
  );
}

Set linkClicks={{ interceptAthenaCitations: false }} to keep Athena citation links opening in the browser while still letting your app observe all link clicks.

Theming

import { themes } from '@athenaintel/react';

<AthenaProvider theme={themes.dark}>
<AthenaProvider theme={{ ...themes.dark, primary: '#8b5cf6' }}>
<AthenaProvider theme={{ primary: '#e11d48', radius: '1rem' }}>

Preset themes: light, dark, midnight, warm, purple, green.

Key Components

• <AthenaProvider> — Runtime, auth, theming, and configuration
• <AthenaChat> — Full chat UI with composer, messages, and tool rendering
• <AthenaLayout> — Split-pane layout with asset panel
• <ThreadList> — Conversation history sidebar
• Toolkits — Constants for all available backend toolkits

Composer Hooks

Use useAppendToComposer() when you want to prefill a draft without sending it.

Use useSendMessage() for workflow buttons, sidebar shortcuts, and other UI that lives outside <AthenaChat> but still needs to submit a prompt.

import { useSendMessage } from '@athenaintel/react';

function WorkflowButton() {
  const sendMessage = useSendMessage();

  return (
    <button onClick={() => void sendMessage('Run the quarterly workflow')}>
      Run workflow
    </button>
  );
}

License

Proprietary. For licensed enterprise customers only.