Component

Cards

A grid of cards that have a link and a description

The component renders the cards as an unordered list element and visually presents it using CSS grid to display the cards in either a one (default), two or three column layout. It doesn’t use the GOV.UK Design System grid but sets its own so that it can separately target desktop, tablet and mobile columns.

Browsers that don’t support CSS grid always display one column.

You must set a href for all the links.

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

Services and information

How to call this component

<%= render "govuk_publishing_components/components/cards", {
  heading: "Services and information",
  items: [
    {
      link: {
        text: "Benefits",
        path: "http://www.gov.uk"
      },
      description: "Includes eligibility, appeals, tax credits and Universal Credit"
    },
    {
      link: {
        text: "Births, deaths, marriages and&nbsp;care",
        path: "http://www.gov.uk"
      },
      description: "Parenting, civil partnerships, divorce and Lasting Power of Attorney"
    },
    {
      link: {
        text: "Business and self-employed",
        path: "http://www.gov.uk"
      },
      description: "Tools and guidance for businesses"
    },
    {
      link: {
        text: "Childcare and parenting",
        path: "http://www.gov.uk"
      },
      description: "Includes giving birth, fostering, adopting, benefits for children, childcare and schools"
    },
    {
      link: {
        text: "Citizenship and living in the&nbsp;UK",
        path: "http://www.gov.uk"
      },
      description: "Voting, community participation, life in the UK, international projects"
    }
  ]
} %>

Accessibility acceptance criteria

The component must:

  • use the correct heading level hierarchy eg. if the component heading uses a <h2>, the subheadings must use a <h3>

It is also good practise to include a heading above the list to tell users what the list contains

Links in the component must:

  • accept focus
  • be focusable with a keyboard
  • be usable with a keyboard
  • indicate when they have focus
  • change in appearance when touched (in the touch-down state)
  • change in appearance when hovered
  • be usable with touch
  • be usable with voice commands
  • have visible text
  • have meaningful text

Other examples

Standard options

This component uses the component wrapper helper. It accepts the following options and applies them to the parent element of the component. See the component wrapper helper documentation for more detail.

  • id - accepts a string for the element ID attribute
  • data_attributes - accepts a hash of data attributes
  • aria - accepts a hash of aria attributes
  • classes - accepts a space separated string of classes, these should not be used for styling and must be prefixed with js-
  • margin_bottom - accepts a number from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale (defaults to no margin)
  • role - accepts a space separated string of roles
  • lang - accepts a language attribute value
  • open - accepts an open attribute value (true or false)
  • hidden - accepts an empty string, ‘hidden’, or ‘until-found’
  • tabindex - accepts an integer. The integer can also be passed as a string.
  • dir - accepts ‘rtl’, ‘ltr’, or ‘auto’.

One column layout without heading (preview)

No border at the top of the list of cards is present when using a one column layout without a heading. The first card item will still include a top border when using a 2 or 3 column layout as shown in the examples below.

<%= render "govuk_publishing_components/components/cards", {
  items: [
    {
      link: {
        text: "Benefits",
        path: "http://www.gov.uk"
      },
      description: "Includes eligibility, appeals, tax credits and Universal Credit"
    },
    {
      link: {
        text: "Births, deaths, marriages and&nbsp;care",
        path: "http://www.gov.uk"
      },
      description: "Parenting, civil partnerships, divorce and Lasting Power of Attorney"
    },
    {
      link: {
        text: "Business and self-employed",
        path: "http://www.gov.uk"
      },
      description: "Tools and guidance for businesses"
    },
    {
      link: {
        text: "Childcare and parenting",
        path: "http://www.gov.uk"
      },
      description: "Includes giving birth, fostering, adopting, benefits for children, childcare and schools"
    },
    {
      link: {
        text: "Citizenship and living in the&nbsp;UK",
        path: "http://www.gov.uk"
      },
      description: "Voting, community participation, life in the UK, international projects"
    }
  ]
} %>

Two column layout (preview)

Override default single column layout on desktop by setting the columns parameter to 2.

<%= render "govuk_publishing_components/components/cards", {
  columns: 2,
  items: [
    {
      link: {
        text: "Benefits",
        path: "http://www.gov.uk"
      },
      description: "Includes eligibility, appeals, tax credits and Universal Credit"
    },
    {
      link: {
        text: "Births, deaths, marriages and&nbsp;care",
        path: "http://www.gov.uk"
      },
      description: "Parenting, civil partnerships, divorce and Lasting Power of Attorney"
    },
    {
      link: {
        text: "Business and self-employed",
        path: "http://www.gov.uk"
      },
      description: "Tools and guidance for businesses"
    },
    {
      link: {
        text: "Childcare and parenting",
        path: "http://www.gov.uk"
      },
      description: "Includes giving birth, fostering, adopting, benefits for children, childcare and schools"
    },
    {
      link: {
        text: "Citizenship and living in the&nbsp;UK",
        path: "http://www.gov.uk"
      },
      description: "Voting, community participation, life in the UK, international projects"
    }
  ]
} %>

Three column layout (preview)

Override default single column layout on desktop by setting the columns parameter to 3.

<%= render "govuk_publishing_components/components/cards", {
  columns: 3,
  items: [
    {
      link: {
        text: "Benefits",
        path: "http://www.gov.uk"
      },
      description: "Includes eligibility, appeals, tax credits and Universal Credit"
    },
    {
      link: {
        text: "Births, deaths, marriages and&nbsp;care",
        path: "http://www.gov.uk"
      },
      description: "Parenting, civil partnerships, divorce and Lasting Power of Attorney"
    },
    {
      link: {
        text: "Business and self-employed",
        path: "http://www.gov.uk"
      },
      description: "Tools and guidance for businesses"
    },
    {
      link: {
        text: "Childcare and parenting",
        path: "http://www.gov.uk"
      },
      description: "Includes giving birth, fostering, adopting, benefits for children, childcare and schools"
    },
    {
      link: {
        text: "Citizenship and living in the&nbsp;UK",
        path: "http://www.gov.uk"
      },
      description: "Voting, community participation, life in the UK, international projects"
    }
  ]
} %>

Custom heading levels (preview)

Override default heading level by passing through heading_level parameter (defaults to <h2>).

Override default subheading level by passing through sub_heading_level parameter (defaults to <h3>)

Services and information

  • Benefits

    Includes eligibility, appeals, tax credits and Universal Credit

<%= render "govuk_publishing_components/components/cards", {
  heading: "Services and information",
  heading_level: 3,
  sub_heading_level: 4,
  items: [
    {
      link: {
        text: "Benefits",
        path: "http://www.gov.uk"
      },
      description: "Includes eligibility, appeals, tax credits and Universal Credit"
    }
  ]
} %>

With data attributes (preview)

Data attributes can be passed to individual links within the component as shown.

Note that the component does not include built in tracking. If this is required consider using the GA4 link tracker.

<%= render "govuk_publishing_components/components/cards", {
  items: [
    {
      link: {
        text: "Benefits",
        path: "http://www.gov.uk",
        data_attributes: {
          an_attribute: "some_value"
        }
      },
      description: "Includes eligibility, appeals, tax credits and Universal Credit"
    },
    {
      link: {
        text: "Births, deaths, marriages and&nbsp;care",
        path: "http://www.gov.uk",
        data_attributes: {
          an_attribute: "some_value"
        }
      },
      description: "Parenting, civil partnerships, divorce and Lasting Power of Attorney"
    }
  ]
} %>