Help users to Send and reply to messages
Overview
Use this pattern to display an index list of conversations between internal and external users.
Messages - message list
Example Message List contents
Nunjucks
{% from "components/message-list/_macro.njk" import onsMessageList %}
{{
onsMessageList({
"ariaLabel": "Message list for ONS Business Surveys",
"unreadText": "New",
"fromLabel": "From",
"dateLabel": "Sent",
"hiddenReadLabel": "Read the message",
"ariaLabelMetaData": "Message information",
"messages": [
{
"id": "message-list-example-1",
"subject": {
"url": "#0",
"text": "BRES 2016 survey response query"
},
"unread": true,
"fromText": "ONS Business Surveys Team",
"dateText": "Tue 4 Jul 2020 at 7:47",
"body": "Hi Jacky. Thanks for that information. Your figures have allowed us to create more accurate…"
},
{
"id": "message-list-example-2",
"subject":{
"url": "#0",
"text": "BRES 2015 Enquiry on data"
},
"fromText": "Jacky Turner",
"dateText": "Mon 1 Oct 2019 at 9:52",
"body": "Hi Jacky, Thank you for returning the Business Register and Employment Survey (BRES) 2016…"
}
]
})
}}
HTML
<ul class="ons-message-list" aria-label="Message list for ONS Business Surveys">
<li class="ons-message-item" aria-labelledby="message-list-example-1">
<h3 class="ons-message-item__subject" id="message-list-example-1">
<a href="#0" class="ons-u-fs-r--b">BRES 2016 survey response query</a>
<span class="ons-message-item__unread ons-u-fs-s">(New)</span>
</h3>
<dl class="ons-message-item__metadata" aria-label="Message information">
<dt class="ons-message-item__metadata-term ons-message-item__metadata-term--from ons-u-vh">From:</dt>
<dd class="ons-message-item__metadata-value ons-message-item__metadata-value--from ons-u-fs-r--b"> ONS Business
Surveys Team </dd>
<dt class="ons-message-item__metadata-term ons-message-item__metadata-term--date ons-u-vh">Sent:</dt>
<dd class="ons-message-item__metadata-value ons-message-item__metadata-value--date ons-u-fs-s"> Tue 4 Jul 2020 at
7:47 </dd>
<dt class="ons-message-item__metadata-term ons-message-item__metadata-term--body ons-u-vh"> Message text: </dt>
<dd class="ons-message-item__metadata-value ons-message-item__metadata-value--body ons-u-fs-r ons-u-mt-s"> Hi
Jacky. Thanks for that information. Your figures have allowed us to create more accurate… </dd>
</dl>
<div class="ons-message-item__link ons-u-vh">
<a href="#0">Read the message: BRES 2016 survey response query</a>
</div>
</li>
<li class="ons-message-item" aria-labelledby="message-list-example-2">
<h3 class="ons-message-item__subject" id="message-list-example-2">
<a href="#0" class="ons-u-fs-r--b">BRES 2015 Enquiry on data</a>
</h3>
<dl class="ons-message-item__metadata" aria-label="Message information">
<dt class="ons-message-item__metadata-term ons-message-item__metadata-term--from ons-u-vh">From:</dt>
<dd class="ons-message-item__metadata-value ons-message-item__metadata-value--from ons-u-fs-r--b"> Jacky Turner
</dd>
<dt class="ons-message-item__metadata-term ons-message-item__metadata-term--date ons-u-vh">Sent:</dt>
<dd class="ons-message-item__metadata-value ons-message-item__metadata-value--date ons-u-fs-s"> Mon 1 Oct 2019 at
9:52 </dd>
<dt class="ons-message-item__metadata-term ons-message-item__metadata-term--body ons-u-vh"> Message text: </dt>
<dd class="ons-message-item__metadata-value ons-message-item__metadata-value--body ons-u-fs-r ons-u-mt-s"> Hi
Jacky, Thank you for returning the Business Register and Employment Survey (BRES) 2016… </dd>
</dl>
<div class="ons-message-item__link ons-u-vh">
<a href="#0">Read the message: BRES 2015 Enquiry on data</a>
</div>
</li>
</ul>Messages - conversation thread
Example Conversation contents
Nunjucks
{% from "components/message/_macro.njk" import onsMessage %}
{% from "components/description-list/_macro.njk" import onsDescriptionList %}
{% from "components/reply/_macro.njk" import onsReply %}
<div class="ons-grid">
<div class="ons-grid__col ons-col-8@m">
<section role="region" aria-label="Conversation: BRES 2017 clarification required for Bolts & Ratchets Ltd">
<h1 class="ons-u-fs-l"><span class="ons-u-vh">Subject: </span>BRES 2017 clarification required for Bolts & Ratchets Ltd</h1>
{{
onsDescriptionList({
"descriptionListLabel": "Information about the survey and respondent",
"termCol": "3",
"descriptionCol": "9",
"itemsList": [
{
"term": "Survey:",
"descriptions": [
{
"description": "Bricks & Blocks"
}
]
},
{
"term": "RU Ref:",
"descriptions": [
{
"description": "49900000118"
}
]
},
{
"term": "Business:",
"descriptions": [
{
"description": "Bolts & Ratchets Ltd."
}
]
}
]
})
}}
{%
call onsMessage({
"variant": 'sent',
"fromLabel": 'From',
"fromValue": 'ONS surveys',
"sentLabel": 'Sent',
"sentValue": 'Today at 12:56'
})
%}
<p>
Dear Jacky<br />
<br />
Thanks for returning the BRES 2017 spreadsheet for Bolts & Ratchets. I wonder if I could clarify employee figures
for two of the sites, as they’re very different to last year’s figures. The sites are:<br />
Macclesfield<br />
2015: 45 - 2017: 1<br />
and Skipton<br />
2015: 11 - 2017: 183<br />
Are these figures correct?<br />
<br />
Many thanks<br />
David Cleere<br />
BRES Survey Team
</p>
{% endcall %}
{%
call onsMessage({
"variant": 'received',
"fromLabel": 'From',
"fromValue": 'Jackie Turner',
"sentLabel": 'Sent',
"sentValue": 'Today at 13:15'
})
%}
<p>
Hi Dave<br />
Thanks for your message. Yes, the figures are right - we had a big expansion last year when we bought The Widgets Group
and moved staff to Skipton.<br />
<br />
Thanks, Jacky
</p>
{% endcall %}
{%
call onsMessage({
"variant": 'sent',
"fromLabel": 'From',
"fromValue": 'ONS surveys',
"sentLabel": 'Sent',
"sentValue": 'Today at 13:30'
})
%}
<p>
Dear Jacky<br />
<br />
Thank you for clarifying. I will now process your data.<br />
<br />
Many thanks<br />
David Cleere<br />
BRES Survey Team
</p>
{% endcall %}
{%
call onsMessage({
"variant": 'received',
"fromLabel": 'From',
"fromValue": 'Jackie Turner',
"sentLabel": 'Sent',
"sentValue": 'Today at 13:45',
"unreadLinkUrl": '#0',
"unreadLinkText": 'Mark unread'
})
%}
<p>
Hi Dave<br />
Brilliant.<br />
<br />
Thanks, Jacky
</p>
{% endcall %}
{{
onsReply({
"textarea": {
"id": "reply-example-conversation",
"name": "reply",
"label": {
"text": "Reply",
"description": "Maximum 300 characters"
},
"rows": 3,
"charCheckLimit": {
"limit": 300,
"charCountSingular": "You have {x} character remaining",
"charCountPlural": "You have {x} characters remaining"
}
},
"button": {
"type": 'button',
"text": 'Send message'
},
"closeLinkText": 'Close conversation',
"closeLinkUrl": '#0'
})
}}
</section>
</div>
</div>
HTML
<div class="ons-grid">
<div class="ons-grid__col ons-col-8@m">
<section role="region" aria-label="Conversation: BRES 2017 clarification required for Bolts & Ratchets Ltd">
<h1 class="ons-u-fs-l"><span class="ons-u-vh">Subject: </span>BRES 2017 clarification required for Bolts &
Ratchets Ltd</h1>
<dl class="ons-description-list ons-description-list__items ons-grid ons-grid--gutterless ons-u-cf"
title="Information about the survey and respondent" aria-label="Information about the survey and respondent">
<div class="ons-description-list__item">
<dt class="ons-description-list__term ons-grid__col ons-col-3@m">Survey:</dt>
<dd class="ons-description-list__value ons-grid__col ons-col-9@m">Bricks & Blocks</dd>
</div>
<div class="ons-description-list__item">
<dt class="ons-description-list__term ons-grid__col ons-col-3@m">RU Ref:</dt>
<dd class="ons-description-list__value ons-grid__col ons-col-9@m">49900000118</dd>
</div>
<div class="ons-description-list__item">
<dt class="ons-description-list__term ons-grid__col ons-col-3@m">Business:</dt>
<dd class="ons-description-list__value ons-grid__col ons-col-9@m">Bolts & Ratchets Ltd.</dd>
</div>
</dl>
<div class="ons-message ons-message--sent">
<div class="ons-message__head">
<dl class="ons-message__metadata">
<div class="ons-message__sender">
<dt class="ons-message__term ons-u-fw-b">From:</dt>
<dd class="ons-message__value ons-u-fw-b"> ONS surveys </dd>
</div>
<div class="ons-message__timestamp">
<dt class="ons-message__term ons-u-fs-s">Sent:</dt>
<dd class="ons-message__value ons-u-fs-s"> Today at 12:56 </dd>
</div>
</dl>
</div>
<div class="ons-message__body">
<p> Dear Jacky<br />
<br /> Thanks for returning the BRES 2017 spreadsheet for Bolts & Ratchets. I wonder if I could clarify
employee figures for two of the sites, as they’re very different to last year’s figures. The sites
are:<br /> Macclesfield<br /> 2015: 45 - 2017: 1<br /> and Skipton<br /> 2015: 11 - 2017: 183<br /> Are
these figures correct?<br />
<br /> Many thanks<br /> David Cleere<br /> BRES Survey Team
</p>
</div>
</div>
<div class="ons-message ons-message--received">
<div class="ons-message__head">
<dl class="ons-message__metadata">
<div class="ons-message__sender">
<dt class="ons-message__term ons-u-fw-b">From:</dt>
<dd class="ons-message__value ons-u-fw-b"> Jackie Turner </dd>
</div>
<div class="ons-message__timestamp">
<dt class="ons-message__term ons-u-fs-s">Sent:</dt>
<dd class="ons-message__value ons-u-fs-s"> Today at 13:15 </dd>
</div>
</dl>
</div>
<div class="ons-message__body">
<p> Hi Dave<br /> Thanks for your message. Yes, the figures are right - we had a big expansion last year when
we bought The Widgets Group and moved staff to Skipton.<br />
<br /> Thanks, Jacky
</p>
</div>
</div>
<div class="ons-message ons-message--sent">
<div class="ons-message__head">
<dl class="ons-message__metadata">
<div class="ons-message__sender">
<dt class="ons-message__term ons-u-fw-b">From:</dt>
<dd class="ons-message__value ons-u-fw-b"> ONS surveys </dd>
</div>
<div class="ons-message__timestamp">
<dt class="ons-message__term ons-u-fs-s">Sent:</dt>
<dd class="ons-message__value ons-u-fs-s"> Today at 13:30 </dd>
</div>
</dl>
</div>
<div class="ons-message__body">
<p> Dear Jacky<br />
<br /> Thank you for clarifying. I will now process your data.<br />
<br /> Many thanks<br /> David Cleere<br /> BRES Survey Team
</p>
</div>
</div>
<div class="ons-message ons-message--received">
<div class="ons-message__head">
<dl class="ons-message__metadata">
<div class="ons-message__sender">
<dt class="ons-message__term ons-u-fw-b">From:</dt>
<dd class="ons-message__value ons-u-fw-b"> Jackie Turner </dd>
</div>
<div class="ons-message__timestamp">
<dt class="ons-message__term ons-u-fs-s">Sent:</dt>
<dd class="ons-message__value ons-u-fs-s"> Today at 13:45 </dd>
</div>
</dl>
<a class="ons-message__unread-link" href="#0">Mark unread</a>
</div>
<div class="ons-message__body">
<p> Hi Dave<br /> Brilliant.<br />
<br /> Thanks, Jacky
</p>
</div>
</div>
<div class="ons-reply ons-js-reply">
<div class="ons-field">
<label class="ons-label ons-label--with-description" for="reply-example-conversation"
aria-describedby="description-hint">Reply</label>
<span id="description-hint" class="ons-label__description ons-input--with-description">Maximum 300
characters</span>
<textarea id="reply-example-conversation" class="ons-input ons-input--textarea ons-js-char-limit-input"
name="reply" rows="3" maxlength="300" data-char-limit-ref="reply-example-conversation-lim"
aria-describedby="reply-example-conversation-lim"></textarea>
<span id="reply-example-conversation-lim" class="ons-input__limit ons-u-fs-s--b ons-u-d-no ons-u-mt-2xs"
data-charcount-singular="You have {x} character remaining"
data-charcount-plural="You have {x} characters remaining" data-charcount-limit-singular=""
data-charcount-limit-plural="">
</span>
</div>
<div
class="ons-grid ons-grid-flex ons-grid--gutterless ons-grid-flex--vertical-center ons-grid-flex--no-wrap@s ons-u-mt-l ons-u-mb-l">
<div class="ons-grid__col ons-u-mr-m ons-u-mb-s">
<button type="button" class="ons-btn">
<span class="ons-btn__inner"><span class="ons-btn__text">Send message</span></span>
</button>
</div>
<div class="ons-grid__col ons-u-mb-s">
<a class="ons-reply__link" href="#0">Close conversation</a>
</div>
</div>
</div>
</section>
</div>
</div>How to use this pattern
This pattern consists of the following elements and components:
- heading that displays the subject of the message thread
- metadata that provides information about the service or survey
- messages displayed in chronological order to create a conversation thread
- optional "mark as unread" link
- form field (textarea) to create a message
- submit button to send a message
- optional close button to end the conversation
The heading that displays the subject should contain a visually hidden span. For example, <span class="ons-u-vh">Subject: </span>. This helps to provide context to screen reader users about the page.
Each message in a thread is a separate message component.
Set the type parameter as sent to display a sent message, and as received to display a received message.
You can optionally set the unreadLink and unreadLinkText parameters on the last received message to allow the user to mark the message as unread.
Help improve this page
Let us know how we could improve this page, or share your user research findings. Discuss the ‘Send and reply to messages’ pattern on GitHub (opens in a new tab)