Web SDK
Display modes
The seven formats a screen can open in, their positions and sizes, and how the call and the placement decide which one is used.
A screen opens in one of seven formats. You can set the format on the placement in the dashboard, or pass mode in code.
type DisplayFormat = 'modal' | 'fullscreen' | 'banner' | 'slide_in' | 'toast' | 'drawer' | 'launcher';
type DisplayPosition = 'top' | 'bottom' | 'bottom_right' | 'bottom_left' | 'bottom_center' | 'corner' | 'left' | 'right';
type DisplaySize = 'small' | 'medium' | 'large';Which one is used
For presentPaywall:
modefrom your call, if you pass one. Then the placement's position, size and duration are ignored too.- Otherwise the placement's format from the dashboard, with its position, size and duration.
- Otherwise
'modal'.
A format the SDK does not know (a newer one) is drawn as a modal. mode: 'launcher' called by hand opens what the placement's launcher opens, without a button. mountPaywall ignores all of this: it draws inline.
Formats
mode | Looks like | Positions (default first) | Widths |
|---|---|---|---|
modal | Centred dialog on a dimmed page | none | small 360, medium 440, large 560 px |
fullscreen | Covers the viewport | none | none |
banner | Full-width bar pinned to an edge | top, bottom | full width |
slide_in | Card near the bottom | bottom_right, bottom_left, bottom_center | small 320, medium 380, large 440 px |
toast | Small note | bottom, top, corner | small 280, medium 360, large 440 px |
drawer | Panel from a side over a dimmed page | right, left | small 360, medium 440, large 560 px |
launcher | Floating button, opens a screen | bottom_right, bottom_left | the opened screen's |
Behaviour
| Page behind | Scroll lock and focus trap | Max height | |
|---|---|---|---|
modal | Dimmed (50% black) | Yes | 100% of the viewport minus 32 px |
fullscreen | Covered | Yes | 100% of the viewport |
drawer | Dimmed (40% black) | Yes | 100% of the viewport |
banner | Usable | No | 40% of the viewport, scrolls inside |
slide_in | Usable | No | 100% of the viewport minus 32 px |
toast | Usable | No | 50% of the viewport |
- A modal, full screen or drawer moves focus into the screen, wraps Tab inside it, locks page scroll, and gives focus back on close. A modal or drawer closes on a backdrop click unless
closeOnBackdrop: false. - A banner, slide-in and toast never take focus, so they do not interrupt typing. Esc closes them only while focus is inside.
- Under 640 px wide a slide-in becomes a bottom sheet: full width, stuck to the bottom, top corners rounded, at most 85% of the viewport tall. A drawer is full width. A toast is the screen's width minus 32 px, and
cornerbecomes bottom centre. - Banner and slide-in slide or fade in over 200 ms. Everything switches off for visitors who prefer reduced motion.
- A toast leaves after
durationseconds (default 6, 3 to 60). It waits while the pointer or focus is on it or the tab is hidden, and keeps at least 2 seconds after the visitor lets go. A toast timing out resolvesclosedand records nocloseevent. - Screens sit at
z-index: 2147483000. The launcher button sits just below. - Roles for assistive technology: a toast is
role="status"; other formats arerole="dialog"witharia-modaltrue only for blocking ones. maxContentWidth(for example'480px') replaces a modal's width.
The SDK adds no close button. Give the screen one with the action Close the screen.