Every data-cstar-* attribute cStar recognizes, on a single page. Use Cmd+F.

Looking for narrative? See:

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.