@spectrum-web-components/card
Advanced tools
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.
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.
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';
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
When the toggles boolean attribute set to true, the card can be toggled between selected and unselected states.
A checkbox will be rendered on hover, focus within, and when the card is selected.
<sp-card toggles 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-card>
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.
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.
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.
1.8.0 (2025-09-23)
sp-picker: Fixed escape key behavior in modal overlays containing picker components. Previously, pressing the Escape key when a picker was open inside a modal overlay would not properly close the modal, instead moving focus to the picker. Now, the escape key correctly closes the picker first (if open), then closes the modal overlay on subsequent escape key presses.
This fix adds a check for this.open in the picker's handleEscape method to ensure proper modal overlay closure behavior.
sp-overlay: Added allow-outside-click property to <sp-overlay> with deprecation notice. This property allows clicks outside the overlay to close it, but is not recommended for accessibility reasons and will be removed in a future version.
This property is being added as deprecated to support the fallback for showModal() which was removed as part of performance optimization. We will no longer support outside clicks for modal overlays as they violate accessibility guidelines.
The property defaults to false and shows deprecation warnings when used. Consider using explicit close buttons or modal/page overlay types instead for better accessibility.
sp-menu: Fixed : Fix iPad scrolling issue in picker dropdown where scrolling through menu items would accidentally select the first touched item and close the picker.
The fix implements touch gesture detection to distinguish between scrolling and selection. Added isScrolling getter for public API access. Test on iPad devices with long menus to validate scrolling behavior and selection accuracy.
sp-overlay: Fixed : Added body scroll prevention for modal and page overlays. Overlay automatically blocks body scroll when modal or page overlays are open and restores the original scroll state when they are closed, improving user experience and accessibility for modal dialogs.
sp-clear-button: Clear button styles have been updated to the latest Spectrum CSS version of the clear button. This update includes a major reduction in the number of custom property abstractions needed to support the multiple theming layers (as seen in the styles package).
This update spans the following additional packages:
As the updated styles now offer additional styling options, we have added the following API to the clear button component that exists in the button package:
quiet - when set to true, the button will be rendered as a quiet button. This is useful for cases where you want to use the clear button in a more subtle way.disabled - when set to true, the button will be rendered as a disabled button.static-color - currently this only supports the white context color. This is useful for cases where the button appears on a dark background texture. This is a replacement for the previously used variant="overBackground" attribute which is deprecated.The variant="overBackground" attribute is deprecated; please use the new static-color="white" attribute instead. When this property is used in the component, a deprecation warning will be shown in the console when in debug mode. The variant attribute will be removed in a future release.
sp-card: Fixed the card component's CSS by moving block-size: 100% from the base :host selector to only apply to gallery and quiet variants
sp-overlay: Fixed : external click registration behavior in the sp-overlay component. Programmatic clicks on elements outside of modal overlays now properly register and close the overlay, while user-initiated clicks are prevented from doing so.
sp-card: Enhanced the Card component's checkbox functionality with improved screen reader support and keyboard navigation.
sp-progress-bar: Added: Deprecation warning for the over-background attribute.
sp-combobox: Replace the use of offsetWidth with a resizeObserver to avoid unecessary, performance-impacting layout reflows.
sp-styles: Bring the CJK font alias token fix from CSS #3883 4e3a120.
The --spectrum-cjk-font token was incorrectly mapped to the code font-family stack instead of --spectrum-cjk-font-family-stack. Thanks @byteakp!
sp-color-wheel: Fixed <sp-color-wheel> step attribute functionality for keyboard navigation. The step attribute now properly controls the increment size when using arrow keys to navigate the color wheel.
sp-switch: ### Fix down state colors for switch
Because the postcss-hover-media-feature plugin converts hover styles into a media query for devices that support hover, the hover styles were overriding any active/down state styles. We needed to target the active/down states of the switch with additional active state selectors, in order to ensure that the active state takes precedence over the hover state, maintaining the correct visual behavior of the switch component across different interaction states.
This fix should address hover + active state discrepancies in S1 and S2 foundations.
sp-contextual-help: Fixed a typo in the default info variant label from "Informations" to "Information".
Additionally, added package dependency for @spectrum-web-components/reactive-controllers@1.7.0.
sp-slider: Editable sliders will now reliably emit input events when interaction starts with the track.
sp-link: Fixed quiet variant links not showing keyboard focus state in Safari. Links with the quiet attribute now properly display focus indicators when navigating with keyboard, improving accessibility for keyboard users.
sp-progress-bar: Smooths the transition animation of indeterminate progress bar by overriding the incoming CSS, and positioning the animating fill element completely off of the progress bar track in both LTR and RTL languages. Before, the fill element was automatically starting on the track which led to a jarring animation loop.
sp-divider: Added: staticColor property to the Divider component, enabling programmatic control of the existing static color functionality.
FAQs
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.
The npm package @spectrum-web-components/card receives a total of 2,987 weekly downloads. As such, @spectrum-web-components/card popularity was classified as popular.
We found that @spectrum-web-components/card demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 7 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Socket researchers uncover how threat actors weaponize Discord across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.
Security News
Socket now integrates with Bun 1.3’s Security Scanner API to block risky packages at install time and enforce your organization’s policies in local dev and CI.
Research
The Socket Threat Research Team is tracking weekly intrusions into the npm registry that follow a repeatable adversarial playbook used by North Korean state-sponsored actors.