Custom Chat Widget (Data Attribute Mode)

Build your own chat interface with complete control over HTML, CSS, and behavior. You provide the markup and styling — cStar binds everything automatically via data-cstar-* attributes.

Overview

Custom Widget mode gives you a lightweight embed script (~9KB gzipped) that connects your HTML to cStar's chat backend. Unlike the pre-built widget (which renders its own UI), custom mode reads data-cstar-* attributes from your existing HTML and wires up all the functionality — authentication, messaging, real-time updates, file attachments, and more.

Choose this mode when you need pixel-perfect control over the chat UI but don't want to build the data layer from scratch.

Looking for full programmatic control via npm packages instead? Check out our JS, React, and Svelte SDKs.

Installation

Add the custom widget script to your page:

<script src="https://YOUR_DOMAIN/widget/custom.min.js?team=YOUR_TEAM_ID"></script>

Replace YOUR_DOMAIN with your cStar instance URL and YOUR_TEAM_ID with your team ID (found in Settings > Chat Widget > Embed Code).

The script scans your page for data-cstar-* attributes and binds them automatically. No initialization code required.

Data Attributes Reference

Action Buttons

Add these to any clickable element (buttons, links, divs) to trigger actions:

Attribute	Description
`data-cstar-launcher`	Toggle chat panel open/closed
`data-cstar-close`	Close the chat panel
`data-cstar-minimize`	Minimize the chat panel
`data-cstar-back`	Navigate back to conversations list
`data-cstar-new-conversation`	Show the new conversation form
`data-cstar-send`	Send the current message
`data-cstar-signup-submit`	Submit the signup form
`data-cstar-login-submit`	Submit the login form
`data-cstar-logout`	Log out the current customer
`data-cstar-switch-to-login`	Switch auth view to login
`data-cstar-switch-to-signup`	Switch auth view to signup
`data-cstar-notifications-enable`	Request push notification permission
`data-cstar-notifications-dismiss`	Dismiss the notification prompt
`data-cstar-attach-trigger`	Open the file picker
`data-cstar-attachment-remove`	Remove the currently attached file
`data-cstar-delete-conversation`	Delete a conversation (on a `[data-cstar-conversation]` element)

Form Inputs

Add these to <input> or <textarea> elements:

Attribute	Description
`data-cstar-input`	Message text input (Enter to send, Shift+Enter for newline)
`data-cstar-email`	Email input for auth forms
`data-cstar-name`	Name input for signup
`data-cstar-subject`	Subject input for new conversations
`data-cstar-attach`	File input (`<input type="file">`) for attachments
`data-cstar-sound-toggle`	Checkbox to toggle sound notifications

Content Display

These elements are automatically updated with live data:

Attribute	Description
`data-cstar-company-name`	Displays your team's company name
`data-cstar-company-logo`	Sets the `src` of an `<img>` to your company logo
`data-cstar-status`	Shows "Online" or "Offline" text
`data-cstar-unread-count`	Shows the number of unread messages
`data-cstar-connection`	Shows connection status text

Visibility Controls

These elements are automatically shown/hidden based on state:

Attribute	Description
`data-cstar-panel`	Main chat panel container (visible when open)
`data-cstar-agent-typing`	Typing indicator (visible when agent is typing)
`data-cstar-loading`	Loading state container
`data-cstar-error`	Error message container
`data-cstar-empty`	Empty state (no conversations)
`data-cstar-notifications-prompt`	Notification permission prompt
`data-cstar-attachment-preview`	Attachment preview (visible when file is attached)

Conditional Visibility

Use data-cstar-show-when for fine-grained visibility based on state:

<!-- Show only when chat is open -->
<div data-cstar-show-when="open">Chat is open</div>

<!-- Show only when customer is logged in -->
<div data-cstar-show-when="identified">Welcome back!</div>

<!-- Show only when not logged in -->
<div data-cstar-show-when="anonymous">Please sign in</div>

Available conditions:

Condition	Description
`open`	Chat panel is open
`closed`	Chat panel is closed
`identified`	Customer is logged in
`anonymous`	Customer is not logged in
`online`	Connected to server
`offline`	Disconnected from server
`loading`	Data is loading
`has-conversations`	Customer has conversations
`no-conversations`	Customer has no conversations
`agentIsTyping:true`	Agent is currently typing
`authForm:signup`	Signup form is active
`authForm:login`	Login form is active
`currentView:messages`	Messages view is active
`currentView:conversations`	Conversations list is active
`conversations:empty`	Conversations list is empty

View Containers

Use data-cstar-view to define sections that switch based on the current view:

<div data-cstar-view="auth"><!-- Login/signup forms --></div>
<div data-cstar-view="conversations"><!-- Conversation list --></div>
<div data-cstar-view="messages"><!-- Active conversation --></div>
<div data-cstar-view="new"><!-- New conversation form --></div>

Only the active view is visible at any time.

Templates

Use template elements to define how conversations and messages are rendered:

<!-- Conversation list -->
<div data-cstar-conversations>
  <template data-cstar-conversation-template>
    <div data-cstar-conversation>
      <span data-cstar-conversation-subject></span>
      <span data-cstar-conversation-preview></span>
    </div>
  </template>
</div>

<!-- Messages -->
<div data-cstar-messages>
  <template data-cstar-message-template="agent">
    <div><span data-cstar-message-content></span></div>
  </template>
  <template data-cstar-message-template="customer">
    <div><span data-cstar-message-content></span></div>
  </template>
</div>

Attachment Preview

<div data-cstar-attachment-preview>
  <span data-cstar-attachment-name></span>
  <span data-cstar-attachment-size></span>
  <img data-cstar-attachment-preview />
  <div data-cstar-attachment-progress></div>
  <button data-cstar-attachment-remove>Remove</button>
</div>

Forms

Group form elements with these container attributes:

Attribute	Description
`data-cstar-signup`	Signup form container
`data-cstar-login`	Login form container
`data-cstar-compose`	Message compose form
`data-cstar-prechat`	Pre-chat form (before conversation starts)

JavaScript API

The embed script also exposes window.CStarChat for programmatic control:

// Panel
CStarChat.open();
CStarChat.close();
CStarChat.toggle();

// Auth
await CStarChat.signup({ email, name, password });
await CStarChat.login({ email, password });
CStarChat.logout();
CStarChat.isIdentified();
CStarChat.getCustomer();

// Messaging
CStarChat.send('Hello!');
await CStarChat.startConversation({ subject, message });
CStarChat.getConversations();

// Knowledge Base
await CStarChat.searchArticles('billing', 5);
await CStarChat.getArticle('api-authentication');
await CStarChat.getPopularArticles(5);
await CStarChat.getCategories();
await CStarChat.getLibraryStats();

// Events
CStarChat.on('message:received', (msg) => { });
CStarChat.on('unread', (count) => { });
CStarChat.on('identify', () => { });
CStarChat.on('logout', () => { });
CStarChat.on('ready', () => { });

Tips

Start with a view container — wrap your chat UI in data-cstar-panel so it toggles visibility
Use templates — let the binder handle rendering conversations and messages
Test data-cstar-show-when — conditional visibility handles most state management for you
Touch targets — keep clickable elements at least 42px for mobile
Article content is markdown — use a library like marked to render article content as HTML