Skip to main content

Web components

Uxopian AI ships two standard HTML custom elements: <chat-element> and <admin-element>. They are built with React 19 and wrapped using @r2wc/react-to-web-component. They are self-contained and require no build step on the consuming application side.

How the bundle is served​

Figure: The browser loads web component bundles from the gateway, which forwards to the WebComponentController in uxopian-ai.

The web component bundles are compiled and embedded in the uxopian-ai image. They are served by WebComponentController under /api/web-components/. The gateway forwards these paths as public (no authentication required for static assets).

The served endpoints are:

AssetEndpoint
Chat JavaScript/api/web-components/chat/script
Chat CSS/api/web-components/chat/style
Admin JavaScript/api/web-components/admin/script
Admin CSS/api/web-components/admin/style

To load the chat component, add these tags to the host application:

<link rel="stylesheet" href="https://your-gateway/api/web-components/chat/style" />
<script src="https://your-gateway/api/web-components/chat/script"></script>

chat-element​

The chat interface custom element. Registered as <chat-element>. Accepts these attributes:

AttributeTypeDescription
endpointstringBase URL for the uxopian-ai REST API (e.g., https://gateway-host/api/v1)
wsendpointstringWebSocket base URL (e.g., wss://gateway-host/ws)
conversationidstringConversation ID to open (for openChat)
requeststringJSON-serialized Request object (for createChat)
promptidstringPrompt ID to pre-load when creating a new conversation

admin-element​

The admin interface custom element. Registered as <admin-element>. Uses React Router internally with these routes:

RouteContent
/Dashboard
/promptsPrompt list
/prompts/:idPrompt detail and editor
/llm-providersLLM provider list
/llm-providers/:idLLM provider configuration
/usersUser list with conversation statistics
/users/:idUser detail
/statisticsUsage statistics and charts

Global window API​

The bundle exposes these functions on the window object:

window.openChat(params)​

Reopens an existing conversation.

window.openChat({
  endpoint: 'https://gateway/api/v1',
  wsEndpoint: 'wss://gateway/ws',
  conversationId: 'existing-conv-id'
});

window.createChat(params)​

Creates a new conversation, optionally with an initial request.

window.createChat({
  endpoint: 'https://gateway/api/v1',
  wsEndpoint: 'wss://gateway/ws',
  promptId: 'arenderContext',         // optional: pre-load a prompt
  request: requestObject              // optional: send an initial request
});

window.connectWebSocket(wsEndpoint, userId)​

Opens a WebSocket connection to the streaming endpoint. Returns a cleanup function.

const disconnect = window.connectWebSocket('wss://gateway/ws', 'user-123');
// later:
disconnect();

Builder classes​

Three fluent builder classes are exposed on window for constructing request payloads:

RequestBuilder​

const request = new window.RequestBuilder()
  .addInput(inputObject)
  .build();

InputBuilder​

const input = new window.InputBuilder()
  .role('USER')
  .addContent(contentObject)
  .build();

ContentBuilder​

const content = new window.ContentBuilder()
  .type('prompt')
  .value('arenderContext')
  .payload({ documentId: 'doc-123' })
  .build();

const textContent = new window.ContentBuilder()
  .type('text')
  .value('Summarize this document.')
  .build();

Content types: text, prompt, goal, image.

Last updated on