@docyrus/ui-pro-ai-assistant

A full-featured, drop-in AI assistant chat UI for React. Ships with multi-turn conversations, a work canvas, project management, multi-model and multi-agent support, voice input, file uploads, deep research, and built-in i18n for 9 languages.

Highlights

• Plug-and-play chat interface — Modal or inline rendering with a single component.
• Work canvas — AI-generated outputs (text, code, spreadsheets, images, charts, documents) are rendered in type-specific viewers side-by-side with the conversation.
• Projects & sessions — Organize conversations into projects, manage threads, and persist context. Session list shows creation date and author on hover.
• Multi-model & multi-agent — Let users switch between AI models and agent deployments on the fly. Agent avatars display in the header and message list.
• Deep research — Extended research mode with live progress streaming.
• AI memories — Persistent memory management across sessions.
• Edit & resend prompts — Hover any user message to edit it; subsequent assistant replies are archived server-side and the conversation regenerates from that point.
• Voice input — Browser-native speech-to-text.
• File uploads — Attach files to messages with configurable format restrictions.
• Agent trigger widget — Standalone agent carousel with prompt input, per-agent capabilities, model/reasoning selection, and suggestion chips. Decoupled from the chat UI — wire it to any destination.
• Chromeless mode — Optionally hide the header and/or border for seamless embedding.
• i18n — English, German, Spanish, French, Italian, Portuguese, Greek, Slovenian, Turkish.
• Vite plugin — Optional dev-server middleware for Plate editor AI commands.

Installation

npm install @docyrus/ui-pro-ai-assistant

Peer dependencies

npm install @docyrus/api-client @docyrus/ui-pro-shared react react-dom

| Peer | Version | |------|---------| | @docyrus/api-client | >= 0.1.0 | | @docyrus/ui-pro-shared | >= 0.0.1 | | react | ^19 | | react-dom | ^19 | | vite | >= 5.0.0 (optional) |

Quick start

import "@docyrus/ui-pro-ai-assistant/styles.css";

import { useCallback, useMemo } from "react";
import { useDocyrusAuth } from "@docyrus/signin";
import { AssistantProvider, DocyAssistant } from "@docyrus/ui-pro-ai-assistant";

function App() {
  const { client, status } = useDocyrusAuth();

  const getAuthToken = useCallback(async () => {
    const token = await client?.getAccessToken();
    if (!token) throw new Error("No access token available");
    return token;
  }, [client]);

  const config = useMemo(() => ({
    apiBaseUrl: "https://api.docyrus.com/v1",
    getAuthToken,
    user: {
      id: "current-user-id",
      firstname: "Ada",
      lastname: "Lovelace",
      email: "[email protected]",
      photo: "https://example.com/avatar.png",
    },
  }), [getAuthToken]);

  if (status !== "authenticated" || !client) {
    return <p>Authenticating...</p>;
  }

  return (
    <AssistantProvider config={config}>
      <DocyAssistant
        tenantAiAgentId="your-agent-id"
        renderMode="inline"
        enableSidebar
        enableNavDropdown
        className="h-full w-full"
      />
    </AssistantProvider>
  );
}

Modal mode

function ModalExample() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Assistant</button>
      <AssistantProvider config={config}>
        <DocyAssistant
          tenantAiAgentId="your-agent-id"
          renderMode="modal"
          isOpen={open}
          onClose={() => setOpen(false)}
        />
      </AssistantProvider>
    </>
  );
}

Exports

| Entry point | Import path | Description | |-------------|-------------|-------------| | Main | @docyrus/ui-pro-ai-assistant | Components, provider, hooks, and types | | Vite plugin | @docyrus/ui-pro-ai-assistant/vite | Dev-server middleware for Plate AI | | Web worker | @docyrus/ui-pro-ai-assistant/worker | Worker entry for AI command handlers | | Stylesheet | @docyrus/ui-pro-ai-assistant/styles.css | Required CSS — import once at app root |

Exported symbols

// Components
import { DocyAssistant, AgentTriggerWidget } from "@docyrus/ui-pro-ai-assistant";

// Provider & config
import {
  AssistantProvider,
  useAssistantConfig,
} from "@docyrus/ui-pro-ai-assistant";

// i18n
import {
  AssistantI18nProvider,
  useAssistantTranslation,
} from "@docyrus/ui-pro-ai-assistant";

// Types
import type {
  AssistantConfig,
  AssistantUser,
  AgentTriggerWidgetProps,
  InitialFeatureFlags,
  PromptFeatureFlags,
  Project,
  Work,
  WorkTypes,
} from "@docyrus/ui-pro-ai-assistant";

// Vite plugin (separate entry)
import { plateEditorPlugin } from "@docyrus/ui-pro-ai-assistant/vite";

API reference

<AssistantProvider>

Wraps your component tree to provide API configuration context. Must be an ancestor of <DocyAssistant>.

<AssistantProvider config={config}>
  {children}
</AssistantProvider>

AssistantConfig

| Property | Type | Required | Description | |----------|------|----------|-------------| | apiBaseUrl | string | Yes | Base API URL, e.g. "https://api.docyrus.com/v1" | | getAuthToken | () => Promise<string> | Yes | Async callback returning a valid Bearer token | | user | AssistantUser | Yes | Current authenticated user. Used to filter sessions/projects to the active user and to display name and avatar in the chat | | getDataSourceSchema | (id: string) => Promise<DataSourceSchema \| null> | No | Resolver for data source schemas |

AssistantUser

interface AssistantUser {
  id: string;       // required — used for server-side filtering
  email?: string;   // optional — shown as fallback display name
  firstname?: string;
  lastname?: string;
  photo?: string;   // optional — avatar in chat messages
}

Note: user.id must be the authenticated user's UUID as stored in Docyrus. Without it, the session list will not be filtered and all tenant users' threads will be visible.

<DocyAssistant>

The main chat interface component.

Core

| Prop | Type | Default | Description | |------|------|---------|-------------| | tenantAiAgentId | string | — | Required. ID of the tenant AI agent | | renderMode | "modal" \| "inline" | "modal" | Render as overlay dialog or embedded inline | | isOpen | boolean | — | Modal visibility (modal mode only) | | onClose | () => void | — | Called when the modal closes | | className | string | — | CSS class on the root element |

Appearance

| Prop | Type | Default | Description | |------|------|---------|-------------| | title | string | — | Header title | | description | string | — | Subtitle below the title | | placeholder | string | — | Chat input placeholder | | logo | string | — | Logo image URL | | footerText | string | — | Footer text | | theme | "auto" \| "light" \| "dark" | "auto" | Color theme | | variant | "default" \| "docked" \| "expanded" | "default" | Layout variant | | size | "default" \| "large" | "default" | Component size |

Layout

| Prop | Type | Default | Description | |------|------|---------|-------------| | enableSidebar | boolean | true | Show the session list sidebar | | enableNavDropdown | boolean | false | Show navigation dropdown | | enableWelcomePage | boolean | true | Show a welcome landing page on first open with agent greeting, inline prompt input, and recent sessions. Sidebar and header are hidden in this view. Dismissed on interaction (new chat, session click, or message send) | | defaultFullscreen | boolean | false | Start in fullscreen | | hideExpand | boolean | false | Hide the fullscreen toggle | | hideCloseButton | boolean | false | Hide the close (X) button in the header | | hideAgentSelector | boolean | false | Hide the agent selector dropdown; shows agent name as static text instead | | hideBorder | boolean | false | Hide the outer border and shadow of the assistant container | | showHeader | boolean | true | Show the header bar; when false the agent selector moves to the top of the sidebar | | maxMessages | number | — | Max messages to keep in context |

Features

| Prop | Type | Default | Description | |------|------|---------|-------------| | supportWebSearch | boolean | true | Web search | | supportThinking | boolean | true | Thinking / reasoning mode | | supportFiles | boolean | true | File uploads | | supportDocumentSearch | boolean | true | Document search | | supportDeepResearch | boolean | true | Deep research mode | | supportMultiModels | boolean | true | Model selector (also read from agent config supportMultipleModels) | | supportWorkCanvas | boolean | true | Work canvas panel | | supportedFileFormats | string[] | — | Allowed upload MIME types / extensions | | enableVoice | boolean | false | Voice input mode | | enableMicrophone | boolean | true | Microphone button | | enableSharing | boolean | false | Show share button on thread headers |

Note: Feature props serve as defaults. When the agent deployment is loaded, the API response capabilities (supportWebSearch, documentSearch, supportDeepResearch, supportThinking, featureWorks, supportFiles, supportMultipleModels, promptOptimizationChoice) take precedence over prop values.

Agent selection

| Prop | Type | Default | Description | |------|------|---------|-------------| | agentSelectorUrl | string | "/ai/agent-deployments" | Deployment selector endpoint | | baseAgentSelectorUrl | string | "/ai/agent-deployments/base" | Base agent selector endpoint | | onAgentChange | (agentId: string, agentType: "base" \| "deployment") => void | — | Fires when the active agent changes |

API

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiEndpoint | string | "/ai/agents/:agentId/chat" | Chat endpoint template (:agentId is replaced at runtime) | | hostEnvironment | string | — | Host environment identifier sent to the chat endpoint as hostEnvironment. The backend uses this to filter the tool list bound to the agent so only tools available in the current environment are exposed. Common values: "web", "desktop", "chrome", "word", "excel", "powerpoint", "outlook" |

Callbacks

| Prop | Type | Description | |------|------|-------------| | onMessageSend | (message: string) => void | Fires when a message is sent | | onVoiceStart | () => void | Fires when voice recording starts | | onVoiceEnd | () => void | Fires when voice recording ends | | onShare | (info: { dataSourceId: string; recordId: string }) => void | Custom share handler. When provided, the thread header share button calls this instead of the built-in sharing editor |

Initial prompt

| Prop | Type | Default | Description | |------|------|---------|-------------| | initialPrompt | string | — | When provided, the assistant auto-sends this message on mount. Useful when launching the assistant from an agent trigger widget or deep link | | initialModelId | string | — | Model ID to pre-select when auto-sending the initial prompt | | initialFeatures | InitialFeatureFlags | — | Feature flags to enable when auto-sending the initial prompt | | initialFiles | File[] | — | Files to attach when auto-sending the initial prompt |

<AgentTriggerWidget>

A standalone agent discovery and prompt input component. Displays agents in a carousel with per-agent capabilities, model selection, reasoning levels, and suggestion chips. Fully decoupled from DocyAssistant — the consumer decides what happens on submit.

import { AssistantProvider, AgentTriggerWidget } from "@docyrus/ui-pro-ai-assistant";

<AssistantProvider config={config}>
  <AgentTriggerWidget
    agentIds={["agent-id-1", "agent-id-2"]}
    onSubmit={(agentId, prompt, features, modelId) => {
      // Open DocyAssistant, navigate to a chat page, call an API, etc.
    }}
  />
</AssistantProvider>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | agentIds | string[] | — | Required. Agent IDs to display in the carousel | | className | string | — | CSS class on the root element | | placeholder | string | — | Prompt input placeholder text | | onSubmit | (agentId, prompt, features, modelId?) => void | — | Fires when the user submits a prompt. Receives the selected agent ID, prompt text, feature flags, and optional model ID |

PromptFeatureFlags

The features object passed to onSubmit:

interface PromptFeatureFlags {
  webSearch: boolean;
  thinking: boolean;
  deepResearch: boolean;
  documentSearch: boolean;
  workCanvas: boolean;
}

InitialFeatureFlags

Used by DocyAssistant.initialFeatures — all fields are optional since you only need to set the ones you want enabled:

interface InitialFeatureFlags {
  webSearch?: boolean;
  thinking?: boolean;
  deepResearch?: boolean;
  documentSearch?: boolean;
  workCanvas?: boolean;
}

Combining with DocyAssistant

function MyPage() {
  const [assistantOpen, setAssistantOpen] = useState(false);
  const [agentId, setAgentId] = useState<string | null>(null);
  const [initialPrompt, setInitialPrompt] = useState<string>();

  return (
    <AssistantProvider config={config}>
      <AgentTriggerWidget
        agentIds={agentIds}
        onSubmit={(id, prompt) => {
          setAgentId(id);
          setInitialPrompt(prompt);
          setAssistantOpen(true);
        }}
      />
      {assistantOpen && agentId && (
        <DocyAssistant
          isOpen
          onClose={() => setAssistantOpen(false)}
          tenantAiAgentId={agentId}
          initialPrompt={initialPrompt}
          renderMode="modal"
        />
      )}
    </AssistantProvider>
  );
}

useAssistantConfig()

Returns the AssistantConfig from the nearest AssistantProvider. Throws if used outside the provider.

const { apiBaseUrl, getAuthToken } = useAssistantConfig();

useAssistantTranslation()

Returns the t function for translating assistant UI strings.

const { t } = useAssistantTranslation();
// t("common.untitled") → "Untitled"

plateEditorPlugin()

Vite plugin that adds dev-server middleware for Plate editor AI commands (/api/ai/command and /api/ai/copilot). Only needed if you use the Plate rich-text editor AI features.

// vite.config.ts
import { defineConfig } from "vite";
import { plateEditorPlugin } from "@docyrus/ui-pro-ai-assistant/vite";

export default defineConfig({
  plugins: [plateEditorPlugin()],
});

Work canvas types

AI-generated outputs open in a side canvas with type-specific viewers:

| WorkTypes value | Viewer | Description | |-------------------|--------|-------------| | Text | Plate.js rich editor | Editable rich text | | Code | Sandpack | Live code preview | | Data / Xlsx | Univer spreadsheet | Full spreadsheet with formulas | | Image | Image viewer | Generated images | | Chart | VChart | Interactive charts | | Html / HtmlTemplate | HTML iframe | Rendered HTML | | Docyment / Docx / Pptx | Document viewer | Office document preview | | App | App renderer | Custom applications | | Record | Record view | Structured data display | | DataSource | Data explorer | Data source output | | CustomQuerySql / CustomQueryJson | Query result | Query output display |

Internationalization

9 built-in locales: en, de, es, fr, it, pt, el, sl, tr.

The language is auto-detected. To override, wrap with AssistantI18nProvider:

import { AssistantI18nProvider } from "@docyrus/ui-pro-ai-assistant";

<AssistantI18nProvider locale="de">
  <DocyAssistant ... />
</AssistantI18nProvider>

Types

Project

interface Project {
  id: string;
  name: string;
  tenant_ai_agent_id: string;
  description?: string;
  instructions?: string;
  tenant_ai_agent_deployment_id?: string;
  color?: string;
  icon?: string;
  shared_to?: string[];
  created_by?: string;
}

Work

interface Work {
  id: string;
  title: string;
  type?: WorkTypes;
  content_json?: unknown;
  content_text?: string;
  description?: string;
  image_url?: string;
  core_ai_model_id?: string | null;
  base_message_id?: string;
  base_thread_id?: string;
  tenant_ai_agent_id?: string;
  tenant_ai_agent_deployment_id?: string;
  tenant_data_source_id?: string;
  tenant_ai_project_id?: string;
  shared_to?: string[];
  created_by?: string;
  created_on?: Date;
  last_modified_on?: Date;
}

WorkTypes

const WorkTypes = {
  Record: "record",
  Data: "data",
  Text: "text",
  Code: "code",
  Image: "image",
  Xlsx: "xlsx",
  Docx: "docx",
  Pptx: "pptx",
  Html: "html",
  Docyment: "docyment",
  Chart: "chart",
  DataSource: "data_source",
  HtmlTemplate: "html_template",
  CustomQuerySql: "custom_query_sql",
  CustomQueryJson: "custom_query_json",
  App: "app",
} as const;

Environment variables

When using with Vite, set these in your .env:

VITE_DOCYRUS_API_URL=https://api.docyrus.com
VITE_DOCYRUS_CLIENT_ID=your-client-id
VITE_DOCYRUS_AGENT_ID=your-agent-id

# Optional — for Plate editor AI plugin
VITE_DOCYRUS_EDITOR_AGENT_ID=your-editor-agent-id

Requirements

• React 19+
• ESM only ("type": "module")
• Tailwind CSS v4 (the stylesheet uses Tailwind utilities)

License

MIT