We’ve migrated our documentation to a new site, which means some URLs have changed.
Subscriptions
Subscriptions
Breadcrumbs

How Do I Customize Modal Template Width in Piano?

Default Behavior

Understanding the default sizing is important for responsive design:

  • If you do not set a custom width, modals render at:\n

    • 735px when the browser width is roughly ≥ 725px

    • 100% width on smaller browser widths

  • If you do set a custom width (for example, 600 or 1920), the modal will still shrink to fit when the viewport is narrower than the configured width.

Composer / Management + Billing Templates (Offers, Checkout, My Account)

For Composer and Management + Billing modals (including checkout and My Account), the recommended way to control width is the directive.

Add the Directive

Place it at the very beginning of the template HTML (before , , or any other markup):

XML
<config width="600"></config>\n<!DOCTYPE html>\n<html>\n  ...\n</html>

  • width is specified in pixels (number or quoted string both commonly work; quoting is recommended).

  • Avoid setting a fixed height unless you have a specific reason; it can introduce layout issues.

Responsive Adjustments with CSS Media Queries

If you want one width for desktop but a different behavior on mobile, keep the width as your desktop baseline and override with CSS:

HTML
<config width="600"></config>\n<style>\n  @media (max-width: 600px) {\n    body { width: 100% !important; }\n  }\n</style>

Troubleshooting: Width Doesn't Change

If the modal width doesn't reflect your value, check for CSS overrides inside the template, for example:

#checkout-container { width: 1000px !important; }

Remove or reduce conflicting rules, or ensure your intended width rule is the one that wins (using careful selectors and !important only when necessary).

In some cases, the editor/preview may not reflect the new width immediately. Publish and validate on a real page placement to confirm behavior.

Identity Management Modals (Login, Registration, Double Opt-In)

For setting the width of Identity Management modals, see the dedicated article: How to Set the Width for Identity Management Templates.

Special Case: Highly Customized "My Account" Templates

If your customized My Account modal stops auto-adjusting size as expected, confirm that the scrolling container class is compatible. In some custom implementations, replacing my-account-widget-scroll with class="scrollable-content" can restore automatic width/height adjustments.

Best Practices

  • Test in a sandbox and then validate on a real page placement before deploying broadly.

  • Prefer one "source of truth" for width per modal type (template-level via , or invocation-level via tp.pianoId.show()), and avoid conflicting rules.

  • If sizing looks wrong, inspect the DOM/CSS for fixed-width containers or !important overrides that may be forcing a different width.

  • When using large widths (for example, 1920), verify layout at common breakpoints so content doesn't appear stretched or sparse on wide screens.

Last updated: