**Marketing -> Popups** in your admin dashboard.

A popup is a message you show your traders inside the platform: a promotion, an
announcement, a code to hand out, a short form. It can also be an announcement
bar: one line of text above the header of the trader app, standing still or
scrolling past. This screen is where you make it, see where it stands, and read
what it did. When a trader sees it is decided
by a rule under **Marketing -> Popup rules**, never by the popup itself.

Nothing shows during the onboarding, whatever a rule targets, so a trader giving
their details is never interrupted. A popup a rule shows once ever waits until
the onboarding is done. The pricing page that may follow it does show popups,
where a code to hand out belongs.

You need `view_popups` to open the screen, see the figures and read and export
the submissions, and `manage_popups` to make, change, switch on, pause, archive,
duplicate or delete a popup, and to delete a submission. Somebody with only the
first sees everything, with the fields switched off and a line saying why. The
Activity tab also needs `view_activity_logs`, a trader's name only leads to
their page for whoever has `view_traders`, and the link to make a discount code
shows for whoever has `view_coupons`.

## The list

The screen opens on the list alone, across its whole width, and shows no popup
in full until you pick one.

Each row is a popup with its name, which editor builds it, where it lands on the
screen, whether it has a form and which code it hands out. A bar says
Announcement bar in place of the editor and the placement, since it always
stands above the header. Then where it stands,
how many rules name it and how many of those are live, how often it was seen,
how often its button was clicked as a share of those views, how many
submissions its form collected, and when it last changed. As the list gets
narrower the less important columns leave first.

Where a popup stands is one of five things:

| State         | What it means                                          |
| ------------- | ------------------------------------------------------ |
| Showing       | Active, and a running rule names it. Traders see it    |
| Shown nowhere | Active, but no running rule names it. Nobody sees it   |
| Draft         | Yours to work on. No rule can show it                  |
| Paused        | Held back, keeping the design and its rules            |
| Archived      | Out of use, kept for the record                        |

Shown nowhere is the state that looks finished and is not, so it reads in full
ink in the list.

The line under the name counts your popups, how many are showing and how many
are shown nowhere, and how many rules you have. Showing and shown nowhere are
filters: click one to see only those. The count of rules opens Popup rules.

Search finds a popup by its name, its id or the code it hands out. The filter
menu sorts the list (newest, name, last changed, most viewed, most clicked, most
conversions or most submissions) and narrows it by where it stands (Active is
showing and shown nowhere together), by editor (visual, HTML or announcement
bar), by placement, by whether it has a form and by whether it hands out a code.
Search, filters, sort and page live in the address, so a link shows the same
list.

`J` and `K` move through the list and Enter opens the lit popup. Right click a
row for everything you can do without opening it: see its analytics or its
submissions, switch it on, pause it, archive it or take it back to a draft,
duplicate it, copy its name, id or link, and delete it.

## A popup

A popup opens beside the list, which folds into a column, and has its own
address, so a link from the command palette, from a rule or one you copy and
send opens on it, with the open tab part of the address. The cross or Escape
folds the list back to the same filters and page.

The head shows the name, which editor builds it, where it lands, whether it has
a form, the code it hands out and its id (click it to copy). Under that, where it
stands, how many rules name it, and when a trader last saw it. Then the figures
over its whole life: views and by how many traders, clicks and conversions each
as a share of the views, submissions, and when it last changed and by whom.

The button in the head is what you most likely want next: **Switch on** for a
draft or a paused popup, **New rule** for one that is on but shown nowhere,
**Pause** for one that is showing, and **Back to draft** for an archived one. The
more menu holds the rest. **New rule**, from the head, the more menu or the Rules tab,
opens a new rule that already names this popup. The rules count in the head and
**See rules** in a row's right click menu open the Rules tab.

The tabs are **Design**, **Settings**, **Rules**, **Analytics**, **Submissions**
and **Activity**. Design and Settings are two halves of one form with one save dock
under both, so you can change the design, set the placement, and save once.
Moving between the two never loses what you typed. Leaving them for another tab
or another popup with unsaved changes asks first. A save sends only what you
changed, so a popup a colleague paused from the list while you had it open stays
paused.

A save that fails marks the tab holding the refused field with a dot and opens
it at that field.

### Design

**Visual** gives you a canvas. Add text, boxes, lines, images, buttons and input
fields from the toolbar, drag them where you want them, and set colours, fonts
and sizes in the panel beside it. Delete removes what is picked, Cmd or Ctrl+D
duplicates it, and Escape lets go of it before it closes anything else. The
canvas is a fixed size that scales down to fit smaller screens, so what you lay
out is what a trader sees.

**Code** gives you an HTML and a CSS box, with the preview beside them. Use it
when the design is beyond what the canvas does. Scripts, iframes and embedded
content are stripped before anything is stored: a popup renders live in your
traders' browsers, so it cannot carry active content.

Text can contain tokens like `{{trader_name}}` and `{{coupon_code}}`, filled per
trader when the popup is shown. The code editor lists the ones available.

#### Converting a visual design to HTML

A visual popup has a **Convert to HTML** button above the canvas. It compiles the
canvas into HTML and CSS you can then edit by hand, keeping your tokens and your
brand colour, and sets the popup's width to the width the canvas was so nothing
gets cropped. The conversion lands in the form and is stored with your next
save.

:::warning This only goes one way
Free HTML cannot be mapped back onto a canvas, so the popup stays in code from
that point on. Convert when you have taken the canvas as far as it goes, not to
have a look.
:::

If the design had inputs on it, the canvas stops being what defines the form.
The fields move into Form on the Settings tab, and the converted markup binds to
those keys. Icons on the canvas have no HTML form yet, so the conversion leaves
them out and says so.

### An announcement bar

A bar has no canvas and no HTML. Its Design tab is a short form with the
preview beside it, which draws the bar above your own trader screen in light or
dark and on a desktop or a phone:

- **Message**: one or two sentences, at most 280 characters, with the same
  tokens as a popup.
- **Icon**: one of sixteen line icons before the message, in the colour of the
  text, or none.
- **Movement**: still, or scrolling past at a slow, normal or fast pace.
- **Look**: your colour, neutral greys that follow light and dark mode, near
  black in both modes, or a background and text colour of your own. Your colour
  follows the design and the mode the trader is in, with text that reads on it.
  On the greys and on near black the button takes your colour.
- **Button**: none, a link, or **Copy code** for the code attached under
  Settings. A link to an address in your app, starting with `/`, opens in the
  same tab, any other in a new one.

On the trader's side the bar stands above the header in every design (Default,
Propper - OG and Tactical), across the whole width, and moves the page down by
its height: 36 pixels for one line. It slides in the first time it shows in a
visit and then stays put while the trader clicks through the app. It steps
aside while a page is in fullscreen, and never shows on your own admin pages.

A scrolling message stops while the pointer is on the bar or something in it
has focus, has a pause button, is read once to a screen reader, and stands
still for a trader whose system asks for less motion.

### Settings

**Details** is the name your team knows it by and its status. **Display** is
where it lands (center, top, bottom, or a card in the corner), its width for a
popup in code, whether traders can close it, and whether the page behind it
dims. A bar always stands above the header and dims nothing, so Display only
asks whether it can be closed. A trader who closes a bar does not see it again
for the rest of the session, or for longer when its rule shows it once ever or
once every few days. **Code** attaches the discount code a button can copy and
`{{coupon_code}}` shows. **Form** is what happens around the fields: the label
of the submit button, who is mailed each entry and under which subject, and what
the trader reads afterwards. Leave the recipient empty to only keep entries
under Submissions.

Beside the settings, from a wide enough screen, stands the preview: the popup on
your own trader screen with your branding, in light and dark, on a desktop and on
a phone, following every change as you type. A firm whose background forces one
mode shows only that one. Under the preview stand the combinations that quietly do nothing:

- Active, but no rule names it, or every rule that does is paused, a draft or
  outside its window.
- Not active while a running rule points at it.
- Not dismissible with nothing linking out of it. There is no close cross, the
  dimmed page does nothing, and a close button does nothing either, so a trader
  cannot get past it.
- A code attached that no button hands out, or a copy code button with no code
  behind it.
- A code that no longer redeems. The popup still hands it out, and the trader
  finds out at checkout.
- Fields that nothing submits, fields nobody is mailed about, an input without
  a label, and a form in code that the markup never places.
- A bar without a message, a bar button without a label or without an address,
  `{{coupon_code}}` in a bar with no code attached, and colours of your own
  that are hard to read together (under 4.5 to 1).

None of these stop a save. They are the things that are easy to miss and hard to
notice once it is live.

### Collecting answers

On the visual canvas, add an input with the **Field** tool and the popup starts
collecting. The inputs on the canvas are the form, and Settings lists them with
their keys. Each has a label, a type (text, email or long text) and a required
flag, set in the panel beside the canvas.

The first field you add brings a send button with it. Any button can become that
button by setting its action to submit the form.

:::note Renaming a field
A field keeps the key it was first saved with. Renaming the label later changes
what the trader reads and leaves earlier answers filed where they already are,
so your submissions stay whole.
:::

In code, switch on **Collect a form** in Settings and declare the fields there.
Three hooks place them:

| Attribute                     | What it does                          |
| ----------------------------- | ------------------------------------- |
| `<div data-popup-form></div>` | Moves our own form block to that spot |
| `data-popup-field="key"`      | Binds your own input to that field    |
| `data-popup-action="submit"`  | Submits the form                      |

Without any of them the form block is drawn underneath your HTML. Every field
you bind yourself drops out of that block. Bind them all and the block
disappears, which makes your own submit button the only way to send it. Settings
shows a snippet with this popup's real keys, ready to copy.

### Buttons

A button does one of four things when clicked:

| Action           | What happens                                  |
| ---------------- | --------------------------------------------- |
| Open a link      | Sends the trader to a URL or an internal page |
| Close the popup  | Dismisses it                                  |
| Copy coupon code | Copies the attached code to the clipboard     |
| Submit the form  | Sends what the trader filled in               |

### The Rules tab

A popup shows only because a rule names it, so this tab answers who sees it. It
lists every rule that can show the popup, a simple rule or a flow that ends in
it, with its name, whether it is a simple rule or a flow, its period, its
priority and where it stands: running, scheduled, ended, draft, paused or
archived. The name opens the rule on [Popup rules](#rules). The number beside
the tab is how many rules name the popup, and a popup nothing names says so and
offers **New rule**, which opens the form with this popup already picked. The
list is read only: changing when a rule runs happens on the rule.

### Analytics

What the popup did over the last 7, 30 or 90 days or 12 months, against the
period of the same length right before it: views, clicks, conversions,
submissions and how often it was closed, as the tabs of one chart with the
previous period drawn behind it. A conversion is a code it handed out being used,
or its form being sent. Under the chart, each as a share of the views with its
change in points. Days follow your firm's timezone, and a year is drawn per
week.

### Submissions

What traders sent through the form, newest first and fifty to a page, each with
its trader, its moment and every field it holds. Search looks in what they wrote
and in who they are. **Export CSV** downloads every submission that matches the
search, with a column per field. Right click a submission, or use its menu, to
open the trader, copy it as text, copy their email address or its id, or delete
it for good, for the trader who asks for their data to go. Exports and deletions
are written to the popup's Activity.

### Activity

Every change your team saved, with the old and the new value of each setting,
every time it was switched on, paused or archived, every export and every
deleted submission, newest first. A change to the design itself says only that
the design changed. The Activity log has the same lines with every filter.

## A new popup

**New popup** opens in the same place, in three steps.

**What is this popup for?** Say something, hand out a code, or collect an email
address. It only decides the content you start from and which designs you are
offered next.

**How do you want to build it?** The visual canvas, HTML and CSS, or an
announcement bar. The canvas and HTML end up as the same popup on the trader's
screen, and the difference is how you edit it. A bar is offered for saying
something and for handing out a code, not for collecting an address, because a
bar holds no form.

**Pick a design.** Every design is drawn on your own trader screen, in your look
and your colour, where it will land: a modal over the dimmed page, a card in the
corner, a banner along the bottom, a bar above the header. For a popup there
are three shapes, each in a light and a dark version you can filter on:

| Design | What it is |
| --- | --- |
| Modal | In the middle over a dimmed page, 420 pixels wide. A band in a tint of your colour holds an icon in a tile of your colour, with a small line, the title and the text centred under it and a full width button. To hand out a code it shows the code in a panel with **Copy code** and a quiet **Maybe later**. To collect an address it has labelled fields, **Subscribe** and a line promising no spam |
| Corner card | 360 pixels in the bottom right corner, leaving the page usable: an icon tile, the title and a line or two, then the button. A code sits in a row with its copy button inside it, and a signup is one field with a full width button |
| Modal, Corner card and Banner (HTML) | The same shapes in hand written HTML and CSS, with their colours in a handful of custom properties at the top of the CSS so they change in one place. The banner runs along the bottom on one line and folds onto two on a phone |

For a bar there are, to say something, **Ticker** (your colour, scrolling, with
a link), **Notice** (neutral greys, still, for maintenance and the like) and
**Midnight** (near black, still, with a link), and to hand out a code, **Offer**
(your colour, still, with Copy code) and **Offer ticker** (near black,
scrolling, with Copy code). Or start from a blank canvas, blank HTML or a blank
bar.

The buttons, bands and tiles take your brand colour with text in whichever of
black or white reads on it, and the dark versions the colour you set for dark
mode. These designs replaced the earlier eighteen on 2026-10-14. A popup made
from one of those keeps its design.

You then get the same Design and Settings as every popup, and the dock creates
it as a draft. **Start from another design** goes back to the gallery, after
asking, since what you changed is thrown away.

## Duplicating and deleting

Duplicate makes a draft copy with the same design and settings under "Copy of"
its name, and opens it. What traders did with the original stays with the
original.

Deleting a popup deletes its views, clicks and submissions with it, and asks
first, saying how many submissions go and how many rules name it. Those rules
stay and show nothing until they name another popup.

## Showing it

**Rules** decides when a popup appears. A simple rule is a popup, the pages it
shows on, an audience, a frequency and a date window. A flow is the same thing as
a canvas of connected steps, for when one message depends on another: it starts
at the visit, branches on yes or no conditions, and ends in the popup each branch
shows.

At most one popup shows per page view, and next to it at most one bar. When
several match, the highest priority wins. A bar counts as seen once per session,
however many pages the trader opens under it. Frequency is enforced server side, so a trader cannot get around a once
ever or once per day rule by reloading.

### Rules

**Marketing -> Popup rules** is a menu entry of its own, directly under Popups.
It also opens from the count of rules in the header of the popup list. It opens
on the list of rules across the whole width and opens nothing until you pick
one. Each row says what the rule shows, how often, the period it runs, its
priority and where it stands: running, scheduled, ended, draft, paused or
archived. The count of running rules in the header is a filter, and the filter menu narrows by state and by simple
rule or flow and sorts by newest, name, highest priority or last changed. Search
finds a rule by its name, its id or the name of a popup it shows. J and K walk
the list, and a right click opens, copies a link or the id, or deletes.

Picking a rule folds the list to a column and opens the rule beside it, with its
own address. The head names it with where it stands, what it shows, how often,
its priority and its period, and links to its popups. Under that the rule is one
form behind the save dock: its name, status and whether it is a simple rule or a
flow, then what it shows, where and to whom, or the canvas, and then how often,
the priority and the period, which you enter in your own timezone. A line above
the form warns when the rule as it stands shows nothing: no popup picked, a popup
that is not active, no page or pattern to show on, no action in a flow, a period
that has ended, or a running rule about to be stopped.

**New rule** opens an empty form in the same place, or one that already names the
popup when it came from that popup. Deleting a rule asks first, and its popups
stay.

## In the older designs

A firm on Propper - OG or Tactical keeps the screen it launched with. The Popup
rules menu entry and the Rules tab inside a popup exist only in the new Default.
The older screen has four counters above a table of popups with a search by name and a status filter, a
Rules tab beside it with a table of rules and a full page to edit one, a full
page to design a popup with the rules and warnings in
a summary column, and separate pages for a popup's analytics over the last 14
days and its submissions. Those designs have no other filters or sorts, no
switching on, pausing or duplicating from the list, no comparison with a
previous period, no search, export or deletion of submissions, no Activity tab
and no preview of the trader screen. They offer the same ready made popup designs
but cannot make or edit an announcement bar: a bar made in the new Default shows
in their list as Announcement bar, and is changed from the new Default. The bar
itself stands above the trader app in every design.