Every data-cstar-* attribute cStar recognizes, on a single page. Use Cmd+F.
Looking for narrative? See:
- Chat Widget Setup — install + mode overview
- Custom Chat Widget — building a custom UI
- Quick Help — inline AI Q&A
- Trigger the Chat Widget from Custom Buttons — open prebuilt chat from anywhere
Mode Detection
The cstar.js script picks a mode based on what's on the page:
| Found on page | Mode loaded |
|---|---|
[data-cstar-launcher] or [data-cstar-panel] |
Custom — your HTML, cStar binds the data layer |
| (none of the above) | Prebuilt — floating chat launcher renders itself |
[data-cstar-quickhelp] |
Quick Help — runs in parallel with either chat mode |
You can mix Quick Help with either chat mode on the same page. You cannot mix Custom and Prebuilt on the same page.
Using cStar in a Single-Page App (SPA)
cstar.js scans the DOM once at script load and binds every data-cstar-* element it finds. In a multi-page site that's all it ever needs to do — every navigation reloads the script. In a single-page app (SvelteKit, React Router, Next.js App Router, Vue Router, etc.) client-side route changes mount new markup without reloading the script, so newly-mounted data-cstar-* elements would be ignored.
Three options, in order of effort:
Option 1: rescan() (recommended)
Call window.CStarChat.rescan() from your router's after-navigation hook. cStar re-scans the DOM and binds any newly-mounted elements. Old bindings are cleaned up automatically.
// SvelteKit: src/routes/+layout.svelte
import { afterNavigate } from '$app/navigation';
afterNavigate(() => window.CStarChat?.rescan());
// React Router v6
import { useLocation } from 'react-router-dom';
import { useEffect } from 'react';
function useCStarRescan() {
const { pathname } = useLocation();
useEffect(() => { window.CStarChat?.rescan(); }, [pathname]);
}
// Next.js App Router
'use client';
import { usePathname } from 'next/navigation';
import { useEffect } from 'react';
export function CStarRescan() {
const pathname = usePathname();
useEffect(() => { window.CStarChat?.rescan(); }, [pathname]);
return null;
}
Library widgets get the same hook: window.CStarLibrary.rescan(). Both are no-ops if the SDK hasn't finished loading yet (calls are queued and drained after init), and rescan() on prebuilt mode is also a no-op — so you can wire it in unconditionally without checking which install method the team is on.
Option 2: Force full reload on cStar pages
If you only render data-cstar-* elements on a few pages, add a per-link reload directive to skip client-side routing on just those navigations:
<!-- SvelteKit -->
<a href="/support" data-sveltekit-reload>Support</a>
<!-- React Router -->
<Link to="/support" reloadDocument>Support</Link>
The browser does a full document load, cstar.js runs from scratch, and you get a clean bind without needing a router hook.
Option 3: Force full reload on every navigation
Nuclear option. Only do this if rescan() can't reach you (say, a no-JavaScript constraint) or your app is small enough that full reloads aren't a UX cost.
<!-- SvelteKit -->
<body data-sveltekit-reload>
This disables client-side routing entirely. Simple, but gives up SPA benefits.
What about library widgets (data-cstar-library-*)?
Library widgets (data-cstar-library-search, data-cstar-library-accordion, data-cstar-library-recent) auto-detect new mounts via a MutationObserver — in most cases they Just Work in an SPA without any setup. Use window.CStarLibrary.rescan() if you have a case where the observer misses something (e.g. shadow-DOM-isolated mounts).
Prebuilt Mode
Used by the floating chat widget. Add to any clickable element.
| Attribute | Values | Behavior |
|---|---|---|
data-cstar-chat |
(none) | Open the chat panel |
data-cstar-chat |
"new" |
Open + start a new conversation |
data-cstar-chat |
"tickets" |
Open + show conversations list |
That's the full prebuilt-mode attribute list. For everything else, use the JavaScript SDK (window.CStarChat).
Quick Help
| Attribute | Behavior |
|---|---|
data-cstar-quickhelp |
Mount an inline AI Q&A box. cStar attaches a Shadow DOM with header, message log, and input. Place this on any element. |
Programmatic mounting + options live in the Quick Help guide.
Custom Mode — Action Triggers
cStar attaches a click handler. Most call event.preventDefault() automatically.
| Attribute | Action |
|---|---|
data-cstar-launcher |
Toggle panel open/closed |
data-cstar-close |
Close panel |
data-cstar-minimize |
Close panel (alias) |
data-cstar-back |
Return to conversations list |
data-cstar-new-conversation |
Switch to the new-conversation view |
data-cstar-create-conversation |
Submit the new-conversation form |
data-cstar-send |
Send the current message draft |
data-cstar-signup-submit |
Submit the signup form |
data-cstar-login-submit |
Submit the login form |
data-cstar-forgot-password-submit |
Submit the forgot-password form |
data-cstar-magic-link |
Send a magic link to the email field |
data-cstar-logout |
Log the customer out |
data-cstar-switch-to-login |
Show the login form |
data-cstar-switch-to-signup |
Show the signup form |
data-cstar-switch-to-forgot |
Show the forgot-password form |
data-cstar-switch-auth="login|signup" |
Flexible: switch via attribute value |
data-cstar-attach-trigger |
Open the file picker (clicks [data-cstar-attach]) |
data-cstar-attachment-remove |
Remove the staged attachment |
data-cstar-notifications-enable |
Request browser push permission |
data-cstar-notifications-dismiss |
Dismiss the notification prompt |
data-cstar-delete-conversation |
Delete a conversation. Reads data-conversation-id from the element or its closest [data-cstar-conversation] ancestor |
Custom Mode — Form Inputs
Add to <input>, <textarea>, or <form> elements.
Inputs
| Attribute | Element | Bound To |
|---|---|---|
data-cstar-input="messageDraft" |
textarea/input | Message composer (Enter sends, Shift+Enter newlines). Default if no value provided. |
data-cstar-input="authEmail" |
input | Auth email field |
data-cstar-input="authName" |
input | Signup name field |
data-cstar-input="authPassword" |
input | Auth password field |
data-cstar-input="subject" |
input | New-conversation subject |
data-cstar-email |
input | Shorthand for data-cstar-input="authEmail" |
data-cstar-name |
input | Shorthand for data-cstar-input="authName" |
data-cstar-subject |
input | Shorthand for data-cstar-input="subject" |
data-cstar-attach |
<input type="file"> |
The hidden file input that data-cstar-attach-trigger clicks |
data-cstar-sound-toggle |
checkbox | Toggle agent-message sound |
Forms
cStar binds the form's submit event to the matching SDK action.
| Attribute | Form Type |
|---|---|
data-cstar-form="signup" |
Signup form |
data-cstar-form="login" |
Login form |
data-cstar-form="forgot" |
Forgot-password form |
data-cstar-form="compose" |
Send a message in the active conversation |
data-cstar-form="prechat" |
Start a new conversation |
data-cstar-form="newConversation" |
Start a new conversation (alias) |
data-cstar-form="new" |
Start a new conversation (alias) |
data-cstar-signup |
Boolean alternative to data-cstar-form="signup" |
data-cstar-login |
Boolean alternative to data-cstar-form="login" |
data-cstar-compose |
Boolean alternative to data-cstar-form="compose" |
data-cstar-prechat |
Boolean alternative to data-cstar-form="prechat" |
data-cstar-newConversation |
Boolean alternative to data-cstar-form="newConversation" |
Custom Mode — Live Content
cStar updates these elements as state changes.
| Attribute | What It Renders |
|---|---|
data-cstar-company-name |
Your team's company name (textContent) |
data-cstar-company-logo |
Sets src on an <img> to your team logo |
data-cstar-status |
"Online" or "Offline" based on agent presence |
data-cstar-unread-count |
Total unread message count (hidden when 0, "99+" when over 99) |
data-cstar-content="currentConversationSubject" |
Subject of the currently open conversation |
data-cstar-connection="connected" |
Visible only when realtime is connected |
data-cstar-connection="connecting" |
Visible only while connecting |
data-cstar-connection="reconnecting" |
Visible only while reconnecting |
data-cstar-connection="offline" |
Visible only when realtime is offline |
Custom Mode — Visibility
Views (mutually exclusive)
Only one view is visible at a time.
| Attribute | Active When |
|---|---|
data-cstar-view="auth" |
Customer is in auth flow |
data-cstar-view="conversations" |
Customer is browsing conversations |
data-cstar-view="messages" |
Customer is reading a conversation |
data-cstar-view="new" |
Customer is starting a new conversation |
data-cstar-view="offline" |
Offline fallback view |
Auth-form panels (standalone)
Use these when you don't want a separate data-cstar-view="auth" wrapper.
| Attribute | Visible When |
|---|---|
data-cstar-auth-signup |
Auth form is "signup" |
data-cstar-auth-login |
Auth form is "login" |
data-cstar-auth-forgot |
Auth form is "forgot" |
data-cstar-forgot-password-sent |
After forgot-password email is sent |
Conditional visibility (data-cstar-show-when)
| Value | Visible When |
|---|---|
open |
Panel is open |
closed |
Panel is closed |
identified |
A customer is logged in |
anonymous |
No customer is logged in |
online |
Agents are available |
offline |
No agents available |
currentView:conversations |
Current view matches |
currentView:messages |
Current view matches |
currentView:auth |
Current view matches |
currentView:new |
Current view matches |
currentView:offline |
Current view matches |
authForm:signup |
Auth form matches |
authForm:login |
Auth form matches |
authForm:forgot |
Auth form matches |
conversations:empty |
Customer has no conversations |
You can combine data-cstar-view and data-cstar-show-when on the same element.
State-driven panels (auto-hidden)
Hidden by default. cStar reveals them when the state matches.
| Attribute | Visible When |
|---|---|
data-cstar-panel |
Wraps your whole chat panel — toggles with open/close. Sets data-open="true|false" for CSS hooks |
data-cstar-loading |
A request is in flight |
data-cstar-error |
An error message is set. Inner [data-cstar-error-text] receives the message |
data-cstar-error-text |
(textContent target) Receives the latest error message |
data-cstar-empty |
The conversation list is empty |
data-cstar-agent-typing |
An agent is typing |
data-cstar-attachment-preview |
A file is staged. Inner [data-cstar-attachment-name] shows the filename |
data-cstar-attachment-name |
(textContent target) Receives the staged attachment's filename |
data-cstar-notifications-prompt |
Browser notification permission is default (not granted, not denied) |
Custom Mode — Conversation List
| Attribute | Where |
|---|---|
data-cstar-conversations |
Container that holds the list |
data-cstar-conversation-template |
<template> cStar clones for each row |
data-cstar-conversation |
Row root inside the template. cStar adds data-conversation-id and binds click → opens that conversation |
data-cstar-title |
Conversation subject (inside row) |
data-cstar-preview |
Latest-message preview (inside row) |
data-cstar-time |
Relative timestamp (inside row) |
data-cstar-unread |
Unread badge content (inside row) |
Custom Mode — Message List
| Attribute | Where |
|---|---|
data-cstar-messages |
Container that holds messages |
data-cstar-message-template="agent" |
<template> cStar clones for agent messages |
data-cstar-message-template="customer" |
<template> cStar clones for customer messages |
data-cstar-message |
Message row root inside the template |
data-cstar-content |
Rendered message body (markdown for agent messages) |
data-cstar-attachments |
Container cStar fills with attachment chips |
data-cstar-time |
Relative timestamp |
data-cstar-avatar |
Receives src for the agent avatar |
data-cstar-agent-name |
Agent display name |
data-cstar-message-status="sending" |
Visible while message is sending |
data-cstar-message-status="sent" |
Visible after message is delivered |
data-cstar-message-status="failed" |
Visible if message failed to send |
data-cstar-message-retry |
Click to retry a failed message |
Index (Alphabetical)
A quick-jump list — every attribute name in one place.
data-cstar-agent-name · data-cstar-agent-typing · data-cstar-attach · data-cstar-attach-trigger · data-cstar-attachment-name · data-cstar-attachment-preview · data-cstar-attachment-remove · data-cstar-attachments · data-cstar-auth-forgot · data-cstar-auth-login · data-cstar-auth-signup · data-cstar-avatar · data-cstar-back · data-cstar-chat · data-cstar-close · data-cstar-company-logo · data-cstar-company-name · data-cstar-compose · data-cstar-connection · data-cstar-content · data-cstar-conversation · data-cstar-conversation-template · data-cstar-conversations · data-cstar-create-conversation · data-cstar-delete-conversation · data-cstar-email · data-cstar-empty · data-cstar-error · data-cstar-error-text · data-cstar-forgot-password-sent · data-cstar-forgot-password-submit · data-cstar-form · data-cstar-input · data-cstar-launcher · data-cstar-loading · data-cstar-login · data-cstar-login-submit · data-cstar-logout · data-cstar-magic-link · data-cstar-message · data-cstar-message-retry · data-cstar-message-status · data-cstar-message-template · data-cstar-messages · data-cstar-minimize · data-cstar-name · data-cstar-new-conversation · data-cstar-newConversation · data-cstar-notifications-dismiss · data-cstar-notifications-enable · data-cstar-notifications-prompt · data-cstar-panel · data-cstar-prechat · data-cstar-preview · data-cstar-quickhelp · data-cstar-send · data-cstar-show-when · data-cstar-signup · data-cstar-signup-submit · data-cstar-sound-toggle · data-cstar-status · data-cstar-subject · data-cstar-switch-auth · data-cstar-switch-to-forgot · data-cstar-switch-to-login · data-cstar-switch-to-signup · data-cstar-time · data-cstar-title · data-cstar-unread · data-cstar-unread-count · data-cstar-view
71 attribute names total — 1 prebuilt, 1 Quick Help, 69 custom mode.