salla-products-list
Renders a grid of product cards from a source such as a category, the latest products, a search, a list of ids or the wishlist.
Renders a grid of product cards from a source such as a category, the latest products, a search, a list of ids or the wishlist. Use it on home, category, brand, search and landing pages, or wherever a theme needs a list of products.
It fetches products from the store API, pages through them with a "Load more" button (or automatic loading with autoload) unless you set limit (the json, selected, recently, related and landing-page sources always load once), and restores the scroll position when the customer comes back from a product page.
Each product is rendered with salla-product-card unless you pass product-card-component.
Themes can change the data through hooks registered on salla-products-list: beforeBuildListUrl (receives { url }) and beforeAppendItems (receives { items }).
Accessibility: with selectable, each card gets a labelled checkbox.
Use it
In HTML or JSX, use the tag <salla-products-list> with the Attribute names below. In React, the wrapper takes the Property names (camelCase).
This component has a native React version. Use it instead of the raw tag:
import { SallaProductsList } from '@salla.sa/twilight-components-react';Example
import { SallaProductsList } from '@salla.sa/twilight-components-react';
export function Example() {
return (
<SallaProductsList source="categories" sourceValue="[12]" limit={8} />
);
}import { SallaProductsList } from '@salla.sa/twilight-components-react';
export function Example() {
return (
<SallaProductsList source="latest" autoload />
);
}Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
autoload | autoload | Loads the next page automatically when the customer scrolls near the end of the list. When false, a "Load more" button is shown instead. Only applies when the list pages through results (no limit). | boolean | false |
compactCards | compact-cards | Shows compact cards, for drawer or list layouts (sets the compact attribute on the cards). | boolean | |
filtersResults | filters-results | Marks this list as the results of the product filters. When true and the store has product filters enabled, the list sends the available filters in the filters::fetched event (or filters::hidden when there are none) and uses the filtered-results layout. The list reloads whenever the salla-filters::changed event fires. | boolean | |
horizontalCards | horizontal-cards | Shows each product card in its horizontal layout (sets the horizontal attribute on the cards). | boolean | |
includes | includes | Extra data to request with each product, as an array or a JSON string of an array, for example ["options"] or '["options","images"]'. Supported values are options (product options) and images (product images). | string[] | |
limit | limit | Maximum number of products to show, as a number of products. When set, the list loads once and has no "load more" button or infinite scroll. When not set, the list pages through results (up to 32 products per request). | number | |
loadMoreText | load-more-text | Text of the "Load more" button. Defaults to the store translation of "Load more". | string | |
productCardComponent | product-card-component | Tag name of a custom element used to render each product, instead of salla-product-card. The element receives the product through its product property. If no element with this tag is registered, salla-product-card is used. | string | 'custom-salla-product-card' |
rowCards | row-cards | Shows the cards in a row layout by adding the s-products-list-row-cards class. | boolean | |
selectable | selectable | Enables multi-selection of products. When enabled, a checkbox is rendered on top of each product card and the selected products are exposed via the selectionChanged event, the salla-products-list::selection.changed global event and the getSelected() method. This works for any source and defaults to false. On the wishlist page the salla-wishlist-actions panel turns it on at runtime (when the customer chooses "share specific items"), so no theme markup changes are required. | boolean | false |
sortBy | sort-by | Sort order sent to the API. Common values: ourSuggest, bestSell, topRated, priceFromTopToLow, priceFromLowToTop. When not set, it is read from the sort or by URL parameter. | string | |
source | source | Where the products come from. categories, brands, tags and selected take ids in source-value; search takes a keyword; related takes a product id; json takes the products themselves; recently shows the recently viewed products you pass as ids in source-value. latest, offers, sales, top-rated and reorder need no value. wishlist shows the customer wishlist, or only the ids given in source-value or in a source_value URL parameter. When not set, it is detected from the current page (for example the category page shows categories, the search page shows search) and falls back to latest. | "brands" | "categories" | "json" | "landing-page" | "latest" | "offers" | "recently" | "related" | "reorder" | "sales" | "search" | "selected" | "tags" | "top-rated" | "wishlist" | |
sourceValue | source-value | The value for source, as a JSON string or a value, depending on the source: - ids as a JSON array, for example [1,2,3], when source is categories, brands, tags, selected or recently (on category, brand and tag pages the current page id is used when this is empty) - a keyword when source is search (defaults to the q URL parameter) - an array of product objects when source is json - a product id when source is related | any |
productCardComponent example
<salla-products-list product-card-component="my-custom-card" source="latest"></salla-products-list>Events
Listen with addEventListener, or the on prop of the React wrapper (for example onModalBack).
| Event | Description | Detail |
|---|---|---|
productsFetched | Fires each time a page of products has been fetched and is about to render (also emitted as the global salla-products-list::products.fetched event). event.detail is the API response: data (the products), cursor, filters when available, plus source, sourceValue and nextPage added by the component. | any |
selectionChanged | Fires when the selection changes (only when selectable is enabled). event.detail is { ids: Array<string|number>, products: Product[], count: number }. | any |
Methods
Call these on the element or a React ref.
clearSelection() => Promise<void>
Clears the selection and unchecks all checkboxes.
getLoadedProducts() => Promise<Product[]>
Returns all products currently rendered in the list, whether selection is enabled or not.
Returns Promise<Product[]>: A Promise that resolves to an array of product objects.
getSelected() => Promise<{ ids: Array<string | number>; products: Product[]; }>
Returns the currently selected products (only used with selectable). The selection is kept across pages.
Returns Promise<{ ids: (string \| number)[]; products: Product[]; }>: A Promise that resolves to { ids, products }: the selected product ids and the product objects.
loadMore() => Promise<void>
Loads the next page of products and appends it. Does nothing when the list is not paging through results or there are no more pages.
reload() => Promise<void>
Reloads the list: clears the rendered products and fetches the first page again with the current props and filters.
selectAll() => Promise<void>
Selects all currently rendered products. Does nothing unless selectable is on.
setFilters(filters: any) => Promise<void>
Applies a set of filters and reloads the list from the first page. Does nothing when the filters are empty or equal to the current ones. It also scrolls the window to the top.
| Parameter | Type | Description |
|---|---|---|
filters | any | Filters object keyed by filter name, as read from the URL filters[...] parameters. Each value is a string, an array of strings, or an object such as { min, max }. |
Related
Used inside: <salla-menu>, <salla-offer>, <salla-order-edit>.
salla-product-size-guide
A modal that shows the size guides of a product, one tab per guide, loaded from the store when it opens.
salla-products-slider
Fetches a set of products (by category, brand, tag, latest, offers, related, a fixed list of ids, or your own JSON) and shows them as product cards in a carousel (salla-slider).