sp-card
NPM 1.4.0
View Storybook
Try it on webcomponents.dev
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
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.
<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>
<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.
Changelog
Patch Changes
- Updated dependencies [
]:3cca7ea
- @spectrum-web-components/styles@1.4.0
- @spectrum-web-components/asset@1.4.0
- @spectrum-web-components/checkbox@1.4.0
- @spectrum-web-components/divider@1.4.0
- @spectrum-web-components/icons-workflow@1.4.0
- @spectrum-web-components/base@1.4.0
- @spectrum-web-components/shared@1.4.0
1.3.0
Patch Changes
- Updated dependencies [
]:468314f
- @spectrum-web-components/checkbox@1.3.0
- @spectrum-web-components/asset@1.3.0
- @spectrum-web-components/divider@1.3.0
- @spectrum-web-components/icons-workflow@1.3.0
- @spectrum-web-components/base@1.3.0
- @spectrum-web-components/shared@1.3.0
- @spectrum-web-components/styles@1.3.0
All notable changes to this project will be documented in this file. See
1.2.0 (2025-02-27)
Note: Version bump only for package @spectrum-web-components/card
1.1.2 (2025-02-12)
Note: Version bump only for package @spectrum-web-components/card
1.1.1 (2025-01-29)
Note: Version bump only for package @spectrum-web-components/card
1.1.0 (2025-01-29)
Bug Fixes
- lock prerelease versions for Spectrum CSS (
#5014 ) (8aa7734 )
1.0.3 (2024-12-09)
Note: Version bump only for package @spectrum-web-components/card
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
API
Attributes and Properties
asset
asset
'file' | 'folder' | undefined
download
download
string | undefined
focused
focused
boolean
false
heading
heading
string
''
horizontal
horizontal
boolean
false
href
href
string | undefined
label
label
string | undefined
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
rel
rel
string | undefined
subheading
subheading
string
''
target
target
'_blank' | '_parent' | '_self' | '_top' | undefined
toggles
toggles
boolean
false
value
value
string
''
variant
variant
'standard' | 'gallery' | 'quiet'
'standard'
Slots
actions
cover-photo
description
footer
heading
preview
subheading
Events
change
Event
Announces a change in the `selected` property of a card
click
Event