# salla-products-list (https://docs.salla.dev/twilight/react/web-components/salla-products-list) {/* Generated by scripts/sync-web-components.mjs from the components docs.json. Do not edit by hand. */} 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 [#use-it] In HTML or JSX, use the tag `` 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: ```tsx import { SallaProductsList } from '@salla.sa/twilight-components-react'; ``` ## Example [#example] ```tsx import { SallaProductsList } from '@salla.sa/twilight-components-react'; export function Example() { return ( ); } ``` ```html ``` ```tsx import { SallaProductsList } from '@salla.sa/twilight-components-react'; export function Example() { return ( ); } ``` ```html ``` ## Properties [#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 [#productcardcomponent-example] ```html ``` ## Events [#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, products: Product[], count: number }`. | `any` | ## Methods [#methods] Call these on the element or a React ref. ### `clearSelection() => Promise` [#clearselection--promisevoid] Clears the selection and unchecks all checkboxes. ### `getLoadedProducts() => Promise` [#getloadedproducts--promiseproduct] Returns all products currently rendered in the list, whether selection is enabled or not. Returns `Promise`: A Promise that resolves to an array of product objects. ### `getSelected() => Promise<{ ids: Array; products: Product[]; }>` [#getselected--promise-ids-arraystring--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` [#loadmore--promisevoid] 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` [#reload--promisevoid] Reloads the list: clears the rendered products and fetches the first page again with the current props and filters. ### `selectAll() => Promise` [#selectall--promisevoid] Selects all currently rendered products. Does nothing unless `selectable` is on. ### `setFilters(filters: any) => Promise` [#setfiltersfilters-any--promisevoid] 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 [#related] Used inside: [``](https://docs.salla.dev/twilight/react/web-components/salla-menu), [``](https://docs.salla.dev/twilight/react/web-components/salla-offer), [``](https://docs.salla.dev/twilight/react/web-components/salla-order-edit).