sp-card

NPM 1.4.0

View Storybook

Try it on webcomponents.dev
Overview API Changelog

Overview

An <sp-card> represents a rectangular card that contains a variety of text and image layouts. Cards are typically used to encapsulate units of a data set, such as a gallery of image/caption pairs.

Usage

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/card

Import the side effectful registration of <sp-card> via:

import '@spectrum-web-components/card/sp-card.js';

When looking to leverage the Card base class as a type and/or for extension purposes, do so via:

import { Card } from '@spectrum-web-components/card';

Anatomy

Normal cards can contain a heading, a subheading, a cover photo, and a footer.

<sp-card heading="Card Heading">
    <img alt="" slot="cover-photo" src="https://picsum.photos/250/300" />
    <span slot="subheading">JPG photo</span>
    <div slot="footer">Footer</div>
</sp-card>

Heading

By default, the heading for an <sp-card> is applied via the heading attribute, which is restricted to string content only. For HTML content, use the heading slot instead.

attribute 
<sp-card
    heading="Card Heading"
    subheading="JPG Photo"
    style="--spectrum-card-body-header-height: auto;"
>
    <img alt="" slot="cover-photo" src="https://picsum.photos/250/300" />
    <div slot="footer">Footer</div>
</sp-card>
 slot

Linking

An <sp-card> can be provided with an href attribute in order for it to act as one large anchor element. When leveraging the href attribute, the download, target and rel attributes customize the card's linking behavior. Use them as follows:

<sp-card
    heading="Card Title"
    subheading="JPG"
    href="https://opensource.adobe.com/spectrum-web-components"
    target="_blank"
>
    <img
        slot="cover-photo"
        src="https://picsum.photos/200/300"
        alt="Demo Image"
    />
</sp-card>

Cover Photo

Use slot="cover-photo" on an image to set it as the card's cover photo.

<sp-card heading="Card Heading" subheading="JPG Photo">
    <img
        slot="cover-photo"
        src="https://picsum.photos/200/300"
        alt="Demo Image"
    />
    <div slot="footer">Footer</div>
</sp-card>

Preview Image

Use slot="preview" on an image to set it as the card's preview image.

<sp-card heading="Card Title" subheading="JPG">
    <img slot="preview" src="https://picsum.photos/200/300" alt="Demo Image" />
    <div slot="footer">Footer</div>
</sp-card>

No Preview Image

Cards with no preview image can contain a heading, a subheading, and a footer.

<sp-card heading="Card Title" subheading="No Preview Image">
    <div slot="footer">Footer</div>
</sp-card>

Actions

Cards can be supplied an actions via a names slot.

<sp-card heading="Card Heading" subheading="JPG Photo">
    <img
        slot="cover-photo"
        src="https://picsum.photos/200/300"
        alt="Demo Image"
    />
    <div slot="footer">Footer</div>
    <sp-action-menu
        label="More Actions"
        slot="actions"
        placement="bottom-end"
        quiet
    >
        <sp-menu-item>Deselect</sp-menu-item>
        <sp-menu-item>Select Inverse</sp-menu-item>
        <sp-menu-item>Feather...</sp-menu-item>
        <sp-menu-item>Select and Mask...</sp-menu-item>
        <sp-menu-divider></sp-menu-divider>
        <sp-menu-item>Save Selection</sp-menu-item>
        <sp-menu-item disabled>Make Work Path</sp-menu-item>
    </sp-action-menu>
</sp-card>

Options

Horizontal

Cards with a horizontal attribute can contain a heading, a subheading, a cover photo, and a description.

<sp-card horizontal heading="Card Heading" subheading="JPG Photo">
    <img alt="" slot="cover-photo" src="https://picsum.photos/200/250" />
    <div slot="description">10/15/18</div>
</sp-card>

Variant

There are multiple card variants to choose from in Spectrum. The variant attribute controls the main variant of the card.

Cards with variant="quiet" can contain a heading, a subheading, a cover photo, a description, and a footer. Quiet cards will also accept actions via a named slot.

<sp-card variant="quiet" heading="Card Heading" subheading="JPG Photo">
    <img alt="" slot="preview" src="https://picsum.photos/200/350" />
    <div slot="description">10/15/18</div>
    <sp-action-menu
        label="More Actions"
        slot="actions"
        placement="bottom-end"
        quiet
    >
        <sp-menu-item>Deselect</sp-menu-item>
        <sp-menu-item>Select Inverse</sp-menu-item>
        <sp-menu-item>Feather...</sp-menu-item>
        <sp-menu-item>Select and Mask...</sp-menu-item>
        <sp-menu-divider></sp-menu-divider>
        <sp-menu-item>Save Selection</sp-menu-item>
        <sp-menu-item disabled>Make Work Path</sp-menu-item>
    </sp-action-menu>
</sp-card>

Cards with variant="gallery" can contain a heading, a subheading, an image preview, a description, and a footer.

<sp-card variant="gallery" heading="Card Heading" subheading="JPG Photo">
    <img alt="" slot="preview" src="https://picsum.photos/532/192" />
    <div slot="description">10/15/18</div>
    <div slot="footer">Footer</div>
</sp-card>

Asset

When leveraging the asset attribute, a card can be declared as representing a file or a folder:

<sp-card heading="Card Heading" subheading="JPG Photo" asset="file">
    <div slot="heading">File Name</div>
    <div slot="description">10/15/18</div>
    <div slot="footer">Footer</div>
</sp-card>
<sp-card subheading="JPG Photo" asset="folder">
    <div slot="heading">Folder Name</div>
    <div slot="description">10/15/18</div>
    <div slot="footer">Footer</div>
</sp-card>

Accessibility

Be concise

Heading text should be no more than 5-7 words. If the card has an href, the heading is used as a link and should ideally be no more than 3 words. For buttons, 1-2 words.

Use descriptive heading, link, and button text

Be descriptive. Set expectations on what someone will find and where they will go once they interact with a card. Avoid using the same text on more than one interactive element, unless both elements go to the same place.

Make the first word in a heading meaningful

Consider making the first word of links, buttons and headings something an assistive technology user might search for when headings and links are listed alphabetically.