Skip to main content

Metadata

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

<dl class="ons-metadata metadata__list ons-grid ons-grid--gutterless ons-u-cf ons-u-mb-l" title="This is an example of the metadata component" aria-label="This is an example of the metadata component">
  <dt class="ons-metadata__term ons-grid__col ons-col-2@m">Survey:</dt>
  <dd class="ons-metadata__value ons-grid__col ons-col-10@m">Bricks &amp; Blocks</dd>
  <dt class="ons-metadata__term ons-grid__col ons-col-2@m">RU Refs:</dt>
  <dd class="ons-metadata__value ons-grid__col ons-col-10@m">49900000118</dd>
  <dd class="ons-metadata__value ons-grid__col ons-col-10@m">49300005832</dd>
  <dt class="ons-metadata__term ons-grid__col ons-col-2@m">Business:</dt>
  <dd class="ons-metadata__value ons-grid__col ons-col-10@m">Bolts &amp; Ratchets Ltd.</dd>
  <dt class="ons-metadata__term ons-grid__col ons-col-2@m">Trading as:</dt>
  <dd class="ons-metadata__value ons-grid__col ons-col-10@m">Bolts &amp; Ratchets</dd>
  <dt class="ons-metadata__term ons-grid__col ons-col-2@m">To:</dt>
  <dd class="ons-metadata__value ons-grid__col ons-col-10@m">Jacky Turner</dd>
  <dd class="ons-metadata__value ons-grid__col ons-col-10@m">Louise Goodland</dd>
</dl>
{% 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"
                    }
                ]
            }
        ]
    })
}}
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
{% macro onsMetadata(params) %}
  <dl class="ons-metadata metadata__list ons-grid ons-grid--gutterless ons-u-cf ons-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="ons-metadata__term ons-grid__col ons-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="ons-metadata__value ons-grid__col ons-col-{{ params.descriptionCol }}@m">{{ description.description }}</dd>
          {% endif %}
        {% endfor %}
    {% endfor %}
  </dl>
{% endmacro %}
.ons-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 (.ons-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