Overview
Go Headless

Changelog

Wix Design System (WDS)
Introduction
About Wix Design System
Get started developing
Get started designing
Theming
Wix Design System AI

Guidelines
Themes
Interaction & Behavior
Guidelines
Localization

Patterns
Patterns Overview
Table Pattern
Grid Switch Pattern
Grid Pattern

Foundations
Tokens and Theming basics
Icon Theming

Contributing
AI-Assisted Development
Component Structure
Contributing to Wix Design System
Creating a New Component
Creating a Pull Request
Deprecating a Component
Documenting
Fixing a Bug
Test Drivers
Contributing Tokens
Token Migration Guidelines
Updating Props
Writing Tests

Components
Actions
Animations
Charts
Feedback
Form
Layout
Lists
Accordion Component
CardGalleryItem Component
HorizontalTimeline Component
NestableList Component
SelectableAccordion Component
SelectorList Component
Table
Timeline Component
Mechanisms
Media
Navigation
Overlays
Panels
Typography
In This Article

  1. Overview
  2. Code
  3. Testkit
  4. Changelog

CardGalleryItem

Components/Lists

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/cardgalleryitem

Overview

Copy

Card gallery item is an interactive component that allows users to display media content and actions related to it in a grid layout.

Do

  • Use it to represent a content entity, such a blog post, product or event.
  • Use it to display content that users can interact with.
  • Use it to display content for grid layout.

Don't

  • Don't use it to display static media. Use <Image/> or <Preview/> instead.
  • Don't use it to display content in a custom layout. Use <Card/> instead.

Feature examples

Background

Define a gallery item's background using one of the following:
 - `backgroundImageUrl` - use it to pass a link to the background image source file.
 - `backgroundImageNode` - use it to pass a custom component as a background.

Copy

Image placement

Specify the placement of the background image using one of the following:

- top (default) - Places the background image on top of the footer, as a <MediaOverlay/>.

- side - Places the image in the footer, to the left of the title/subtitle.

Copy

Title

Give more context to a card with following props:
 - `title` - use it for a short and descriptive card title.
 - `subtitle` - use it for a short caption to provide more narrative.

Copy

Badge

Emphasise item status with a `badge`. Use it to promote new items or highlight ones that require attention.

Copy

Actions

Define primary and secondary actions for an item with `primaryActionProps` and `secondaryActionProps`. This component is an interactive element so primary action is mandatory, while the secondary button is optional.

Copy

Draggable

Control if the component is draggable with these properties:

  • draggable: Enables drag behavior and shows an interactive drag handle on the card.
  • dragDisabled: Disables dragging when draggable is enabled, keeping the drag handle visible but non-interactive.
Copy

Settings menu

Allow users to act on a specific item by providing a settingsMenu. Popover menu can contain any required number of actions inside of it.

Copy

Size

Control the size of the card. It supports 2 sizes:

- small. Use this size if the card is stretched to less than 200px.

- medium (default). This size is supposed to be used if the card is stretched to more than or equal 200px in the container.

Note that if imagePlacement="side" is enabled, the size prop will change the size of the image.

Copy

Suffix

Define a component (commonly icon) to be added to the footer. Use showSuffixOnHover to make it appear only when hovering over the card.

Copy

Skin

Control the look of the card border with skin prop.

- standard (default) shows a shadow around the card

- outlined gives a one pixel border around the card

Copy

Skin visibility

Control if the skin should be visible at all times or only on hover with skinVisibility prop.

Copy

Common use case examples

Product list

Use <CardGalleryItem/> to list down visual items, such as dishes, blog posts, products or their collections. These lists are commonly accompanied by an <AddItem/> component at the end of the list which allows users to add a new item to the grid.

Copy

Code

Copy

Props

NameTypeDefaultDescription
aspectRatiostring | number1.6Recommended values: - Square - 1 - Portrait - 3/4 - Cinema - 16/9 - Landscape - 4/3 - Custom number (e.g. 1.5)
backgroundImageNodeReactNode—Accepts any component to be rendered as a background image.
backgroundImageUrlstring—Specifies background image URL.
badgeReactNode—Accepts a or any other static indicator. The passed element is displayed at the top left corner of the card.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
dragDisabledboolean—Show disabled drag handle.
draggableboolean—Show drag handle.
draggingboolean—Indicates the element is dragging.
dragHandlePropsPartial<DragHandleProps>—Extra props to pass to the <DragHandle /> element.
droppableboolean—Removes buttons when other element is dragging and this card is droppable.
footerReactNode—Accepts any component to be rendered under default footer. Only on imagePlacement 'top'.
imagePlacement"top" | "side"'top'Sets placement of background image.
primaryActionProps{ label?: ReactNode; onClick?: MouseEventHandler<HTMLDivElement> | undefined; disabled?: boolean | undefined; disabledMessage?: string | undefined; }—Defines properties for the primary action button.
secondaryActionProps{ label?: ReactNode; onClick?: MouseEventHandler<HTMLButtonElement> | undefined; }—Defines properties for the secondary action button.
settingsMenuReactNode—Defines a popover menu to be displayed on hover at the top right corner or a card.
showSuffixOnHoverbooleanfalseSets suffix behavior to appear only on card hover.
size"small" | "medium"'medium'Set card size.
skin"standard" | "outlined"'standard'Sets skin to the card item.
skinVisibility"hover" | "always"'always'Sets when the skin is visible.
subtitleReactNode—Set card subtitle.
suffixReactNode—Accepts any component to be rendered as a suffix of the card's footer.
tabIndexnumber—Specifies the tab order of the component.
titleReactNode—Set card title.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getTitleGets the cards title.
getBadgeGets the badge node element.
getSubtitleGets the cards subtitle.
getBackgroundImageUrlGets the background image URL.
clickClicks on the primary action.
clickOnContainerClicks on the container.
clickFooterClicks on the footer.
getPrimaryActionLabelGets the primary action label.
isPrimaryActionDisabledChecks whether the primary action is clickable.
clickOnPrimaryActionClicks on the primary action button.
getSecondaryActionLabelGets the secondary action label. l
clickOnSecondaryActionClicks on the secondary action.
getSettingsMenuGets the the settingsMenu node.
getBackgroundImageNodeGets the background image element.
hoverHovers the component.
dragHandleExistsIndicates drag handle exists
clickDragHandle—
hoverDragHandle—
isDragHandleTooltipEnabled—
getDragHandleTooltipContent—
getCustomFooter—
existsChecks whether the component found with the given data hook.
elementGets the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.335.0 (2026-10-12) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.1 (2026-09-28) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.324.0 (2026-09-14) — maintenance release, no component-specific changes
  • 1.323.0 (2026-09-10) — maintenance release, no component-specific changes
  • 1.316.0 (2026-08-25) — maintenance release, no component-specific changes
  • 1.314.0 (2026-08-19) — maintenance release, no component-specific changes
  • 1.312.0 (2026-08-14) — fix: in Harmony (odeditor), a card with a footer now shows its image inset with fully rounded corners, the badge sits inside the image top-left corner instead of hanging off the card edge, the hover overlay is blurred with a new tint, and the title and subtitle typography match MarketingLayout. The footer is tighter (16px on a medium card, 12px on a small one) with a 2px gap between title and subtitle, the hover action button is smaller, side cards use a larger image, the small-card title is bold Madefor Display, the hover buttons are centred as a pair rather than just the primary one, and the standard and outlined skins now match ClickableCard. Two side effects worth knowing about in Harmony: the outlined skin no longer draws a shadow behind its ring, and skinVisibility="hover" now really hides the shadow at rest instead of always showing it. (#16775) — has visual changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.305.1 (2026-07-30) — maintenance release, no component-specific changes
  • 1.299.0 (2026-07-17) — fix: correct title and subtitle font sizes for Harmony theme (#16533) — has visual changes
  • 1.295.0 (2026-07-03) — maintenance release, no component-specific changes
  • 1.294.0 (2026-07-02) — feat: tokenize footer and bottom action paddings (#16452)
  • 1.294.0 (2026-07-02) — feat: no-hover layout for imagePlacement top (touch + mobile flag) (#16437) — has visual changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.273.0 (2026-04-30) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.261.0 (2026-03-24) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.250.0 (2026-01-27) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.220.2 (2025-10-06) — maintenance release, no component-specific changes
  • 1.217.0 (2025-09-08) — maintenance release, no component-specific changes
  • 1.215.0 (2025-08-27) — breaking: tokenize component (#15238)
  • 1.215.0 (2025-08-27) — breaking: remove horizontal divider (#15240)
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.209.0 (2025-07-30) — maintenance release, no component-specific changes
  • 1.204.1 (2025-07-10) — maintenance release, no component-specific changes
  • 1.198.0 (2025-06-09) — maintenance release, no component-specific changes
  • 1.170.0 (2025-03-12) — feat: primaryActionProps now optional | New attribute footer (#14590)
  • 1.169.0 (2025-03-10) — maintenance release, no component-specific changes
  • 1.154.0 (2025-01-17) — maintenance release, no component-specific changes
  • 1.120.0 (2024-08-02) — breaking: make inner container fit the CardGalleryItem outer container (#14010)
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.103.3 (2024-04-30) — maintenance release, no component-specific changes
  • 1.103.1 (2024-04-24) — maintenance release, no component-specific changes
  • 1.103.0 (2024-04-23) — feat: new testkit method clickOnContainer (#13631)
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.100.0 (2024-04-04) — feat: skinVisibility prop (#13565)
  • 1.99.0 (2024-03-29) — feat: add new skin prop (#13523)
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?