Ana Ruiz
Pushed the new status tokens to the branch.
Message list
A message list shows a conversation, grouping each person's messages in a row under one heading with their name and picture. A group ends when the author changes, the day changes, or enough time passes. Every reason a group breaks is a named rule you can test, and the whole list takes one Tab stop: arrow keys move between messages, Enter goes into one, Escape comes back out.
Message listTab in, then use the arrow keys. Enter goes into a message with a link, Escape comes back out.
Examples
Rolling, 5 minutes
Fixed, 5 minutes
Rolling or fixed windowFive messages, four minutes apart. Measured from the previous message, the window never runs out and they stay one group. Measured from the first, a new group starts once five minutes have passed since it began.
UnreadThe divider above the first unread message is red with a “New” label, so it doesn't rely on colour alone, and it breaks the group.
With a dividerdividers maps a message id to a label. The divider sits above that message, and the message starts a new group.
Custom spacingSpace between groups and within a group are two values. Change the first for a more open list without pulling a group apart.
TranslatedTimes and dates follow locale. strings holds the list's name, the screen reader labels and the deleted message text.
EmptyWith no messages, the list shows strings.empty in an Empty state. Pass empty to show your own, or null to show nothing.
Freeze unreadFrom when the conversation opens, so the line stays where it
was while people read; clear it when they send a message, press Escape or mark
the conversation read. Pair it with fibo's Jump bar.
Break rules
groupMessages checks these in order, and the first that holds is the
message's breakReason. The first message in the list is start.
| Rule | A new group starts when |
|---|---|
divider | A new group starts whenthe message has a divider above it |
day | A new group starts whenthe message is on a different day from the one before |
system | A new group starts whenthis message or the one before is a system message |
deleted | A new group starts whenthis message or the one before was deleted |
reply | A new group starts whenthe message is a reply |
author | A new group starts whena different person sent it |
identity | A new group starts whenthe same person sent it under a new name or picture |
window | A new group starts whenmore than windowMinutes have passed since the window began |
Each message also gets a position of single, first, middle or last,
rendered as data-position. Bubble layouts use it to square off the corners
where bubbles meet.
Anatomy
A log of articles, one per message, with a labelled separator above any message that starts a day, carries a divider or is the first unread. The first message of a group carries the avatar and heading; later ones keep the time in the gutter, shown on hover or focus.
- Divider
- Avatar
- Heading
- Time
- Reply
- Content
- Message
A day's first messagesA run of two from Ben, then a reply from Ana. The gutter time is held visible here.
Guidelines
- 01Put the list in a scrolling container and keep the composer outside it, so Tab goes from the list straight to the composer.
- 02Keep the window short. Five minutes keeps a burst of messages together without merging two separate thoughts.
- 03Use system messages for events, such as someone joining, not for things people said.
- 04Mark where unread messages begin with unreadFrom. Use dividers for other markers between messages; each one also breaks the group.
Best practices
Accessibility
| Key | Does |
|---|---|
| Tab | DoesMoves onto the list, at the newest message or the last one focused |
| ↑↓ | DoesMoves to the previous or next message |
| Home or End | DoesJumps to the first or last message |
| ↵ | DoesMoves into the message, to its first control |
| Esc | DoesComes back out to the message |
- 01The list is a
role="log", so screen readers announce new messages as they arrive. The ARIA feed pattern was the alternative; it suits browsing a long stream, but announces nothing new on its own. - 02Each group's author is a heading, so screen reader users can jump from author to author. Set headingLevel to fit the page's outline.
- 03Every message is an article named with its author and time, because a screen reader user can land in the middle of a group and never hear the heading.
- 04Controls inside a message stay out of the tab order until the message is entered, including ones your content adds later. Clicking into a message enters it too.
- 05If the focused message is removed, focus moves to the message that takes its place, never to the page.
- 06On later messages in a group, the time sits in a
timeelement and shows on hover or focus. A tap focuses the message, so it shows on a phone too. - 07Day dividers and your own dividers are separators named by their label. The unread divider says “New” as well as turning red, so it doesn't rely on colour alone (WCAG 1.4.1).
Related components
- Typing indicatorSays who's typing in a conversation, naming up to three people.
- Jump barTakes people to unread messages, new messages or the present in a conversation.
- AvatarIn fibo's Storybook
References
- WAI-ARIA log role
- WAI-ARIA feed pattern, the alternative
- Stream Chat's message list, for the four positions in a group
- Twilio Paste: chat log, which requires a metadata label on every message
- AFB AccessWorld's review of Discord, December 2023, on author headings