Chat widget chrome

The storefront's Inbox chat widget is theme chrome, like the promo bar. The platform keeps the session, the live connection, message delivery and attachments behind @poltura/theme-sdk/inbox. The theme decides how the pieces are arranged.

Where it isCopy Anchor Link

Put the widget in src/layout/chat.tsx as the file's default export. The storefront mounts it from that path. Without the file, the platform's complete widget mounts instead, the same one <InboxWidget /> draws. The default theme ships this file:

import {
  InboxChatGlyph,
  InboxComposer,
  InboxConversation,
  InboxLauncher,
  InboxOfflineForm,
  InboxPanel,
  InboxPanelHeader,
  InboxRoot,
  InboxStatusLine,
} from '@poltura/theme-sdk/inbox';

export default function ThemeChatWidget() {
  return (
    <InboxRoot className='pol-chat'>
      <InboxPanel className='pol-chat__panel'>
        <InboxPanelHeader className='pol-chat__header' />
        <InboxConversation className='pol-chat__conversation' />
        <InboxStatusLine className='pol-chat__status' />
        <InboxOfflineForm className='pol-chat__offline' />
        <InboxComposer className='pol-chat__composer' />
      </InboxPanel>
      <InboxLauncher className='pol-chat__launcher'>
        <InboxChatGlyph />
      </InboxLauncher>
    </InboxRoot>
  );
}

Every part must render inside <InboxRoot>, which renders nothing when the store offers no chat. useInbox() reads the view and actions from that context.

Render InboxConversation as the panel body. It shows the message list, and shows the open help article in its place once a shopper picks one. A layout that renders InboxMessageList directly must switch to InboxKnowledgeArticle itself while view.knowledge.article is set, or picking an article does nothing visible.

PartsCopy Anchor Link

useInbox() returns { view, actions }:

• view.copy holds the widget's wording, already resolved: the theme's chat texts first, then the platform's inbox.* messages.
• actions.send, attach, removeAttachment and retry are the only chat actions a theme calls. actions.open, close and toggle drive the panel.
• view.appearance carries the merchant's side, colour mode and colours.
• The store's help articles live on view.knowledge (enabled, query, results, loading, article), with actions.searchKnowledge, openArticle and closeArticle. enabled is true when the store has at least one published article. An article links to /guides/{category}/{slug} when that page exists. Otherwise the panel shows its sanitized body inline.

The platform widget (InboxWidget) shows an empty thread as a greeting card and one Help section: a search field, then up to three suggested articles. InboxMessageList draws that empty state when help articles are on. InboxConversation replaces the list with InboxKnowledgeArticle while an article is open. "Still need help? Send a message" closes the article and focuses the composer. In the Customizer, the help search returns sample results. The launcher stays visible on desktop while the panel is open, and hides on screens narrower than 640px.

Stable classesCopy Anchor Link

Restyle from src/styles/theme.css with :where(), same as the other chrome hooks. See Chrome stable classes.

Colours are CSS variables on the root: --inbox-accent, --inbox-accent-text, --inbox-bg and --inbox-text.

SettingsCopy Anchor Link

The theme settings group chat (and chat_dark for the dark mode colours) styles the widget in the Customizer. It does not turn chat on for the store: that is the store's Inbox setting.

Selecting the chat in the Customizer opens the panel on sample data. InboxRoot does this, so theme code needs nothing for it.

NextCopy Anchor Link

• Chrome stable classes: the override pattern for every platform part.
• inbox reference: every export of @poltura/theme-sdk/inbox.