Design guidelines for Custom Views

Learn about best practices for designing user-friendly Custom Views.

This page applies only to Custom Views.

On this page, we'll give you practical advice to help you design and build Custom Views. To do that, we'll describe some best practices for working with common UI components.

Panel sizes

A Custom View is rendered inside a panel that opens from the right side of the page, on top of the Merchant Center page you're working within. Your custom functionality must fit within the panel, therefore, it's important to choose the correct panel type for your specific use case.

We provide two Custom View panel types: extended and narrow, depending on the types of content you want to display. You can select the panel type when you add a Custom View in the Merchant Center. During development, you can set the panel type with the typeSettings.size key in the custom-view-config.mjs file.

Extended panel

The extended panel is ideal for large and comprehensive content, making it easy to accommodate large tables, charts, forms, or extensive textual content and/or interactions.

Custom Views extended panel expanded

We recommend using an extended panel to:

  • Display large amounts of content and/or actions that require more substantial user interaction.
  • Present extensive flows that require detailed navigation.

Narrow panel

The narrow panel is ideal for displaying small amounts of information, and/or completing simple actions that don't require a navigation flow.

Custom Views narrow panel expanded

We recommend using a narrow panel to:

  • Provide additional context for a specific item on the page. For example, displaying the tracking information for an order.
  • Ask the user for basic input and/or complete simple actions (for example, using a short form with only a few fields).

Dialog components

Dialog components are presented as modals to users to display additional information (InfoDialog), confirm an action (ConfirmationDialog), or collect additional information (FormDialog).

Dialogs are best suited for use in the larger, extended panels. While you can use dialogs in the smaller, narrow panels, this should only be done in exceptional cases.

We recommend using a dialog to present confirmation messages when additional user actions are required. You should also use the size=scale prop value to ensure that the dialog is rendered responsively according to the available space.

To ensure a good user experience, be sure to minimize the amount of form fields and possible actions within the dialog.

Page content layouts

Layouts are the foundation for your page content structure. We recommend the following layout types for different panel types.

Layout typeExtended panelNarrow panel
Wide (single column)
Wide (Two columns: 1/1)
Wide (Two columns: 2:1)

Modal pages are used to display information in a separate context from the Custom View initial page.

We recommend only using modal pages in the extended panel. The larger size of the panel provides a smoother transition to the modal pages.