Card
The card component provides a navigation mechanism consisting of a title and link, descriptive text and an optional list of further links.
Example: Example Card contents
Nunjucks
{% from "components/card/_macro.njk" import onsCard %}
{{ onsCard({
"id": 'title',
"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 |
| titleSize | string | 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 |
Image
| 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" aria-describedBy="text">
<h2 class="ons-card__title ons-u-fs-m" id="title"><a class="ons-card__link" href="#0">Your data and security</a></h2>
<p id="text">How we keep your data safe and what happens to your personal information.</p>
</div>When to use this component
Use the card component to signpost users to pages and to provide context and further information on the contents of the destination page.
Good examples of where the use of cards work well include; the homepage, to create a collection of the main areas of the service and provide further affordance of what the service offers; hub level pages, to show the key content areas of what could be a deep structure; as a consistent pattern of navigation at any level within a site structure.
How to use this component
Cards should be used in the main container of the page and not within side bars, footers etc. The card component needs to be implemented using the ons-grid component and the various layout options available to display cards in rows. A row should contain no more than 3 or 4 cards and stack vertically on small viewports. The html tab shows the various classes used to achieve the layout.
Card set
The example below shows a row of 3 cards.
Example: 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": 'title1',
"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": 'title2',
"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": 'title3',
"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 |
| titleSize | string | 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 |
Image
| 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" aria-describedBy="text1">
<h2 class="ons-card__title ons-u-fs-m" id="title1"><a class="ons-card__link" href="#0">About the census</a></h2>
<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" aria-describedBy="text2">
<h2 class="ons-card__title ons-u-fs-m" id="title2"><a class="ons-card__link" href="#0">Working on the census</a>
</h2>
<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" aria-describedBy="text3">
<h2 class="ons-card__title ons-u-fs-m" id="title3"><a class="ons-card__link" href="#0">Your data and
security</a></h2>
<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
The example below shows a row of 3 cards with a list of links that relate to the main heading link.
Example: 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": 'title1',
"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'
},
{
"url": '#0',
"text": 'List item 2'
}
]
}) }}
</div>
<div class="ons-grid__col ons-col-4@m">
{{ onsCard({
"id": 'title2',
"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'
},
{
"url": '#0',
"text": 'List item 2'
}
]
}) }}
</div>
<div class="ons-grid__col ons-col-4@m">
{{ onsCard({
"id": 'title3',
"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'
},
{
"url": '#0',
"text": 'List item 2'
}
]
}) }}
</div>
</div>
</div>
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| title | string | true | The title for the card heading |
| titleSize | string | 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 |
Image
| 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" aria-describedBy="text1">
<h2 class="ons-card__title ons-u-fs-m" id="title1"><a class="ons-card__link" href="#0">About the census</a></h2>
<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</a>
</li>
<li class="ons-list__item">
<a href="#0" class="ons-list__link">List item 2</a>
</li>
</ul>
</div>
</div>
<div class="ons-grid__col ons-col-4@m">
<div class="ons-card" aria-describedBy="text2">
<h2 class="ons-card__title ons-u-fs-m" id="title2"><a class="ons-card__link" href="#0">Working on the census</a>
</h2>
<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</a>
</li>
<li class="ons-list__item">
<a href="#0" class="ons-list__link">List item 2</a>
</li>
</ul>
</div>
</div>
<div class="ons-grid__col ons-col-4@m">
<div class="ons-card" aria-describedBy="text3">
<h2 class="ons-card__title ons-u-fs-m" id="title3"><a class="ons-card__link" href="#0">Your data and
security</a></h2>
<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</a>
</li>
<li class="ons-list__item">
<a href="#0" class="ons-list__link">List item 2</a>
</li>
</ul>
</div>
</div>
</div>
</div>Cards with images
The example below shows a row of 3 cards with images.
Example: 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": 'title1',
"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": 'title2',
"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": 'title3',
"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 |
| titleSize | string | 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 |
Image
| 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" aria-describedBy="text1"><a href="#0" class="ons-card__link ons-u-db">
<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="title1"> 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" aria-describedBy="text2"><a href="#0" class="ons-card__link ons-u-db">
<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="title2"> 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" aria-describedBy="text3"><a href="#0" class="ons-card__link ons-u-db">
<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="title3"> 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>How to use this component
If using the card pattern with images, we have two versions of the image, one for standard screens and the other for retina screens.
Image dimensions (width × height):
- standard screen is:
303px × 200px - retina screen is:
606px × 400px
We specify a small and a large image path, which is defined in the macro as smallSrc and largeSrc.
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)