List block

Developer reference for the deprecated List app block, its placement, and every schema setting.

The List app block renders an upsell list of recommended products from a campaign. It is a Shopify theme app extension block targeted at the section level, and it can either render in place or inject itself into any element on the page using a CSS selector.

This block is deprecated. The schema name is List (Deprecated) and it is only available when the customizer_2024_02 deprecation metafield is present. For new installs, use the Upsell Widget block instead.

Overview

The block loads the campaign list runtime through a shared loader and, when quick view is enabled, also injects the quick view modal script.

{% render 'lib-loader' with block, settings: block.settings, name: 'lcuList' %}

{% if block.settings.enableQuickView %}
  {% render 'inject-unique-lib', name: 'lcuQuickViewModal.js' %}
{% endif %}

Key facts from the {% schema %}:

Name: List (Deprecated)
Target: section
JavaScript: lcuList.js
Available if: {{ app.metafields.deprecation.customizer_2024_02 }}

Placement

By default the block renders where you add it in the theme editor. To render it somewhere else on the page instead, enable Embed block and provide a CSS selector for the target element, plus a placement relative to that target.

The where setting maps directly to the positions accepted by the DOM insertAdjacentElement API:

Value	Label	Position relative to the target
`beforebegin`	Before the target	Immediately before the target element
`afterend`	After the target	Immediately after the target element
`afterbegin`	Before the first child of the target	Inside the target, before its first child
`beforeend`	After the last child of the target	Inside the target, after its last child

The default placement is afterbegin.

Schema settings

All settings live in the settings array of the block's {% schema %}. They are grouped under headers in the theme editor.

General

ID	Type	Label	Default	Notes
`widgetId`	text	Campaign ID	—	The campaign to render. The Campaign ID is available in the Admin Panel.
`isEmbed`	checkbox	Embed block	`false`	Render the block inside a given target instead of in place.
`embedSelector`	text	Embed selector	`body`	CSS selector of the target where the block will be rendered.
`where`	radio	Placement	`afterbegin`	Where to place the block relative to the target. See Placement.
`enableQuickView`	checkbox	Enable quick view	`false`	Use a modal to quickly preview a product. Loads `lcuQuickViewModal.js` when enabled.
`enableRefreshOnCartChange`	checkbox	App refresh on cart change	`true`	Refresh the block when the cart changes.

Content

ID	Type	Label	Default	Notes
`title`	text	Heading text	`You may also like`	Heading shown above the product list.
`addToCartText`	text	Add to cart button text	`Add`	Label for the add to cart button.
`addedToCartText`	text	Add to cart button text on item added	`Added`	Label shown after an item is added to the cart.
`groupVariants`	checkbox	Group variants	`true`	Group a product's variants together.
`hideOutOfStock`	checkbox	Hide out of stock variants	`true`	Hide variants that are out of stock.

Sizes and spaces

ID	Type	Label	Default	Range	Notes
`productPlaceholdersCount`	range	Product placeholders count	`4`	1–4, step 1	Number of loading placeholders shown while products load.
`productImageSizeDesktop`	range	Product image size	`80`	10–200, step 2 (px)	Product image size in pixels.
`paddingDesktop`	text	Container padding	`8px`	—	Space around the container. Accepts any CSS padding value, e.g. `16px 18px 12px 16px` or `16px 14px`.

Styles

ID	Type	Label	Default	Notes
`fontColor`	color	Primary font color	`#121212`	Primary text color.
`backgroundColor`	color	Background Color	`rgba(0,0,0,0)`	Container background color (transparent by default).
`addToCartBgColor`	color	Add to cart button bg color	`#121212`	Background color of the add to cart button.
`addToCartTextColor`	color	Add to cart button font color	`#fff`	Text color of the add to cart button.
`customCss`	textarea	Custom CSS	—	Custom CSS for fine-grained styling, e.g. `.app__product__image { border: 1px solid red; }`.

Color values follow Shopify's color setting format, so you can use hex or rgba() values. The backgroundColor default of rgba(0,0,0,0) makes the container transparent so it inherits the surrounding theme background.

Example configuration

A minimal embedded configuration that injects the list after the last child of the cart drawer might be saved as block settings like this:

{
  "widgetId": "your-campaign-id",
  "isEmbed": true,
  "embedSelector": ".cart-drawer__content",
  "where": "beforeend",
  "title": "Complete your order",
  "addToCartText": "Add",
  "addedToCartText": "Added"
}

Screenshot: Theme editor showing the List block settings grouped under General, Content, Sizes and spaces, and Styles headersAdd a real image by setting the `src` prop.

The List block settings as they appear in the Shopify theme editor.

On this page