Description list

Use a description list to organise and display important information about a business, object, product or system.

Example Description List contents

Nunjucksfor Example Description List
Nunjucks macro optionsfor Example Description List
HTMLfor Example Description List

Nunjucks

{% from "components/description-list/_macro.njk" import onsDescriptionList %}
{{
    onsDescriptionList({
        "classes": "ons-u-mb-no",
        "descriptionListLabel": "Information about this business and its survey requirements",
        "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"
                    }
                ]
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
id	string	false	The HTML `id` for the description list (`<dl>`)
classes	string	false	Classes to apply to description list (`<dl>`)
descriptionListLabel	string	false	Sets the HTML `title` and `aria-label` attributes to provide additional information about the description list
termCol	number	true	The number of grid columns used for the `<dt>` elements above medium breakpoint
descriptionCol	number	true	The number of grid columns used for the `<dd>` elements above medium breakpoint
itemsList	array`<Item>`	true	Settings for the terms and descriptions of the description list items

Item
Name	Type	Required	Description
term	string	true	The value of the description term
descriptions	array`<Description>`	true	Settings for each description item

Description
Name	Type	Required	Description
id	string	false	The HTML `id` for the description of the related term
description	string	true	The value of the description of the related term

HTML

<dl class="ons-description-list ons-description-list__items ons-grid ons-grid--gutterless ons-u-cf ons-u-mb-no"
  title="Information about this business and its survey requirements"
  aria-label="Information about this business and its survey requirements">
  <dt class="ons-description-list__term ons-grid__col ons-col-2@m">Survey:</dt>
  <dd class="ons-description-list__value ons-grid__col ons-col-10@m">Bricks &amp; Blocks</dd>
  <dt class="ons-description-list__term ons-grid__col ons-col-2@m">RU Refs:</dt>
  <dd class="ons-description-list__value ons-grid__col ons-col-10@m">49900000118</dd>
  <dd class="ons-description-list__value ons-grid__col ons-col-10@m">49300005832</dd>
  <dt class="ons-description-list__term ons-grid__col ons-col-2@m">Business:</dt>
  <dd class="ons-description-list__value ons-grid__col ons-col-10@m">Bolts &amp; Ratchets Ltd.</dd>
  <dt class="ons-description-list__term ons-grid__col ons-col-2@m">Trading as:</dt>
  <dd class="ons-description-list__value ons-grid__col ons-col-10@m">Bolts &amp; Ratchets</dd>
  <dt class="ons-description-list__term ons-grid__col ons-col-2@m">To:</dt>
  <dd class="ons-description-list__value ons-grid__col ons-col-10@m">Jacky Turner</dd>
  <dd class="ons-description-list__value ons-grid__col ons-col-10@m">Louise Goodland</dd>
</dl>

How to use this component

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

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

Use the metadataLabel to effectively describe the description list.

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss the ‘Metadata’ component on GitHub (opens in a new tab)