sp-card

NPM 1.0.1

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

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.

Attributes and Properties

Property Attribute Type Default Description asset asset 'file' | 'folder' | undefined Applies imagery representing a `file` or a `folder` download download string | undefined Causes the browser to treat the linked URL as a download. focused focused boolean false heading heading string '' horizontal horizontal boolean false href href string | undefined The URL that the hyperlink points to. label label string | undefined An accessible label that describes the component. It will be applied to aria-label, but not visually rendered. referrerpolicy referrerpolicy | 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url' | undefined How much of the referrer to send when following the link. rel rel string | undefined The relationship of the linked URL as space-separated link types. subheading subheading string '' target target '_blank' | '_parent' | '_self' | '_top' | undefined Where to display the linked URL, as the name for a browsing context (a tab, window, or <iframe>). toggles toggles boolean false value value string '' variant variant 'standard' | 'gallery' | 'quiet' 'standard' Applies alternate styling: `standard` for default styling; `gallery` for a heading, a subheading, an image preview, a description, and a footer; `quiet` a heading, a subheading, a cover photo, a description, and a footer plus optional actions

Slots

Name Description actions an `sp-action-menu` element outlining actions to take on the represented object cover-photo This is the cover photo for Default description A description of the card footer Footer text heading HTML content to be listed as the heading preview This is the preview image for Gallery Cards and Quiet Cards subheading HTML content to be listed as the subheading

Events

Name Type Description change Event Announces a change in the `selected` property of a card click Event

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/card

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/card

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/card

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/card

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/card

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/card

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/card

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/card

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/card

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/card

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/card

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/card

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/card

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/card

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/card

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/card

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/card

0.42.0 (2024-03-19)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/card

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/card

0.41.0 (2024-02-13)

Note: Version bump only for package @spectrum-web-components/card

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/card

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/card

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/card

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/card

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/card

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/card

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/card

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/card

0.39.2 (2023-10-13)

Bug Fixes

  • update deps graph, update link docs (#3709) (2deb284)

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/card

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/card

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/card

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/card

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/card

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/card

0.34.0 (2023-07-11)

Features

  • card: use core tokens (9cccd26)

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/card

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/card

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/card

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/card

0.30.0 (2023-05-03)

Bug Fixes

  • add Grid pattern (341f493)
  • add likeAnchor API to Card element (5c338fb)
  • card: allow for preview or cover-photo (2d2f42b)
  • card: correctly apply :focus-visible styling to variants (d7c7539)
  • card: create no preview image variant of card instead of no imageless variant at all (7b102b9)
  • card: do not transform subheadling text to uppercase (4244390)
  • card: include dependencies (18beaf6)
  • card: normalize sizing technique to align with future t-shirt size usage (6f05b3b)
  • card: removed empty card from documentation/stories (8322894)
  • card: stop event propogation on handleselectedchange (0ef95e5)
  • dialog: normalize sizing technique to align with future t-shirt size usage (da33797)
  • ensure that all paths to user change of selected trigger a change event (2eee81e)
  • include "type" in package.json, generate custom-elements.json (1a8d716)
  • include default export in the "exports" fields (f32407d)
  • include the "types" entry in package.json files (b432f59)
  • match "pointerup" listeners with "pointercancel" for full coverage (7f2ce92)
  • override and clear text-transform: uppercase (dddce4b)
  • remove usage where deprecated (387db3b)
  • remove standard variant from image getter (97e4713)
  • stop merging selectors in a way that alters the cascade (369388f)
  • switch to heading/subheading instead of title (d182a0f)
  • tests weren't fully updated (22bf3b1)
  • these selectors didn't actually change (a5ac275)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • update side effect listings (8160d3a)
  • update to latest spectrum-css packages (a5ca19f)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • add screenshot regression testing to CI (8205dfe)
  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • allow slotted title for card (aaf7157)
  • button: use synthetic button instead of native (49e94bc)
  • card: update spectrum css input (18b6dae)
  • card: upgrade to Spectrum CSS v3.0.0 (84cf1a9)
  • delivery dev mode messages in various packages (62370a1)
  • include all Dev Mode files in side effects (f70817c)
  • leverage "exports" field in package.json (321abd7)
  • sets action-menu quiet to false by default, fixes #3040 (8414cab)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • styles: vend CSS literal versions of the typography system (6406c96)
  • update card and tabs to latest spectrum-css (55b8d67)
  • update lit-* dependencies, wip (377f3c8)
  • use :focus-visable (via polyfill) instead of :focus (11c6fc7)
  • use @adobe/spectrum-css@2.15.1 (3918888)
  • use latest exports specification (a7ecf4b)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)
  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

Reverts

  • Revert "chore: release new versions" (a6d655d)

BREAKING CHANGES

  • renamed title/subtitle attributes and slot.

0.14.2 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/card

0.14.1 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/card

0.14.0 (2023-03-22)

Features

  • sets action-menu quiet to false by default, fixes #3040 (8414cab)

0.13.9 (2023-03-08)

Note: Version bump only for package @spectrum-web-components/card

0.13.8 (2023-02-23)

Note: Version bump only for package @spectrum-web-components/card

0.13.7 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/card

0.13.6 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/card

0.13.5 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/card

0.13.4 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/card

0.13.3 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/card

0.13.2 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/card

0.13.1 (2022-10-28)

Note: Version bump only for package @spectrum-web-components/card

0.13.0 (2022-10-17)

Features

  • update card and tabs to latest spectrum-css (55b8d67)

0.12.3 (2022-10-10)

Bug Fixes

  • match "pointerup" listeners with "pointercancel" for full coverage (7f2ce92)

0.12.2 (2022-09-14)

Note: Version bump only for package @spectrum-web-components/card

0.12.1 (2022-08-24)

Note: Version bump only for package @spectrum-web-components/card

0.12.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.11.0 (2022-08-04)

Features

  • delivery dev mode messages in various packages (62370a1)

0.10.13 (2022-07-18)

Bug Fixes

  • card: stop event propogation on handleselectedchange (0ef95e5)

0.10.12 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/card

0.10.11 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/card

0.10.10 (2022-05-27)

Note: Version bump only for package @spectrum-web-components/card

0.10.9 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/card

0.10.8 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/card

0.10.7 (2022-03-30)

Note: Version bump only for package @spectrum-web-components/card

0.10.6 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/card

0.10.5 (2022-03-04)

Bug Fixes

  • add Grid pattern (341f493)

0.10.4 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/card

0.10.3 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/card

0.10.2 (2022-01-07)

Note: Version bump only for package @spectrum-web-components/card

0.10.1 (2021-12-13)

Note: Version bump only for package @spectrum-web-components/card

0.10.0 (2021-11-08)

Features

  • update lit-* dependencies, wip (377f3c8)

0.9.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/card

0.9.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.8.18 (2021-10-12)

Bug Fixes

  • add likeAnchor API to Card element (5c338fb)

0.8.17 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/card

0.8.16 (2021-09-13)

Note: Version bump only for package @spectrum-web-components/card

0.8.15 (2021-08-24)

Note: Version bump only for package @spectrum-web-components/card

0.8.14 (2021-08-17)

Bug Fixes

  • card: normalize sizing technique to align with future t-shirt size usage (6f05b3b)
  • dialog: normalize sizing technique to align with future t-shirt size usage (da33797)

0.8.13 (2021-08-03)

Note: Version bump only for package @spectrum-web-components/card

0.8.12 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/card

0.8.11 (2021-07-01)

Note: Version bump only for package @spectrum-web-components/card

0.8.10 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/card

0.8.9 (2021-06-07)

Note: Version bump only for package @spectrum-web-components/card

0.8.8 (2021-05-24)

Note: Version bump only for package @spectrum-web-components/card

0.8.7 (2021-05-12)

Note: Version bump only for package @spectrum-web-components/card

0.8.6 (2021-04-15)

Note: Version bump only for package @spectrum-web-components/card

0.8.5 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/card

0.8.4 (2021-03-29)

Note: Version bump only for package @spectrum-web-components/card

0.8.3 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/card

0.8.2 (2021-03-22)

Bug Fixes

  • remove usage where deprecated (387db3b)

0.8.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/card

0.8.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.7.3 (2021-02-11)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

0.7.2 (2021-02-02)

Note: Version bump only for package @spectrum-web-components/card

0.7.1 (2021-01-28)

Bug Fixes

  • card: create no preview image variant of card instead of no imageless variant at all (7b102b9)
  • remove standard variant from image getter (97e4713)
  • card: allow for preview or cover-photo (2d2f42b)
  • card: removed empty card from documentation/stories (8322894)

0.7.0 (2021-01-21)

Bug Fixes

  • ensure that all paths to user change of selected trigger a change event (2eee81e)
  • include the "types" entry in package.json files (b432f59)
  • override and clear text-transform: uppercase (dddce4b)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • card: do not transform subheadling text to uppercase (4244390)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • button: use synthetic button instead of native (49e94bc)
  • card: update spectrum css input (18b6dae)
  • styles: vend CSS literal versions of the typography system (6406c96)

0.6.0 (2021-01-13)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • override and clear text-transform: uppercase (dddce4b)
  • stop merging selectors in a way that alters the cascade (369388f)
  • switch to heading/subheading instead of title (d182a0f)
  • tests weren't fully updated (22bf3b1)
  • these selectors didn't actually change (a5ac275)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • card: do not transform subheadling text to uppercase (4244390)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • button: use synthetic button instead of native (49e94bc)
  • card: update spectrum css input (18b6dae)
  • styles: vend CSS literal versions of the typography system (6406c96)

BREAKING CHANGES

  • renamed title/subtitle attributes and slot.

1.0.0 (2020-11-20)

Bug Fixes

  • switch to heading/subheading instead of title (d182a0f)
  • tests weren't fully updated (22bf3b1)
  • these selectors didn't actually change (a5ac275)

BREAKING CHANGES

  • renamed title/subtitle attributes and slot.

0.5.4 (2020-10-12)

Note: Version bump only for package @spectrum-web-components/card

0.5.3 (2020-10-12)

Bug Fixes

  • card: include dependencies (18beaf6)
  • include default export in the "exports" fields (f32407d)

0.5.2 (2020-09-25)

Bug Fixes

  • update side effect listings (8160d3a)

0.5.1 (2020-09-14)

Note: Version bump only for package @spectrum-web-components/card

0.5.0 (2020-08-31)

Features

  • card: upgrade to Spectrum CSS v3.0.0 (84cf1a9)

0.4.3 (2020-08-19)

Note: Version bump only for package @spectrum-web-components/card

0.4.2 (2020-07-27)

Note: Version bump only for package @spectrum-web-components/card

0.4.1 (2020-07-22)

Note: Version bump only for package @spectrum-web-components/card

0.4.0 (2020-07-17)

Features

  • leverage "exports" field in package.json (321abd7)

0.3.5 (2020-06-08)

Note: Version bump only for package @spectrum-web-components/card

0.3.4 (2020-05-08)

Bug Fixes

  • card: correctly apply :focus-visible styling to variants (d7c7539)

0.3.3 (2020-04-16)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

0.3.2 (2020-04-07)

Note: Version bump only for package @spectrum-web-components/card

0.3.1 (2020-03-11)

Note: Version bump only for package @spectrum-web-components/card

0.3.0 (2020-02-05)

Features

  • allow slotted title for card (aaf7157)

0.2.3 (2020-01-30)

Note: Version bump only for package @spectrum-web-components/card

0.2.2 (2020-01-06)

Note: Version bump only for package @spectrum-web-components/card

0.2.1 (2019-11-27)

Bug Fixes

  • include "type" in package.json, generate custom-elements.json (1a8d716)

0.2.0 (2019-11-19)

Features

  • add screenshot regression testing to CI (8205dfe)
  • use :focus-visable (via polyfill) instead of :focus (11c6fc7)
  • use @adobe/spectrum-css@2.15.1 (3918888)

0.1.4 (2019-10-14)

Performance Improvements

  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

0.1.3 (2019-10-03)

Note: Version bump only for package @spectrum-web-components/card