Lists

Display a simple list of stacked items or compose a more complex arrangement of elements.

Example

  • Frederick Banting

    JDRF One Walk, Denver 2018

  • Frederick Eloie

    JDRF One Walk, New Orleans 2019

  • Frederick Sacks

    JDRF 2019 Saratoga Springs Ride to Cure Diabetes

Elements

A List item can include various elements, depending on context and intended behavior.

Title

The title describes the list item using a word or phrase. Title is the only required element for a list item.

Text

The default is a simple, unlinked word or phrase that describes the list item.

  • Washington, DC

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item">
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title"> Washington, DC </h3>
        </div>
    </li>
</ul>

Linked

If the item is an invitation to read more, link the title to the page with more details. Except for conventional patterns familiar to users, such as search results, always reinforce a linked title with a separate action link.

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item">
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title">
                <a class="spirit-list-item__link-title" href="#"> Delaware Chapter </a>
            </h3>
            <div class="spirit-list-item__links-contain">
                <a class="spirit-list-item__link" href="#">View</a>
            </div>
        </div>
    </li>
</ul>

Microcopy

Microcopy supports the item title with additional details.

Title Metadata

Use title metadata for important but terse details, such as an donation amount or event date. It is positioned opposite the title on the same row.

  • Frederick Banting $9999

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item">
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title"> Frederick Banting <span class="spirit-list-item__title-meta"> $9999 </span>
            </h3>
        </div>
    </li>
</ul>

Item Metadata

Use item metadata to supplement the title with useful structured data, such as a location or date. Each list item (without Caption) can have up to two item metadata fields.

  • Frederick Banting

    September 13, 2018

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item">
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title"> Frederick Banting </h3>
            <p class="spirit-list-item__meta">September 13, 2018</p>
        </div>
    </li>
</ul>

Item Caption

Use item caption to summarize the item. This is useful for lists of articles or press releases.

  • Distinction in Innovation Award

    JDRF celebrates Sherry and Larry Benaroya’s noteworthy contributions as volunteer supporters with the Distinction in Innovation Award.

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item">
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title"> Distinction in Innovation Award </h3>
            <p class="spirit-list-item__caption">JDRF celebrates Sherry and Larry Benaroya’s noteworthy contributions as volunteer supporters with the Distinction in Innovation Award.</p>
        </div>
    </li>
</ul>

Invite action with one or two links per list item, positioning underneath the item or to the right of the title. Match the first action's link to the title's link.

Underneath

Use action links underneath the item when the items often have long titles that may wrap. Although the component prevents conflict, it is more aesthetically pleasing to put the links underneath.

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item">
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title">
                <a class="spirit-list-item__link-title" href="#"> Hy-Vee Finishes Strong at JDRF Ride to Cure Diabetes® in La Crosse, WI </a>
            </h3>
            <div class="spirit-list-item__links-contain">
                <a class="spirit-list-item__link" href="#">Read More</a>
                <a class="spirit-list-item__link spirit-list-item__link--secondary" href="#">Donate</a>
            </div>
        </div>
    </li>
</ul>

On the right

Use action links on the right for single-line list items, when you want to keep the list as compact as possible. Avoid using item metadata with action links on the right.

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item">
        <div class="spirit-list-item__content spirit-list-item__content--links-right">
            <h3 class="spirit-list-item__title">
                <a class="spirit-list-item__link-title" href="#"> Christine Jakubowski </a>
            </h3>
            <div class="spirit-list-item__links-contain">
                <a class="spirit-list-item__link" href="#">View</a>
                <a class="spirit-list-item__link spirit-list-item__link--secondary" href="#">Donate</a>
            </div>
        </div>
    </li>
</ul>

Numbers (Ordered List)

Use an ordered list for a leaderboard. Numbers are supplied automatically.

  1. John Hughes

  2. Jeff Weiser

  3. Christine Jakubowski

Code Copied
Copy Code 
<ol class="spirit-list">
    <li class="spirit-list-item">
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title"> John Hughes </h3>
        </div>
    </li>
    <li class="spirit-list-item">
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title"> Jeff Weiser </h3>
        </div>
    </li>
    <li class="spirit-list-item">
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title"> Christine Jakubowski </h3>
        </div>
    </li>
</ol>

Avatar

Use an avatar to personalize and differentiate list items. If no image is available, fallback to an icon placeholder.

  • John Hughes

  • Jeff Weiser

  • Test Image

    Christine Jakubowski

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item spirit-list-item--avatar">
        <div class="spirit-list-item__avatar">
            <svg aria-label="user" class="spirit-icon spirit-list-item__icon spirit-icon--user" aria-hidden="true">
                <use xlink:href="/icons/spirit.svg#user">
                </use>
            </svg>
        </div>
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title"> John Hughes </h3>
        </div>
    </li>
    <li class="spirit-list-item spirit-list-item--avatar">
        <div class="spirit-list-item__avatar">
            <svg aria-label="user" class="spirit-icon spirit-list-item__icon spirit-icon--user" aria-hidden="true">
                <use xlink:href="/icons/spirit.svg#user">
                </use>
            </svg>
        </div>
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title"> Jeff Weiser </h3>
        </div>
    </li>
    <li class="spirit-list-item spirit-list-item--avatar">
        <div class="spirit-list-item__avatar">
            <figure class="spirit-image" itemprop="image" itemtype="http://schema.org/ImageObject">
                <span class="spirit-image__image-wrap ">
                    <img class="spirit-image__image" src="https://picsum.photos/300/100?image=64" alt="Test Image">
                </span>
            </figure>
        </div>
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title"> Christine Jakubowski </h3>
        </div>
    </li>
</ul>

Icon

Use icons in lists displaying various types of content to increase scannability and help differentiate list items.

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item spirit-list-item--avatar">
        <div class="spirit-list-item__avatar">
            <a class="spirit-list-item__link-avatar" href="#">
                <svg aria-label="user" class="spirit-icon spirit-list-item__icon spirit-icon--user" aria-hidden="true">
                    <use xlink:href="/icons/spirit.svg#user">
                    </use>
                </svg>
            </a>
        </div>
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title">
                <a class="spirit-list-item__link-title" href="#"> Frederick Banting </a>
            </h3>
            <p class="spirit-list-item__meta">JDRF One Walk, Denver 2018</p>
            <div class="spirit-list-item__links-contain">
                <a class="spirit-list-item__link" href="#">View Participant</a>
            </div>
        </div>
    </li>
    <li class="spirit-list-item spirit-list-item--avatar">
        <div class="spirit-list-item__avatar">
            <a class="spirit-list-item__link-avatar" href="#">
                <svg aria-label="calendar" class="spirit-icon spirit-list-item__icon spirit-icon--calendar" aria-hidden="true">
                    <use xlink:href="/icons/spirit.svg#calendar">
                    </use>
                </svg>
            </a>
        </div>
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title">
                <a class="spirit-list-item__link-title" href="#"> JDRF One Walk, Four Rivers 2018 </a>
            </h3>
            <div class="spirit-list-item__links-contain">
                <a class="spirit-list-item__link" href="#">View Event</a>
            </div>
        </div>
    </li>
    <li class="spirit-list-item spirit-list-item--avatar">
        <div class="spirit-list-item__avatar">
            <a class="spirit-list-item__link-avatar" href="#">
                <svg aria-label="user" class="spirit-icon spirit-list-item__icon spirit-icon--user" aria-hidden="true">
                    <use xlink:href="/icons/spirit.svg#user">
                    </use>
                </svg>
            </a>
        </div>
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title">
                <a class="spirit-list-item__link-title" href="#"> Frederick Sacks </a>
            </h3>
            <p class="spirit-list-item__meta">JDRF 2019 Saratoga Springs Ride to Cure Diabetes</p>
            <div class="spirit-list-item__links-contain">
                <a class="spirit-list-item__link" href="#">View Rider</a>
            </div>
        </div>
    </li>
</ul>

Photo

Use a photo to differentiate list items and/or to support an item title. Photos can be positioned to the left (default) or right.

Left (Default)

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item spirit-list-item--image">
        <div class="spirit-list-item__image-contain">
            <a class="spirit-list-item__link-image" href="#">
                <figure class="spirit-image" itemprop="image" itemtype="http://schema.org/ImageObject">
                    <span class="spirit-image__image-wrap  spirit-image__image-wrap--standard">
                        <img class="spirit-image__image" src="https://picsum.photos/300/300?image=63" alt="Test Image">
                    </span>
                </figure>
            </a>
        </div>
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title">
                <a class="spirit-list-item__link-title" href="#"> Ravens rookie tight end Mark Andrews inspires fellow Type 1 diabetics to follow their dreams </a>
            </h3>
            <p class="spirit-list-item__meta">09/09/2018 – Baltimore Sun</p>
            <div class="spirit-list-item__links-contain">
                <a class="spirit-list-item__link" href="#">Read More</a>
            </div>
        </div>
    </li>
</ul>
Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item spirit-list-item--image spirit-list-item--image--right">
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title">
                <a class="spirit-list-item__link-title" href="#"> How To Organize The Perfect Fundraising Gala </a>
            </h3>
            <p class="spirit-list-item__meta">08/28/2018 – Forbes</p>
            <div class="spirit-list-item__links-contain">
                <a class="spirit-list-item__link" href="#">Read More</a>
            </div>
        </div>
        <div class="spirit-list-item__image-contain spirit-list-item__image-contain--right">
            <a class="spirit-list-item__link-image" href="#">
                <figure class="spirit-image" itemprop="image" itemtype="http://schema.org/ImageObject">
                    <span class="spirit-image__image-wrap  spirit-image__image-wrap--standard">
                        <img class="spirit-image__image" src="https://picsum.photos/300/300?image=58" alt="Test Image">
                    </span>
                </figure>
            </a>
        </div>
    </li>
</ul>

Sizes

Lists can be scaled for a variety of scenarios. Scaling only affects the item title, and thus the visual prominence of the list. The default (extra large) is recommended for most situations.

Extra Large (default)

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item spirit-list-item--xl spirit-list-item--image">
        <div class="spirit-list-item__image-contain">
            <a class="spirit-list-item__link-image" href="#">
                <figure class="spirit-image" itemprop="image" itemtype="http://schema.org/ImageObject">
                    <span class="spirit-image__image-wrap  spirit-image__image-wrap--standard">
                        <img class="spirit-image__image" src="https://picsum.photos/300/300?image=63" alt="Test Image">
                    </span>
                </figure>
            </a>
        </div>
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title spirit-list-item__title--xl">
                <a class="spirit-list-item__link-title" href="#"> How To Organize The Perfect Fundraising Gala </a>
            </h3>
            <p class="spirit-list-item__meta">08/28/2018 – Forbes</p>
            <div class="spirit-list-item__links-contain">
                <a class="spirit-list-item__link" href="#">Read More</a>
            </div>
        </div>
    </li>
</ul>

Large

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item spirit-list-item--l spirit-list-item--image">
        <div class="spirit-list-item__image-contain">
            <a class="spirit-list-item__link-image" href="#">
                <figure class="spirit-image" itemprop="image" itemtype="http://schema.org/ImageObject">
                    <span class="spirit-image__image-wrap  spirit-image__image-wrap--standard">
                        <img class="spirit-image__image" src="https://picsum.photos/300/300?image=63" alt="Test Image">
                    </span>
                </figure>
            </a>
        </div>
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title spirit-list-item__title--l">
                <a class="spirit-list-item__link-title" href="#"> How To Organize The Perfect Fundraising Gala </a>
            </h3>
            <p class="spirit-list-item__meta">08/28/2018 – Forbes</p>
            <div class="spirit-list-item__links-contain">
                <a class="spirit-list-item__link" href="#">Read More</a>
            </div>
        </div>
    </li>
</ul>

Medium

Code Copied
Copy Code 
<ul class="spirit-list">
    <li class="spirit-list-item spirit-list-item--m spirit-list-item--image">
        <div class="spirit-list-item__image-contain">
            <a class="spirit-list-item__link-image" href="#">
                <figure class="spirit-image" itemprop="image" itemtype="http://schema.org/ImageObject">
                    <span class="spirit-image__image-wrap  spirit-image__image-wrap--standard">
                        <img class="spirit-image__image" src="https://picsum.photos/300/300?image=63" alt="Test Image">
                    </span>
                </figure>
            </a>
        </div>
        <div class="spirit-list-item__content">
            <h3 class="spirit-list-item__title spirit-list-item__title--m">
                <a class="spirit-list-item__link-title" href="#"> How To Organize The Perfect Fundraising Gala </a>
            </h3>
            <p class="spirit-list-item__meta">08/28/2018 – Forbes</p>
            <div class="spirit-list-item__links-contain">
                <a class="spirit-list-item__link" href="#">Read More</a>
            </div>
        </div>
    </li>
</ul>

Guidelines

Use When

  • Linking several content blurbs to the corresponding content pages. List is the “hub” in the “hub and spoke” navigation model.
  • Listing a homogeneous set of items, such as people, teams, donors, donations, events, or chapters.

Do not use when

  • You need to structure prose text into an numbered or bulleted list. Use Long Form Text.

Visual Language

  • Use a consistent arrangement of elements for every item in a list. For example, if some items have an avatar and others don’t, use a placeholder image to keep the list balanced and consistent.

Behavior

  • Link images, avatars and icons to the same destination as the item title.

Editorial

Item Titles

  • Keep list item titles brief.
  • Match the release title if linking to a press release.
  • For named items, like people, teams, or events, just use the name. Further explanation is unnecessary.
  • Consider truncating redundant information from item titles and including it in a heading above the list instead. A list entitled “Chapters” should contain a “New York” item, rather than “New York Chapter”.

Numbering

  • Use an ordered list when the rank of items is significant, such as on a leaderboard.
  • Don’t number items to convey chronological order, such as press releases. Use an unordered list.
  • Always use an action link when linking an item. Add redundant links on the title, icon, avatar, and image for the default action.
  • Keep action labels terse. One or two words is ideal.
  • Keep the number of actions to a minimum. One or two links is ideal.

Title Metadata

  • Limit this to dollar amounts, counts, or dates. Due to sharing a line with the title, this functions best when it is very short and a number.

Metadata

  • Add relevant metadata to each list item to support your messaging goals. For example, include dates in a list of press releases or donation amounts in a list of donations.

Item Caption

  • Keep the caption brief. One sentence is ideal.

Code Reference

Class Applies to Outcome

.spirit-list

<ul> or <ol>

Applies list styling to an overall list. <ol> adds item numbers.

.spirit-list-item

<li>

Applies list styling to a list item.

.spirit-list-item--[size]

.spirit-list-item

Use --xl, --l, --m. Default size (xl) is implied and does not need to be specified.

.spirit-list-item__content--links-right

.spirit-list-item__content

Switches layout on content links to align them to the right of the list item.

.spirit-list-item--avatar

.spirit-list-item

Changes list item layout to support an avatar.

.spirit-list-item--image

.spirit-list-item

Changes list item layout to support an image.

.spirit-list-item--image--right

.spirit-list-item--image

Switches the layout on the image to align it to the right of the list item.