Themes

Themes/Theme SDK/Modules/listing

listing

Collection, category and search listings: product cards, filters, sort and paging.

On this page

import { … } from '@poltura/theme-sdk/listing';

Hooks

Name	What it is
`useListingFilters`	The filters of the product list the component sits in: its groups, the shopper's selection and the actions that change it.
`useListing`	The product list the component sits in: its heading, the cards of the current page, the sort, the paging and the merchant's grid choices.

Parts

Name	What it is
`FilterOption`	One checkbox choice with its match count, and a disclosure for its nested choices such as subcategories.
`SwatchFilter`	A swatch group's choices as colour or picture dots with their names, with search and "show more" for long lists.
`PriceRangeFilter`	A price group's range as a slider, two amount fields or both, as the merchant chose, with a reset.
`FilterGroup`	One filter group as a collapsible section: its title and selection count, then its checklist, swatches, price range or toggle.
`AppliedFilters`	The applied filters as removable chips, with a "clear all" link; nothing while no filter is applied.
`FilterSheet`	The narrow-screen filters: a button with the selected count that opens `FilterPanel` in a sheet with "clear all" and "show results".
`SortSelect`	The sort menu: a button naming the current order that opens the list of orders.
`ListingPagination`	Previous and next buttons around the first, last and nearby page numbers; nothing for a single page.
`ProductCardSkeleton`	A grey placeholder in the shape of a product card, for lists that are still loading.
`ProductCardBadge`	The merchant's card badge, the first specification the store shows on cards; nothing without one.
`ProductCardSpecs`	The attribute values the store shows on cards, such as a game's platform, as small chips with their icons and "+N" for the rest; nothing without any.
`ProductList`	Reports the cards inside as one product list to the store's analytics: the list once it shows, and the card a shopper opens.
`ListingHeader`	A listing's title, product count and description, with a "clear search" button on a results page.
`ListingEmpty`	The block a listing shows when nothing matches: an icon, a heading and a line of text.

Defaults

Name	What it is
`FilterPanel`	The complete filter panel of the product list it sits in: every group of `useListingFilters` with a "clear all".
`ProductCard`	A complete product card: image, discount, title, badges, price and an add-to-cart button that opens the product page when options must be chosen.
`ProductGrid`	A responsive grid of product cards, with placeholders while loading and `ListingEmpty` when there are none.
`ProductRail`	A titled row of product cards with a "view all" link, as a grid or a scrolling row with arrows; nothing without cards.

Constants

Name	What it is
`collectionRegions`	The collection template's regions, where merchants place the listing's blocks.

Types

Name	What it is
`AppliedFilter`	One applied filter, as a removable chip.
`FilterGroupKind`	How a filter group is presented: a checklist, colour swatches, a price range or an on/off toggle.
`FilterGroupView`	One filter of a product list, such as brand, colour or price.
`FilterOptionView`	One choice inside a filter group.
`FilterPriceDisplay`	How a price group takes its range: a slider, two amount fields, or both.
`ListingFilterSelection`	The filters a product list is narrowed by.
`ListingFiltersState`	The filter panel's state and the actions that change the selection.
`ListingState`	A collection, category or search results page with its products, sort and paging.
`ListingVisibility`	Which parts of a product list the merchant has switched on.
`Pagination`	Where a paged list is and how to reach its other pages.
`PriceRangeSelection`	A price range a shopper selected, in major units; a null bound leaves that side open.
`SortOption`	One choice of the sort menu.
`ProductCard`	A product as a list, rail or search result shows it.
`FilterOptionProps`	Props of `FilterOption`.
`SwatchFilterProps`	Props of `SwatchFilter`.
`PriceRangeFilterProps`	Props of `PriceRangeFilter`.
`FilterGroupProps`	Props of `FilterGroup`.
`AppliedFiltersClassKey`	The parts of `AppliedFilters` its `classes` prop styles.
`AppliedFiltersProps`	Props of `AppliedFilters`.
`FilterPanelProps`	Props of `FilterPanel`.
`FilterSheetProps`	Props of `FilterSheet`.
`SortSelectProps`	Props of `SortSelect`.
`ListingPaginationProps`	Props of `ListingPagination`.
`ProductCardLayout`	Whether a card is a tile in a grid or a wide row in a list.
`ProductCardVisibility`	Which parts of a product card are shown; every part is on unless switched off.
`ProductCardLabels`	The button texts of a product card; each falls back to the store's own wording.
`ProductCardProps`	Props of `ProductCard`.
`ProductCardSkeletonProps`	Props of `ProductCardSkeleton`.
`ProductCardBadgeProps`	Props of `ProductCardBadge`.
`ProductCardSpecsProps`	Props of `ProductCardSpecs`.
`ProductGridProps`	Props of `ProductGrid`.
`ProductListProps`	Props of `ProductList`.
`ProductRailClassKey`	The parts of `ProductRail` its `classes` prop styles.
`ProductRailProps`	Props of `ProductRail`.
`ListingHeaderProps`	Props of `ListingHeader`.
`ListingEmptyProps`	Props of `ListingEmpty`.

Last updated Oct 29, 2026