@botonic/webchat-react

React components and styles for Botonic webchat UIs, using CSS modules and class-variance-authority (CVA). Part of the current @botonic/* line.

Source and versions

| Line | npm | Source | | ----------- | ----- | ---------------------------------------------------------------- | | Legacy | 0.x | github.com/hubtype/botonic | | Current | 2.x | Hubtype internal monorepo (not public; packages publish to npm) |

Use the same major version as @botonic/core and related packages.

Installation

pnpm add @botonic/webchat-react
# or
npm install @botonic/webchat-react

Dependencies

This package requires:

• class-variance-authority for conditional styling
• react-aria for accessibility patterns

Usage

Basic Setup

Load foundations (reset + tokens), then Lilara component CSS, then webchat overrides (shared CSS layers control cascade):

@import '@lilara/foundations/base.css';
@import '@lilara/ui-web-react/styles.css';
@import '@botonic/webchat-react/styles.css';

import '@lilara/foundations/base.css'
import '@lilara/ui-web-react/styles.css'
import '@botonic/webchat-react/styles.css'

Import @lilara/ui-web-react components from that package, not from @botonic/webchat-react.

Components

import { WebchatProvider, WebchatContainer, WebchatHeader, WebchatMessages, WebchatInput, WebchatTrigger } from '@botonic/webchat-react'

function App() {
  return (
    <WebchatProvider>
      {/* Trigger button - positioned fixed */}
      <WebchatTrigger position='bottom-right' />

      {/* Container - automatically positioned relative to trigger */}
      <WebchatContainer layout='default' size='normal' position='bottom-right'>
        <WebchatHeader title='Customer Support' subtitle="We're here to help" showClose={true} />

        <WebchatMessages variant='default' />

        <WebchatInput placeholder='Type your message...' variant='default' />
      </WebchatContainer>
    </WebchatProvider>
  )
}

Grid Layout System

The webchat container uses CSS Grid with template areas for a clean, flexible layout. Each child component is automatically assigned to a grid area.

Default Layout

// Default layout: header / messages / input (stacked vertically)
<WebchatContainer layout='default'>
  <WebchatHeader title='Support' />
  <WebchatMessages />
  <WebchatInput />
</WebchatContainer>

Grid Template Areas

The default layout uses the following CSS Grid template:

• Grid areas: 'header' / 'messages' / 'input'
• Grid rows: auto 1fr auto (header auto-sized, messages flexible, input auto-sized)
• Grid columns: 1fr (single column, full width)

Custom Layouts

Delivery teams can create custom layouts by extending the CSS module:

/* custom-layout.module.css */
.custom-layout {
  grid-template-areas:
    'input header'
    'messages messages';
  grid-template-rows: auto 1fr;
  grid-template-columns: 1fr auto;
}

// Apply custom layout
<WebchatContainer className={customStyles.customLayout}>
  <WebchatHeader title='Support' />
  <WebchatMessages />
  <WebchatInput />
</WebchatContainer>

Positioning System

The webchat uses a coordinate positioning system:

• WebchatTrigger: Always positioned fixed on the viewport
• WebchatContainer: Automatically positioned near the trigger
• Supported positions: bottom-right | bottom-left | top-right | top-left

// Trigger in bottom-right, container appears above it
<WebchatTrigger position="bottom-right" />
<WebchatContainer position="bottom-right" />

// Trigger in top-left, container appears below it
<WebchatTrigger position="top-left" />
<WebchatContainer position="top-left" />

Open/Close State

The webchat is controlled by shared state through WebchatProvider:

• Trigger click: Toggles isOpen state
• Container visibility: Controlled by isOpen state
• Animation: Smooth slide-in/out animations

// State is managed automatically
const state = useWebchatContext()
// state.isOpen - boolean
// state.open() - opens webchat
// state.close() - closes webchat
// state.toggle() - toggles webchat

Styling Patterns

This library follows the same patterns as @lilara/ui-web-react:

1. Component Tokens: Each component uses specific CSS custom properties that reference base tokens
2. CSS Modules: All styling is scoped using CSS modules
3. CVA (Class Variance Authority): Conditional styling based on component props
4. Design Tokens: Uses design tokens

Component Variants

WebchatContainer

• layout: default | compact | fullscreen
• size: small | normal | large
• position: bottom-right | bottom-left | top-right | top-left
• Animation states: isOpening | isClosing

WebchatTrigger

• position: bottom-right | bottom-left | top-right | top-left
• Animation states: isPulsing | isOpening | isClosing

WebchatHeader

• variant: default | minimal

WebchatMessages

• variant: default | compact | bubble

WebchatInput

• variant: default | compact | outlined
• State: isLoading

Responsive Behavior

• Desktop: Container positioned relative to trigger
• Mobile: Container becomes fullscreen automatically
• Positioning: Responsive adjustments for smaller screens

Customization

You can override the webchat-specific tokens by defining them after importing the styles:

@import '@botonic/webchat-react/styles.css';

:root {
  /* Override webchat tokens */
  --webchat-container-bg: #f8f9fa;
  --webchat-header-bg: #007bff;
  --webchat-message-user-bg: #007bff;
  --webchat-trigger-position-offset: 32px;
  --webchat-trigger-size: 64px;
}

React Aria Integration

Components use React Aria hooks for accessibility and follow the compound component pattern:

// Access underlying hook if needed
import { useWebchatContainer, useWebchatTrigger } from '@botonic/webchat-react'

function CustomWebchat() {
  const state = useWebchatState({
    /* options */
  })
  const { containerProps } = useWebchatContainer(props, state, ref)

  return <div {...containerProps}>/* custom implementation */</div>
}

Architecture

• Foundation hooks: Core state management (e.g., useWebchatState)
• Component hooks: React Aria pattern hooks (e.g., useWebchatContainer)
• React components: Styled components using CSS modules + CVA
• Design tokens: Component-specific tokens that reference base design system
• State management: Shared state through React Context for open/close coordination