advanced-chat-kai

A highly customizable chat Web Component that integrates easily with shadcn - works with any framework (React, Vue, Angular, Svelte, etc.)

"Kai" (改) means "improved" in Japanese - inspired by vue-advanced-chat, this project started with the goal of building an improved alternative.

Features

• Framework-agnostic - Can be used with any frontend framework
• Backend-agnostic - No assumptions about your backend
• Lightweight - Built with Lit for minimal bundle size and high performance
• Logic-free - Component handles only UI
• Theming - Light and dark themes with CSS variables, which is designed to be easily used with shadcn based UI

Comparison

Demo

👉 Storybook

👉 Live Chat Example

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.
• timestamp can be a string (displayed as-is) or a Date object (formatted using timestampFormatter or default Intl format).
• 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", // or new Date()
    reactions: {
      "👍": ["2", "3"],
      "🎉": ["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: {
    "👍": ["2", "3"],
    "🎉": ["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

CSS variable names are based on the shadcn design system and Tailwind CSS spacing/typography scale, prefixed with --chat-. You can override these variables to customize the appearance of the chat component.

Color Variables

Font Size Variables

Border Radius Variables

Spacing Variables

Shadow Variables

Custom Variables

Usage

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-primary: oklch(0.65 0.24 15);
  --chat-primary-foreground: oklch(1 0 0);
  --chat-message-mine: oklch(0.65 0.24 15);
  --chat-message-mine-foreground: oklch(1 0 0);
}

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