# React component and hook reference

Props, callbacks, loading, polling and authentication for the browser package.

`@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](https://beepgrid.com/docs/sdks/react.md).

## 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

`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

`<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

`<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

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](https://beepgrid.com/docs/sdks/react.md) is type-checked against a clean consumer of the built packages.