Skip to main content

Testing

Help us to improve the ONS Design System. Take part in a short study

Metadata

The metadata component is a way to organise and explain a block of key-value pairs of related information.

<dl class="metadata metadata__list grid grid--gutterless u-cf u-mb-l" title="This is an example of the metadata component" aria-label="This is an example of the metadata component">
  <dt class="metadata__term grid__col col-2@m">Survey:</dt>
  <dd class="metadata__value grid__col col-10@m">Bricks &amp; Blocks</dd>
  <dt class="metadata__term grid__col col-2@m">RU Refs:</dt>
  <dd class="metadata__value grid__col col-10@m">49900000118</dd>
  <dd class="metadata__value grid__col col-10@m">49300005832</dd>
  <dt class="metadata__term grid__col col-2@m">Business:</dt>
  <dd class="metadata__value grid__col col-10@m">Bolts &amp; Ratchets Ltd.</dd>
  <dt class="metadata__term grid__col col-2@m">Trading as:</dt>
  <dd class="metadata__value grid__col col-10@m">Bolts &amp; Ratchets</dd>
  <dt class="metadata__term grid__col col-2@m">To:</dt>
  <dd class="metadata__value grid__col col-10@m">Jacky Turner</dd>
  <dd class="metadata__value grid__col col-10@m">Louise Goodland</dd>
</dl>
Nunjucks macro options
Name Type Required Description
metadataLabel string false Value for the ‘title’ and ‘aria-label’ attributes describing the description list
termCol number false The number of grid columns used for the <dt> elements above medium breakpoint
descriptionCol number false The number of grid columns used for the <dd> elements above medium breakpoint
itemsList Array<Item> true An array of terms to render in the description list

Item

Name Type Required Description
term string true The value of the description term
descriptions Array<Description> true An array of descriptions to render in the description list

Description

Name Type Required Description
description string true The description of the related term
{% from "components/metadata/_macro.njk" import onsMetadata %}
{{
    onsMetadata({
        "metadataLabel": "This is an example of the metadata component",
        "termCol": "2",
        "descriptionCol": "10",
        "itemsList": [
            {
                "term": "Survey:",
                "descriptions": [
                    {
                        "description": "Bricks & Blocks"
                    }
                ]
            },
            {
                "term": "RU Refs:",
                "descriptions": [
                    {
                        "description": "49900000118"
                    },
                    {
                        "description": "49300005832"
                    }
                ]
            },
            {
                "term": "Business:",
                "descriptions": [
                    {
                        "description": "Bolts & Ratchets Ltd."
                    }
                ]
            },
            {
                "term": "Trading as:",
                "descriptions": [
                    {
                        "description": "Bolts & Ratchets"
                    }
                ]
            },
            {
                "term": "To:",
                "descriptions": [
                    {
                        "description": "Jacky Turner"
                    },
                    {
                        "description": "Louise Goodland"
                    }
                ]
            }
        ]
    })
}}

{% macro onsMetadata(params) %}
  <dl class="metadata metadata__list grid grid--gutterless u-cf u-mb-l"{% if params.id is defined and params.id %} id="{{ params.id }}" {% endif %}{% if params.metadataLabel is defined and params.metadataLabel %} title="{{ params.metadataLabel }}" aria-label="{{ params.metadataLabel }}"{% endif %}>
    {% for item in (params.itemsList if params.itemsList is iterable else params.itemsList.items()) %}
      {% if item.term | length %}
          <dt class="metadata__term grid__col col-{{ params.termCol }}@m">{{ item.term }}</dt>
      {% endif %}
        {% for description in item.descriptions %}
          {% if description.description | length %}
            <dd {% if description.id is defined and description.id %}id="{{ description.id }}" {% endif %}class="metadata__value grid__col col-{{ params.descriptionCol }}@m">{{ description.description }}</dd>
          {% endif %}
        {% endfor %}
    {% endfor %}
  </dl>
{% endmacro %}

.metadata {
  &__list {
    margin: 0;
  }
  &__term {
    clear: both;
    float: left;
    font-weight: $font-weight-bold;
    &:not(:first-child) {
      margin-top: 0.5rem;
    }
  }
  &__value {
    float: right;
    margin-left: 0; /* As normalize adds a 40px left margin */
    &:not(:nth-of-type(1)) {
      @include mq(m) {
        margin-top: 0.5rem;
      }
    }
    & + & {
      @include mq(m) {
        margin-top: 0;
      }
    }
  }
}

When to use this component

Use the metadata component when you need to display a group of properties and their associated values for an object, product or system. For example, a product’s specification.

How to use this component

A description list <dl> is used to divide the metadata information into terms <dt> and descriptions <dd>.

Use the grid to build the layout of two columns of metadata, setting the number of columns (col-<n>@m) to ensure the terms display on a single line where possible.

Use the metadataLabel to succinctly describe the description list.

Help improve this component

Let us know how we could improve this component or share your user research findings.

Discuss the ‘Metadata’ component on GitHub