Component reference
Look up PraxisKit properties, methods, events and default behavior by object.
<praxis-agent> renders an agent conversation on your website. Initialize it with element.setOptions(options). This reference covers properties, methods and events. For integration steps, see Embed in a web page.
Initialize
Initial options require api.url, agent.name, and either api.getToken or api.publishableKey. Missing values throw TypeError. Choose getToken for authenticated users or publishableKey for anonymous visitors. Supply one; when both are supplied, the publishable key takes precedence and getToken is not called.
This anonymous example targets Develop. Create a publishable key there, save an embed policy, and allow your host origin. Replace PRAXIS_PUBLISHABLE_KEY and serve this HTML from that origin. A publishable key is not a server API Key. The script URL, version and integrity value must belong to the same release.
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Course assistant</title>
<script type="module"
src="https://kit-develop.praxisusercontent.com/v0.2.8/praxis-kit.js"
integrity="sha384-vey+VZZcFIWJq9Fmv/nmLxspKtXRiL8XiDOfg2g2QFvwZi5MA+tkiQvPBtoMS8eU"
crossorigin="anonymous"></script>
<praxis-agent style="display:block;height:600px;width:100%"></praxis-agent>
<p id="status" role="status"></p>
<script type="module">
await customElements.whenDefined('praxis-agent');
const agent = document.querySelector('praxis-agent');
const status = document.querySelector('#status');
agent.addEventListener('praxis.ready', () => { status.textContent = 'Interface mounted'; });
agent.addEventListener('praxis.error', () => { status.textContent = 'Check the failed network request'; });
agent.setOptions({
api: {
url: 'https://api-develop.deepraxis.com',
publishableKey: 'PRAXIS_PUBLISHABLE_KEY',
},
agent: { name: 'Course assistant' },
locale: 'en',
});
</script>
</html>Expected: A chat interface appears and sending a question produces a real reply. Interface mounted only confirms mounting; also verify replies and user isolation.
Properties
api and agent
| Property | Type | Meaning |
|---|---|---|
api.url | string | Required API origin or base ending in /agent/v1; immutable after initialization |
api.getToken | (current: string | null) => Promise<string> | Returns an embed token. Initially current is null; refresh receives the current token. Recheck host login on your backend every time |
api.publishableKey | string | Anonymous token entry point instead of getToken; immutable after initialization. A privately stored visitor_secret preserves visitor identity |
agent.name | string | Required display name; does not select an agent |
agent.avatar | string | Avatar URL; credentials determine the actual agent accessed |
onClientTool | (call: { id, name, input }) => unknown | Promise<unknown> | Element property, outside setOptions. Handles client tools; throw for unknown tools |
Layout and content
| Property | Type / default | Effect |
|---|---|---|
layout | inline, sidebar, popup, modal; default inline | Conversation layout |
width | number; 400 CSS pixels | Sidebar width |
launcher.type | none, bubble, mascot | Required when supplying launcher; defaults to none for inline, bubble otherwise |
launcher.image, launcher.label | string | Launcher image and text |
launcher.position | bottom-right, bottom-left | Launcher position; defaults to bottom-right |
header.title, header.subtitle | string | Title and subtitle; title defaults to agent.name |
header.icon | string | Supported Lucide icon name or image URL |
header.actions | { id: string; icon: string; label: string }[] | Custom header buttons emitting click events |
history.enabled | boolean; true | History entry; false also disables showHistory() |
startScreen.greeting | string | Empty-conversation greeting |
startScreen.prompts | { label: string; prompt: string }[] | Displays the first 4; clicking sends prompt |
composer.placeholder | string | Defaults to the localized input hint |
composer.attachments.enabled | boolean; true | Allows file selection, pasting and dropping |
disclaimer, footer | string | Conversation notice and footer text |
autoScroll | boolean | Whether new content scrolls automatically |
locale | zh, en | Falls back to host page language, then browser language. Tags starting with zh select Chinese; otherwise English. No language information defaults to English |
theme
| Property | Values / constraints |
|---|---|
colorScheme | light, dark, system; light when omitted, system follows the browser |
accent, surface | Explicit opaque CSS colors; var(), currentcolor and transparency throw TypeError |
grayscale | neutral, warm, cool |
radius | none, sm, md, lg, full; base radii of 0, 4, 10, 18, 9999 CSS pixels |
density | compact, normal, spacious; base spacing of 3, 4, 5 CSS pixels |
fontFamily | Nonempty font-family string without ; { } < >; otherwise TypeError |
fontSize | Positive finite number in CSS pixels; otherwise RangeError |
Default accent colors are #167A43 in light mode and #30a46c in dark mode. Foreground colors are selected for contrast.
React props
React's PraxisAgent uses these props. The current React binding still requires a top-level getToken, even though options.api includes publishableKey in its type. For anonymous access, use the Web Component above directly.
| Prop / return object | Meaning |
|---|---|
getToken | Required; same signature as api.getToken |
options | Options above without api.getToken; omission renders an unconfigured element |
layout, launcher | Override options.layout and options.launcher.type; launcher accepts none/bubble/mascot |
className, style, children | Host element styling and React children |
onClientTool | Client tool callback, matching the element property |
ref / usePraxisAgent() | ref exposes a control handle; the hook returns stable { ref, control } |
Methods
| Method | Return / behavior |
|---|---|
setOptions(partial) | Initializes or merges options |
sendUserMessage(text) | Promise<"accepted" | "rejected" | "unknown">; can reject empty or oversized text, pending approvals or unavailable submission. accepted does not prove a successful reply; inspect the session before resending an unknown result |
setComposerValue(text) | Replaces the draft without sending |
focusComposer() | Focuses the composer; no effect while history is open |
setThreadId(id) | Switches sessions and closes history; null opens an empty conversation, not a different user identity |
showHistory(), hideHistory() | Opens or closes history |
open(), close(), toggle() | Opens, closes or toggles the panel; no effect for inline |
setReadable(name, value) | Registers page context. Name: 1–64 characters, letters, digits or _ . : -. Value: string or JSON-serializable value |
removeReadable(name) | Removes the named page value |
The React control handle includes the methods from sendUserMessage through toggle above. Calls before onReady or after unmount throw a not-ready error rather than queueing. For React page context and tools, use usePraxisReadable and usePraxisTool, with PraxisProvider when sharing a registry scope. See the guides below.
Events
Events are bubbling, composed CustomEvent objects that cross Shadow DOM. React callbacks receive the same event object; read its event.detail.
| Event / React callback | Detail and timing |
|---|---|
praxis.ready / onReady | None; interface mounted, not proof of authentication or network success |
praxis.error / onError | KitError with code, status, retryable, message, or only { message }; check fields before using them |
praxis.thread.change / onThreadChange | { threadId: string | null }; current session changed |
praxis.response.start / onResponseStart | None; processing became busy |
praxis.response.end / onResponseEnd | None; processing stopped being busy, not a success assertion |
praxis.open, praxis.close / onOpen, onClose | None; panel opened or closed |
praxis.history.open, praxis.history.close / onHistoryOpen, onHistoryClose | None; history opened or closed |
praxis.header.action / onHeaderAction | { id: string }; custom header button clicked |
praxis.tool.change / onToolChange | { id, name, status: "start" | "end", isError? }; client tool execution changed |
praxis.log / onLog | { level: "info" | "warn" | "error", message, data? }; context trimming or tool diagnostics |
praxis.frame.close | None; requests that the host close an iframe; no corresponding React callback prop |
Defaults and lifecycle
setOptions merges objects recursively and replaces arrays. Explicit undefined resets a field. Changing api.url or api.publishableKey after initialization throws TypeError. Destroy and recreate the element when changing backends or user identity. Removing an element releases connections and refresh timers, but does not revoke issued tokens.
Page context snapshots allow 32 items and 4096 UTF-8 bytes. Excess entries are omitted starting with the earliest registration, with a log event. These runtime options are separate from Dashboard-persisted iframe/Hosted appearance, which has its own fields and size limits.
Usage guides
Embed tokens and users · Pass context · Add client tools · Customize appearance