Components/Lists
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/cardgalleryitem
Card gallery item is an interactive component that allows users to display media content and actions related to it in a grid layout.
<Image/> or <Preview/> instead.<Card/> instead.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.
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.
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.
Emphasise item status with a `badge`. Use it to promote new items or highlight ones that require attention.
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.
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.Allow users to act on a specific item by providing a settingsMenu. Popover menu can contain any required number of actions inside of it.
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.
Define a component (commonly icon) to be added to the footer. Use showSuffixOnHover to make it appear only when hovering over the card.
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
Control if the skin should be visible at all times or only on hover with skinVisibility prop.
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.
| Name | Type | Default | Description |
|---|---|---|---|
aspectRatio | string | number | 1.6 | Recommended values: - Square - 1 - Portrait - 3/4 - Cinema - 16/9 - Landscape - 4/3 - Custom number (e.g. 1.5) |
backgroundImageNode | ReactNode | — | Accepts any component to be rendered as a background image. |
backgroundImageUrl | string | — | Specifies background image URL. |
badge | ReactNode | — | Accepts a |
dataHook | string | — | Applies a data-hook HTML attribute that can be used in the tests. |
dragDisabled | boolean | — | Show disabled drag handle. |
draggable | boolean | — | Show drag handle. |
dragging | boolean | — | Indicates the element is dragging. |
dragHandleProps | Partial<DragHandleProps> | — | Extra props to pass to the <DragHandle /> element. |
droppable | boolean | — | Removes buttons when other element is dragging and this card is droppable. |
footer | ReactNode | — | 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. |
settingsMenu | ReactNode | — | Defines a popover menu to be displayed on hover at the top right corner or a card. |
showSuffixOnHover | boolean | false | Sets 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. |
subtitle | ReactNode | — | Set card subtitle. |
suffix | ReactNode | — | Accepts any component to be rendered as a suffix of the card's footer. |
tabIndex | number | — | Specifies the tab order of the component. |
title | ReactNode | — | Set card title. |
Import the driver matching your test environment:
| Method | Description |
|---|---|
getTitle | Gets the cards title. |
getBadge | Gets the badge node element. |
getSubtitle | Gets the cards subtitle. |
getBackgroundImageUrl | Gets the background image URL. |
click | Clicks on the primary action. |
clickOnContainer | Clicks on the container. |
clickFooter | Clicks on the footer. |
getPrimaryActionLabel | Gets the primary action label. |
isPrimaryActionDisabled | Checks whether the primary action is clickable. |
clickOnPrimaryAction | Clicks on the primary action button. |
getSecondaryActionLabel | Gets the secondary action label. l |
clickOnSecondaryAction | Clicks on the secondary action. |
getSettingsMenu | Gets the the settingsMenu node. |
getBackgroundImageNode | Gets the background image element. |
hover | Hovers the component. |
dragHandleExists | Indicates drag handle exists |
clickDragHandle | — |
hoverDragHandle | — |
isDragHandleTooltipEnabled | — |
getDragHandleTooltipContent | — |
getCustomFooter | — |
exists | Checks whether the component found with the given data hook. |
element | Gets the component root element. |
base | Returns UniDriver for the base element. |
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 changesLast updated: 22 October 2026