# Installation > Every install path in depth: script tag, async loader, npm, web component, CDN URLs and version pinning. Deep-dive for every install path. See [Quickstart](/sdk/quickstart) for the 5-minute version. --- ## Choose your path | Path | Best for | Delivery | | ----------------------------------------------------------------- | --------------------------------------------------- | ---------- | | [A. ` ``` ### Attributes The zero-JavaScript path intentionally exposes a small, flat subset of `ChatWidgetOptions`. These are the attributes parsed by the current bundle: | Attribute | Maps to | Example | | ---------------------------------------------- | --------------------------------- | ------------------------------- | | `data-public-key` | `publicKey` | `agent_pk_...` | | `data-ai-agent-deployment-id` | `aiAgentDeploymentId` | deployment UUID | | `data-base-url` | `baseUrl` | `https://help.ai` | | `data-agent-api-base-url` | `agentApiBaseUrl` | `http://localhost:3069` | | `data-api-base-url` | `dataApiBaseUrl` | `http://localhost:3071` | | `data-theme` | `theme` | `auto` / `light` / `dark` | | `data-mode` / `data-position` | `presentation` | `floating` / `bottom-right` | | `data-iframe` | `presentation.iframe` | `true` | | `data-width` / `data-height` | `presentation.size` | `420px` / `640px` | | `data-response-mode` | `behavior.responseMode` | `streaming` / `buffered` | | `data-start-minimized` | `behavior.startMinimized` | `false` | | `data-show-reasoning` | `behavior.showReasoning` | `true` | | `data-show-tool-calls` | `behavior.showToolCalls` | `true` | | `data-show-sources` | `behavior.showSources` | `true` | | `data-disable-message-feedback` | `behavior.disableMessageFeedback` | `true` | | `data-auto-send-suggestions` | `behavior.autoSendSuggestions` | `true` | | `data-pop-out-url` | `behavior.popOutUrl` | `https://chat.example.com` | | `data-locale` | `i18n.locale` | `fr-FR` | | `data-launcher-variant` / `-size` / `-icon` | `launcher` fields | `pill` / `lg` / `spark` | | `data-launcher-label` / `-hidden` | `launcher` fields | `Ask AI` / `true` | | `data-callout-text` / `-delay` | `launcher.callout` | `Hi! 👋` / `2000` | | `data-actions` | `header.actions` (CSV) | `theme,history,close` | | `data-features-disable-file-upload` | `features.disableFileUpload` | `true` | | `data-features-voice` | `features.voice` | `local` / `server` / `disabled` | | `data-endpoint-upload` / `-transcribe` | `endpoints` | `/pai/upload` | | `data-user-id` / `-email` / `-name` | `userContext` scalar fields | `user_42` | | `data-user-context` | `userContext` extras (JSON) | `'{"plan":"pro"}'` | | `data-page-area` / `-url` / `-path` / `-title` | `pageContext` scalar fields | `support` | | `data-page-context` | `pageContext` extras (JSON) | `'{"experiment":"b"}'` | Unknown attributes are ignored. Full option semantics: [Configuration](/sdk/configuration). > Explicit scalar attributes (`data-user-id`, `data-page-area`, …) win > over keys in the `data-user-context` / `data-page-context` JSON. For > SPAs where the visitor logs in after load or navigates between pages, > set context dynamically with > [`instance.setUserContext(...)` / `setPageContext(...)`](/sdk/configuration#setting-context-after-login--on-navigation). > The `data-user-*` / `data-page-*` attributes are reactive — updating > one re-handshakes with the same anonymous visitor/conversation. This > context is informational for the AI, never an auth credential. ### Load without mounting The script tag mounts the widget only when it carries `data-ai-agent-deployment-id`. Leave that attribute out to load the bundle **without** mounting, then call `init()` from JavaScript when you're ready: ```html ``` ### Multi-widget For two widgets on one page, load the bundle once and call `mount()` with distinct `widgetId` values: ```js HelpAI.mount({ widgetId: 'support', publicKey: SUPPORT_KEY, aiAgentDeploymentId: SUPPORT_DEPLOYMENT_ID }); HelpAI.mount({ widgetId: 'sales', publicKey: SALES_KEY, aiAgentDeploymentId: SALES_DEPLOYMENT_ID }); ``` --- ## Path B — async loader snippet Tag-manager-style snippet. Defers the bundle download without blocking first paint, while letting your page queue commands immediately. ```html ``` ### Queueable commands | Call | What it does | | ----------------------------------------- | ---------------------------------------------------------------- | | `HelpAI('init', opts)` | Mount once; update the same widget id | | `HelpAI('mount', opts)` | Mount fresh; replace the same widget id | | `HelpAI('destroy')` | Unmount all live widgets | | `HelpAI('open')` | Open the default widget's panel | | `HelpAI('close')` | Close the default widget's panel | | `HelpAI('expand')` | Toggle the default widget's expanded tier | | `HelpAI('ask', text, { send })` | Open the chat with `text` in the composer; `send: true` sends it | | `HelpAI('on', eventName, fn)` | Subscribe to a default-widget event | | `HelpAI('update', { /* patch */ })` | Update the default widget's options | | `HelpAI('hook', widgetId, eventName, fn)` | Register a global lifecycle hook | ### Pre-boot hooks `window.HelpAIHooks` is a pre-boot queue for event listeners. Push arrays or objects to it before the bundle arrives: ```html ``` Full details: [Events & hooks](/sdk/events-and-hooks#global-lifecycle-hooks). ### After boot Once the bundle loads, `window.HelpAI` becomes a real API: ```js window.HelpAI.init(opts) window.HelpAI.destroy(widgetId?) window.HelpAI.getInstance(widgetId?) // returns handle or null window.HelpAI.getAllInstances() window.HelpAI.hook(widgetId, event, fn) window.HelpAI.open() / close() / expand() window.HelpAI.version // semver string window.HelpAI.brand // { id, displayName, cdnUrl, ... } ``` --- ## Path C — NPM package For sites with a bundler. Full framework-specific walkthroughs: [Framework integrations](/sdk/frameworks). ### Install ```bash npm install @helpai/elements # or yarn add @helpai/elements # or pnpm add @helpai/elements # or bun add @helpai/elements ``` ### Entry points The package ships two entries: ```ts // Main entry — everything except the web component. import { init, mount, destroy, hook } from '@helpai/elements'; // Sub-entry — registers as a custom element. import '@helpai/elements/web-component'; ``` Tree-shaking: the main entry has zero mount-on-import side effects. Unused exports are dropped by your bundler. Importing only types costs zero runtime bytes. ### Minimal React usage ```tsx import { init, type ChatWidgetInstance } from '@helpai/elements'; import { useEffect, useRef } from 'react'; export function Chat() { const instance = useRef(null); useEffect(() => { instance.current = init({ publicKey: import.meta.env.VITE_HELPAI_KEY, aiAgentDeploymentId: import.meta.env.VITE_HELPAI_DEPLOYMENT_ID, }); return () => instance.current?.destroy(); }, []); return null; // the widget renders its own DOM outside your tree } ``` ### Typed options Autocomplete for every option: ```ts import type { ChatWidgetOptions } from '@helpai/elements'; const opts: ChatWidgetOptions = { publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000', presentation: { mode: 'floating' }, theme: { accent: '#ff3e00' }, launcher: { variant: 'pill', label: 'Ask AI' }, // ... }; ``` ### SSR The widget is client-only. Never call `init()` on the server. In Next.js app router, wrap your component with `'use client'` (shown above). In Remix / SvelteKit, use the `onMount` / `useEffect` equivalent to defer init until the browser. --- ## Path D — Web Component Declarative tag. Works in any framework or plain HTML. ### Load + use ```html ``` ### Attributes Same parser fields as ` ``` Pinning means you control upgrade timing. The floating URL means you get new features + bug fixes automatically. Both are supported; most customers use the floating URL for marketing sites and pinned versions for mission-critical apps. --- ## Path E — Standalone ESM bundle (no build, no NPM install) For pages without a build step (plain HTML, MDX, sandbox demos, code playgrounds, AI-generated UIs), load the pre-bundled ESM file shipped with every release. `elements.esm.js` is fully self-contained — every dependency (preact, signals, streaming-markdown) is inlined. No bare specifiers, no import maps, no `+esm` magic. Drop into any page with ` ``` ### Web component (declarative tag) The web-component bundle self-registers `` on import: ```html ``` ### File catalog (every `dist//` ships these) | File | Purpose | Use with | | --------------------------------- | ------------------------------------------------------ | --------------------------------------- | | `elements.js` | IIFE bundle, defines `window.HelpAI` | Plain ` ``` - jsDelivr serves a pinned version as `Cache-Control: public, max-age=31536000, immutable` — cached for a year, global edge, free. - **Always pin an exact version** for production. `@latest` / ranges (`@0.56`) are mutable (jsDelivr revalidates ~daily) **and** auto-update — a published patch can change behavior under you. - Trade-off: the customer must **bump the version in their snippet to update**, and every release re-downloads the whole ~107 KB (one self-contained file). - Speed it up on pages you control: `` (and optionally `rel="modulepreload"`). ### Option 2 — your own CDN behind a stable URL (recommended; simplest for customers) Point a CDN (`cdn.help.ai`, a Cloudflare/CloudFront origin, …) at the built `dist//` assets and give customers **one URL that never changes**: ```html ``` You ship updates **behind** that stable URL — the customer's page is frozen. The caching rule is the whole trick: | Asset | `Cache-Control` | Why | | ------------------------------------- | -------------------------------------- | -------------------------------------------- | | The stable entry (`elements.js`) | `public, max-age=300, must-revalidate` | Short TTL so a deploy propagates in minutes. | | Content-hashed chunks (`*..js`) | `public, max-age=31536000, immutable` | Hash in the name → safe to cache forever. | Plus Brotli/Gzip, HTTP/2+3, and (optionally) `integrity="sha384-…"` SRI hashes. ### Automatic chunking (zero customer changes) The value of Option 2 is the **stable URL** above — the customer's snippet never changes and you own caching + region. Chunking is a further, _optional_ step on top (usually **not** worth it — see the caveat below). With **content-hashed chunk filenames served from a version-less path**, an unchanged chunk keeps the **same URL** across releases, so the browser reuses it — only the chunks that actually changed re-download. To get there: 1. Build ESM with code-splitting on (esbuild/tsdown `splitting: true`, `format: "esm"`) and `[hash]` filenames. The thin entry imports the chunks. 2. Add lazy `import()` boundaries at the **optional surfaces** — messenger tabs (Home/Help/News), forms/HITL, voice. esbuild emits each as its own chunk and hoists shared code (e.g. Preact) into a common chunk automatically. Core chat loads first → smaller first paint; each feature caches independently. 3. The customer keeps the single stable `