1 min read

Product Listing

Last Updated - Platform 24.0 - SDK 19.0

Product Listings are widget views that control their own state from v24 onwards. Instead of the Product List, the Product Listing handles navigation and user interaction.

product listing

Product Card

The ProductListingView uses the vertical ProductCardView which is shared by Product Carousels so customisations can be consistent. Its infoContainer groups text based views such as brand, title, and price. Add additional views to its mainContainer or infoContainer.

Container.shared.views.verticalProductCardView.replace { VProductCardView() }


Images are presented first within an ImageViewer (a paged image view) that can show any amount of images. When showing more than one image a page indicator is presented over the bottom of the image.

The current image position is lost when the cell is scrolled out of view due to the nature of iOS lists.

Container.shared.views.imageViewer.replace { PoqImageViewer() }

The image limit is controlled by the imageLimit catalogue setting that affects all cards. By default the limit is set to 1 which shows the only the first image.

Settings.Catalogue.imageLimit = nil // No limit.


The ProductCardView supports more than the listing presents but to keep the Product List simple listings present only the brand, title and price.

Variant Grouping

Product listings work with variant groups instead of variants (as explained here). The last slot of the listings is used to present the listings other variant groups.

The SDK offers different variations of this view but defaults to swatches.

Container.shared.views.variantGroupView.replace { ... }

More Options

The MoreOptionsView to present 'More Colors' if there is more than 1 variant group. This is a static view but the image can be customised via AppStyling.

Container.shared.views.variantGroupView.replace { FormSwitcherVariantGroupView() }


The FormSwitcherVariantGroupView is the default view that present swatches for the variant groups. This allows the user to switch the appearance of the listing by tapping on a different swatch.

When the user switches swatch the selection is sent as the formVariationIds to persist to the Product Details screen and when adding to cart. The selection is lost when the cell is scrolled out of view due to the nature of iOS lists.

Container.shared.views.variantGroupView.replace { FormSwitcherVariantGroupView() }

Cart Widget

The ProductListingView supports cart widgets from v24 onwards to allow users to add to the cart from the Product List. When enabled, the widget will fetch the full Product from the Product API then show the VariantSelector as needed.

To enable this you will need to inject a cart widget into the view. The cart button is presented in the bottom right corner of the image (over the image) so we offer an icon button to match the look of the wishlist button.

Container.shared.views.productListingView.replace { PoqProductListingView(cartWidget: CartWidget(view: IconCartButton())) }