Cookies on ons.gov.uk

Cookies are small files stored on your device when you visit a website. We use some essential cookies to make this website work.

We would like to set additional cookies to remember your settings and understand how you use the site. This helps us to improve our services.

You have accepted all additional cookies. You have rejected all additional cookies. You can change your cookie preferences at any time.

Skip to main content

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",
        "ariaLabelMsg": "Message preview",
        "messages": [
            {
                "id": "message-list-example-1",
                "unread": true,
                "url": "#0",
                "subject": "BRES 2016 survey response query",
                "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",
                "url": "#0",
                "subject": "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>
    </dl>
    <div class="ons-message-item__body" aria-label="Message preview"> Hi Jacky. Thanks for that information. Your
      figures have allowed us to create more accurate… </div>
    <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>
    </dl>
    <div class="ons-message-item__body" aria-label="Message preview"> Hi Jacky, Thank you for returning the Business
      Register and Employment Survey (BRES) 2016… </div>
    <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 &amp; Ratchets Ltd">
            <h1 class="ons-u-fs-l"><span class="ons-u-vh">Subject: </span>BRES 2017 clarification required for Bolts &amp; 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({
                    "type": '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 &amp; 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({
                    "type": '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({
                    "type": '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({
                    "type": 'received',
                    "fromLabel": 'From',
                    "fromValue": 'Jackie Turner',
                    "sentLabel": 'Sent',
                    "sentValue": 'Today at 13:45',
                    "unreadLink": '#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 &amp; Ratchets Ltd">
      <h1 class="ons-u-fs-l"><span class="ons-u-vh">Subject: </span>BRES 2017 clarification required for Bolts &amp;
        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">
        <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 &amp; Blocks</dd>
        <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>
        <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 &amp; Ratchets Ltd.</dd>
      </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 &amp; 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" aria-describedby="description-hint"
            for="reply-example-conversation">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-xs"
            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--vertical-center ons-grid--no-wrap@s ons-u-mt-m ons-u-mb-m">
          <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)