advanced-chat-kai

A highly customizable Web Component for building chat interfaces

"Kai" (改) means "improved" in Japanese - this is a modern, lightweight, and framework-agnostic chat component built for flexibility and ease of integration.

Features

• Framework-agnostic - Can be used with any frontend framework or none at all
• Backend-agnostic - No assumptions about your backend; integrate freely
• Lightweight - Built with Lit for minimal bundle size and high performance
• Logic-free - You own the data, state and behavior; components only handle UI
• Theming support - Built-in light and dark themes
• Customizable style - Easily style components with CSS variables

Table of contents

• Installation
• Usage
• Props
• Events
• Styling
• Contributing
• License

Installation

npm install advanced-chat-kai

Usage

<advanced-chat-kai></advanced-chat-kai>

Props

Interfaces

ChatRoom

Notes:

• The footer will be hidden if hasEnded is true and selectedRoomId matches the room’s id.

Example:

rooms = [
  {
    id: "1",
    headerTitle: "title",
    headerSubtitle: "subtitle",
    sidebarTitle: "title",
    siderbarSubtitle: "subtitle",
    avatar: "/avatar.png",
    meta: "May 1",
    badge: {
      type: "success",
      label: "Success",
    },
    hasEnded: false,
  },
];

ChatItemType

Notes:

• type must be either divider or message.
• reactions represents the emoji reactions and the list of user IDs who reacted with each emoji.
• isSelected can be used to indicate that an action (such as editing) is currently active on the message.

Example:

messages = [
  {
    id: "0",
    type: "divider",
    roomId: "1",
    content: "May 1",
  },
  {
    id: "1",
    type: "message",
    roomId: "1",
    senderId: "1",
    senderName: "User 1",
    senderAvatar: "/avatar.png",
    content: "Hello, world",
    timestamp: "12:34 PM",
    reactions: new Map<string, Set<string>>([
      ["👍", new Set(["2", "3"])],
      ["🎉", new Set(["1", "4", "5"])],
    ]),
    attachments: [
      {
        name: "file1.txt",
        meta: "20 KB",
        id: "0",
      }
    ],
    isDeleted: false,
    isSelected: false,
    replyTo: null,
  }
]

ChatMessageAttachment

Example:

attachments = [
  {
    name: "file1.txt",
    meta: "20 KB",
    id: "0",
  },
  {
    name: "image.png",
    meta: "2 MB",
    id: "1",
    imageUrl: "/image.png",
  },
];

ChatMessageSuggestion

Example:

suggestions = [
  {
    text: "Hello",
    value: "hello",
  },
];

ChatMessageReply

Example:

chatMessageReply = {
  id: "1",
  type: "message",
  roomId: "1",
  senderId: "1",
  senderName: "User 1",
  senderAvatar: "/avatar.png",
  content: "Hello, world",
  timestamp: "12:34 PM",
  reactions: new Map<string, Set<string>>([
    ["👍", new Set(["2", "3"])],
    ["🎉", new Set(["1", "4", "5"])],
  ]),
  attachments: [
    {
      name: "file1.txt",
      meta: "20 KB",
      id: "0",
    }
  ],
  isDeleted: false,
  isSelected: false,
}

ChatAction

Example:

myMessageActions = [
  {
    label: "Edit",
    value: "edit-message",
  },
  {
    label: "Delete",
    value: "delete-message",
  },
];

Dialog

Example:

dialog = {
  event: "confirm-deletion-message",
  body: "Are you sure you want to delete this message?",
  leftButton: {
    text: "Cancel",
  },
  rightButton: {
    text: "OK",
    variant: "danger",
  },
};

I18nType

The default value is shown below. You can override only the fields you want to customize.

const DEFAULT_I18N = {
  DELETED_MESSAGE: "This message has been deleted.",
  CHAT_FOOTER_TEXTAREA_PLACEHOLDER: "Write a message..",
  CHAT_SEARCH_PLACEHOLDER: "Search room",
  CLOSED_ROOM_MESSAGE: "This chat has been ended.",
  NEW_MESSAGE_NOTIFICATION: "New messages",
};

⚠️　Note on updating arrays and objects

Lit uses shallow comparison to detect changes to reactive properties. When working with arrays or objects, you must assign a new reference to trigger updates. Mutating the existing object or array in place (e.g. using push() or modifying a property directly) will not cause the component to update.

✅ Correct:

this.messages = [...this.messages, newMessage];

❌ Won’t work:

this.messages.push(newMessage);

Events

Styling

The --chat-surface-50 to --chat-surface-950 variables define the primary surface color scale, used across light and dark themes for backgrounds and component surfaces.

Also, a minimal set of CSS variables is exposed specifically for applying brand colors to the key UI elements:

You can override the component's style using CSS custom properties (variables). These are applied directly to advanced-chat-kai element:

advanced-chat-kai {
  --chat-success: green;
  --chat-danger: red;
  --chat-warning: yellow;
  --chat-info: blue;
}

All styles are encapsulated in Shadow DOM, so direct CSS selectors from outside will not apply - only CSS variables can be used for styling.

Contributing

• Bug fix PRs are always welcome.
• UI changes or new features should not be submitted without prior discussion. Please open an issue first to propose and discuss them.

Thanks for your understanding and contributions.

License

MIT