Surface and chat
The floating chat surface, a static chat for previews, and how to open and close it.
BaseeraSurface is the default chat. It is a launcher in a corner of the page that opens a panel with the conversation and a typing row. On a phone the panel takes the whole screen. It runs on useBaseeraChat, and it streams text, shows tool activity and approval cards inside the conversation, shows sources under replies, and turns errors into friendly text.
It lives in @baseera/ui/connected and must render inside BaseeraProvider.
import "@baseera/ui/baseera.css";
import { BaseeraSurface } from "@baseera/ui/connected";
<BaseeraSurface locale="ar" placement="bottom-end" />Props
Prop
Type
Placement
placement fixes the corner. The reading end follows the direction: bottom-end is bottom right in English and bottom left in Arabic.
<BaseeraSurface locale="en" placement="bottom-start" />Open and close from your own UI
The surface opens on the chat each time openRequest goes up. Keep a counter in state and bump it from a button, or from a first-visit greeting.
"use client";
import { BaseeraSurface } from "@baseera/ui/connected";
import { useState } from "react";
export function HelpButton() {
const [request, setRequest] = useState(0);
const [open, setOpen] = useState(false);
return (
<>
<button type="button" onClick={() => setRequest((n) => n + 1)} aria-expanded={open}>
Ask Baseera
</button>
<BaseeraSurface openRequest={request} onOpenChange={setOpen} />
</>
);
}onOpenChange reports every open and close, including the ones the person does with the launcher or the close button. Closing from code is not part of the surface props: the person closes it with the close button or Esc.
Put the launcher in your toolbar
Pass anchorRef to draw the launcher inside an element you own. It sits in the page flow instead of floating, and gives the place back while the panel is open. placement is then where the open panel sits, and defaults to top-end.
"use client";
import { BaseeraSurface } from "@baseera/ui/connected";
import { useRef, useState, useEffect } from "react";
export function Toolbar() {
const slot = useRef<HTMLSpanElement>(null);
const [ready, setReady] = useState(false);
useEffect(() => setReady(true), []);
return (
<header>
<span ref={slot} />
{ready && <BaseeraSurface anchorRef={slot} />}
</header>
);
}Errors
The surface shows friendly text for these codes and a generic line for any other: provider_out_of_credit, provider_rate_limited, agent_not_configured, network_error, rate_limited and limit_reached. The developer message is never shown to end users. Use onError on the provider for your own logging.
The chat without the surface
If you want a different layout, skip BaseeraSurface and use useBaseeraChat with ChatTranscript, BaseeraApprovals and BaseeraToolActivity. To show the chat panel in a page with no session at all, for a preview or a docs page, use BaseeraStaticChat.