@greatstore/react

A React component for embedding GreatStore chat, with typed props and lifecycle that follows your component tree instead of managing it by hand.

npm install @greatstore/react

import { GreatStore } from "@greatstore/react";

<GreatStore store="my-store" />

Renders no visible DOM of its own. Unmounting fully tears the embed down (script tag, mounted UI, listeners) rather than leaking it. Works in Server Component trees (no "use client" needed in your own file).

Props

| Prop | Type | Default | Notes | |---|---|---|---| | store | string | — required | Tenant slug. | | host | string | "greatstore.ai" | Apex domain the embed loads from. | | theme | GreatStoreTheme | undefined | See below. Unset fields fall back to the store's admin config. | | aiDisclaimer | { enabled?: boolean; text?: string } | undefined | text up to 200 chars; implies enabled: true unless enabled: false is also set. | | pushSwPath | string | undefined | Path to a self-hosted gs.js, if not at site root. Only relevant with enableNotifications(). | | onError | (error: Error) => void | undefined | Fires on load/mount failure (bad domain, network, or a stalled mount after 15s). Never thrown. |

Not overridable via props: sales guide, display name, assistant name, logo, icons — always the store's admin config.

Props are read once, at mount — not watched reactively. Changing theme/aiDisclaimer/pushSwPath after mount has no effect; changing store/host unmounts and remounts with a fresh script.

GreatStoreTheme

| Field | Type | Notes | |---|---|---| | mode | "auto" \| "light" \| "dark" \| "custom" | | | radius | "sharp" \| "default" \| "rounded" | | | panelPosition | "left" \| "right" \| "middle" | Desktop only. | | mobileBottomBar | boolean | | | zIndex | number | Stacking order of the chat overlay, 0–2147483647. Lower it if page UI must stay on top. | | fontFamily | string | CSS font-family value. | | secondaryFontFamily | string | CSS font-family value. | | brandColor | string | CSS color. Only used when mode: "custom". | | surfaceColor | string | CSS color. Only used when mode: "custom". | | textColor | string | CSS color. Only used when mode: "custom". |

Ref (GreatStoreHandle)

const ref = useRef<GreatStoreHandle>(null);
<GreatStore store="my-store" ref={ref} />
ref.current?.sendMessage("What's on sale?");

| Member | Signature | |---|---| | open | () => void | | close | () => void | | toggle | () => void | | sendMessage | (text: string) => void | | updateModelContext | (text: string) => void | | on | (event: "open" \| "close", handler: (...args: unknown[]) => void) => () => void (unsubscribe) | | generateStructuredContent | <T>(schema: object, prompt: string) => Promise<T> | | enableNotifications | () => Promise<{ ok: boolean }> | | ready | Promise<void> — fresh promise per mount, rejects on mount failure |

Calls made before the embed finishes loading are queued and replayed once ready.

Constraints

• One <GreatStore> at a time — window.GreatStore is a page-level singleton; a second concurrent mount won't create an independent panel.