2.7.1 • Published 1 month ago

@saytv/chat-react

Licence

—

Version

2.7.1

Deps

Size

21 kB

Vulns

Weekly

Summary Dependency Versions

@saytv/chat-react

React wrapper for the SayTV Chat SDK — a fully featured, themeable chat widget.

Installation

npm install @saytv/chat-react

Usage

import { SayTVChat, useSayTVChat } from '@saytv/chat-react';

function App() {
  const { chatRef, setToken, setTheme } = useSayTVChat();

  return (
    <SayTVChat
      ref={chatRef}
      appId="your-app-id"
      theme="light"
      height={700}
      width="100%"
      onMessageSent={(e) => console.log('Sent:', e.detail)}
      onError={(e) => console.error('Error:', e.detail)}
    />
  );
}

Props

Prop	Type	Required	Description
`appId`	`string`	No	App identifier (resolves API URL)
`env`	`'production' \| 'staging'`	No	Environment (default: `'production'`)
`apiUrl`	`string`	No	API base URL (overrides appId/env)
`authToken`	`string`	No	User access token
`builtInAuth`	`boolean`	No	Enable built-in login UI (default: `true`)
`fanzone`	`boolean`	No	Enable fanzone features (default: `false`)
`height`	`number`	No	Height in pixels (default: `850`)
`width`	`string`	No	CSS width (default: `'450px'`)
`theme`	`'light' \| 'dark'`	No	Color theme (default: `'light'`)
`locale`	`string`	No	BCP-47 UI language, e.g. `'ar'`, `'pt-BR'` (default: `'en'`). RTL languages lay out automatically
`translations`	`Record<string, Record<string, string>>`	No	Translation catalogs keyed by locale, merged over English
`translationsUrl`	`string`	No	URL of a hosted flat catalog to fetch for the active locale
`mode`	`'page-chat'`	No	Widget mode
`pageId`	`string`	No	Page identifier (used with `mode="page-chat"`)
`pageName`	`string`	No	Page display name (used with `mode="page-chat"`)
`hideHeader`	`boolean`	No	Hide the top title bar (default: `false`)
`hideFooter`	`boolean`	No	Hide the bottom tab-bar navigation (default: `false`)
`avatarUrl`	`string`	No	Image URL to use as the signed-in user's avatar (unless they pick one in-app)
`className`	`string`	No	CSS class on wrapper div
`style`	`CSSProperties`	No	Inline styles on wrapper div

Visual customization (colors, spacing, header/footer styling, moderator/message appearance, etc.) is done with --stv-* CSS variables set on the <saytv-chat> element. Pass them through the style prop, e.g. style={{ ['--stv-header-bg']: '#0b1020', ['--stv-message-gap']: '12px' }}. See the Theming and Sizing & Layout guides for the full list.

Event Callbacks

Prop	Description
`onReady`	Widget initialized and ready
`onUserLogin`	User logged in
`onUserLogout`	User logged out
`onMessageSent`	Current user sent a message
`onMessageReceived`	New message received from another user
`onNavigation`	Page changed within the widget
`onEpisodeChanged`	User selected an episode
`onRoomJoined`	User entered a chat room
`onThemeChanged`	Color theme switched
`onPageChatReady`	Page chat episode created or reconnected
`onError`	SDK error occurred

All event callbacks receive a CustomEvent with relevant data in event.detail.

Hook

const { chatRef, getElement, setToken, setTheme, setUsername } = useSayTVChat();

Return	Description
`chatRef`	Pass to `<SayTVChat ref={chatRef}>` for imperative access
`getElement()`	Returns the underlying `<saytv-chat>` HTMLElement
`setToken(token)`	Update the access token
`setTheme(theme)`	Switch between `'light'` and `'dark'`
`setUsername(name)`	Rename the signed-in user. Returns a `Promise<User>`; rejects with a `422` and `errors.username` when the name is taken, too short, or blocked by moderation

Theming

Override CSS custom properties via inline styles:

<SayTVChat
  appId="your-app-id"
  style={{ '--stv-color-primary': '#4f46e5' } as React.CSSProperties}
/>

See the @saytv/chat-sdk docs for the full list of CSS custom properties.

Localization

Set the UI language with locale (BCP-47). English is built in; supply other languages as catalogs — any untranslated key falls back to English. RTL locales lay out automatically.

// Option A: point at a hosted catalog (SayTV publishes en/ar/es/fr)
<SayTVChat
  appId="your-app-id"
  locale="es"
  translationsUrl="https://sdk.saytv.net/@saytv/chat-sdk@latest/locales/es.json"
/>

// Option B: pass a catalog object
<SayTVChat
  appId="your-app-id"
  locale="ar"
  translations={{ ar: { 'auth.login.title': 'مرحبا بعودتك', 'nav.chat': 'الدردشة' } }}
/>

See the Localization guide for the full key list and ready-made catalogs.