# Product cards ![](https://docs-assets.foxecom.app/pebble-theme/05f60a78-f879-4a55-a8b7-01cf6d7a6620.png) Product cards display product information throughout your store, such as in collection grids, featured collections, recommendations, and other product lists. Use the **Product cards** settings to control product images, content, badges, swatches, and interactive actions. ## How to edit Product cards 1. In the theme editor (**Edit theme**), go to **Theme settings**. 2. Open **Product cards**. 3. Adjust the settings as needed. 4. Click **Save**. ## Settings ### Media These options control how product images are displayed within the card. | Setting | Description | Options | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Aspect ratio** | Controls the shape of the product image area. | **Auto:** Keeps the original image proportions.

**Square (1/1)**, **Portrait (4/5)**, **Portrait (3/4)**, **Landscape (16/9)**, **Landscape (4/3):** Crops images to the selected ratio for a more consistent grid. | | **Corner radius** | Controls how rounded the product image corners appear. | Increase the value for more rounded corners or decrease it for a sharper look. | | **Show second image on hover** | Shows the product's second image when a customer hovers over the product card on desktop.
![image](https://docs-assets.foxecom.app/pebble-theme/productcards_6UzB0Gqv.gif) | **On:** Shows the second image on hover.

**Off:** Keeps the main image displayed. |
### Content These options control the layout and product information displayed within the card. | Setting | Description | Options | | ----------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **Style** | Controls the visual presentation of the product card. | **Standard:** Displays the product directly on the section background.

**Card:** Displays the product within a styled card. | | **Card color scheme** | Sets the color scheme used for the card background and content. | Select a theme color scheme.

*Available when **Style** is set to **Card**.* | | **Alignment** | Controls the alignment of the product title, price, and other product information. | **Left**, **Center**, or **Right** | | **Show product vendor** | Displays the product vendor or brand above the product title. | **On** or **Off** | | **Show product type** | Displays the product type, such as Shirts or Backpacks. | **On** or **Off** |
### Badges Customize how product badges such as **New**, **Hot**, **On Sale**, or **Sold Out** appear. | Setting | Description | Options | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Layout** | Controls how multiple badges are arranged on the product image. | **Vertical**: Stacks badges.

**Horizontal**: Displays badges side by side. | | **Show custom badges** | Displays custom badges assigned to products.

*Learn how to add custom badges:* [*Product badges*](https://docs.foxecom.com/pebble-theme/theme-settings/product-badges) | **On** or **Off** | | **Show sold out badge** | Displays a Sold Out badge when a product is out of stock. | **On** or **Off** | | **Show sale badge** | Displays a sale badge when a product has a discounted price. | **On** or **Off** | | **Sale badge type** | Appears when **Show sale badge** is enabled. Controls how the discount is shown. | **Text**: Displays a label such as "On Sale".

**Percentage**: Displays the percentage saved like "Save 20%".

**Fixed amount**: Displays the amount saved like "Save $10.00". |
**Note:** To change badge colors, go to **Theme settings > Colors**. ### Swatches Swatches represent product variant colors or patterns in a visual way, allowing customers to see available options directly from the product card. | Setting | Description | Options | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Show swatches** | Displays color or pattern swatches below the product information.

*Learn how to* [*setting up Swatches via Shopify Category Metafields*](#setting-up-swatches)*.*![image](https://docs-assets.foxecom.app/pebble-theme/image_uXfGKZzh.png) | **On:** Displays swatches and makes the related swatch settings available.

**Off:** Hides swatches and the related settings. | | **Show variant images** | Uses the image assigned to each variant as the swatch instead of a color or pattern swatch.
![image](https://docs-assets.foxecom.app/pebble-theme/image_e4DAQTp4.png) | **On:** Uses each variant's assigned image as its swatch.

**Off:** Uses the swatch color or pattern defined by the product's category metafield. | | **Swatch shape** | Controls the shape of each swatch. | **Circle** or **Square (1/1)** | | **Swatch width** | Controls the size of each swatch. | **20–100px** | | **Maximum items to show** | Controls how many swatches appear before the remaining options are collapsed into a `+X` indicator.
![image](https://docs-assets.foxecom.app/pebble-theme/image_htaqqXT7.png) | **1–6 items** |
**Fallback behavior:** When **Show variant images** is enabled but a variant doesn't have an assigned image, the theme first uses the **swatch image** defined in its category metafield, if available. If there is no swatch image, it uses the metafield's **color value** (HEX/RGB) instead.
![image](https://docs-assets.foxecom.app/pebble-theme/image_BlJZYg7L.png)![image](https://docs-assets.foxecom.app/pebble-theme/image_dl7il2D8.png)
### Actions These settings control the shopping actions customers can use directly from product cards. | Setting | Description | Options | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Show quick add** | Adds a quick purchase action directly to the product card. The action changes depending on the product's variants. | **On:** Single-variant products show **Add to cart** and are added immediately. Products with multiple variants show **Choose options**, which opens Quick view so customers can select a variant.

**Off:** Hides Quick add. | | **Show quick add on mobile** | Controls whether quick add is available on mobile devices. | **On** or **Off** | | **Quick add style** | Controls how the Quick add button appears on desktop. | **Text only** or **With icon** | | **Quick add icon** | Selects the icon displayed when **Quick add style** is set to **With icon**. | **Plus** or **Cart** | | **Quick add color scheme** | Controls the colors used by the Quick add button. | Select a theme color scheme. The selected scheme controls properties such as the **background**, **text**, **border**, and **hover state** colors. | | **Show quick view** | Lets customers preview product details without leaving the current page. | **On:** Displays the Quick view icon and opens the product preview when selected.

**Off:** Hides Quick view. | | **Show quick view on mobile** | Controls whether Quick view is available on mobile devices. | **On** or **Off** |
**Notes:** * Quick add isn't displayed for **sold-out products**. * **Quick add style** and **Quick add icon** apply to desktop only. * Quick add colors are managed in **Theme settings > Colors**. * Quick view content can be customized in the **Quick add drawer** settings. ## Setting up swatches The settings under **Product cards > Swatches** control how swatches appear on product cards. The actual swatch colors, patterns, and images are set up through Shopify's **Category Metafields**. 1. In Shopify Admin, go to **Products**. 2. Open the product you want to edit. 3. In the **Category** section, select an appropriate category from Shopify's Standard Product Taxonomy, such as *Apparel & Accessories > Clothing > Tops > Shirts*. 4. Click **Save**. Choose a category that supports the product attribute you want to use for swatches, such as **Color**. Assigning the appropriate category makes its supported category metafields available for the product. ![image](https://docs-assets.foxecom.app/pebble-theme/image_vWu9OqGT.png) In the product, locate the **Category metafields** section and open the metafield you want to use, such as **Color**. To edit an existing entry: 1. Open the category metafield. 2. Select the entry you want to edit. 3. Make your changes. 4. Click **Save**. ![image](https://docs-assets.foxecom.app/pebble-theme/image_59nXVCTN.png) To create a new entry: 1. Open the category metafield. 2. Click **Add new entry**. 3. Fill in the available fields, such as the label, color value, or image. 4. Click **Save**. 5. Save the product again. ![image](https://docs-assets.foxecom.app/pebble-theme/image_DPdFl7MN.png) A swatch entry can include: | Field | Description | | ---------------- | -------------------------------------------------------------------------------- | | **Label** | The customer-friendly name of the swatch, such as Navy/Blue. | | **Color value** | A HEX or RGB value used to display a solid-color swatch. | | **Image** | An optional image used for patterns, textures, prints, or other visual swatches. | | **Base color** | The main color family associated with the swatch. | | **Base pattern** | Defines the general pattern type, such as Solid or Striped. | | **References** | Shows products currently using the swatch entry. | | **Handle** | The automatically generated internal reference for the entry. |
![image](https://docs-assets.foxecom.app/pebble-theme/image_djVUhMny.png) **Note:** If both an **Image** and a **Color value** are set, the image takes priority. The color value is used when no image is available.
1. Return to the product in Shopify Admin. 2. In the **Variants** section, click **Add options like size or color**, or edit an existing option. 3. Select the relevant category metafield, such as **Color**. Shopify automatically fills the option values with entries from that metafield.![image](https://docs-assets.foxecom.app/pebble-theme/image_EufYhuNU.png) 4. If you need a value that doesn't exist yet, select the custom option value, click **Add new entry**, complete the entry, and save it.![image](https://docs-assets.foxecom.app/pebble-theme/image_cZIntjRG.png)![image](https://docs-assets.foxecom.app/pebble-theme/image_G5ap1xBk.png) 5. Click **Save** on the product. **Tip:** If the product already has variant options, you can connect those options to the appropriate category metafield instead of recreating them.
![image](https://docs-assets.foxecom.app/pebble-theme/image_AdHGUgEE.png)![image](https://docs-assets.foxecom.app/pebble-theme/image_jctwazdt.png)
Using category metafields ensures: * Centralized, reusable swatch definitions * Consistent labels and colors across products * Easier filtering and swatch display in your theme *Learn more about setting up swatches with category metafields in* [*Shopify Help: Using category metafields*](https://help.shopify.com/en/manual/custom-data/metafields/category-metafields/using-category-metafields)*.* ## Tips and best practices * Use a fixed **Aspect ratio** when product images have different proportions to keep product grids consistent. **Auto** may result in uneven card heights. * Turn on **Show second image on hover** when the second image adds useful context, such as another angle, product detail, or lifestyle view. * Show the **product vendor** or **product type** only when it helps customers identify or compare products. * Keep badges focused on useful information. Too many badges can make product cards feel crowded. * Use **Percentage** or **Fixed amount** sale badges when highlighting the actual savings is more useful than a simple sale label. * Limit the number of visible swatches to keep card heights consistent, especially for products with many variants. * Use **Show variant images** when seeing the actual product appearance is more helpful than a color swatch, such as for prints, patterns, or finishes. * Use **Quick add** for products that are easy to purchase without reviewing many options. Products with multiple variants may require customers to select an option first.