Card
Overview
Use the card component to help users navigate through your service. For example, this could be used on:
- homepages
- index pages
- hub pages
Important information:
For links to related content from an information page, use related content.
Important information:
To allow users to access a single service, use a hero.
Example Card contents
Nunjucks
{% from "components/card/_macro.njk" import onsCard %}
{{ onsCard({
"id": 'card-example',
"textId": 'text',
"title": 'Your data and security',
"url": '#0',
"text": 'How we keep your data safe and what happens to your personal information.'
}) }}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| title | string | true | The title for the card heading |
| headingLevel | int | false | Number used to determine the heading level of the card title. Defaults to 2 |
| titleClasses | string | false | Font size classes for the card heading. Defaults to ons-u-fs-m |
| url | string | true | The URL for the title link href attribute |
| id | string | true | The HTML id attribute for the card heading |
| text | string | true | The excerpt text for the card element |
| textId | string | true | The HTML id for the card text excerpt. Used for the card’s aria-describedBy attribute |
| image | Object<Image> or true | false | An object containing path attributes for the card’s image. If value is true will show placeholder with root as placeholderURL base path |
| itemsList | Array<ListItem> (ref) | false | A list of links for child items of the card |
| Name | Type | Required | Description |
|---|---|---|---|
| smallSrc | string | true | Path to the non-retina version of the image |
| largeSrc | string | false | Path to the retina version of the image |
| alt | string | false | The HTML alt tag to explain the appearance and function of the image. Not required if the image is only decorative |
| placeholderURL | string | false | Optional base path for placeholder image |
HTML
<div class="ons-card">
<a href="#0" class="ons-card__link">
<h2 class="ons-card__title ons-u-fs-m" id="card-example"> Your data and security </h2>
</a>
<p id="text">How we keep your data safe and what happens to your personal information.</p>
</div>When not to use this component
Only use cards in the <main> container of the page. Do not use them within an <aside> or <footer>.
How to use this component
The card component needs to be implemented using the grid foundation.
A row should contain no more than three or four cards and stack vertically on small viewports.
When using images in a card, use two versions of the image:
- one for standard screens (
303px width × 200px height) - one for retina screens (
606px width × 400px height)
Define a small and a large image path in the macro as smallSrc and largeSrc.
Variants
Card set
This is a row of three cards.
Example Card Set contents
Nunjucks
{% from "components/card/_macro.njk" import onsCard %}
<div class="ons-container">
<div class="ons-grid ons-grid--column@xxs@s">
<div class="ons-grid__col ons-col-4@m">
{{ onsCard({
"id": 'card-set-1',
"textId": 'text1',
"title": 'About the census',
"url": '#0',
"text": 'The census is a survey that gives us information about all the households in England and Wales.'
}) }}
</div>
<div class="ons-grid__col ons-col-4@m">
{{ onsCard({
"id": 'card-set-2',
"textId": 'text2',
"title": 'Working on the census',
"url": '#0',
"text": 'For Census 2021, we’ll be hiring at least 30,000 field staff across England and Wales.'
}) }}
</div>
<div class="ons-grid__col ons-col-4@m">
{{ onsCard({
"id": 'card-set-3',
"textId": 'text3',
"title": 'Your data and security',
"url": '#0',
"text": 'How we keep your data safe and what happens to your personal information.'
}) }}
</div>
</div>
</div>
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| title | string | true | The title for the card heading |
| headingLevel | int | false | Number used to determine the heading level of the card title. Defaults to 2 |
| titleClasses | string | false | Font size classes for the card heading. Defaults to ons-u-fs-m |
| url | string | true | The URL for the title link href attribute |
| id | string | true | The HTML id attribute for the card heading |
| text | string | true | The excerpt text for the card element |
| textId | string | true | The HTML id for the card text excerpt. Used for the card’s aria-describedBy attribute |
| image | Object<Image> or true | false | An object containing path attributes for the card’s image. If value is true will show placeholder with root as placeholderURL base path |
| itemsList | Array<ListItem> (ref) | false | A list of links for child items of the card |
| Name | Type | Required | Description |
|---|---|---|---|
| smallSrc | string | true | Path to the non-retina version of the image |
| largeSrc | string | false | Path to the retina version of the image |
| alt | string | false | The HTML alt tag to explain the appearance and function of the image. Not required if the image is only decorative |
| placeholderURL | string | false | Optional base path for placeholder image |
HTML
<div class="ons-container">
<div class="ons-grid ons-grid--column@xxs@s">
<div class="ons-grid__col ons-col-4@m">
<div class="ons-card">
<a href="#0" class="ons-card__link">
<h2 class="ons-card__title ons-u-fs-m" id="card-set-1"> About the census </h2>
</a>
<p id="text1">The census is a survey that gives us information about all the households in England and Wales.
</p>
</div>
</div>
<div class="ons-grid__col ons-col-4@m">
<div class="ons-card">
<a href="#0" class="ons-card__link">
<h2 class="ons-card__title ons-u-fs-m" id="card-set-2"> Working on the census </h2>
</a>
<p id="text2">For Census 2021, we’ll be hiring at least 30,000 field staff across England and Wales.</p>
</div>
</div>
<div class="ons-grid__col ons-col-4@m">
<div class="ons-card">
<a href="#0" class="ons-card__link">
<h2 class="ons-card__title ons-u-fs-m" id="card-set-3"> Your data and security </h2>
</a>
<p id="text3">How we keep your data safe and what happens to your personal information.</p>
</div>
</div>
</div>
</div>Card set with list
This is a row of three cards with a list of links that direct the user to the <h2> headings on the linked pages.
You must ensure that all the heading links are unique.
Example Card Set With Lists contents
Nunjucks
{% from "components/card/_macro.njk" import onsCard %}
<div class="ons-container">
<div class="ons-grid ons-grid--column@xxs@s">
<div class="ons-grid__col ons-col-4@m">
{{ onsCard({
"id": 'card-with-list-1',
"textId": 'text1',
"title": 'About the census',
"url": '#0',
"text": 'The census is a survey that gives us information about all the households in England and Wales.',
"itemsList": [
{
"url": '#0',
"text": 'List item 1 about the census'
},
{
"url": '#0',
"text": 'List item 2 about the census'
}
]
}) }}
</div>
<div class="ons-grid__col ons-col-4@m">
{{ onsCard({
"id": 'card-with-list-2',
"textId": 'text2',
"title": 'Working on the census',
"url": '#0',
"text": 'For Census 2021, we’ll be hiring at least 30,000 field staff across England and Wales.',
"itemsList": [
{
"url": '#0',
"text": 'List item 1 about working on the census'
},
{
"url": '#0',
"text": 'List item 2 about working on the census'
}
]
}) }}
</div>
<div class="ons-grid__col ons-col-4@m">
{{ onsCard({
"id": 'card-with-list-3',
"textId": 'text3',
"title": 'Your data and security',
"url": '#0',
"text": 'How we keep your data safe and what happens to your personal information.',
"itemsList": [
{
"url": '#0',
"text": 'List item 1 about your data and security'
},
{
"url": '#0',
"text": 'List item 2 about your data and security'
}
]
}) }}
</div>
</div>
</div>
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| title | string | true | The title for the card heading |
| headingLevel | int | false | Number used to determine the heading level of the card title. Defaults to 2 |
| titleClasses | string | false | Font size classes for the card heading. Defaults to ons-u-fs-m |
| url | string | true | The URL for the title link href attribute |
| id | string | true | The HTML id attribute for the card heading |
| text | string | true | The excerpt text for the card element |
| textId | string | true | The HTML id for the card text excerpt. Used for the card’s aria-describedBy attribute |
| image | Object<Image> or true | false | An object containing path attributes for the card’s image. If value is true will show placeholder with root as placeholderURL base path |
| itemsList | Array<ListItem> (ref) | false | A list of links for child items of the card |
| Name | Type | Required | Description |
|---|---|---|---|
| smallSrc | string | true | Path to the non-retina version of the image |
| largeSrc | string | false | Path to the retina version of the image |
| alt | string | false | The HTML alt tag to explain the appearance and function of the image. Not required if the image is only decorative |
| placeholderURL | string | false | Optional base path for placeholder image |
HTML
<div class="ons-container">
<div class="ons-grid ons-grid--column@xxs@s">
<div class="ons-grid__col ons-col-4@m">
<div class="ons-card">
<a href="#0" class="ons-card__link">
<h2 class="ons-card__title ons-u-fs-m" id="card-with-list-1"> About the census </h2>
</a>
<p id="text1">The census is a survey that gives us information about all the households in England and Wales.
</p>
<ul class="ons-list ons-list--dashed">
<li class="ons-list__item">
<a href="#0" class="ons-list__link">List item 1 about the census</a>
</li>
<li class="ons-list__item">
<a href="#0" class="ons-list__link">List item 2 about the census</a>
</li>
</ul>
</div>
</div>
<div class="ons-grid__col ons-col-4@m">
<div class="ons-card">
<a href="#0" class="ons-card__link">
<h2 class="ons-card__title ons-u-fs-m" id="card-with-list-2"> Working on the census </h2>
</a>
<p id="text2">For Census 2021, we’ll be hiring at least 30,000 field staff across England and Wales.</p>
<ul class="ons-list ons-list--dashed">
<li class="ons-list__item">
<a href="#0" class="ons-list__link">List item 1 about working on the census</a>
</li>
<li class="ons-list__item">
<a href="#0" class="ons-list__link">List item 2 about working on the census</a>
</li>
</ul>
</div>
</div>
<div class="ons-grid__col ons-col-4@m">
<div class="ons-card">
<a href="#0" class="ons-card__link">
<h2 class="ons-card__title ons-u-fs-m" id="card-with-list-3"> Your data and security </h2>
</a>
<p id="text3">How we keep your data safe and what happens to your personal information.</p>
<ul class="ons-list ons-list--dashed">
<li class="ons-list__item">
<a href="#0" class="ons-list__link">List item 1 about your data and security</a>
</li>
<li class="ons-list__item">
<a href="#0" class="ons-list__link">List item 2 about your data and security</a>
</li>
</ul>
</div>
</div>
</div>
</div>Cards with images
This is a row of three cards with images.
Example Card Set With Images contents
Nunjucks
{% from "components/card/_macro.njk" import onsCard %}
<div class="ons-container">
<div class="ons-grid ons-grid--column@xxs@s">
<div class="ons-grid__col ons-col-4@m">
{{ onsCard({
"id": 'card-with-image-1',
"textId": 'text1',
"title": 'About the census',
"url": '#0',
"text": 'The census is a survey that gives us information about all the households in England and Wales.',
"image": true
}) }}
</div>
<div class="ons-grid__col ons-col-4@m">
{{ onsCard({
"id": 'card-with-image-2',
"textId": 'text2',
"title": 'Working on the census',
"url": '#0',
"text": 'For Census 2021, we’ll be hiring at least 30,000 field staff across England and Wales.',
"image": true
}) }}
</div>
<div class="ons-grid__col ons-col-4@m">
{{ onsCard({
"id": 'card-with-image-3',
"textId": 'text3',
"title": 'Your data and security',
"url": '#0',
"text": 'How we keep your data safe and what happens to your personal information.',
"image": true
}) }}
</div>
</div>
</div>
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| title | string | true | The title for the card heading |
| headingLevel | int | false | Number used to determine the heading level of the card title. Defaults to 2 |
| titleClasses | string | false | Font size classes for the card heading. Defaults to ons-u-fs-m |
| url | string | true | The URL for the title link href attribute |
| id | string | true | The HTML id attribute for the card heading |
| text | string | true | The excerpt text for the card element |
| textId | string | true | The HTML id for the card text excerpt. Used for the card’s aria-describedBy attribute |
| image | Object<Image> or true | false | An object containing path attributes for the card’s image. If value is true will show placeholder with root as placeholderURL base path |
| itemsList | Array<ListItem> (ref) | false | A list of links for child items of the card |
| Name | Type | Required | Description |
|---|---|---|---|
| smallSrc | string | true | Path to the non-retina version of the image |
| largeSrc | string | false | Path to the retina version of the image |
| alt | string | false | The HTML alt tag to explain the appearance and function of the image. Not required if the image is only decorative |
| placeholderURL | string | false | Optional base path for placeholder image |
HTML
<div class="ons-container">
<div class="ons-grid ons-grid--column@xxs@s">
<div class="ons-grid__col ons-col-4@m">
<div class="ons-card">
<a href="#0" class="ons-card__link">
<img class="ons-card__image ons-u-mb-s " height="100" width="303"
srcset="/img/small/placeholder-card.png 1x, /img/large/placeholder-card.png 2x"
src="/img/small/placeholder-card.png" alt="" loading="lazy">
<h2 class="ons-card__title ons-u-fs-m" id="card-with-image-1"> About the census </h2>
</a>
<p id="text1">The census is a survey that gives us information about all the households in England and Wales.
</p>
</div>
</div>
<div class="ons-grid__col ons-col-4@m">
<div class="ons-card">
<a href="#0" class="ons-card__link">
<img class="ons-card__image ons-u-mb-s " height="100" width="303"
srcset="/img/small/placeholder-card.png 1x, /img/large/placeholder-card.png 2x"
src="/img/small/placeholder-card.png" alt="" loading="lazy">
<h2 class="ons-card__title ons-u-fs-m" id="card-with-image-2"> Working on the census </h2>
</a>
<p id="text2">For Census 2021, we’ll be hiring at least 30,000 field staff across England and Wales.</p>
</div>
</div>
<div class="ons-grid__col ons-col-4@m">
<div class="ons-card">
<a href="#0" class="ons-card__link">
<img class="ons-card__image ons-u-mb-s " height="100" width="303"
srcset="/img/small/placeholder-card.png 1x, /img/large/placeholder-card.png 2x"
src="/img/small/placeholder-card.png" alt="" loading="lazy">
<h2 class="ons-card__title ons-u-fs-m" id="card-with-image-3"> Your data and security </h2>
</a>
<p id="text3">How we keep your data safe and what happens to your personal information.</p>
</div>
</div>
</div>
</div>Help improve this page
Let us know how we could improve this page, or share your user research findings. Discuss the ‘Card’ component on GitHub (opens in a new tab)