Quick Start (Developers) — Guide52

What You're Installing

@bizfirst/hil-ui-chat-window is a standalone package that plugs into the existing HIL frontend stack (hil-types → hil-core → hil-react → hil-ui). It sits alongside hil-ui's existing overlay, not inside it — your app decides which one to render for a given request.

1. Install the Package

It's a workspace package in the monorepo, so add it as a dependency the same way as any other @bizfirst/* package:

{
  "dependencies": {
    "@bizfirst/hil-ui-chat-window": "workspace:*"
  }
}

2. Import Both Stylesheets

Both stylesheets are required The chat window reuses a couple of components from hil-ui (the action bar and the countdown timer) unmodified — they render CSS classes defined in hil-ui's own stylesheet, not this package's. Importing only hil-ui-chat-window/styles produces an unstyled action bar with no visible error.

import '@bizfirst/hil-ui/styles';
import '@bizfirst/hil-ui-chat-window/styles';

3. Mount the Window

The simplest possible wiring, using the package's zero-config default settings:

import { HilChatWindow, defaultChatSettings } from '@bizfirst/hil-ui-chat-window';

<HilProvider submitClient={yourSubmitClient}>
  <HilChatWindow settings={defaultChatSettings} />
</HilProvider>

HilProvider is the existing hil-react context provider your app already sets up for any HIL presentation. HilChatWindow automatically shows or hides itself based on whether there's an active HIL request — you don't need to conditionally render it yourself for that part.

4. Choose Chat vs. the Classic Overlay

HilChatWindow and hil-ui's HilOverlay both watch the same active HIL request. If your app wants to use the chat window only for chat-style requests and keep the classic form overlay for everything else, branch on the request's type at your composition root:

{active?.HilType === 'chat'
  ? <HilChatWindow settings={defaultChatSettings} />
  : <HilOverlay />}

Never mount both for the same request Rendering HilChatWindow and HilOverlay at the same time for the same active session produces two competing windows reacting to the same request. Always pick one per session, not both.

Alternatively, an app going all-in on the chat experience can mount only HilChatWindow and never render HilOverlay at all.

5. Inline Forms Need a Form Renderer

If any request your app handles includes an inline form turn, the chat window needs a way to actually render that form. It looks for one in this order:

Your app's existing form renderer

If your app already registers a form renderer via hil-ui's HilFormRendererProvider (for example, for the classic Form-HIL overlay), the chat window reuses it automatically — no extra work.

A fetch-by-ID fallback

If there's no registered renderer but settings.api.formFetchURL is supplied, the chat window fetches the form's schema itself and renders an editable data view. See Settings Reference.

A placeholder

If neither is available, the form bubble shows a placeholder message instead of failing silently.

6. Make the Close Button Work

The shipped default settings show a close icon in the header, but HilChatWindow has no built-in opinion about what "close" should do for your app (dismiss the panel? cancel the request?). Pass an onClose handler to make it clickable — without one, the icon renders visible but disabled:

<HilChatWindow settings={defaultChatSettings} onClose={() => setShowChat(false)} />

Full Minimal Example

import '@bizfirst/hil-ui/styles';
import '@bizfirst/hil-ui-chat-window/styles';
import { HilChatWindow, defaultChatSettings } from '@bizfirst/hil-ui-chat-window';
import { HilOverlay } from '@bizfirst/hil-ui';
import { useHilStore } from '@bizfirst/hil-react';

function HilMountPoint() {
  const activeType = useHilStore(s => s.active?.HilType);
  return activeType === 'chat'
    ? <HilChatWindow settings={defaultChatSettings} onClose={() => {}} />
    : <HilOverlay />;
}

← Using the Chat Window Next: Settings Reference →