---
title: Embedded widgets and placeholders
slug: embedded-widgets
description: How to embed Personizely widgets in your pages: embed code, placeholders with CSS selectors, Shopify app blocks, WordPress shortcodes, timing and limitations.
image: https://archbee-image-uploads.s3.amazonaws.com/1y1Fr-DMGy_apx7FwibyA/ORDTWfNKMXiY3ZRv0QSgP_personizely-docs-og.png
docTags: 
createdAt: 2026-10-17T09:42:10.887Z
---

An embedded widget appears inside your page content instead of floating over it: an inline sign-up form at the end of a blog post, a banner on product pages, a product recommendation block in the cart. You decide where it goes with an embed code, a reusable **placeholder**, a Shopify app block or a WordPress shortcode. Embedded widgets use the same elements, rules, automations and A/B testing as other widgets.

**Available on:** all platforms. Shopify app blocks need an Online Store 2.0 theme; shortcodes need the Personizely WordPress plugin.

## How it works

1. **You mark a spot on your page**, either with the widget's embed code or with a placeholder (see below).
2. **The widget needs a trigger**, like any other widget. **Landing** shows it as soon as the page is ready; a Scroll or Time trigger reveals it later.
3. **When the trigger fires**, Personizely looks for the spot. If it isn't on the page yet, for example because your theme renders it later, Personizely waits up to 5 seconds for it to appear.
4. **The widget replaces the spot's content.** Anything inside the target element is removed and the widget is inserted in its place, taking the width of that element.
5. If the spot doesn't appear in that time, the widget isn't shown on that page view and no view is recorded.

## Choosing where a widget appears

In the builder, open the widget's **Settings** tab and choose **Placement**:

| Placement                     | What you add to your site                                                                     | Best for                                                                              |
| ----------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Embeddable code** (default) | `<div data-ply-embedded-widget="WIDGET_ID"></div>`, shown in the **Code** box under Placement | One widget in one spot                                                                |
| A placeholder                 | The placeholder's code, or nothing if the placeholder has a CSS selector                      | A spot you'll reuse for different widgets over time, or a spot you can't edit by hand |

### Embed code

Copy the code from the **Code** box and paste it into your theme, page builder or CMS where the widget should appear. The number is the widget's ID.

```html
<div data-ply-embedded-widget="5521"></div>
```

### Placeholders

A placeholder is a named spot on your site that any embedded widget can use. You add it to your theme once, then choose it in a widget's **Placement** setting. Swapping the widget later doesn't require touching the theme again.

1. Go to **Settings → Placeholders** and click **Add placeholder**.
2. Enter a **Name**, such as "Blog footer".
3. Either leave **CSS selector (optional)** empty and add the placeholder's code to your site:

   ```html
   <div data-ply-placeholder="42"></div>
   ```

   or enter a **CSS selector**, such as `.product-detail .description`, to use an element that's already on your pages. No code change is needed.
4. In the widget's **Settings** tab, choose the placeholder under **Placement**.

When a placeholder has a CSS selector, the widget goes into the **first** element on the page that matches it, and the `data-ply-placeholder` markup isn't used.

:::hint{type="warning"}
The widget replaces the content of the element it goes into. With a CSS selector, pick an empty wrapper or an element you're happy to replace, not an element with content you need, such as the product description itself.
:::

### Shopify app blocks

With the Personizely app installed, two blocks are available in the Shopify theme editor (**Online Store → Themes → Customize**), under **Apps** when you add a block to a section:

| Block               | Setting            | What it inserts          |
| ------------------- | ------------------ | ------------------------ |
| **Embedded widget** | **Widget ID**      | That widget's embed code |
| **Placeholder**     | **Placeholder ID** | A placeholder's code     |

Add the block where the widget should appear, enter the ID and save the theme.

### WordPress shortcodes

The [Personizely WordPress plugin](https://docs.personizely.net/install-wordpress) adds two shortcodes you can use in posts, pages and widget areas:

```text
[ply-widget 5521]
[ply-placeholder 42]
```

`[ply-widget ID]` inserts a widget's embed code. `[ply-placeholder ID]` inserts a placeholder.

## Configuration

| Option                             | What it does                                   | Values / default                                                            |
| ---------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
| Placement                          | Where the widget is inserted                   | Embeddable code, or one of your placeholders                                |
| Width / Height                     | Widget size inside its container               | Auto: fills the container's width, height fits the content                  |
| Overflow                           | What happens to content larger than the widget | Default hidden                                                              |
| Margin                             | Space around the widget                        | 0–100 px                                                                    |
| Background, border, radius, shadow | Widget surface                                 | From your [branding](https://docs.personizely.net/branding), without shadow |

## Behavior details and limitations

- **No close button, Esc, teaser, backdrop or animation.** An embedded widget stays until the visitor navigates away or an action closes it (a button set to **Close widget**, or a [close trigger](https://docs.personizely.net/close-triggers)).
- **One spot per widget.** If the code or selector matches several elements, only the first one gets the widget.
- **One widget per spot.** If two widgets that target the same spot show on the same page, the second replaces the first, and both record a view. Use rules so only one of them can show on a given page, or test them as [variations](https://docs.personizely.net/widget-experiments-and-ab-testing) of one widget.
- **Control groups keep the original content.** In a widget A/B test, visitors in the control group see the spot's existing content, as if the widget weren't there.
- **The widget appears after the page is ready**, so content below it can move down when it's inserted. To avoid layout shift, give the spot a fixed `min-height` in your theme.
- **Changing steps scrolls the widget into view** if the new step would otherwise be off-screen.
- **Embedded widgets inherit more of your site's CSS** than floating widgets, because they sit inside your content. Override unwanted styles in the widget's custom CSS.
- **Single-page apps:** if your storefront changes pages without a reload, the spot must appear on the new page within 5 seconds of the page change.

## Examples

- **Inline blog sign-up:** a placeholder with the selector `article .post-content` won't work because it would replace the post. Instead, add `<div data-ply-placeholder="42"></div>` after the post content in your blog template, and show a list-building widget there with a Landing trigger.
- **Product page trust banner (Shopify):** add the **Placeholder** app block under the add-to-cart button. Run an embedded widget there on product pages with a free-returns message, and A/B test the copy.
- **Cart cross-sell:** an embedded widget with a [products](https://docs.personizely.net/product) element in a placeholder on `/cart`, showing products based on cart items.

## Troubleshooting

- **The widget never appears** → the spot isn't on the page within 5 seconds of the trigger, or the widget ID or placeholder ID in the code is wrong. Check the page source for the `data-ply-embedded-widget` or `data-ply-placeholder` element, or test the selector with `document.querySelector('<selector>')` in the console.
- **The widget appears in the wrong place** → the CSS selector matches an earlier element on the page. Make it more specific.
- **Part of my page disappeared** → the selector points to an element with content. The widget replaces it; use an empty wrapper.
- **The widget shows on some pages only** → check its **Pages** rule and that your theme renders the spot on those pages.

## Related

- [Widget types](https://docs.personizely.net/widget-types)
- [Install on Shopify](https://docs.personizely.net/install-shopify)
- [Install on WordPress](https://docs.personizely.net/install-wordpress)
- [Triggers](https://docs.personizely.net/triggers)
- [How widgets load and display](https://docs.personizely.net/widgets-how-they-work)