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

Comparison

| | Bundle size (minified) | Bundle size (minified + gzipped) | Download time (slow 3G) | Download time (4G) | | ------------------- | ---------------------- | -------------------------------- | ----------------------- | ------------------ | | advanced-chat-kai | 112.9kB | 23.2kB | 465ms | 27ms | | vue-advanced-chat | 493.4kB | 149.8kB | 3s | 171ms | | | 📦 77% smaller | 📦 84% smaller | ⚡️ 85% faster | ⚡️ 84% faster |

Table of contents

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

Installation

npm install advanced-chat-kai

Usage

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

Props

| Name | Type | Required | Default | Description | | ------------------------------ | ------------------------------------------------- | -------- | ---------------------- | --------------------------------------------------------------------------------- | | currentUserId | string | null | false | null | The current user id using the chat | | rooms | ChatRoom[] | false | [] | The list of chat rooms showing in the sidebar | | messages | ChatItemType[] | false | [] | The list of messages in the room currently selected | | attachments | ChatMessageAttachment[] | false | [] | The list of attachments in the message | | suggestions | ChatMessageSuggestion[] | false | [] | The list of message suggestions | | replyTo | ChatMessageReply | null | false | null | The message being replied to, if any | | selectedRoomId | string | null | false | null | The id of the room currently selected | | isLoadingRoom | boolean | false | false | Whether the list of the initial rooms are loading or not | | isLoadingMessage | boolean | false | false | Whether the list of the initial messages are loading or not | | isLoadingMoreRooms | boolean | false | false | Whether more rooms are loading or not | | isLoadingMoreMessages | boolean | false | false | Whether more messages are loading or not | | inputMessage | string | false | "" | The current message input used for two-way binding | | roomActions | ChatAction[] | false | [] | The list of actions available for the rooms | | myMessageActions | ChatAction[] | false | [] | The list of actions available for the user's messages | | theirMessageActions | ChatAction[] | false | [] | The list of actions available for other user's messages | | isMobile | boolean | false | false | Whether the chat component should be rendered in mobile mode or not | | isSingleRoom | boolean | false | false | Whether the sidebar and toggle button should be rendered or not | | isEmojiPickerAvailable | boolean | false | true | Whether the emoji picker on the footer should be rendered or not | | isEmojiReactionAvailable | boolean | false | true | Whether the emoji reaction button on the message should be rendered or not | | isReplyAvailable | boolean | false | true | Whether the reply button on the message should be rendered or not | | isMessageAttachmentAvailable | boolean | false | true | Whether the message attachment button on the footer should be rendered or not | | isMarkdownAvailable | boolean | false | false | Whether the markdown message format should be rendered or not | | isTyping | boolean | false | false | Whether the typing indicator should be rendered or not | | showRoomAvatar | boolean | false | true | Whether the room avatar on the list of rooms should be rendered or not | | showTheirAvatar | boolean | false | true | Whether the other user's avatar on the message should be rendered or not | | alignMyMessagesLeft | boolean | false | false | Whether my messages should be aligned to the left or not | | enterToSend | boolean | false | false | Whether the enter key should send the message or not | | dialog | Dialog | null | false | null | The dialog to be rendered | | height | string | false | "60em" | The height of the chat component | | width | string | false | "80em" | The width of the chat component | | i18n | PartialI18nType | false | See below | The i18n object to be used for translations | | theme | ThemeType | false | "light" | The theme to be used for the chat component. It must be either light or dark. |

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

| Name | Detail / Payload | Fires when a user | | ----------------------- | ------------------------------------- | -------------------------------------------------- | | add-room | - | Clicked the add button on the sidebar | | search-room | { value } | Changed the input on the searchbox | | select-room-action | { label, value, roomId } | Selected an action on the room | | load-more-rooms | - | Reached the bottom of the room list | | select-room | { room } | Selected a room in the list | | load-more-messages | - | Reached the top of the message list | | select-message-action | { label, value, messageId } | Selected an action on the message | | select-suggestion | { suggestion } | Selected a suggestion in the list | | select-emoji | { messageId, currentUserId, emoji } | Selected an emoji reaction in picker for a message | | reply-to-message | { replyTo } | Clicked the reply button on a message | | click-reaction | { messageId, reaction } | Clicked an existing emoji reaction on a message | | download-attachment | { attachment } | Clicked the download button on an attachment | | remove-attachment | { attachment } | Clicked the close button on an attachment | | cancel-reply | - | Clicked the close button on the reply message | | select-file | { file } | Selected a file | | send-message | { roomId, senderId, content } | Clicked the send button on the footer | | click-dialog-button | { event, side } | Clicked a button on a dialog |

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.

| Variable | Description | | -------------------------------------- | --------------------------------------------------- | | --chat-base-font-size | The base font size of the chat component | | --chat-white | | | --chat-black | | | --chat-success | | | --chat-danger | | | --chat-warning | | | --chat-info | | | --chat-surface-50 | | | --chat-surface-100 | | | --chat-surface-200 | | | --chat-surface-300 | | | --chat-surface-400 | | | --chat-surface-500 | | | --chat-surface-600 | | | --chat-surface-700 | | | --chat-surface-800 | | | --chat-surface-900 | | | --chat-surface-950 | | | --chat-text | The default text color | | --chat-subtext | The default subtext color | | --chat-border | The default border color | | --chat-floating-item-border | The default border color for floating items | | --chat-floating-item-box-shadow | The default box shadow for floating items | | --chat-placeholder | The default placeholder color | | --chat-deleted | The default background color for deleted messages | | --chat-overlay | The default background color for overlay | | --chat-notification-badge-background | The default background color for notification badge | | --chat-notification-badge-text | The default text color for notification badge |

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

| Variable | Description | | -------------------------------------- | ------------------------------------------------------------------- | | --chat-send-button-bg | The background color of the send button | | --chat-send-button-bg-hover | The background color of the send button on hover | | --chat-my-message-bg | The background color of my messages | | --chat-my-message-bg-selected | The background color of my messages when selected | | --chat-my-reaction-list-bg | The background color of the reaction list on my messages | | --chat-my-reaction-button-bg | The background color of the reaction button on my messages | | --chat-my-reaction-button-bg-hover | The background color of the reaction button on my messages on hover | | --chat-suggestion-list-item-bg | The background color of the suggestion list item | | --chat-suggestion-list-item-bg-hover | The background color of the suggestion list item on hover | | --chat-my-message-menu-bg | The background color of the message menu on my messages | | --chat-my-message-button-bg-hover | The background color of the message button on my messages on hover | | --chat-my-attachment-bg | The background color of the attachment on my messages | | --chat-my-attachment-bg-hover | The background color of the attachment on my messages on hover | | --chat-text-on-brand | The text color on brand colors | | --chat-subtext-on-brand | The subtext color on brand colors |

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