Introduction

A chat-style message history web component. Render conversations from plain text, with avatars, bubbles, and smooth animations.

Installation

Install the component from your command line.

npm install @bbki.ng/bb-msg-history

Basic Usage

Use plain text with author: message format. Each author gets a letter avatar by default.

[23:27:10] bbki.ng: 谁呀 [23:27:15] xwy: 谁谁谁，你猴爷爷！

<bb-msg-history>
  bbki.ng: 谁呀
  xwy: 谁谁谁，你猴爷爷！
</bb-msg-history>

Timestamps

Add optional timestamps using the [timestamp] author: text format. Timestamps appear on hover near the message bubble.

[09:00] alice: Good morning! [09:02] bob: Hey, how are you? [09:05] alice: Pretty good, thanks alice: (no timestamp here - backward compatible) [09:08] bob: Same here

<bb-msg-history>
[09:00] alice: Good morning!
[09:02] bob: Hey, how are you?
[09:05] alice: Pretty good, thanks
alice: (no timestamp here - backward compatible)
[09:08] bob: Same here
</bb-msg-history>

Custom Avatars

Use setAuthor() to customize avatars (emoji, SVG, or image), side position, and bubble colors.

me: Hey there! me: How's it going? friend: Pretty good, thanks! friend: What are you up to? me: Just trying out this component friend: Looks great!

el.setAuthor('me', { avatar: '<svg>...</svg>', side: 'right', bubbleColor: '#f3f4f6' });
el.setAuthor('friend', { avatar: '<svg>...</svg>', side: 'left', bubbleColor: '#e0f2fe' });

Append Messages

Use appendMessage() to add messages programmatically with smooth scrolling.

alice: Try the appendMessage() API! bob: Click the buttons below to add messages

el.appendMessage({ author: 'alice', text: 'Hello!' });
el.appendMessage({ author: 'bob', text: 'How are you?' });

Message Grouping

Consecutive messages from the same author are grouped together. The avatar is only shown on the first message.

alice: First message alice: Second message, avatar hidden alice: Third, still hidden bob: Got it! bob: I'll send two as well

Scrollable View

Long conversations automatically scroll. Use --bb-max-height CSS variable to customize the container height.

alice: Hey, are you free this weekend? bob: Yeah, what's up? alice: Want to grab coffee? bob: Sounds good! When? alice: Saturday morning, around 10? bob: Perfect. Which place? alice: The usual spot on Main St. bob: Great, see you then! alice: Can't wait! bob: Me neither. It's been a while. alice: Way too long! bob: Agreed. See you Saturday. alice: I'll bring that book you wanted. bob: Oh right! Thanks for remembering. alice: No problem. See you! bob: See ya!

<bb-msg-history style="--bb-max-height: 200px;">...</bb-msg-history>

Multi-party Chat

Support for more than two participants in a conversation.

me: Hey everyone, let's have a meeting alice: Sure thing bob: On my way dave: I'm here too me: Let's get started alice: OK bob: No problem dave: Got it me: That's all for today

Loading State

Use the loading attribute or setLoading() method to show a loading animation while fetching messages. The loading overlay appears centered over the message area.

<!-- HTML attribute -->
<bb-msg-history loading></bb-msg-history>

<!-- JavaScript API -->
const el = document.querySelector('bb-msg-history');

// Show loading while fetching
el.setLoading(true);
fetchMessages().then(messages => {
  el.setLoading(false);
  messages.forEach(msg => el.appendMessage(msg));
});

Infinite Mode

Use the infinite attribute to remove height constraints. The container expands to fit all messages without scrolling. Useful when the parent handles scrolling or when displaying a full conversation.

alice: Hey there! This is an infinite mode demo. bob: Cool! So there's no height limit? alice: Exactly - the container just grows to fit all messages. bob: That's perfect for full-page chats or when the parent handles scrolling. alice: Yep! And notice there's no scroll-to-bottom button either. bob: Nice and clean. Perfect for displaying an entire conversation. alice: You got it. Works great with long message histories too. bob: Let's add a few more messages to demonstrate. alice: Sure thing! Here's another message. bob: And another one from me. alice: The container will keep expanding... bob: ...as more messages are added. alice: No max-height constraints at all. bob: Just pure, unlimited message display.

<!-- No height limit, container expands to fit all messages -->
<bb-msg-history infinite>
  alice: Hey there!
  bob: No height limit here
  alice: The container just expands
</bb-msg-history>

Custom Scroll Button

Use the hide-scroll-button attribute to hide the default scroll-to-bottom button. Listen for bb-scrollbuttonshow and bb-scrollbuttonhide events to implement your own button or trigger other actions.

alice: This demo hides the default button bob: But we can listen to events alice: And build our own custom button bob: Or trigger other actions alice: Scroll up to see it in action bob: The event will fire when button would show alice: Try it now! bob: Pretty cool, right?

<!-- Hide default button with attribute -->
<bb-msg-history hide-scroll-button>
  alice: Hello
  bob: Hi there
</bb-msg-history>

<!-- Listen to events for custom behavior -->
<script>
  const el = document.querySelector('bb-msg-history');

  el.addEventListener('bb-scrollbuttonshow', (e) => {
    // Show custom button or trigger other actions
    console.log('Scroll button would show');
  });

  el.addEventListener('bb-scrollbuttonhide', (e) => {
    // Hide custom button
    console.log('Scroll button would hide');
  });

  // Scroll to bottom programmatically
  el.scrollToBottom();
</script>