Use @alzaf-it/chat-react alongside @alzaf-it/chat-sdk. React is a peer dependency; Vue is not required. The panel also needs class-variance-authority, clsx, lucide-react, radix-ui, tailwind-merge and @shadcn/react (declared as package dependencies). The host app must already provide the standard shadcn theme tokens (:root/.dark variables such as --primary); the package ships prebuilt CSS that resolves its brand styling to those host variables at runtime, so no Tailwind wiring or shadcn/tailwind.css import is required for the panel itself (the host keeps its own setup for its own components). Restricted GitHub Packages metadata is configured; local workspace/archive use remains available before registry release verification.
'use client';
import { useEffect, useMemo } from 'react';
import { ChatClient } from '@alzaf-it/chat-sdk';
import { ChatPanel } from '@alzaf-it/chat-react';
export function Messages({ token }: { token: string }) {
const client = useMemo(() => new ChatClient({
apiBaseUrl: 'https://chat.example.com/api/chat', token,
reverb: { key: 'public-app-key', host: 'chat.example.com', port: 443, scheme: 'https' }
}), [token]);
useEffect(() => () => client.disconnect(), [client]);
return <ChatPanel client={client} title="Shope messages" height={620} />;
}Tailwind v4 host wiring (as in examples/nextjs-app): install tailwindcss and @tailwindcss/postcss, add a postcss.config.mjs enabling @tailwindcss/postcss, define the standard shadcn :root/.dark tokens with an @theme inline mapping in the global CSS (the example uses an orange primary: #ea580c light / #fb923c dark), and import Tailwind before other styles:
@import "tailwindcss";Styling needs no host wiring. The package entry imports its prebuilt dist/chat.css itself, so host bundlers (Next.js/Turbopack/webpack/Vite) include the panel styles automatically when the component is imported — no Tailwind @source registration and no stylesheet import. Host precedence is structural: package utilities are emitted into @layer components while host utilities live in the later @layer utilities, so on any identical class (flex, bg-primary, rounded-md, ...) the host definition wins regardless of stylesheet order, and dark: utilities are class-based (.dark) like the host's. The host only provides the standard shadcn :root/.dark theme tokens with an @theme inline mapping in its global CSS (the example uses an orange primary: #ea580c light / #fb923c dark); brand colors and radii resolve to those host variables at runtime. Older guides mention a Tailwind @source registration pointing at the package (required up to 0.1.5) and a one-line import "@alzaf-it/chat-react/styles.css" in the root layout (0.1.6–0.1.8): both are now unnecessary — new integrations render correctly with no CSS lines, and existing ones can delete those lines after upgrading. A manual import "@alzaf-it/chat-react/chat.css" (or the styles.css alias, kept for backward compatibility) remains available but is redundant with the entry import; do not set sideEffects: false handling that drops it. Plain-Node ESM/CJS runners without CSS handling (vitest/jest, direct node imports) need a *.css stub/mock — see troubleshooting. Next.js, Vite, and webpack process the entry CSS import automatically. Host pages must also set the viewport meta (width=device-width, initial-scale=1, i.e. the Next.js viewport export) — without it mobile browsers fall back to a ~980px layout viewport, so the md panel breakpoints never trigger correctly on phones.
If the inbox looks broken in a host app — header title block and conversation list stretching full-width on desktop, thread squeezed to nothing, message bubbles without backgrounds, own messages not right-aligned — first check which package build is installed. On 0.1.5-era builds the cause is almost certainly a missing @source registration (add it per the legacy note above, or upgrade to a build containing the prebuilt CSS). On 0.1.6–0.1.8 builds confirm the root layout imports @alzaf-it/chat-react/styles.css. On newer builds the entry imports the stylesheet automatically: confirm the bundler actually processes the chat.css import from the package entry — the served page must load a stylesheet chunk from @alzaf-it/chat-react/dist, and the panel rules (for example .ac\:md\:w-75 inside the md breakpoint) must be present.
Panel height: pass height for a fixed inline height (as in the snippet above), or omit it and size with className — the default is ac:h-150 (620px), and height utilities (ac:h-*/ac:min-h-*/ac:max-h-* from the prebuilt stylesheet, or the host's own) override or extend it (for example className="min-h-page max-h-page" for a full-page inbox). An explicit height prop always wins over those classes.
The inbox composes shadcn message/message-scroller/bubble/avatar/badge/button/input/input-group/textarea/item/empty/scroll-area/separator/skeleton primitives: conversation search, status badges, unread-count badges, last-message preview with timestamps, counterpart avatars, sender/role headers, loading skeletons, empty states, a responsive list/thread layout, and Enter-to-send (Shift+Enter for newline). Attachments (images and PDFs, with or without a text body) render as tiles outside the message bubble — a text or card bubble is rendered only when there is body/card content, and the image/file tile follows it as a sibling, so an attachment-only message has no empty bubble and a wide image cannot stretch the bubble. The composer has attach and emoji controls: the attach button opens a file picker limited to the configured types and shows staged files with remove buttons while an upload is in flight; the emoji popover is built from the SDK's curated EMOJI_GROUPS (no third-party picker) and inserts at the caret. MessageAttachments is exported for hosts that render their own message list. The conversation title uses the server-selected primary participant (participants.find(item => item.is_primary)): customers receive the provider/store while sellers receive the customer, and the subject is the fallback. The same participant fills the avatar. A grouped conversation keeps that avatar's exact footprint — exactly two participants layer the second avatar over the bottom-right, and three or more keep the primary avatar with a +N badge there — while the selected thread header names the other participants (with ...) ahead of last activity. A service admin's selected thread header titles the thread with the provider/store provider_name (falling back to the subject) with the provider_avatar_url image (initials fallback) and lists every other participant in the description; the admin's list row and avatar keep the server-selected primary participant. The thread header info button opens read-only details (subject, status, provider, participants, activity) as a sidebar on roomy panels and a Details page on narrow widths and the compact popover; the full popover variant inherits the panel sidebar. Search matches every participant name, the provider/store name, the subject and the status. The thread follows the live edge with a jump-to-latest control and keeps its position when earlier history loads; the composer is an input group with the send action in a block-end addon. Colors come entirely from the host theme: set --primary/--primary-foreground/--ring (plus .dark overrides) to rebrand. Neutral surfaces all key off --muted (kept equal to --secondary); no rendered component depends on --secondary, so a single muted override recolors them. The inbox inherits the host typeface; the example scopes DM Sans first with an Inter fallback to .alzaf-inbox and loads the webfont via Google Fonts links in the root layout. Vue and the plain-HTML widget keep the dependency-free chatStyles rendering and need no Tailwind.
Read frontend reference for behavior and limitations. A client must remain stable during a session. Changing token recreates it; an async token getter supports refreshed credentials without remounting. Do not fetch privileged service credentials into this component. Next.js server pages may import the client component; connections start after mount.
The standalone website's root account provider keeps verified identity across client navigation and shows neutral placeholders on reload until /auth/me succeeds. This is example-site behavior, not SDK token persistence. See website session lifecycle. Vue, the HTML widget and embedded Laravel host authentication are unaffected.
Popover, seller buttons and in-page embeds#
Wrap the app (or layout segment) in ChatProvider so seller buttons and the popover share one session. The popover is a shadcn Popover: floating by default with a fixed corner, or inline for in-page placement. The fixed position is a preset overridable with wrapperClassName/wrapperStyle; the panel size and popover placement are overridable with className/style/side/align. The last opened conversation is persisted to localStorage (selection only, SSR-safe); set persistKey={false} to disable.
'use client';
import { useEffect, useMemo } from 'react';
import { ChatClient } from '@alzaf-it/chat-sdk';
import { ChatProvider, ChatPopover, useChatWithSeller } from '@alzaf-it/chat-react';
export function ShopLayout({ token, children }: { token: string; children: React.ReactNode }) {
const client = useMemo(() => new ChatClient({
apiBaseUrl: 'https://chat.example.com/api/chat', token,
reverb: { key: 'public-app-key', host: 'chat.example.com', port: 443, scheme: 'https' }
}), [token]);
useEffect(() => () => client.disconnect(), [client]);
return (
<ChatProvider client={client}>
{children}
{/* Floating widget, bottom-right by default */}
<ChatPopover />
</ChatProvider>
);
}
export function SellerChatButton({ sellerId, label = 'Chat' }: { sellerId: string; label?: string }) {
const { openChat, opening } = useChatWithSeller(sellerId, { subject: 'Product enquiry' });
return <button onClick={() => void openChat()} disabled={opening}>{opening ? 'Opening...' : label}</button>;
}Position, trigger and panel overrides:
<ChatPopover position="bottom-left" title="Support" width={400} height={600} />
<ChatPopover wrapperClassName="bottom-6 right-6" triggerClassName="size-14" className="rounded-2xl" />
<ChatPopover showTrigger={false} /> // seller buttons only; no floating button
<ChatPopover mode="inline" title="Messages" height={640} /> // in-page embed, no fixed positioning
<ChatPopover variant="full" /> // sidebar inbox on md+ (2-page flow below md), 860x620 defaultInside the provider, useChat() exposes openChatWithProvider(providerId), openConversation(conversation), backToInbox(), isOpen/setOpen/toggle and totalUnread. Message cards render through the built-in generic MessageCardView; to customize a kind, pass cardRenderers={{ order: (card) => <OrderCard card={card} /> }} to ChatProvider (or directly to ChatPanel) — unregistered types keep the built-in card. See message cards for the host mapping recipe, the suggestCard "chat about this product" flow and the runnable /chat-preview demo. To share a full-page inbox with the popover, render it inside the provider; it inherits the client and shared session, so <ChatPanel /> alone is enough. Passing them explicitly (const { client, session } = useChat(); <ChatPanel client={client} session={session} />) is equivalent and kept for clarity. Standalone popover without a provider: <ChatPopover client={client} />. No extra Tailwind wiring is needed; the entry's automatic stylesheet import covers ui/popover.tsx like the rest of the panel.
Runnable example: examples/nextjs-app. Build packages first, then use the repository's local setup commands. The example accepts a user token; production host authentication supplies it. It uses public LAN-accessible API and Reverb endpoints, with matching allowed origins.