> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elasticfunnels.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Product Item Tag

> Display dynamic product listings filtered by type, classification, or specific product codes

The `<product-item>` tag allows you to create dynamic product listings on your pages. It automatically loops through products that match your criteria and displays them using a template you define.

## Overview

The product item tag is perfect for:

* Product catalogs and listings
* Featured products sections
* Related products
* Category pages
* Upsell product displays

Each product matching your filter criteria will be rendered using your template, with product data automatically inserted.

## Basic Usage

### Simple Product Listing

```html theme={null}
<product-item data-type="any">
  <div class="product">
    <h3>{product.name}</h3>
    <p>{product.price}</p>
  </div>
</product-item>
```

### With Filtering

```html theme={null}
<product-item data-type="physical" data-classification="main">
  <div class="product-card">
    <img src="{product.image_url}" alt="{product.name}">
    <h4>{product.name}</h4>
    <p class="price">{product.price}</p>
    <p>{product.description}</p>
  </div>
</product-item>
```

## Attributes

### Required Attributes

#### `data-type`

Filters products by type.

**Values:**

* `"any"` - All product types (default if not specified)
* `"physical"` - Physical products only
* `"digital"` - Digital products only
* `"service"` - Service products only
* Any other product type defined in your system

**Example:**

```html theme={null}
<product-item data-type="physical">
  <!-- Only physical products will be displayed -->
</product-item>
```

### Optional Attributes

#### `data-classification`

Filters products by classification.

**Values:**

* `"any"` - All classifications (default)
* `"main"` - Main products only
* `"upsell"` - Upsell products only
* `"downsell"` - Downsell products only
* `"bump"` - Bump products only
* Any other classification defined in your system

**Example:**

```html theme={null}
<product-item data-type="any" data-classification="upsell">
  <!-- Only upsell products will be displayed -->
</product-item>
```

#### `data-codes`

Filter by specific product codes (comma-separated).

**Format**: Comma-separated list of product codes

**Example:**

```html theme={null}
<product-item data-codes="PROD001,PROD002,PROD003">
  <!-- Only products with these codes will be displayed -->
</product-item>
```

#### `id`

Optional element ID applied to each product wrapper.

**Example:**

```html theme={null}
<product-item data-type="physical" id="product-item">
  <!-- Each product will be wrapped in <div id="product-item"> -->
</product-item>
```

## Product Placeholders

Within the `<product-item>` template, you can use these placeholders to display product information:

### Standard Product Fields

Use `{product.field_name}` to access standard product attributes:

* `{product.name}` - Product name
* `{product.code}` - Product code
* `{product.price}` - Product price
* `{product.description}` - Product description
* `{product.image_url}` - Product image URL
* `{product.type}` - Product type
* `{product.classification}` - Product classification
* `{product.currency}` - Currency code
* `{product.status}` - Product status
* `{product.primary_download_url}` - Primary downloadable file URL

**Example:**

```html theme={null}
<product-item data-type="physical">
  <div class="product">
    <img src="{product.image_url}" alt="{product.name}">
    <h3>{product.name}</h3>
    <p class="code">SKU: {product.code}</p>
    <p class="price">${product.price}</p>
    <p>{product.description}</p>
  </div>
</product-item>
```

### Custom Product Attributes

Use `{product.attributes.attribute_name}` to access custom product attributes.

**Example:**

```html theme={null}
<product-item data-type="physical">
  <div class="product">
    <h3>{product.name}</h3>
    <p>Color: {product.attributes.color}</p>
    <p>Size: {product.attributes.size}</p>
    <p>Material: {product.attributes.material}</p>
  </div>
</product-item>
```

**Note**: Custom attributes must be defined in your product settings. If an attribute doesn't exist, it will be empty.

### Downloadable Files

Digital and bonus downloads are exposed through `{product.product_files}`. Each file can include `purpose`, `title`, `description`, `image`, `file`, `is_primary`, `sort_order`, and `metadata`.

Use these helper shapes when you want filtered access:

* `{product.digital_files}` - Downloadable files with `purpose: "digital"`
* `{product.bonus_files}` - Downloadable files with `purpose: "bonus"`
* `{product.primary_download_url}` - First primary file URL across available product files

## Filtering Examples

### Filter by Type Only

```html theme={null}
<!-- Show only digital products -->
<product-item data-type="digital">
  <div class="digital-product">
    <h3>{product.name}</h3>
    <p>Download: {product.attributes.download_link}</p>
  </div>
</product-item>
```

### Filter by Classification

```html theme={null}
<!-- Show only main products -->
<product-item data-type="any" data-classification="main">
  <div class="main-product">
    <h3>{product.name}</h3>
    <p>{product.price}</p>
  </div>
</product-item>
```

### Filter by Specific Codes

```html theme={null}
<!-- Show only specific products -->
<product-item data-codes="FEATURED001,FEATURED002,FEATURED003">
  <div class="featured-product">
    <span class="badge">Featured</span>
    <h3>{product.name}</h3>
    <p>{product.price}</p>
  </div>
</product-item>
```

### Combined Filters

```html theme={null}
<!-- Physical upsell products -->
<product-item data-type="physical" data-classification="upsell">
  <div class="upsell-product">
    <h3>{product.name}</h3>
    <p>Add to order: {product.price}</p>
  </div>
</product-item>
```

## Complete Example

Here's a complete example of a product catalog page:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Our Products</title>
  <style>
    .product-grid {
      display: grid;
      grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
      gap: 20px;
      padding: 20px;
    }
    .product-card {
      border: 1px solid #ddd;
      border-radius: 8px;
      padding: 15px;
      text-align: center;
    }
    .product-card img {
      width: 100%;
      height: 200px;
      object-fit: cover;
      border-radius: 4px;
    }
    .product-card h3 {
      margin: 10px 0;
    }
    .product-card .price {
      font-size: 1.5em;
      font-weight: bold;
      color: #1d4ed8;
    }
  </style>
</head>
<body>
  <h1>Our Products</h1>
  
  <div class="product-grid">
    <product-item data-type="physical" data-classification="main">
      <div class="product-card">
        <img src="{product.image_url}" alt="{product.name}">
        <h3>{product.name}</h3>
        <p class="price">${product.price}</p>
        <p>{product.description}</p>
        <button>Add to Cart</button>
      </div>
    </product-item>
  </div>
</body>
</html>
```

## How It Works

1. **Tag Detection**: The system finds all `<product-item>` tags in your page
2. **Filter Application**: Products are filtered based on `data-type`, `data-classification`, and `data-codes` attributes
3. **Template Rendering**: For each matching product, the template is rendered
4. **Placeholder Replacement**: Product placeholders (`{product.*}`) are replaced with actual product data
5. **Output**: Each product is wrapped in a `<div>` with the specified `id` (if provided)

## Best Practices

### Performance

* **Limit Results**: Use specific `data-codes` when you only need a few products
* **Filter Early**: Use `data-type` and `data-classification` to reduce the product pool
* **Optimize Images**: Ensure product images are optimized for web

### User Experience

* **Consistent Layout**: Keep product card layouts consistent
* **Clear Pricing**: Always display price clearly
* **Product Images**: Include product images for better visual appeal
* **Call-to-Action**: Include clear CTAs (buy buttons, learn more, etc.)

### Template Design

* **Responsive**: Design templates that work on mobile and desktop
* **Accessible**: Use semantic HTML and proper alt text for images
* **Flexible**: Design templates that work with varying product data

## Troubleshooting

### No Products Displaying

**Possible Causes:**

* No products match your filter criteria
* `data-type` is too restrictive
* Product codes in `data-codes` don't exist
* Products are inactive or unpublished

**Solutions:**

* Check your filter attributes
* Verify products exist in your system
* Try `data-type="any"` to see all products
* Check product status in your dashboard

### Placeholders Not Replacing

**Issue**: Placeholders show as literal text (e.g., `{product.name}`)

**Solutions:**

* Check placeholder spelling (case-sensitive)
* Ensure you're using `{product.*}` format, not `%product.*%`
* Verify the product field exists

### Custom Attributes Empty

**Issue**: `{product.attributes.*}` is empty

**Solutions:**

* Verify the custom attribute is defined in product settings
* Check attribute name spelling (case-sensitive)
* Ensure the attribute has a value for that product

## Related Documentation

* [Collection Item Tag](/pages/collection-item-tag) - Display collection entries
* [Page Variables](/pages/page-variables) - Use variables and placeholders
* [Buy Links](/products/buy-links) - Add purchase links to products