@karibukit/ranger-widget

An embeddable AI concierge chat widget for hospitality websites. Ranger helps guests check availability, explore rooms, plan activities, and get answers — powered by your property's knowledge base and live booking data.

Built for KaribuKit, the property management system for safari lodges and boutique hotels.

Features

• Two modes: Embedded concierge section or floating chat bubble
• AI-powered: Answers guest questions using your property's knowledge base, real-time availability, and pricing
• Animated character: SVG ranger character with cursor tracking, blinking, and state-based expressions
• Suggestion chips: Contextual follow-up actions after each response
• Markdown rendering: Bold, lists, and formatted responses
• Expand on interact: Compact invitation state that expands into a full chat on first message
• Per-property theming: Primary color, welcome message, and suggestions configurable per property
• Mobile responsive: Optimized layouts for desktop and mobile
• Lightweight: No heavy dependencies — pure React + CSS

Installation

npm install @karibukit/ranger-widget

Quick Start

import { RangerChat } from '@karibukit/ranger-widget'
import '@karibukit/ranger-widget/styles.css'

// Embedded mode — concierge section on your page
<RangerChat
  apiUrl="https://your-karibukit-api.com"
  propertySlug="your-property"
  embedToken="your-embed-token"
  mode="embedded"
/>

// Floating mode — chat bubble in the corner
<RangerChat
  apiUrl="https://your-karibukit-api.com"
  propertySlug="your-property"
  embedToken="your-embed-token"
  mode="floating"
/>

Advanced: External Character

For custom layouts, you can render the Ranger character separately and connect it to the chat state:

import { RangerChat, RangerCharacter } from '@karibukit/ranger-widget'
import type { CharacterState } from '@karibukit/ranger-widget'

const [charState, setCharState] = useState<CharacterState>('idle')

<RangerCharacter state={charState} size={120} />
<RangerChat
  mode="embedded"
  showAvatar={false}
  onChatStateChange={setCharState}
  // ...other props
/>

Props

RangerChat

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiUrl | string | required | KaribuKit API base URL | | propertySlug | string | required | Property identifier | | embedToken | string | required | Widget authentication token | | mode | 'embedded' \| 'floating' | required | Widget display mode | | showAvatar | boolean | true | Show character avatar inside the chat panel | | onChatStateChange | (state) => void | — | Callback for chat state changes (idle, listening, thinking, responding) | | className | string | — | Additional CSS class | | riveUrl | string | — | Custom Rive animation URL (future) |

RangerCharacter

| Prop | Type | Default | Description | |------|------|---------|-------------| | state | CharacterState | required | Animation state: idle, listening, thinking, responding | | size | number | 96 | Character size in pixels | | className | string | — | Additional CSS class |

Theming

The widget uses CSS custom properties for theming. Set --ranger-primary on the widget container to match your brand:

.ranger-widget {
  --ranger-primary: #F4694C;
}

Properties can also configure their primary color through KaribuKit settings, which is applied automatically.

Requirements

• React 18+
• A KaribuKit API instance with the Ranger web chat module enabled
• Property configured with an embed token and allowed origins

About KaribuKit

KaribuKit is a property management system built for safari lodges and boutique hotels. It handles reservations, guest management, channel distribution (OTAs), invoicing, and AI-powered guest communication — all designed for the unique needs of African hospitality.

Ranger is KaribuKit's AI assistant, available as a staff copilot and as this embeddable guest-facing widget.

License

MIT