Card block

Use the vf-card component to feature categories of content.

github location npm version

Usage

There are currently two types of card component that can be used for your projects. Each card component requires the additional modifier class to be added into either your .yml file or directly into the HTML.

The cards are available in two styled varieties: bordered and striped. To avoid visual confusion it is recommended to use one variant in a container.

As the striped variant makes use of the brand colour it is recommended not to use this when displayed in a container that has a background colour.

A striped card must always have a heading (vf-card__heading).

Should I use a Card or Summary or Hero?

The vf-card is one of the most popular ways to feature content, however it is not always the best way.

As a general rule:

  • use vf-card to feature a range of different categories (to display event types)
  • use vf-summary for a list of the same type of content (a list of upcoming events)
  • use vf-hero to indicate a singular theme of content for a page

Layout

The vf-card should look like it's around the same size as card from an average set of playing cards.

Content

The vf-card can take a variety optional of content:

Content type .njk / .yml variable CSS class Description
image card_image vf-card__image
alt text card_image__alt
aspect ratio card_custom_aspect_ratio
heading card_heading vf-card__heading
link card_href vf-card__link
subheading card_subheading vf-card__subheading
text card_text vf-card__text

CSS Custom Properties

For browsers that support the CSS aspect-ratio property we provide the option to stipulate the images aspect ratio in a card using a CSS custom property. By default, if no CSS custom property is set, the aspect ratio is 8 / 4. This can be set on the individual cards using the nunjucks 'key' in the .yml or with the {%  render  %} api using the variable card_custom_aspect_ratio.

--vf-card__image--aspect-ratio: 16 / 9;

Variants

Bordered variant

Image alt text

A Bordered Card Heading

With sub–heading

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?

Nunjucks syntax

Depending on your environment you'll want to use render or include. As a rule of thumb: server-side use include, precompiled browser use render. If you're using vf-eleventy you should use include.

Using include

You'll need to pass a context object from your code or Yaml file (example), as well as the path to the Nunjucks template. Nunjucks' include is an abstraction of render and provides some additional portability.


{% set context fromYourYamlFile %}
- or -
{% set context = {
  "component-type": "block",
  "card_heading": "A Bordered Card Heading",
  "card_subheading": "With sub–heading",
  "variant": "bordered",
  "newTheme": "primary",
  "card_href": "JavaScript:Void(0);",
  "card_image": "https://acxngcvroo.cloudimg.io/v7/https://www.embl.org/files/wp-content/uploads/2020/04/SCHOOLS_1011_ells-learninglab_hd_01_Cool_500px.jpg",
  "card_text": "Lorem ipsum dolor sit amet, consectetur <a href=\"JavaScript:Void(0);\" class=\"vf-card__link\">adipisicing elit</a>. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?",
  "card_image__alt": "Image alt text"
}
 %}
{% include "../path_to/vf-card/vf-card.njk" %}

Using render

This approach is best for bare-bones Nunjucks environments, such as precompiled templates with the Nunjucks slim runtime where include is not be available.

{% render '@vf-card', {
  "component-type": "block",
  "card_heading": "A Bordered Card Heading",
  "card_subheading": "With sub–heading",
  "variant": "bordered",
  "newTheme": "primary",
  "card_href": "JavaScript:Void(0);",
  "card_image": "https://acxngcvroo.cloudimg.io/v7/https://www.embl.org/files/wp-content/uploads/2020/04/SCHOOLS_1011_ells-learninglab_hd_01_Cool_500px.jpg",
  "card_text": "Lorem ipsum dolor sit amet, consectetur <a href=\"JavaScript:Void(0);\" class=\"vf-card__link\">adipisicing elit</a>. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?",
  "card_image__alt": "Image alt text"
} %}
React syntax (pre-alpha) 

import { VfCard } from "@visual-framework/vf-card/vf-card.react.js";
// or
import { VfCard } from "@visual-framework/vf-card/vf-card.jsx";
<VfCard parameter="value" />

For individual parameter names and options, see the Nunjucks syntax example. Also follow the React setup guide. Note: React support is in its early pre-alpha stage and not all component are yet supported.

HTML 
<article class="vf-card vf-card--brand vf-card--bordered">

  <img src="https://acxngcvroo.cloudimg.io/v7/https://www.embl.org/files/wp-content/uploads/2020/04/SCHOOLS_1011_ells-learninglab_hd_01_Cool_500px.jpg" alt="Image alt text" class="vf-card__image" loading="lazy">
  <div class="vf-card__content | vf-stack vf-stack--400">
    <h3 class="vf-card__heading"><a class="vf-card__link" href="JavaScript:Void(0);">A Bordered Card Heading <svg aria-hidden="true" class="vf-card__heading__icon | vf-icon vf-icon-arrow--inline-end" width="1em" height="1em" xmlns="http://www.w3.org/2000/svg">
          <path d="M0 12c0 6.627 5.373 12 12 12s12-5.373 12-12S18.627 0 12 0C5.376.008.008 5.376 0 12zm13.707-5.209l4.5 4.5a1 1 0 010 1.414l-4.5 4.5a1 1 0 01-1.414-1.414l2.366-2.367a.25.25 0 00-.177-.424H6a1 1 0 010-2h8.482a.25.25 0 00.177-.427l-2.366-2.368a1 1 0 011.414-1.414z" fill="currentColor" fill-rule="nonzero"></path>
        </svg>
      </a></h3>
    <p class="vf-card__subheading">With sub–heading</p>
    <p class="vf-card__text">Lorem ipsum dolor sit amet, consectetur <a href="JavaScript:Void(0);" class="vf-card__link">adipisicing elit</a>. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?</p>
  </div>
</article>

Striped variant

Image alt text

A Striped Card Heading

With sub–heading

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?

Nunjucks syntax

Depending on your environment you'll want to use render or include. As a rule of thumb: server-side use include, precompiled browser use render. If you're using vf-eleventy you should use include.

Using include

You'll need to pass a context object from your code or Yaml file (example), as well as the path to the Nunjucks template. Nunjucks' include is an abstraction of render and provides some additional portability.


{% set context fromYourYamlFile %}
- or -
{% set context = {
  "component-type": "block",
  "card_heading": "A Striped Card Heading",
  "card_subheading": "With sub–heading",
  "variant": "striped",
  "newTheme": "primary",
  "card_href": "JavaScript:Void(0);",
  "card_image": "https://acxngcvroo.cloudimg.io/v7/https://www.embl.org/files/wp-content/uploads/2020/04/SCHOOLS_1011_ells-learninglab_hd_01_Cool_500px.jpg",
  "card_text": "Lorem ipsum dolor sit amet, consectetur <a href=\"JavaScript:Void(0);\" class=\"vf-card__link\">adipisicing elit</a>. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?",
  "card_image__alt": "Image alt text"
}
 %}
{% include "../path_to/vf-card/vf-card.njk" %}

Using render

This approach is best for bare-bones Nunjucks environments, such as precompiled templates with the Nunjucks slim runtime where include is not be available.

{% render '@vf-card', {
  "component-type": "block",
  "card_heading": "A Striped Card Heading",
  "card_subheading": "With sub–heading",
  "variant": "striped",
  "newTheme": "primary",
  "card_href": "JavaScript:Void(0);",
  "card_image": "https://acxngcvroo.cloudimg.io/v7/https://www.embl.org/files/wp-content/uploads/2020/04/SCHOOLS_1011_ells-learninglab_hd_01_Cool_500px.jpg",
  "card_text": "Lorem ipsum dolor sit amet, consectetur <a href=\"JavaScript:Void(0);\" class=\"vf-card__link\">adipisicing elit</a>. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?",
  "card_image__alt": "Image alt text"
} %}
React syntax (pre-alpha) 

import { VfCard } from "@visual-framework/vf-card/vf-card.react.js";
// or
import { VfCard } from "@visual-framework/vf-card/vf-card.jsx";
<VfCard parameter="value" />

For individual parameter names and options, see the Nunjucks syntax example. Also follow the React setup guide. Note: React support is in its early pre-alpha stage and not all component are yet supported.

HTML 
<article class="vf-card vf-card--brand vf-card--striped">

  <img src="https://acxngcvroo.cloudimg.io/v7/https://www.embl.org/files/wp-content/uploads/2020/04/SCHOOLS_1011_ells-learninglab_hd_01_Cool_500px.jpg" alt="Image alt text" class="vf-card__image" loading="lazy">
  <div class="vf-card__content | vf-stack vf-stack--400">
    <h3 class="vf-card__heading"><a class="vf-card__link" href="JavaScript:Void(0);">A Striped Card Heading <svg aria-hidden="true" class="vf-card__heading__icon | vf-icon vf-icon-arrow--inline-end" width="1em" height="1em" xmlns="http://www.w3.org/2000/svg">
          <path d="M0 12c0 6.627 5.373 12 12 12s12-5.373 12-12S18.627 0 12 0C5.376.008.008 5.376 0 12zm13.707-5.209l4.5 4.5a1 1 0 010 1.414l-4.5 4.5a1 1 0 01-1.414-1.414l2.366-2.367a.25.25 0 00-.177-.424H6a1 1 0 010-2h8.482a.25.25 0 00.177-.427l-2.366-2.368a1 1 0 011.414-1.414z" fill="currentColor" fill-rule="nonzero"></path>
        </svg>
      </a></h3>
    <p class="vf-card__subheading">With sub–heading</p>
    <p class="vf-card__text">Lorem ipsum dolor sit amet, consectetur <a href="JavaScript:Void(0);" class="vf-card__link">adipisicing elit</a>. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?</p>
  </div>
</article>

Examples

Bordered Headings

A Bordered Card Heading as an example

With sub–heading

Bordered Headings With Link

Bordered

Image alt text

A Bordered Card Heading

With sub–heading

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?

Bordered With Link

A Bordered Card Heading

With sub–heading

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?

Bordered With Image

Image alt text

A Bordered Card Heading

With sub–heading

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?

Bordered With Image And No Heading

Image alt text

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?

Striped Only Headings

A Striped Card Heading

With sub–heading

Striped Only Linked Headings

Striped

Image alt text

A Striped Card Heading

With sub–heading

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?

Striped With Link

Striped With Image

Image alt text

A Striped Card Heading

With sub–heading

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sapiente harum, omnis provident saepe aut eius aliquam sequi fugit incidunt reiciendis, mollitia quos?

Installation info

This repository is distributed with npm. After installing npm, you can install vf-card with this command.

$ yarn add --dev @visual-framework/vf-card

Sass/CSS

The style files included are written in Sass. If you're using a VF-core project, you can import it like this:

@import "@visual-framework/vf-card/index.scss";

Make sure you import Sass requirements along with the modules. You can use a project boilerplate or the vf-sass-starter

Changelog

Changelog

2.7.0

  • Updates vf-stack custom properties to work nicely with vf-stack version 3.

2.6.2

  • Use vf-stack custom property for card text spacing.

2.6.1

  • Resolves an accessibility issue with contrast for the striped card subheading variant.
  • https://github.com/visual-framework/vf-core/issues/1657

2.6.0

  • Requires at least @visual-framework@vf-sass-config@2.6.1.
  • Use design tokens for text colours.
  • https://github.com/visual-framework/vf-core/pull/1606

2.5.9

  • Bug: correct a missing space in Nunjucks template.
  • https://github.com/visual-framework/vf-core/pull/1603

2.5.8

  • Documentation: clarity on using card vs summary components.
  • https://github.com/visual-framework/vf-core/issues/1592

2.5.7

  • Fixes the vertical centering of the svg arrow on vf-card titles. Also aligns better with the Figma design kit.
  • https://github.com/visual-framework/vf-core/pull/1562

2.5.6

  • Fixes issue with modifiers
  • https://github.com/visual-framework/vf-core/issues/1523

2.5.5

  • corrects colouring of visited link in heading on striped variant.

2.5.4

  • adds word-break: break-word; to text so the text won't exceed the box model.

2.5.3

  • Corrects fix in 2.5.2 by using align-content: start;.
  • https://github.com/visual-framework/vf-core/issues/1395#issuecomment-801232527

2.5.2

  • adds align-items: start; to the card so all child align when in a card container.
  • Fixes CSS to match stylelint rules.
  • https://github.com/visual-framework/vf-core/pull/1405

2.5.1

  • fixes issue with HTML Entities and the README when running fractal.

2.5.0

  • changes any set- style functions to cleaner version
  • fixes issue with vf-card__image height in Safari.
  • removes grid-template-rows as it's difficult to define now cards do not have to have images.
  • adds a --vf-card__image--aspect-ratio CSS custom property to help with the initial image height.
  • updates documentation to replace 'title' with 'heading' so it matches CSS classname.

2.4.0

  • creates option to for a subheading
  • creates option for a card with no image
  • adds a svg icon similar to vf-section-header when the heading has a link
  • adds documentation
  • adds more examples for the variants available depending on the content
  • hides all variants that should not be used.

2.3.3

  • React: Use react-dom-fragment to return HTML fragments.
  • https://github.com/visual-framework/vf-core/pull/1291

2.3.2

  • adds prototype react template
  • https://github.com/visual-framework/vf-core/pull/1278

2.3.1

  • issue with margin-bottom still in place when using vf-stack with vf-card__content.

2.3.0

  • adds new --bordered and --striped design variants.
  • added vf-stack to the vf-card__content element to determine spacing.
  • allows for the lack of vf-stack for older components.
  • started the deprecation of the 'Mortal Kombat' variants, initially by hiding them in vf-core.
  • introduced newTheme so the 'Mortal Kombat' variants can live side-by-side with news versions for now.
  • the newTheme moves us back to the 'primary' being the embl green, the secondary the embl blue, etc.
  • we now remove the -theme part of the css class moving forward as it's cleaner, easier to read, and states the same thing without it.
  • created theme variants of the new design variants (these are hidden, and should not be used).

2.2.1

  • fixes a hover issue if the card has a link and is the --easy variant.

2.2.0

  • adds a slight box shadow to all card variants to denote that it's something on the page, not 'of the page'
  • updates the hover box shadow so that it fits with the new box shadow on all cards

2.1.2

  • fixes issue with vf-card__image height in safari
  • adds object-position: center for image
  • adds loading="lazy" to the img element for better performance

2.1.1

  • adds alt text to examples
  • conditional display of card_title

2.1.0

  • makes theme variant naming and decisions consistent

2.0.0

  • gives title option to have a link that fills 'card'
  • makes links in text have a higher z-index than the whole card link
  • fundamental .yml and .njk changes

1.0.4 (2020-03-20)

  • Flattens Nunjucks template variables for more portability https://github.com/visual-framework/vf-core/pull/805

1.0.3

  • Removes --medium variants
  • Introduces --very-easy variant
  • Pulls all design variants back one

1.0.2 (2020-01-28)

  • Corrects YAML template usage and NJK template

1.0.1 (2020-01-24)

  • Improves layout and design support

1.0.0 (2019-12-17)

  • Initial stable release

Assets


File system location: components/vf-card

Find an issue on this page? Propose a change or discuss it.