React component and hook reference
@beepgrid/react is the optional browser package for a same-origin application with an authenticated HttpOnly person session. It is not a way to embed an owner or worker token in a webpage. The SDK packages are currently built from source; see React setup.
browserClient
Section titled “browserClient”browserClient(baseURL = window.location.origin): Client constructs the HTTP client with an empty bearer token so the browser’s same-origin session can authenticate. Call it in a browser context or pass an explicit URL during SSR. A cross-origin URL does not create a new authentication mechanism.
Create the client once rather than recreating it on every render, because hooks depend on client identity.
useBeepgridRequest
Section titled “useBeepgridRequest”useBeepgridRequest(client: Client, id: string) takes a stable client and canonical request ID. It returns:
| Return | Usage |
|---|---|
request: RequestItem | null |
Current request; null before loading or after an inaccessible read |
error: string |
Current safe error text |
busy: boolean |
Whether a typed response is being submitted |
respond(outcome, answer?) |
Submit with the hook’s current request version |
It fetches immediately and polls every second without overlapping refreshes. ID/client changes clear stale state. Cleanup aborts pending reads and clears the timer; an old response does not populate a new request. A version conflict remains an error and is not overwritten locally as if the decision succeeded.
BeepgridRequest
Section titled “BeepgridRequest”<BeepgridRequest client={client} id={id} onConversation={...} onResolved={...} />
| Prop | Required | Meaning |
|---|---|---|
client: Client |
Yes | Stable authenticated browser client |
id: string |
Yes | Canonical request ID |
onConversation?: (id: string) => void |
No | Called when opening its conversation |
onResolved?: (request: RequestItem) => void |
No | Called once per displayed request reaching a non-open state, including cancellation/expiry |
The component renders loading/error state, choice or text input and typed outcome controls according to the current request. Successful rendering never grants permission to decide. It uses the hook’s lifecycle and current version.
BeepgridConversation
Section titled “BeepgridConversation”<BeepgridConversation client={client} id={conversationId} /> requires the stable authenticated client and canonical conversation ID. It loads currently disclosed participants and messages, polls for updates and supports sending normal follow-up messages in that history. Errors remain visible; changing ID clears stale conversation state. Unmount cleanup prevents stale updates.
Styling and re-exports
Section titled “Styling and re-exports”Components use beepgrid-request and beepgrid-conversation class roots with semantic HTML, status/error roles and native form controls. Import the optional @beepgrid/react/styles.css export for default styling, or supply your own CSS around those classes. They are deliberately small primitives rather than a complete dashboard design system; there are no undocumented theme-provider or renderer-slot props.
The package re-exports Client and RequestItem types and declares an exported Conversation type with id: string, title: string and messages: Message[]. Other engine operations remain available through the underlying client; React components do not define a separate capability boundary.
The repository tests cover polling cleanup, ID changes, stale response protection, decisions and rendering. The maintained React example is type-checked against a clean consumer of the built packages.