# Connect a React app to your backend with Beamline UI

By Danylo Pravda, 2026-10-23

Beamline UI provides React components and screens. Your app supplies the records, streams, sessions and saves.
A backend connection has two directions: decoded data goes into props, and a person's action goes out through a
callback. The component does not choose your API or store credentials.

The [full data integration guide](https://beamline.io/docs/data-integration) contains complete TypeScript files for a paged REST grid,
React Query and SWR reads, WebSocket/SSE market snapshots, a form POST and a Next.js Server Component. Each example
is compiled and rendered against built Beamline packages in a fresh consumer app. Its API is a local test fixture,
so the result is evidence for the examples, not certification of a customer's backend.

## Choose the boundary you already have

| Your app has | Put the connection here | Give Beamline |
|---|---|---|
| A REST API | A fetch function and a hook in your app | Decoded records and request state |
| React Query or SWR | The app's existing query cache | Its data, loading and error values |
| A WebSocket or SSE stream | One subscription with cleanup and a data adapter | A new bounded snapshot when data changes |
| Next.js server-rendered pages | Fetch in the Server Component; keep handlers in a client file | Serializable records passed to the client view |
| An authenticated form endpoint | An awaited submit handler | Confirmed saved values or a rejected promise |

## Start with one read

Use the [REST example](https://beamline.io/docs/data-integration#rest-validate-once-then-render) to map your response into the
[data grid](https://beamline.io/components/data-grid). Its columns are typed, record IDs are stable and a missing amount stays `null`.
A response with no records shows an empty state; a failed response shows an error. Neither is replaced by a made-up
zero. An aborted old request cannot overwrite the current page.

The example's `data` and `total` are an explicit contract you implement. An existing API can keep its own contract:
map its fields in the adapter, without changing the component. When the page works, reuse that adapter with
[React Query or SWR](https://beamline.io/docs/data-integration#react-query-and-swr) if the app already uses either one.

## Make writes report the server's result

For a form, return the request promise from the handler. Check the HTTP status and validate the response before
showing success. The [form POST example](https://beamline.io/docs/data-integration#forms-that-post-back) keeps the draft on rejection
and uses the server's confirmed value on success. The [Form component](https://beamline.io/components/form) supplies the field and
pending/error wiring; your server supplies validation and storage.

A grid edit is a different contract. `DataGrid.onCellEdit` tells your app what changed; it does not await a save or
manage rollback. Keep pending/error state in the app and update the grid's `data` with your chosen confirmed or
draft values. For an entire profile screen, [Settings](https://beamline.io/components/settings) has an awaited `onSave` callback and
preserves continued edits; the [profile notes](https://beamline.io/docs/data-integration#personal-profile-and-continued-edits) explain it.

Verify a save by reading the stored record after reload. A success toast proves that the UI displayed a message.

## Add live data without losing its meaning

The [stream example](https://beamline.io/docs/data-integration#live-streams-websocket-or-sse-into-a-book-chart-and-grid) connects either
WebSocket or SSE to the same [order book](https://beamline.io/components/order-book), [price chart](https://beamline.io/components/price-chart) and grid.
It validates complete snapshots, rejects out-of-order sequence numbers within a connection, bounds retained rows
and candles, closes the connection on unmount, and labels old data when a connection stops delivering updates.

That contract matters: replacing a full snapshot is different from applying an exchange's delta feed. If your
exchange sends deltas, preserve its sequencing rules and reload a snapshot after a gap. Put that logic in the
adapter, not in several components. Candle times are UTC seconds, and missing prices must not become zero.

## Keep large results on the server when needed

The grid virtualizes the rows it receives. It still sorts and filters those received rows in the browser. For
server paging, use [Pagination](https://beamline.io/components/pagination) to request one page, disable local controls that would
misrepresent a partial dataset, and label totals for the scope they actually cover. A cursor API does not need an
invented page count. See [pagination and large data](https://beamline.io/docs/data-integration#pagination-and-large-data).

## Keep authentication separate from the screen

**Clerk is the only authentication integration proven in Beamline's own service.** beamline.io uses the kit's
[Auth block](https://beamline.io/components/auth) with Clerk. Auth.js, Supabase Auth, Firebase Auth, Auth0 and a custom session API are
possible adapter patterns, explicitly untested here. A displayed sign-in state is not permission to read a record;
server-side authorization must protect requests and subscriptions. The [authentication section](https://beamline.io/docs/data-integration#authentication-what-is-proven-and-what-is-a-pattern)
states the boundary and the stream-credential constraints.

## Ask your agent for a connection you can verify

After [connecting your agent](https://beamline.io/connect), give it the endpoint contract, identity/permission rules and the screen's
expected states. For example: “Install Beamline's data grid and pagination. Use our /api/deals page response. Keep
unknown amounts unmeasured, show loading and failed requests separately, and verify page changes and saved records
after reload. Use our existing authentication and query cache.”

The agent can choose and install the UI parts. Your API contract determines whether the connection is correct.

Part of [Beamline UI: polished, editable React components and complete screens for custom applications](https://beamline.io/). [Build your own style from any look; tokens, fonts, radii, motion; not only colours](https://beamline.io/docs/customize).