@useknest/widget-web
v0.1.0-beta.18
Published
Svelte web component for Knest chat widget
Readme
@useknest/widget-web
Web component for the Knest chat widget. Works with any framework or vanilla HTML via a custom element.
Installation
npm install @useknest/widget-web
# or
pnpm add @useknest/widget-web
# or
yarn add @useknest/widget-webUsage: Script Tag (CommonJS)
<script src="https://unpkg.com/@useknest/widget-web/dist/widget.umd.js"></script>
<knest-chat publishable-api-key="pk_your_public_key_here"></knest-chat>Attributes
| Attribute | Type | Required | Default | Description |
| --------------------- | ---------------------- | -------- | ---------- | ---------------------------------------------------------------- |
| publishable-api-key | string | Yes | - | Your project's publishable API key |
| mode | 'inline' \| 'bubble' | No | 'inline' | Display mode: inline or floating bubble button |
| default-open | boolean | No | false | Whether the chat starts open (only applies to bubble mode) |
| user | WidgetUser (object) | No | - | Identifies the logged-in user; requires at least id or email |
The user attribute must be set as a JavaScript property (not an HTML attribute) since it is an object:
const widget = document.querySelector('knest-chat');
widget.user = { id: currentUser.id, email: currentUser.email, fullName: currentUser.name };interface WidgetUser {
id?: string; // Your system's user ID (cross-device dedup key)
email?: string;
fullName?: string;
metadata?: Record<string, unknown>; // Custom attributes (e.g. plan, company)
}Features
- Web Component - Works with any framework or vanilla HTML
- Streaming Support - Real-time message streaming via Server-Sent Events (SSE)
- Self-Contained - Styles are encapsulated in Shadow DOM
- Customizable - Fetches branding (avatar, colors, welcome message) from your project dashboard at useknest.com
- Lightweight - ~51KB minified UMD (~19KB gzipped)
- Framework-Agnostic Core - Shares business logic with other platform packages for a consistent experience
Examples
Full Page Chat using HTML/CSS
<!DOCTYPE html>
<html>
<head>
<style>
body {
margin: 0;
height: 100vh;
}
knest-chat {
display: block;
height: 100%;
}
</style>
</head>
<body>
<script type="module" src="https://unpkg.com/@useknest/widget-web"></script>
<knest-chat publishable-api-key="pk_your_public_key_here"></knest-chat>
</body>
</html>Vue.js
<template>
<knest-chat :publishable-api-key="apiKey"></knest-chat>
</template>
<script setup>
import '@useknest/widget-web';
const apiKey = 'pk_your_public_key_here';
</script>Angular
// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
@NgModule({
schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {}// component.ts
import '@useknest/widget-web';<!-- component.html -->
<knest-chat publishable-api-key="pk_your_public_key_here"></knest-chat>Floating Bubble Mode
<knest-chat publishable-api-key="pk_your_public_key_here" mode="bubble"></knest-chat>Bubble Mode (Auto-Open)
<knest-chat
publishable-api-key="pk_your_public_key_here"
mode="bubble"
default-open="true"
></knest-chat>Customization
The widget automatically loads customization from your project's configuration from useknest.com:
- Avatar image
- Brand color
- Welcome message
- Example questions
No additional attributes needed - just provide your publishable-api-key.
Architecture
This package uses @useknest/widget-core for all business logic (API calls, streaming, markdown rendering). The Svelte component handles only the UI rendering, compiled as a web component with Shadow DOM encapsulation.
Browser Support
- Modern browsers (Chrome, Firefox, Safari, Edge)
- Requires native ES modules and custom elements support
- Requires
EventSourceAPI for streaming
Troubleshooting
Widget not rendering
Ensure the script is loaded before the custom element is used:
<!-- Load first -->
<script type="module" src="https://unpkg.com/@useknest/widget-web"></script>
<!-- Then use -->
<knest-chat publishable-api-key="pk_your_public_key_here"></knest-chat>License
Proprietary - All rights reserved. This software is for use by authorized Knest customers only.
Support
For issues and questions, please email us at [email protected]