Props Reference

The Copilot accepts one required prop (mode) and a set of optional props that control the worker context, panel visibility, styling, and callbacks. Some props are build-specific - the Build column below indicates where each prop applies.

Required props

Prop	Type	Description	Example
mode	string	Application mode. Controls UI layout and features. See Modes.	"embed"

Optional props

Prop	Type	Default	Build	Description	Example
userId	string	auto-generated	All	Unique identifier for the current user (email, UUID, or internal user ID).	"user-123"
type	string	"worker"	All	Context type. Determines which entity the copilot interacts with. Options: worker, agent.	"worker"
workerId	string	''	All	ID of a specific worker to use explicitly.	"worker-456"
agentId	string	''	All	ID of the AI agent to use (requires workerId).	"agent-789"
version	number | null	null	All	Version number of the worker or agent (internal use).	1
showConversations	boolean	mode-dependent	All	Show or hide the conversations panel in the sidebar. Default varies by mode.	true
showActivity	boolean	mode-dependent	All	Show or hide the activity / trace panel for debugging. Default varies by mode.	false
systemContext	Record<string, string>	undefined	All	Dynamic metadata passed to the postCopilotMessage API.	{ firstName: 'John' }
containerId	string	-	Browser ESM, UMD	DOM element ID where the widget mounts. Not used by the React build.	"copilot-container"
shadowDom	boolean	true	Browser ESM	Render inside a shadow root to isolate styles. UMD is always shadow-DOM-enabled; React manages this internally.	true

Note

Panel visibility defaults vary by mode. See the Modes panel visibility table for the per-mode defaults of showConversations and showActivity.

React example

import { Copilot } from '@/lib/copilot';

export function DashboardPage() {
  return (
    <Copilot
      userId="user-123"
      mode="embed"
      systemContext={{ firstName: 'John' }}
    />
  );
}

Browser ESM example

For the recommended non-React path, props are passed to CmtnCopilot.init() after dynamically importing the SDK. See the Browser ESM guide for the full setup.

<div id="copilot-container"></div>
<script type="module">
  const { initializeCopilotSDK, CmtnCopilot } = await import('<YOUR_CDN_URL>');

  initializeCopilotSDK('<YOUR_APP_KEY>', { environment: 'production' });

  const instance = CmtnCopilot.init({
    containerId: 'copilot-container',
    mode: 'embed',
    userId: 'user-123',
  });
</script>

UMD example

The UMD build is a legacy fallback for environments without dynamic import(). Props are passed to sdk.Copilot.init(). See the UMD guide for the full setup.

<div id="copilot-container"></div>
<script>
  const sdk = window.initializeCommotionSDK('<YOUR_APP_KEY>');
  const copilot = sdk.Copilot.init({
    containerId: 'copilot-container',
    userId: 'user-123',
    mode: 'embed',
  });
</script>