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

# Adding Zones Using Widgets

> How to add PureClarity zones to your Magento 2.x site using the widget system for flexible content placement

You can add PureClarity zones anywhere on your Magento site using the built-in widget system. The PureClarity extension adds a "PureClarity Zone" widget type that provides flexible zone placement options.

## Zone Widget Configuration Options

### Zone ID

The unique identifier for the zone that must match your campaign configuration in PureClarity admin. If no matching campaigns exist, no content will display.

### Fallback Block ID

Optional static block to display if PureClarity doesn't populate the zone when the page renders.

<Note>
  To find block IDs, navigate to **Content > Blocks** in Magento admin and check the "Identifier" column.
</Note>

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/cms-blocks-identifier.webp" alt="Magento CMS blocks listing showing identifier column" />

### Zone Display Mode

Controls device targeting for the zone:

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/zone-display-mode.webp" alt="PureClarity Widget Zone Display mode options" />

* **Default** - Display on all devices
* **Mobile Only** - Display only on mobile devices
* **Desktop Only** - Display only on desktop devices

<Warning>
  The description for "Desktop Only" in the original article appears to be incorrect (it said "mobile devices"). Desktop Only mode displays content only on desktop devices.
</Warning>

### Apply Margin

When enabled, adds 10px margin above and below the zone content area for better visual spacing.

### CSS Custom Classes

Add custom CSS classes to help the zone integrate with your theme styling.

## Step-by-Step Widget Creation

### Example: Adding a Search Results Zone

Let's walk through adding a zone to the search results page:

#### 1. Navigate to Widget Management

Go to **Content > Widgets** and click **"Add Widget"**.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/add-widget-button.webp" alt="Add Widget button at the top of the Widget list" />

#### 2. Select Widget Type

Choose **"PureClarity Zone"** from the **Type** dropdown.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/widget-type-selection.webp" alt="Widget setup page with type and design theme options" />

#### 3. Select Design Theme

Choose your active theme from the **Design Theme** dropdown.

<Tip>
  The theme must match the one active on the store view where PureClarity is installed.
</Tip>

#### 4. Continue to Configuration

Click **"Continue"** to proceed to the detailed configuration.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/widget-setup-complete.webp" alt="Completed Widget setup page" />

#### 5. Configure Storefront Properties

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/storefront-properties.webp" alt="Storefront Properties overview" />

**Widget Title:** Add a descriptive title for reference (e.g., "PC Zone SR-01" for Search Results Zone)

**Assign to Store Views:** Select the store view where PureClarity is installed

**Sort Order:** Set priority if multiple widgets occupy the same position

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/storefront-properties-filled.webp" alt="Storefront properties filled in as per example" />

#### 6. Configure Layout Updates

Layout updates determine where the widget appears on your site.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/layout-updates-example.webp" alt="Layout updates configuration example" />

For our search results example:

1. Click **"Add Layout Update"**
2. Select **"Specified Page"** from **Display on** dropdown
3. Choose **"Quick Search Form"** from **Page** dropdown
4. Select **"Before Main Columns"** from **Container** dropdown

#### 7. Save the Widget

Click **"Save"** to create your zone widget.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/save-widget-button.webp" alt="Save button at the top of the Widget create page" />

## Cache Management

<Warning>
  After creating zone widgets, you must clear specific Magento caches for the zone to appear on your frontend.
</Warning>

Clear these cache types:

* **Layouts**
* **Blocks HTML output**
* **Page Cache**

Navigate to **System > Cache Management** to clear these caches.

## Widget Placement Options

### Common Container Positions

| Container           | Location            | Use Case                      |
| ------------------- | ------------------- | ----------------------------- |
| Before Main Columns | Above main content  | Hero zones, announcements     |
| After Main Columns  | Below main content  | Related products, cross-sells |
| Sidebar Additional  | Right sidebar       | Recommendations, promotions   |
| Content Top         | Top of content area | Category banners, filters     |

### Page-Specific Placements

| Page Type      | Display On Setting    | Common Zones                     |
| -------------- | --------------------- | -------------------------------- |
| Category Pages | Catalog Category View | Category recommendations         |
| Product Pages  | Catalog Product View  | Related products, cross-sells    |
| Search Results | Quick Search Form     | Search-based recommendations     |
| Homepage       | CMS Home Page         | Featured products, hero content  |
| Cart Page      | Checkout Cart Index   | Upsells, abandoned cart recovery |

## Zone Widget Best Practices

### Naming Conventions

* Use descriptive widget titles with zone IDs
* Include page type in the title (e.g., "PC Zone CAT-01 Category Page")
* Maintain consistent naming across your site

### Performance Considerations

* **Limit widget count** - Too many zones can impact page load times
* **Use fallback blocks** - Provide content when PureClarity is unavailable
* **Test responsiveness** - Verify zones work across all devices

### Content Strategy

* **Match zone purposes** - Align widget placement with campaign goals
* **Consider user flow** - Place zones where they enhance user experience
* **Monitor performance** - Track zone effectiveness in PureClarity analytics

## Testing Your Zone Widget

After creating and caching:

1. **Visit the target page** to confirm the zone appears
2. **Check device responsiveness** if using display mode settings
3. **Verify zone ID matching** in PureClarity admin
4. **Test fallback content** by temporarily disabling campaigns

<Info>
  If your zone doesn't appear, enable [Zone Debug Mode](/integrations/magento/magento-2/zone-debug) to see zone placeholders and troubleshoot placement issues.
</Info>

## Troubleshooting Widget Issues

### Widget Not Appearing

* Clear all relevant caches
* Verify layout update configuration
* Check store view assignment
* Confirm theme selection

### Zone Content Not Loading

* Verify zone ID matches campaign configuration
* Check PureClarity is enabled for the store view
* Review feed status and data synchronization
* Test with debug mode enabled

### Styling Issues

* Add custom CSS classes to the widget
* Check theme compatibility
* Adjust margin settings
* Review container positioning

For comprehensive zone troubleshooting, see [Why Zones Not Showing](/integrations/magento/magento-2/zones-not-showing).

## Related Resources

* [Zone Debug Mode](/integrations/magento/magento-2/zone-debug)
* [Default Zone Installation](/integrations/magento/magento-2/default-zone-installation)
* [Adding Zones Using HTML](/integrations/magento/magento-2/adding-zones-html)