Components

Card

Cards contain content and actions about a single subject.

A card is often a subset or summary of a larger idea. It acts as an entry point to more detailed information. This summary can contain a variety of content types, such as text, images and multimedia, or buttons and links.

An individual card is typically a member of a collection of similar cards, not a single card in isolation. A card is distinguished from others in its collection by its content, and cards are distinguished from the broader page context in form — usually with a border or a shadow.

Finally, a card is modular. This means that you can vary the order of cards in a collection without destroying any individual card’s meaning.

Standard Layout
  • Card

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Facilis earum tenetur quo cupiditate, eaque qui officia recusandae. Excepturi nobis dolores molestias! Quas quisquam a officia eos.

  • Card with media

    A placeholder image

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Facilis earum tenetur quo cupiditate, eaque qui officia recusandae. Excepturi nobis dolores molestias! Quas quisquam a officia eos.

  • Media and header first

    A placeholder image

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Facilis earum tenetur quo cupiditate, eaque qui officia recusandae.

  • Inset media

    A placeholder image

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Facilis earum tenetur quo cupiditate, eaque qui officia recusandae.

  • Exdent media

    A placeholder image

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Facilis earum tenetur quo cupiditate, eaque qui officia recusandae.

Flag Layout
  • Flag default

    A placeholder image

    Lorem ipsum dolor sit amet consectetur adipisicing elit.

  • Flag media on right

    A placeholder image

    Lorem ipsum dolor sit amet consectetur adipisicing elit.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
<h6 class="padding-bottom-2">Standard Layout</h6>
<ul class="usa-card-group">
  <li class="tablet:grid-col-4 usa-card">
    <div class="usa-card__container">
      <header class="usa-card__header">
        <h2 class="usa-card__heading">Card</h2>
      </header>
      <div class="usa-card__body">
        <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Facilis earum tenetur quo cupiditate, eaque qui officia recusandae. Excepturi nobis dolores molestias! Quas quisquam a officia eos.</p>
      </div>
      <div class="usa-card__footer">
        <button class="usa-button">Visit Florida Keys</button>
      </div>
    </div>
  </li>
  <li class="tablet:grid-col-4 usa-card">
    <div class="usa-card__container">
      <header class="usa-card__header">
        <h2 class="usa-card__heading">Card with media</h2>
      </header>
      <div class="usa-card__media">
        <div class="usa-card__img">
          <img src="https://designsystem.digital.gov/img/introducing-uswds-2-0/built-to-grow--alt.jpg" alt="A placeholder image">
        </div>
      </div>
      <div class="usa-card__body">
        <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Facilis earum tenetur quo cupiditate, eaque qui officia recusandae. Excepturi nobis dolores molestias! Quas quisquam a officia eos.</p>
      </div>
      <div class="usa-card__footer">
        <button class="usa-button">Visit Florida Keys</button>
      </div>
    </div>
  </li>
  <li class="tablet:grid-col-4 usa-card usa-card--header-first">
    <div class="usa-card__container">
      <header class="usa-card__header">
        <h2 class="usa-card__heading">Media and header first</h2>
      </header>
      <div class="usa-card__media">
        <div class="usa-card__img">
          <img src="https://designsystem.digital.gov/img/introducing-uswds-2-0/built-to-grow--alt.jpg" alt="A placeholder image">
        </div>
      </div>
      <div class="usa-card__body">
        <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Facilis earum tenetur quo cupiditate, eaque qui officia recusandae.</p>
      </div>
      <div class="usa-card__footer">
        <button class="usa-button">Visit Florida Keys</button>
      </div>
    </div>
  </li>
  <li class="tablet:grid-col-4 usa-card usa-card--header-first">
    <div class="usa-card__container">
      <header class="usa-card__header">
        <h2 class="usa-card__heading">Inset media</h2>
      </header>
      <div class="usa-card__media usa-card__media--inset">
        <div class="usa-card__img">
          <img src="https://designsystem.digital.gov/img/introducing-uswds-2-0/built-to-grow--alt.jpg" alt="A placeholder image">
        </div>
      </div>

      <div class="usa-card__body">
        <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Facilis earum tenetur quo cupiditate, eaque qui officia recusandae.</p>
      </div>
      <div class="usa-card__footer">
        <button class="usa-button">Visit Florida Keys</button>
      </div>
    </div>
  </li>
  <li class="tablet:grid-col-4 usa-card usa-card--header-first">
    <div class="usa-card__container">
      <header class="usa-card__header">
        <h2 class="usa-card__heading">Exdent media</h2>
      </header>
      <div class="usa-card__media usa-card__media--exdent">
        <div class="usa-card__img">
          <img src="https://designsystem.digital.gov/img/introducing-uswds-2-0/built-to-grow--alt.jpg" alt="A placeholder image">
        </div>
      </div>

      <div class="usa-card__body">
        <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Facilis earum tenetur quo cupiditate, eaque qui officia recusandae.</p>
      </div>
      <div class="usa-card__footer">
        <button class="usa-button">Visit Florida Keys</button>
      </div>
    </div>
  </li>
</ul>

<h6 class="padding-bottom-2">Flag Layout</h6>
<ul class="usa-card-group">
  <li class="tablet:grid-col-6 usa-card usa-card--flag">
    <div class="usa-card__container">
      <header class="usa-card__header">
        <h2 class="usa-card__heading">Flag default</h2>
      </header>
      <div class="usa-card__media">
        <div class="usa-card__img">
          <img src="https://designsystem.digital.gov/img/introducing-uswds-2-0/built-to-grow--alt.jpg" alt="A placeholder image">
        </div>
      </div>

      <div class="usa-card__body">
        <p>Lorem ipsum dolor sit amet consectetur adipisicing elit.</p>
      </div>
      <div class="usa-card__footer">
        <button class="usa-button">Visit Florida Keys</button>
      </div>
    </div>
  </li>
  <li class="tablet:grid-col-6 usa-card usa-card--flag usa-card--media-right">
    <div class="usa-card__container">
      <header class="usa-card__header">
        <h2 class="usa-card__heading">Flag media on right</h2>
      </header>
      <div class="usa-card__media">
        <div class="usa-card__img">
          <img src="https://designsystem.digital.gov/img/introducing-uswds-2-0/built-to-grow--alt.jpg" alt="A placeholder image">
        </div>
      </div>

      <div class="usa-card__body">
        <p>Lorem ipsum dolor sit amet consectetur adipisicing elit.</p>
      </div>
      <div class="usa-card__footer">
        <button class="usa-button">Visit Florida Keys</button>
      </div>
    </div>
  </li>
</ul>

When to use the card component

  • Collections of related content. When you need to present a collection of related groups of content, like articles or sections of a website.

When to consider something else

  • Tabular data. Don't use a card as a substitute for a table row.
  • Simple calls to action. Use a button instead.
  • Standalone content. Consider an aside or another standalone element.
  • Sequential, continuous text. Cards should be self-contained and modular. If the reader is meant to read from card to card, consider a list or simple body text and headings.

Usability guidance

  • Make cards actionable. Since cards are used as a summary of more detailed information, any individual card should link out to that information.
  • Don't use the card component only for decoration. Use the card component for cards, not for any type of content that's designed to have a border around it.
  • Include non-redundant content. Don't repeat images or content common to all or most cards in a collection. Repeated information (like using the same image for each card in a collection) makes it more difficult to distinguish cards from one another.
  • Make sure images are properly sized. Cards often change size depending on the device. Make sure you use an image that works well on any device at any size.
  • Use simple styling. Avoid distracting skeumorphism. Don't include any card styling that calls too much attention to the metaphor of a paper card, like folds, bent edges, or paper texture.

Accessibility

  • Use unordered lists and list items. Use a ul for a card group and an li for each card. This allows screen readers to enumerate the items in the card group and allows shortcuts between list items.
  • Use the appropriate heading level for your page. Update heading level based on the content of your page to make sure card headings are in the correct logical outline order.
  • Use CSS to order the media element. Logically, the media element should follow the header elmement. Don't re-organize the markup to reverse their order.

Implementation

  • Control card size and layout with grid utilities. The usa-card-group block is functionally a wrap-able grid-row and each individual usa-card is a grid-col. This means that you can use a grid utility like tablet:grid-col-4 to set a four-column size on a card at tablet width. You can also set custom grid gaps on a usa-card-group using the grid-gap utilities. Since the USWDS grid is based on flexbox, you can use flex positioning utilities on the card group. The default alignment is stretch (this aligns the top and bottom of each card in a row), but the flex-align-start utility can set the alignment to the top of the row.
  • Style cards with utilities. Style the usa-card__container element with utilities to achieve custom effects, such as changing the border or background color, or adding a drop shadow.
Card settings
Variable Description
$theme-card-border-color

Stroke color of card

$theme-card-border-radius
$theme-card-border-width

Stroke thickness of card

$theme-card-gap

Gap between cards in a card group

$theme-card-flag-min-width

Width at which flag cards change to horizontal layout

$theme-card-flag-image-width

Fixed image width in the card flag variant

$theme-card-font-family

Font family for card body

$theme-card-header-typeset

Family, size, and line height of the heading

$theme-card-margin-bottom

Bottom margin for card

$theme-card-padding-perimeter

Padding between card elements and card border

$theme-card-padding-y

Vertical padding between card elements

Card variants
Variant Description
usa-card--flag Display in a horizontal ("flag") orientation at a specified width (`$theme-card-flag-min-width`).
usa-card--header-first Displays the header element before the media element.
usa-card--media-right In combination with usa-card--flag, sets the media element on the right. (Flag cards display media on the left by default.)
usa-card__media--indent Indents the media element so it doesn't extend to the edge of the card.
usa-card__media--set-aspect Sets a fixed aspect ratio on the card media. The default is 16x9, but this can be changed by adding an add-aspect utility to the media element, like usa-card__media--set-aspect.add-aspect-1x1
usa-card__media--exdent Extends the media element out over the card border. Useful for light-bordered cards.
usa-card__body--exdent Extends the body element out over the card border. Useful for light-bordered cards.
usa-card__footer--exdent Extends the footer element out over the card border. Useful for light-bordered cards.

Package information

  • Package usage: @import usa-card
  • Requires: required, global