Creating responsive widgets

You can create responsive widget content so that they are optimized for web browsers on desktop, tablet, and mobile devices.

Before you begin

Ensure that you are familiar with the process of creating and registering custom widgets. Once you create and register your custom widget, these guidelines help make your widget responsive.


The following are a list of responsive style guidelines:
  • Do not fix the width of the widget or preset its margin. That is, the root HTML element of the widget must have the following CSS styles:
    display: block;
    width: auto;
    margin: 0;
    This allows the layout container or slot to determine the width and spacing between widgets.

    Contrary to width, assign the widget a fixed height or minimum height, or let its content determine its height (height: auto. An automatic height is recommended if the widget is intended to be fluid.

  • Ensure that the internal user interface widget elements are fluid by using CSS. Common techniques are as follows:
    • Use a CSS grid system to arrange the user interface elements into rows and columns. For example, the CSS grid system that is used by the default layouts and containers arranges user interface elements in a 12-column grid.
    • Use display: inline-block or float: left to flow the user interface elements left-to-right, top-to-bottom.
      Note: If you use float: left, ensure that you clear the float at the end. For example:
      .myContainer:after {
      content: "";
      display: block;
      clear: both;

      However, ensure that you use float: right instead for RTL languages.

    • Use overflow: scroll in combination with min-width if you want to display user interface elements that require a minimum amount of horizontal space. For example, tables. Scrollable divs typically work well on most current tablet and mobile web browsers, however some older versions of devices or web browsers might not display them correctly.
  • Avoid the use of absolute positioning in a fluid container unless you want to anchor the user interface element to a specific corner or side of the container.
  • When you use text blocks:
    • Avoid fixing the heights of text blocks in a fluid container, since text might re-flow or re-wrap when the container width changes. If you want the text block to have a minimum height, use min-height.
    • Avoid the use of line-height to specify the height of a single-line text block, as it does not display correctly if the text wraps. Use padding instead if you want to pad the text block.
    • Consider the use of display: table-cell if you want to vertically center text that might wrap.
  • If possible, optimize the widget user interface elements further for different viewport or slot widths. Common techniques are as follows:
    • If you are using a responsive CSS grid system, use it to define responsive behavior such as column stacking on smaller screens.
    • Use CSS media queries to optimize widget styling for different breakpoints. To align with the default styling, optimize for the following page ranges:
      Aurora starter store page range breakpoints
      Device Range breakpoint Page range
      Desktop RWD-C 1281 CSS pixels and above
      Tablet RWD-B 601 - 1280 CSS pixels
      Mobile RWD-A 600 CSS pixels and below
    • Use JavaScript to split widget content into multiple pages, depending on the amount of space available. Remember shoppers who use touch screen devices expect pagination to work by swiping. If possible, implement support for touch events and MS pointer events.
  • CSS media queries are sensitive to screen (viewport) widths but not slot widths. Therefore, consider using JavaScript to optimize the widget to respond to the slot size. See the Content Recommendation widget for more information.
  • Test the widget on different layouts and containers to ensure that it works across different screen and slot widths.