@eka-care/medassist-widget-embed
v0.2.73
Published
Embeddable MedAssist widget loader built with Web Components.
Readme
@eka-care/medassist-widget-embed
Lightweight, embeddable widget loader for MedAssist using Web Components. Add the script and the <eka-medassist-widget> custom element to any page for a framework-agnostic, lazy-loaded chat widget.
Overview
- Custom Web Component –
<eka-medassist-widget>for easy embedding - Lazy loading – Widget assets load when the user opens the widget
- Framework agnostic – No React or build step required
- Isolated styling – Shadow DOM avoids conflicts with host styles
- Simple integration – Script tag + custom element
Installation
npm install @eka-care/medassist-widget-embedOr load from a CDN (replace the version as needed):
<script
src="https://cdn.jsdelivr.net/npm/@eka-care/medassist-widget-embed@latest/dist/index.js"
async></script>For self-hosting, ensure the built widget assets (medassist-widget.js, medassist-widget.css) are served alongside index.js, or use the package’s default CDN for widget assets (see How it works).
Usage
<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
</head>
<body>
<h1>Welcome</h1>
<eka-medassist-widget agent-id="your-agent-id-here"></eka-medassist-widget>
<script src="https://cdn.jsdelivr.net/npm/@eka-care/medassist-widget-embed@latest/dist/index.js" async></script>
</body>
</html>The widget appears as a floating button; clicking it loads and opens the chat.
Configuration
Required attributes
agent-id– Your MedAssist agent identifier
Optional attributes
icon-url– Custom icon URL for the widget button (default: Eka CDN icon)title– Widget titlebase-url– Base URL for API/agent configdisplay-mode–"widget"(floating button) or"full"(inline full view)context– JSON string of context key-value pairs
Programmatic config with EkaMedAssist.init()
After the script loads, you can set or override config before the user opens the widget:
window.EkaMedAssist.init({
agentId: "your-agent-id",
title: "MedAssist",
iconUrl: "https://example.com/icon.svg",
baseUrl: "https://api.example.com",
context: { key: "value" },
theme: {
background: "#1a1738",
primary: "#09FBD3",
textColor: "white",
},
});Custom icon example
<eka-medassist-widget
agent-id="your-agent-id"
icon-url="https://example.com/custom-icon.svg"></eka-medassist-widget>Custom launcher styling
If you need to reposition the floating launcher button (different breakpoints, custom z-index, etc.), pass CSS via customLauncherStyles in init() — or set it directly with the custom-launcher-styles attribute. The CSS is injected into the launcher's Shadow DOM, so you can use media queries, hover states, and anything else CSS allows.
Two selectors are supported as a stable contract:
:host— the launcher wrapper. Use this to overrideposition,bottom,right,left,top,transform,z-index, etc.#medassist-open-btn— the button element itself. Use this for size, background, box-shadow, border-radius, etc.
window.EkaMedAssist.init({
agentId: "your-agent-id",
customLauncherStyles: `
@media (max-width: 991px) {
:host {
right: auto;
left: 50%;
bottom: 47px;
transform: translateX(-50%);
}
}
@media (max-width: 767px) {
:host { bottom: 34px; }
}
`,
});This only affects the launcher button — the chat panel that opens on click is unaffected.
How it works
- Initial load – The script registers the custom element
<eka-medassist-widget>. - Button – The element shows a floating button (or full view if
display-mode="full"). - Lazy load – On first open, the script fetches the widget JS and CSS (from the same origin or from
https://cdn.jsdelivr.net/npm/@eka-care/medassist-widget@latest/dist/by default). - Isolation – The widget runs inside Shadow DOM to avoid style and script conflicts.
To use your own widget assets (e.g. after building @eka-care/medassist-widget), host medassist-widget.js and medassist-widget.css and point the script via the data-widget-assets attribute:
<script
src="/path/to/widget-embed/index.js"
data-widget-assets="/path/to/widget-assets/"
async></script>File structure
widget-embed/
├── dist/
│ ├── index.js # Loader and custom element
│ ├── iframe.js # Optional iframe helper
│ └── iframe.html # Optional iframe template
├── assets/
│ └── bot-icon.svg # Default button icon (or CDN)
└── README.mdBrowser support
- Chrome, Firefox, Safari, Edge (latest)
- Requires Custom Elements, Shadow DOM, and ES6+
Development
Build the package:
npm run buildTo build and bundle the widget assets locally:
npm run build:with-widget(Requires the widget package to be built first.)
Integration examples
React
import { useEffect } from "react";
function App() {
useEffect(() => {
const script = document.createElement("script");
script.src = "https://cdn.jsdelivr.net/npm/@eka-care/medassist-widget-embed@latest/dist/index.js";
script.async = true;
document.body.appendChild(script);
}, []);
return (
<div>
<h1>My App</h1>
<eka-medassist-widget agent-id="your-agent-id" />
</div>
);
}Vue
<template>
<div>
<eka-medassist-widget :agent-id="agentId" />
</div>
</template>
<script>
export default {
data: () => ({ agentId: "your-agent-id" }),
mounted() {
const script = document.createElement("script");
script.src = "https://cdn.jsdelivr.net/npm/@eka-care/medassist-widget-embed@latest/dist/index.js";
script.async = true;
document.body.appendChild(script);
},
};
</script>Troubleshooting
- Widget not appearing – Check
agent-id, ensure the loader script loads (Network tab), and check the console for errors. - Assets 404 – If using self-hosted assets, ensure
medassist-widget.jsandmedassist-widget.cssare served at the path given indata-widget-assets(or use the default CDN).
License
MIT