@velmhq/embed-react

React component for the Velm embed chat widget.

A thin (~1KB) wrapper around the standard <script> tag installer. Drop <Velm /> into your tree, pass your agent ID, and the widget appears. SSR-safe (mounts only on the client) and idempotent across remounts.

Install

npm install @velmhq/embed-react
# or
pnpm add @velmhq/embed-react

Usage

import { Velm } from "@velmhq/embed-react";

export default function App() {
  return (
    <>
      {/* your app */}
      <Velm agent="acme/sales-bot" />
    </>
  );
}

That's it. The widget injects itself into the bottom-right corner and takes over from there.

Props

Prop	Type	Default	Description
agent	string	(required)	Agent reference. "tenant/agent" slug (e.g. "acme/sales-bot"), 32-char ID, or UUID.
mode	"auto" | "compact" | "editorial"	"auto"	Visual layout. auto samples host body luminance.
theme	"auto" | "dark" | "light"	"auto"	Color theme. auto follows prefers-color-scheme.
color	string	"#6E7CFF"	Brand accent color override. Hex only.
greeting	string	-	First message rendered in the thread before any user input.
suggested	string[]	-	Up to 3 starter prompts shown as a vertical list above the input. Hides once the user sends their first message. Coexists with greeting.
title	string	-	Customer-configurable header label (max 40 chars). When set, a small "by Velm" attribution renders inline after it. Defaults to "VELM" (compact) / "ASK VELM" (editorial).
position	"bottom-right" | "bottom-left" | "top-right" | "top-left"	"bottom-right"	Corner the widget docks to.
src	string	embed.velm.run	Launcher script URL. Override only for self-hosting.

How it works

The component uses useEffect to inject a <script src="https://embed.velm.run/v1.js" data-agent="..."> tag into document.body, deduped via a stable id="velm-embed-launcher". Subsequent prop changes don't re-init: the launcher is mounted once per page and persists across SPA navigations. On unmount the script is deliberately left in place so an open conversation isn't lost on a route change.

If you need to mount and unmount the widget aggressively, use the bare script tag installer instead.

Mode picker

Velm ships two preset visual modes that share the same DNA but lay out differently for different host-site types:

• compact: dense, REPL-ish, intended for SaaS dashboards, dev tools, fintech.
• editorial: atmospheric, spacious, intended for marketing pages, e-commerce, healthcare.

Pass mode="auto" (the default) and the launcher samples the host body's background luminance to pick: light renders editorial, dark renders compact. Override explicitly when you know better.

Documentation

Full reference at velm.run/docs.

License

MIT. See LICENSE.