loki-banya

loki-banya is a React library designed to create customizable chatbot UIs. It provides a range of components and hooks that make it easy to build and manage chatbot applications.

Key Features:

• Customizable UI: Tailor styles and components to your preferences.
• Message Management: Manage and add messages using provided hooks.
• Dynamic Button Collections: Integrate dynamic button interactions into the chat interface.

1. Install

Installing loki-banya only takes a single command and you're ready to roll:

# with npm
npm install loki-banya

# with yarn
yarn add loki-banya

2. Usage

2.1. Getting Started

loki-banya can use the AI chatbot by simply importing the chatbot library and entering the given key.

import React from 'react'
import { BanyaAIChat, ChatBotContainer } from 'loki-banya'

const App = () => {
  const PRIVATE_KEY = 'givenKey'
  return (
    <ChatBotContainer>
      <BanyaAIChat privateKey={PRIVATE_KEY} />
    </ChatBotContainer>
  )
}

export default App

2.2. Custom Configuration Example

loki-banya offers several components and hooks for building chatbot interfaces. Below are examples of how to use the library. You can customize the style and behavior of the chatbot through the config object.

import React, { useRef, useEffect } from 'react'
import {
  useChat,
  Header,
  MessagesContainer,
  InputContainer,
  ChatBotContainer,
  ButtonCollections
} from 'loki-banya'

const App = () => {
  const PRIVATE_KEY = 'givenKey' // change it to given key
  // initialization
  const {
    messages,
    connected,
    addMessage,
    addComponent,
    handleSend,
    handleButton
  } = useChat(PRIVATE_KEY)
  const messagesContainerRef = useRef(null)

  const buttonsData = useMemo(
    () => [
      { label: '🔧 Service Usage Guide', content: 'Service Usage Guide' },
      { label: '🗣️ Consulting Request', content: 'Consulting Request' },
      { label: '💰 Pricing Information', content: 'Pricing Information' },
      { label: '💡 Success Stories', content: 'Success Stories' }
    ],
    []
  )

  // initializeMessages
  useEffect(() => {
    if (connected && messages.length === 0) {
      addMessage({
        text: 'Hello! How can I help you?',
        isUser: false,
        timestamp: new Date().getTime()
      })
      addComponent(() => (
        // customed components also could be sent
        <ButtonCollections data={buttonsData} onSend={handleButton} />
      ))
    }
  }, [
    connected,
    messages.length,
    addMessage,
    addComponent,
    buttonsData,
    handleButton
  ])

  return (
    <ChatBotContainer>
      <Header />
      <MessagesContainer
        ref={messagesContainerRef}
        messages={messages}
        config={{ container: { backgroundColor: '#fff' } }}
      />
      <InputContainer
        config={{ input: { placeholderConnected: 'Message' } }}
        onSend={handleSend}
        connected={connected}
      />
    </ChatBotContainer>
  )
}

export default App

3. Key Components

3.1. MessagesContainer

This is the container for displaying chat messages. The chat history is rendered here.

• Props

  • ref*: (required) add ref to the MessageContainer to function correctly

  • messages*: (required) The list of messages to display.

  • [config]: Customize component style and scroll buttons.

    • Namespace: config.container

    • | Name | Default | Description | | ----------------- | --------- | --------------------------------- | | backgroundColor | #262628 | The background color of container | | padding | 1rem | The padding of the container |

      Namespace: config.bubble

      • User's Chat Bubble

        Namespace: config.bubble.user

        | Name | Default | Description | | ----------------- | ----------------- | ------------------------------------- | | padding | 0.5rem 0 | Padding inside the user bubble | | margin | 0 10px 0 0.5rem | Margin around the user bubble | | backgroundColor | #e0f3f6 | Background color of user bubble | | color | #282826 | Font color of user bubble | | maxWidth | 70% | Maximum width of the user bubble | | borderRadius | 3px | The border-radius for rounded corners |

      • AI's Chat Bubble

        Namespace: config.bubble.ai

        | Name | Default | Description | | --------------------- | ---------- | ------------------------------------------------------------- | | gridTemplateColumns | 1fr 9fr | The grid column ratio of the AI profile image and chat bubble | | padding | 0.5rem 0 | Padding inside the AI bubble | | margin | 0 0.5rem | Margin around the AI bubble | | backgroundColor | #f1f1f1 | Background color of AI bubble | | color | #282826 | Color of AI bubble | | maxWidth | 72% | Maximum width of the AI bubble | | borderRadius | 3px | The border-radius for rounded corners |

        • AI's Profile

          Namespace: config.bubble.ai.profile

          | Name | Default | Description | | ----------------- | ------------------- | ------------------------------------ | | backgroundColor | #262628 | Background color of the AI profile | | border | 2px solid #ffffff | Border around the AI profile | | borderRadius | 50% | The border-radius for the AI profile | | height | 2rem | Height of the AI profile wrapper | | width | 2rem | Width of the AI profile wrapper | | padding | 3px | Padding inside the AI profile | | imgHeight | 1.5rem | Height of the AI profile image | | imgWidth | 1.5rem | Width of the AI profile image |

    • Scroll Down Button

      Namespace: config.button

      | Name | Default | Description | | ----------------- | ------------------- | ---------------------------------------------- | | backgroundColor | #fff | The background color of the scroll down button | | color | #4c34b4 | The text/icon color inside the button | | height | 2rem | The height of the button | | width | 2rem | The width of the button | | top | '' | The top position of the button | | left | '' | The left position of the button | | right | 1rem | The right position of the button | | bottom | 4rem | The bottom position of the button | | borderRadius | 47% | The border-radius for rounded corners | | border | 1px solid #f2f2f2 | The border style for the button | | zIndex | 1000 | Z-index for layering the button | | padding | 0.5rem | Padding inside the button | | iconWidth | 15 | The height of the icon inside the button | | iconHeight | 15 | The width of the icon inside the button | | iconColor | #0c0c0c | Custom image source for the scroll own icon |

3.2. InputContainer

This component contains the input field and send button for users to type and send messages.

• Props

  • onSend*: (required) Function to handle sending messages.

  • connected*: (required) State of connection.

  • [config]: Customize the container, input field and button styles.

    • Namespace: config.container

      | Name | Default | Description | | ----------------- | --------- | ------------------------------------------- | | backgroundColor | #262628 | The background color of the input container | | padding | 0.5rem | The padding inside the container |

    • Namespace: config.input

      | Name | Default | Description | | ---------------------- | ---------------- | ------------------------------------------------------- | | backgroundColor | #262628 | The background color of the input field | | color | #fff | The text color inside the input field | | padding | 0.4rem 0.8rem | Padding inside the input field (top, bottom, sides) | | borderRadius | 30px | The border-radius for the input field (rounded corners) | | border | 1px solid #fff | The border style for the input field | | fontSize | 1rem | Font size for the text in the input field | | focusOutline | none | Outline style when the input field is focused | | focusBoxShadow | 0 0 5px #fff | Box-shadow when the input field is focused | | placeholderConnected | "Message" | (String) The message in placeholder when connected | | placeholderWaiting | "Connecting" | (String) The message in placeholder while connected | | attachmentIconWidth | 24 | The attachment icon width | | attachmentIconHeight | 24 | The attachment icon height | | attachmentIconColor | #fff | The attachment icon color | | deleteIconWidth | 20 | The delete icon width of the attached image | | deleteIconHeight | 20 | The delete icon height of the attached image | | deleteIconColor | #fff | The delete icon color of the attached image | | sendIconWidth | 20 | The send icon width | | sendIconHeight | 20 | The send icon height | | sendIconColor | #fff | The send icon color |

3.3. ButtonCollections

This component renders a collection of buttons that users can interact with for dynamic conversation flow.

• Props

  • data*: (required) Custom data to show user button collections.

    example

    ;[
      { label: '🔧 Service Usage Guide', content: 'Service Usage Guide' },
      { label: '🗣️ Consulting Request', content: 'Consulting Request' },
      { label: '💰 Pricing Information', content: 'Pricing Information' },
      { label: '💡 Success Stories', content: 'Success Stories' }
    ]

  • onSend*: (required) Function to handle button interaction.

  • [config]: Customize button container and buttons.

    | Name | Default | Description | | ---------------------- | ---------------- | --------------------------------------------------------------------------------- | | justifyContent | flex-end | The alignment of the button collection along the main axis (horizontal alignment) | | gap | 0.5rem | The spacing between the buttons | | padding | 0 0.5rem 0 0 | Padding around the button container | | paddingButton | 0.5rem 1rem | Padding inside each button | | marginButton | 0 0 0 10px | Margin around each button | | borderRadius | 20px | The border radius of the buttons (rounded corners) | | border | 1px solid #ddd | The border style of the buttons | | backgroundColor | #fff | The background color of the buttons | | color | #333 | The text color of the buttons | | fontSize | 1rem | The font size of the button text | | backgroundColorHover | #e0f3f6 | The background color when hovering over a button |

4. Hooks

4.1. useChat

useChat(privateKey)

The useChat hook manages the chat's state, handles API interactions, and processes user input. It allows for real-time communication with the chat server and keeps track of messages, connectivity status, and component-based interactions.

4.1.1. Parameters:

• privateKey: (string) — The private key required to authenticate and send messages to the chat API.

4.1.2. State:

• messages: (array) — An array containing all the messages and components displayed in the chat.
  • Each message object contains:
    • type: 'message' or 'component'
    • content: The text of the message or the component to be displayed.
    • isUser: (boolean) — Whether the message is from the user or the AI.
    • isMarkdown: (boolean) — Whether the message content is formatted in markdown.
    • timestamp: (number) — The time the message was sent.
• connected: (boolean) — A flag that indicates whether the API connection is successfully established.

4.1.3. Functions:

• addMessage(message):
  • Adds a new text message to the chat.
  • The message parameter is an object with the following properties:
    • text: (string) — The message text.
    • isUser: (boolean) — Whether the message is from the user.
    • timestamp: (number) — The time the message was created.
• addComponent(Component):
  • Adds a new React component to the chat instead of a text message.
  • The Component is rendered within the chat as part of the conversation.
• handleSend(text):
  • Sends a user message and processes the bot's response.
  • Steps:
    1. Checks if the text is valid and if the chat is connected.
    2. Adds the user's message to the chat.
    3. Detects the language of the message using the detectLanguage utility.
    4. Sends the message to the chat API.
    5. Adds the bot's response to the chat.
• handleButton(text):
  • Handles button-based interactions by sending text to the bot when triggered by a button click.
  • Similar to handleSend, but does not add the user’s message (since it’s triggered by a button).

4.1.4. Return Values:

The useChat hook returns an object containing:

• messages: The array of messages and components.
• connected: The current connection status.
• addMessage: Function to add a user or AI message.
• addComponent: Function to add a React component to the chat.
• handleSend: Function to handle sending a user message and processing the response.
• handleButton: Function to handle button-triggered interactions with the bot.

4.1.5. Usage:

The useChat hook can be used in a chat component to handle message input, API responses, and display both text and components dynamically. It ensures the chat stays responsive and properly interacts with the backend API.

5. Styling Options

Each loki-banya component accepts a config object for customization, allowing you to easily adjust colors, sizes, positions, and more.

5.1. ChatBotContainer

This component is the container for the entire chatbot interface and can be customized via config.

• Props

  • [config]: Defines the styles for the container.

    | Name | Default | Description | | -------------- | ---------- | ------------------------------------------------------------------------------------------------------- | | height | 800px | The height of the container | | width | 400px | The width of the container | | zIndex | 0 | The stack order of the container | | position | relative | The CSS positioning of the container. Can be set to absolute, fixed, sticky, etc. | | top | '' | The distance from the top of the viewport when position is set to absolute or fixed | | left | '' | The distance from the left of the viewport when position is set to absolute or fixed | | right | '' | The distance from the right of the viewport when position is set to absolute or fixed | | bottom | '' | The distance from the bottom of the viewport when position is set to absolute or fixed | | borderRadius | '' | The border radius for rounded corners | | border | '' | The border of the container, defined by size, style, and color, e.g., 1px solid #000 | | overflow | visible | Controls how overflow content is handled. Set to hidden, scroll, or auto to manage excess content | | boxShadow | '' | Adds a shadow effect around the container. e.g., 0px 4px 10px rgba(0, 0, 0, 0.2) for shadow |

5.2. Header

This component represents the header section of the chatbot, typically for branding or showing a logo.

• Props

  • [config]: Defines the styles for the container and aAllows customization of logo.

    | Name | Default | Description | | ----------------- | ----------- | -------------------------------------------------- | | backgroundColor | #262628 | The background color of the header | | color | #fff | The text color of the header | | height | 2.5rem | The height of the header | | width | 100% | The width of the header | | padding | 0.5rem 0 | The padding inside the header | | margin | '' | The margin around the header | | textAlign | center | The text alignment within the header | | zIndex | 1000 | The stack order of the header | | position | sticky | The positioning method of the header | | top | '' | The top offset when using absolute or fixed | | left | '' | The left offset when using absolute or fixed | | right | '' | The right offset when using absolute or fixed | | bottom | '' | The bottom offset when using absolute or fixed | | borderRadius | '' | The border radius for the header | | border | '' | The border style for the header | | imgHeight | 2.5rem | The height of the logo image | | imgWidth | '' | The width of the logo image | | logoSrc | undefined | The source URL for the logo image |

6. Event Handling

loki-banya offers built-in event handling functions for sending messages and interacting with buttons, managed through the useChat hook.

6.1. Sending Messages

Use the handleSend function to send a message.

<InputContainer onSend={handleSend} />

6.2. Button Interactions

Handle button interactions using the handleButton function.

<ButtonCollections onSend={handleButton} />

7. License