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

# Embeds

> Place cards inside your app's own layout — upgrade prompts, inline tips, getting-started cards and short in-place guides — at the elements you choose.

> [!NOTE]
>
> Looking to put a video, a form or another web page inside a flow step? That is the **Embed**
> content block — see [Embed any content](https://docs.usertour.io/how-to-guides/embed.md). This page is about the **Embeds**
> content type: cards that live in your app's layout.

## What is an embed?

An embed is a card that lives inside your app's page, at an element you choose. It is not a popup
and it does not float over the page: it sits in the layout, next to or inside your own components,
and the page flows around it.

You can use embeds to:

* **Upsell and gate features** — Cover a locked chart or report with an "Upgrade to Pro" card
* **Announce in context** — Put a "what's new" card right in the area the feature lives
* **Fill empty states** — Show a getting-started card where the list is still empty
* **Ask in place** — Run a short inline survey where the answer is on the user's mind
* **Run campaigns** — Promote a webinar or an offer in a dashboard sidebar

Two things set embeds apart from banners. **Several embeds can show at once**: every embed a user
qualifies for renders, each at its own element. And an embed can have **several steps**, paged
inside the same card, so a short guide can live in place without opening a flow.

## Creating an embed

1. Click **Embeds** in the left sidebar

   ![](https://mintcdn.com/usertour/OXEFDjzvD_JS9uEv/images/embeds-01.png?fit=max\&auto=format\&n=OXEFDjzvD_JS9uEv\&q=85\&s=e32aea78ccca72738b113e43145c0bc8)
2. Click **Create embed**
3. Enter a name for your embed and click **Submit**

   ![](https://mintcdn.com/usertour/OXEFDjzvD_JS9uEv/images/embeds-02.png?fit=max\&auto=format\&n=OXEFDjzvD_JS9uEv\&q=85\&s=3908bf3d7fe4ee8bf7b11c6bba095fb8)
4. The editor opens with the preview on the right and the settings panel on the left

   ![](https://mintcdn.com/usertour/OXEFDjzvD_JS9uEv/images/embeds-03.png?fit=max\&auto=format\&n=OXEFDjzvD_JS9uEv\&q=85\&s=96a0b8b987a3cb7f2bde9f87f825e9e7)

The left panel reads top to bottom in the order you usually work: the theme, where the embed
goes, its steps, and then layout and settings you set once.

## Choosing where it shows

Every embed is placed relative to one element of your page: its **target**. Pick the placement
first, then point the embed at the element.

### Placement

* **Top of container element** — Inside the element, as its first child
* **Bottom of container element** — Inside the element, as its last child
* **Immediately before element** — As a sibling, right above the element
* **Immediately after element** — As a sibling, right below the element
* **Cover element** — Over the element, sized to it. The element stays in the page underneath

![](https://mintcdn.com/usertour/OXEFDjzvD_JS9uEv/images/embeds-04.png?fit=max\&auto=format\&n=OXEFDjzvD_JS9uEv\&q=85\&s=b5aaa423c252cd53f85ecef20c4b197c)

The first four placements insert the card into the document flow, so your page makes room for it.
**Cover element** does not take space: the card is laid over the element and follows it when the
page scrolls or resizes. The card is placed inside the element; if the element has no `position` of
its own, the SDK gives it `position: relative` while the cover shows. An element that cannot hold a
child (an image, a canvas, a form field, an iframe) or that scrolls its own content gets the card laid
over it from outside instead, so the card stays over the element rather than scrolling with its
content. Either way, the element's content is not touched.

> [!WARNING]
>
> A cover **places content; it does not gate access**. Your app still renders the element
> underneath and still enforces its own permissions. Use the cover for the message, and keep the
> real check in your product.

### Target element

Click the **Target** row under the placement to open the target settings, and enter a CSS selector
that matches exactly one element. If the element has no stable selector, add an `id` or a `data-*`
attribute to it in your app — see [Selecting elements](https://docs.usertour.io/how-to-guides/selecting-elements.md).

The selector is matched against your page itself, not inside iframes: like a banner, an embed is
inserted into the page, so an element that exists only inside a frame keeps the embed waiting. See
[Iframes](https://docs.usertour.io/how-to-guides/iframes.md).

![](https://mintcdn.com/usertour/OXEFDjzvD_JS9uEv/images/embeds-05.png?fit=max\&auto=format\&n=OXEFDjzvD_JS9uEv\&q=85\&s=1565f55512e9d0068b5a7b35dfe72040)

For a cover, the same view has two more settings:

* **Z-index** — Stacking order of the cover above your page. Leave it empty for the default
* **Content position** (back in the Placement section) — Where the content sits inside the covered
  area: **Top**, **Center** or **Bottom**. The cover is as tall as the element it covers, so the
  content has room to move. Center is the default

![](https://mintcdn.com/usertour/OXEFDjzvD_JS9uEv/images/embeds-06.png?fit=max\&auto=format\&n=OXEFDjzvD_JS9uEv\&q=85\&s=b93f773bffd877b607aec27e62f5c993)

The embed shows only while the target element is on the page and visible. If the element goes away
or is hidden — the user switches a tab, closes a panel, navigates to another view — the embed goes
with it, and comes back when the element does. If your app re-renders the element, the embed moves to
the new one the selector finds. An embed whose target is in the page but hidden does not start, so it
is not counted as a view until the user can see it.

## Adding steps

An embed's content lives in **steps**, the same building blocks a flow uses. Most embeds have one
step. Use more when you want the card to page through something in place: a two-screen "what's
new", a question followed by a thank-you, a short guide.

1. In the **Steps** section, click **Add step** and pick a kind:
   * **Inline** — A step the user sees, rendered inside the card
   * **Hidden** — No UI; a step that only runs triggers, for routing between steps
2. Click a step to edit its content in the preview on the right
3. Type your text directly into the preview. Click the **+** button to add buttons, images, or a
   question — one question per step

![](https://mintcdn.com/usertour/OXEFDjzvD_JS9uEv/images/embeds-07.png?fit=max\&auto=format\&n=OXEFDjzvD_JS9uEv\&q=85\&s=db54d130fee12c090853beb8abbccc89)

### Button actions

When someone clicks a button, you can:

* **Go to step** — Move to another step of this embed, by name
* **Dismiss embed** — Close the card
* **Navigate to page** — Send them somewhere specific
* **Start new flow** — Launch a flow or a checklist
* **Evaluate JavaScript** — Run your own custom code

![](https://mintcdn.com/usertour/OXEFDjzvD_JS9uEv/images/embeds-08.png?fit=max\&auto=format\&n=OXEFDjzvD_JS9uEv\&q=85\&s=56d0b25071dbc447f656fecaadd9b9a9)

Every button click is recorded, so you can see later which button people pressed.

## Layout and settings

* **Max content width** — Caps the width of the content column, in pixels. Leave it empty to fill
  the embed
* **Outer margin** — Space between the embed and the surrounding content, on each side
* **Allow users to dismiss** — Shows a close button in the card's top-right corner. Dismissing ends
  the current session; whether the embed shows again is decided by its frequency, below
* **Animate on appear** — Reveals the card with an animation instead of just popping into place: an
  in-flow embed expands to its height while fading in, a cover fades in over its element. It plays
  once each time the embed appears, not on a step change, and not for users who ask their system for
  reduced motion. Off by default, so the card looks like part of your page

![](https://mintcdn.com/usertour/OXEFDjzvD_JS9uEv/images/embeds-09.png?fit=max\&auto=format\&n=OXEFDjzvD_JS9uEv\&q=85\&s=6010dd0c0807f066f94cb240ad62c181)

Click **Save** when you are done.

## Deciding who sees it

Back on the embed's page, open **Settings** and set the rules under **Show embed if…**. These work
like start rules do elsewhere — see [How start rules work](https://docs.usertour.io/how-to-guides/how-start-rules-work.md) —
with one difference worth knowing:

**The rules are checked continuously, not just once.** The embed is visible while the user matches
them and the target element exists, and it disappears the moment either stops being true. A user
on the free plan sees the upgrade card; the moment the plan changes, the card is gone, with no
dismiss and no reload. If the user qualifies again later, the card comes back on the step it was on.
When you publish a new version, a user's card stays on the step it was on; if that step was removed,
it starts again from the first step.

There are no separate hide rules. "Show if A, hide if B" is simply "show if A and not B".

![](https://mintcdn.com/usertour/OXEFDjzvD_JS9uEv/images/embeds-10.png?fit=max\&auto=format\&n=OXEFDjzvD_JS9uEv\&q=85\&s=cb1f799933c2d1e313b7bb66f46e9478)

### Frequency

The frequency setting decides what happens after the user dismisses the embed:

* **Once per user** — Dismissing is final; the embed never shows again for that user
* **Unlimited times per user** — The embed may come back once the gap you set has passed since the
  dismissal, as long as the rules still match. One day is the default
* **Multiple times per user** — The same gap, plus a cap on the total number of times the embed may
  show for that user

The gap is measured from the moment the previous session ended. A gap of zero means the embed is
back at the next check while the rules match, so the close button has no lasting effect — pick a
gap that fits the message.

## Several embeds at once

Every embed whose rules match shows at the same time, each at its own element. Several embeds can
even share one element: they stack in the order they were delivered. There is no priority between
embeds and nothing to arbitrate — if you want one card instead of two, give them rules that do not
overlap.

## Styling embeds

Embeds take their look from the theme. In the theme editor, the **Embed** section sets the card's
**Background color** and **Text color**; the default background follows the theme's main color, so
the card looks like part of your page rather than a brand-colored banner. **Animation duration** and
**Animation style** set how the card is revealed for embeds with **Animate on appear** turned on.
Padding and borders come from the shared settings of the theme.

![](https://mintcdn.com/usertour/OXEFDjzvD_JS9uEv/images/embeds-11.png?fit=max\&auto=format\&n=OXEFDjzvD_JS9uEv\&q=85\&s=d4f55ac464a8926885fda625197ce42f)

## Measuring embeds

The embed's **Analytics** tab shows:

* **Unique views** — People the embed started showing for in the selected date range. Someone it
  comes back to after being dismissed counts again when it comes back
* **Unique clickers** — People who pressed any button in the selected date range
* **Dismissals** — People whose embed ended in the selected date range: they closed it, or it was
  unpublished or ended for them

Below the headline numbers, a table per step shows how many users reached each step, and a table
per button shows the clicks on each button. An embed is counted once each time it starts showing
for someone; impressions are not counted, since a card that lives in the page is seen on every visit.

![](https://mintcdn.com/usertour/OXEFDjzvD_JS9uEv/images/embeds-12.png?fit=max\&auto=format\&n=OXEFDjzvD_JS9uEv\&q=85\&s=c729eebac28d22a1eda2f053410923fe)

## Requirements

Embeds are delivered by Usertour.js 0.8.6 or later. On
Usertour Cloud that is automatic. On a self-hosted instance, upgrade to the server release that
introduces embeds; the bundle is served by your own instance and upgrades with it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.