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. For full programmatic control via npm packages instead, check the JS, React, and Svelte SDKs. ## Installation Add the custom widget script to your page: ```html ``` Replace `YOUR_TEAM_SLUG` with your team slug or ID (found in Settings > Team > Install). 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: | 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 | ### Form Inputs Add these to `` or `

` elements:

| Attribute | Description |
|-----------|-------------|
| `data-cstar-input` | Message text input (Enter sends, 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">`) |
| `data-cstar-sound-toggle` | Checkbox for sound notifications |

### Content Display

Automatically updated with live data:

| Attribute | Description |
|-----------|-------------|
| `data-cstar-company-name` | Your team's company name |
| `data-cstar-company-logo` | Sets `src` on an `<img>` to your logo |
| `data-cstar-status` | "Online" or "Offline" |
| `data-cstar-unread-count` | Number of unread messages |
| `data-cstar-connection` | Connection status text |

### Conditional Visibility

Use `data-cstar-show-when` for state-based visibility:

```html
<div data-cstar-show-when="identified">Welcome back!</div>
<div data-cstar-show-when="anonymous">Please sign in</div>
```

Available conditions: `open`, `closed`, `identified`, `anonymous`, `online`, `offline`, `loading`, `has-conversations`, `no-conversations`, `agentIsTyping:true`, `authForm:signup`, `authForm:login`, `currentView:messages`, `currentView:conversations`, `conversations:empty`.

### View Containers

Define sections that switch based on the current view:

```html
<div data-cstar-view="auth"></div>
<div data-cstar-view="conversations"></div>
<div data-cstar-view="messages"></div>
<div data-cstar-view="new"></div>
```

Only the active view is visible at any time.

### Templates

Define how conversations and messages render:

```html
<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>

<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>
```

## JavaScript API

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

```javascript
// 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

1. Wrap your chat UI in `data-cstar-panel` so it toggles visibility
2. Use templates to let the binder handle rendering conversations and messages
3. Test `data-cstar-show-when` -- conditional visibility handles most state management
4. Keep clickable elements at least 42px for mobile touch targets
5. Article content comes back as markdown -- use a library like marked to render it as HTML</article></body></html>

Welcome to cStar Support

Popular articles