React components

All components are exported from @gnomondigital/nebulas-kit-react and are client components. In Next.js, use them from a file marked "use client".

A2AChatFloating

A floating button (bottom-right) that opens a chat panel. Accepts every A2AChat prop except layout, plus:

Prop	Type	Default	Description
panelTitle	string	labels.title or "Chat"	Header title of the panel.
defaultOpen	boolean	false	Open the panel on mount.
panelClassName	string		Classes for the panel (width, height, shadow).
fabClassName	string		Classes for the floating button.
usePortal	boolean	true	Render into document.body so parent stacking contexts can’t clip it.

A2AChat

The chat UI: message list, streaming answers, suggested prompts and the message input.

Prop	Type	Default	Description
a2aEndpoint	string	"/api/a2a"	Your chat proxy route.
configEndpoint	string	"/api/a2a/config"	Your config route (agent card, project, brand).
nebulasBaseUrl	string		Nebulas proxy route. When set, conversations are recorded in the project. See Full-page chat.
user	{ name?, picture? } | null		Signed-in user, used for avatars.
labels	A2AChatLabels	see below	UI texts.
suggestedPrompts	string[]		Clickable prompts shown on an empty chat.
showAttachFileButton	boolean	false	Shows the paperclip (PDF, Word, Markdown, plain text).
layout	"page" | "panel"	"page"	page takes the viewport height, panel fills its parent.
streaming	boolean	from agent card	Force streaming on or off.
getAuthHeaders	() => Record<string,string> | Promise<…>		Extra headers on config and chat requests, such as a Bearer token.
authDependency	unknown		Change it (for example to the token) to reload the config.
onError	(message: string) => void		Called when a request fails.
locale	string		Locale for dates and times.
className	string		Classes on the root element.

A2AChatLabels (defaults in brackets): title (“Chat”), description (“Ask anything”), newChat (“New chat”), howCanIHelp (“How can I help?”), askAbout (“Ask me anything.”), placeholder (“Type a message…”).

NebulasSurface

Renders a widget (surface) from Nebulas on its own, such as a form, a report or a list, and sends its actions back to Nebulas.

Give it either surfaceName or surfaceId, not both.

Prop	Type	Default	Description
surfaceName	string		Name of the widget in Studio. Works across environments.
surfaceId	string		Id of the widget definition. Skips the name lookup.
endpoint	string	"/api/nebulas-surfaces"	Where your surface handler is mounted.
inputs	Record<string, unknown>		Values for the widget’s declared inputs, hidden ones included.
data	Record<string, unknown>		Prefill, merged over the initial data.
trackingParams	boolean | string[]		true reads the five utm_* keys from the URL. A list reads the keys you name.
searchParams	string | URLSearchParams	window.location.search	Where to read trackingParams from.
theme	"brand" | "product"	"brand"	Use the widget’s brand, or your page’s tokens.
successDialog	{ title?, message, closeLabel? }		Show a dialog on success, then reset to a blank form.
captcha	{ render(onVerify), dataPath? }		Blocks submitting until onVerify(token) is called. The token goes to dataPath (default /captcha_token).
onResult	(result, action) => void		Called after every action with the raw result { status, message, errors, … }.
onChatMessage	(message, action) => void		A chat handler produced a message. You decide what to do with it.
sessionId	string		Conversation id, so the submission is recorded in that conversation.
labels	{ loading, error, retry, pending, captchaRequired }	English	Built-in texts.
locale	string	"en"	Language of the widget’s own labels.
t	(key, options?) => string		Translates i18n: labels the widget doesn’t cover.
resolveImageSrc	(src) => Promise<string | null>		Turns an image src (such as neb://…) into a URL that can load.
className	string		Classes on the wrapper.

result.status is one of:

• "ok": success.
• "invalid": field errors in result.errors, keyed by field.
• "error": something failed; see result.message.

useA2AAuth

Sign-in state for browser ROP.

const { token, isLoading, error, login, logout } = useA2AAuth({
  authEndpoint: "/api/a2a/auth", // POST { username, password } → { access_token }
  storageKey: "nebulas-kit-a2a-token", // sessionStorage key (default)
});
await login(username, password);

See Full-page chat → browser ROP.

Lower-level exports

To build your own UI: ChatMessages, ChatInput, SurfaceRenderer, useSurfaceActions, useSurfaceModel, renderCatalogComponent.