Scalar / Web Component

Add an AI-powered chat assistant to any website using our framework-agnostic Web Component.

Open Source

This component is MIT licensed and free to use.
View on GitHub · npm package

Use Cases

Scalar API documentation
Plain HTML/CSS/JS websites
React, Vue, Svelte, or any framework
Static site generators
Anywhere you can add a <script> tag

Installation

Via npm

npm install vetradocs-scalar

Via CDN

<script type="module" src="https://unpkg.com/vetradocs-scalar/dist/vetradocs-scalar.js"></script>

Prerequisites

Before using this component, you need a backend service to handle AI requests.

Setting Up the Backend

npx create-vetradocs-backend@latest

Choose Node.js (Express) (recommended) or Cloudflare Workers, then deploy it.

See Backend Setup for detailed instructions.

Quick Start

Step 1: Add the Script

<!-- Via npm -->
<script type="module" src="./node_modules/vetradocs-scalar/dist/vetradocs-scalar.js"></script>

<!-- Or via CDN -->
<script type="module" src="https://unpkg.com/vetradocs-scalar/dist/vetradocs-scalar.js"></script>

Step 2: Add the Component

<vetradocs-widget
  api-endpoint="https://your-backend.com"
  api-key="your-api-key"
  title="AI Assistant"
  accent-color="#f97316"
></vetradocs-widget>

Step 3: Build the Search Index (Optional)

If you have Markdown documentation, build a search index:

npx vetradocs-build-generic --docs ./docs --output ./public/search-index.json

Then point the widget to it:

<vetradocs-widget
  index-path="/search-index.json"
  ...
></vetradocs-widget>

Attributes Reference

Attribute	Type	Default	Description
`api-endpoint`	`string`	`/api/chat`	Backend API URL
`api-key`	`string`	`""`	API key for authentication
`index-path`	`string`	`/search-index.json`	Path to search index
`title`	`string`	`"AI Assistant"`	Chat window title
`accent-color`	`string`	`"#f97316"`	Primary theme color (any CSS color)
`placeholder`	`string`	`"Ask a question..."`	Input placeholder text
`position`	`string`	`"bottom-right"`	`bottom-right`, `bottom-left`, `bottom-center`

Examples

Basic Usage

<vetradocs-widget
  api-endpoint="https://api.example.com"
></vetradocs-widget>

Full Configuration

<vetradocs-widget
  api-endpoint="https://api.example.com"
  api-key="secret-key-123"
  index-path="/search-index.json"
  title="Documentation AI"
  accent-color="#8b5cf6"
  placeholder="What can I help you with?"
  position="bottom-right"
></vetradocs-widget>

With Scalar API Docs

<!DOCTYPE html>
<html>
<head>
  <title>My API Docs</title>
  <script src="https://cdn.scalar.com/api-reference.js"></script>
  <script type="module" src="https://unpkg.com/vetradocs-scalar/dist/vetradocs-scalar.js"></script>
</head>
<body>
  <!-- Scalar API Reference -->
  <script data-url="https://api.example.com/openapi.json" id="api-reference"></script>
  
  <!-- VectraDocs AI Chat -->
  <vetradocs-widget
    api-endpoint="https://your-backend.com"
    api-key="your-api-key"
    title="API Assistant"
    accent-color="#8e4ec6"
  ></vetradocs-widget>
</body>
</html>

Framework Integration

React

import 'vetradocs-scalar/dist/vetradocs-scalar.js';

function App() {
  return (
    <div>
      <vetradocs-widget
        api-endpoint="https://api.example.com"
        api-key="your-key"
      ></vetradocs-widget>
    </div>
  );
}

Vue

<script setup>
import 'vetradocs-scalar/dist/vetradocs-scalar.js';
</script>

<template>
  <vetradocs-widget
    api-endpoint="https://api.example.com"
    api-key="your-key"
  ></vetradocs-widget>
</template>

Plain HTML

<script type="module" src="https://unpkg.com/vetradocs-scalar/dist/vetradocs-scalar.js"></script>
<vetradocs-widget api-endpoint="https://api.example.com"></vetradocs-widget>

Styling

Custom Colors

Use any CSS color value:

<vetradocs-widget accent-color="#10b981"></vetradocs-widget>
<vetradocs-widget accent-color="rgb(139, 92, 246)"></vetradocs-widget>
<vetradocs-widget accent-color="hsl(262, 83%, 58%)"></vetradocs-widget>

CSS Custom Properties

Override internal styles using CSS:

vetradocs-widget {
  --vd-accent: #8b5cf6;
  --vd-bg: #18181b;
  --vd-text: #fafafa;
}

CLI Reference

vetradocs-build-generic

Builds a search index from Markdown files.

npx vetradocs-build-generic [options]

Options:
  --docs <path>     Path to docs directory (default: ./docs)
  --output <path>   Output path for index (default: ./public/search-index.json)
  --help            Show help

Note: If you're using Scalar with an OpenAPI spec, you may need to create a custom indexer or convert your API spec to markdown for optimal AI search.

Troubleshooting

Check browser console for JavaScript errors
Ensure the script is loaded with type="module"
Verify the api-endpoint is accessible

AI gives generic responses

Create a search index from your documentation
Point index-path to the generated JSON file
Rebuild the index when content changes

CORS errors

Check backend FRONTEND_URL matches your website
Ensure you're using the correct protocol (http/https)

Scalar / Web Component

Scalar / Web Component

Use Cases

Installation

Via npm

Via CDN

Prerequisites

Setting Up the Backend

Quick Start

Step 1: Add the Script

Step 2: Add the Component

Step 3: Build the Search Index (Optional)

Attributes Reference

Examples

Basic Usage

Full Configuration

With Scalar API Docs

Framework Integration

React

Vue

Plain HTML

Styling

Custom Colors

CSS Custom Properties

CLI Reference

vetradocs-build-generic

Troubleshooting

Widget doesn't appear

AI gives generic responses

CORS errors

Links

On this page

How can I help?