Skip to main content

Collection

A collection displays a compact list of multiple related items like articles or events. The list links each item to its original source.


Default Collection

Component Preview

  • Article headline one

    Brief description of the article content. This provides context for what the user will find when they click through.

    • By Author Name
    • New
    • Topic

  • Article headline two

    Another brief description of the article content providing context for users.

    • By Another Author

Component Code

<ul class="usa-collection">
  <li class="usa-collection__item">
    <div class="usa-collection__body">
      <h4 class="usa-collection__heading">
        <a class="usa-link" href="#">Article headline</a>
      </h4>
      <p class="usa-collection__description">
        Brief description of the article content.
      </p>
      <ul class="usa-collection__meta" aria-label="More information">
        <li class="usa-collection__meta-item">By Author Name</li>
        <li class="usa-collection__meta-item">
          <time datetime="2024-01-15">January 15, 2024</time>
        </li>
      </ul>
      <ul class="usa-collection__meta" aria-label="Topics">
        <li class="usa-collection__meta-item usa-tag usa-tag--new">New</li>
        <li class="usa-collection__meta-item usa-tag">Topic</li>
      </ul>
    </div>
  </li>
</ul>

Media Thumbnail Collection

Component Preview

  • Placeholder image

    Article with thumbnail

    This collection item includes a thumbnail image alongside the content.

    • By Author Name
  • Placeholder image

    Another article with thumbnail

    Another collection item with a thumbnail image for visual interest.

    • By Another Author

Component Code

<ul class="usa-collection">
  <li class="usa-collection__item">
    <img
      class="usa-collection__img"
      src="/path/to/image.jpg"
      alt="Descriptive alt text"
    />
    <div class="usa-collection__body">
      <h4 class="usa-collection__heading">
        <a class="usa-link" href="#">Article with thumbnail</a>
      </h4>
      <p class="usa-collection__description">
        This collection item includes a thumbnail image.
      </p>
      <ul class="usa-collection__meta" aria-label="More information">
        <li class="usa-collection__meta-item">By Author Name</li>
        <li class="usa-collection__meta-item">
          <time datetime="2024-01-15">January 15, 2024</time>
        </li>
      </ul>
    </div>
  </li>
</ul>

Calendar Display Collection

Component Preview

  • Upcoming event title

    Description of the upcoming event with details about what participants can expect.

  • Another event title

    Another event description providing context and details for attendees.


Component Code

<ul class="usa-collection">
  <li class="usa-collection__item">
    <div class="usa-collection__calendar-date">
      <time datetime="2024-01-15">
        <span class="usa-collection__calendar-date-month">JAN</span>
        <span class="usa-collection__calendar-date-day">15</span>
      </time>
    </div>
    <div class="usa-collection__body">
      <h4 class="usa-collection__heading">
        <a class="usa-link" href="#">Event title</a>
      </h4>
      <p class="usa-collection__description">
        Description of the event.
      </p>
    </div>
  </li>
</ul>

Condensed Collection (Headings Only)

Component Preview


Component Code

<ul class="usa-collection usa-collection--condensed">
  <li class="usa-collection__item">
    <div class="usa-collection__body">
      <h4 class="usa-collection__heading">
        <a class="usa-link" href="#">Link title</a>
      </h4>
      <ul class="usa-collection__meta" aria-label="More information">
        <li class="usa-collection__meta-item position-relative">
          Source Name
        </li>
      </ul>
    </div>
  </li>
</ul>


Guidance

When to use the collection component

To feature content with its metadata.
The collection component is a good option when displaying content that should be accompanied by limited metadata like tags, date/time, or source and attribution.
To group related content together.
The collection component can provide links to articles from a trusted source, popular guides and resources, or a collection of pages that cover different aspects of a single topic.
To collect items from multiple sources.
Use collections when you want to guide users to additional resources available elsewhere.

When to consider something else

Providing an archive of articles or pages.
Consider limiting the number of items in each collection to six or fewer. If you need to allow users to search or browse a larger content catalog, consider using a separate index or archive page.
When you want to display large images or other media.
Collections are meant to be compact. If you need something with large images or other media, consider using the card component.

Usability guidance

Use thumbnail images consistently.
If you use a thumbnail image on one item, use a similar kind of image on every item in the collection.
Use a consistent width for images.
Display item images with a consistent width. This promotes consistent alignment and easy scannability.
Use a descriptive title.
The collection's title should make the collection's theme clear.

Accessibility guidance

Use unordered lists and list items.
Use a ul for a collection and an li for each item. This allows screen readers to enumerate the items.
Use the appropriate heading level for your page.
Update heading levels based on the content of your page to make sure collection headings are in the correct logical outline order.
Each link should have a unique name.
Those using assistive technology may collect all page links together. Unique names help users distinguish between links.

USWDS Documentation

For more guidance, view the USWDS Collection Component Documentation.



Settings

Variable Description
$theme-collection-font-family

Font family for collection body.
$theme-collection-header-typeset

Family, size, and line height of the heading.


Variants

Variant Description

.usa-collection--condensed

A more condensed item presentation with less space between items.
Looking for U.S. government information and services?
Visit USA.gov