From our perspective on search expertise, the ultimate goal is for the visitor to find the right product immediately on the first page. If the search engine does its job well, browsing further is not necessary. This is one of the reasons why toggling the number of items per page is not a standard part of our solution.

However, users often have different preferences for how many products they want to view at once. While some prefer a compact view for speed, others want to see as many items as possible to compare options.

In this guide, we show how you can implement a dropdown selector that allows the user to control the number of products displayed.

Implementation

To achieve this, we will use the pageSize property within the tweakwiseListerPage initialization object. We will source this value from sessionStorage, defaulting to a standard value if no preference is set.

1. Add the Selector

First, add a simple HTML select element to your lister page template, typically near the sort options or pagination controls.

<label for="pagesize-select">Items per page:</label>
<select id="pagesize-select">
    <option value="24">24</option>
    <option value="48">48</option>
    <option value="96">96</option>
</select>
<div id="tweakwise-output"></div>

2. Configure Tweakwise JS

In your JavaScript file, retrieve the stored value before initializing Tweakwise.

// 1. Get the element and the stored preference
const sizeSelector = document.getElementById('pagesize-select');
const storedSize = sessionStorage.getItem('tw-pagesize');

// 2. Determine the actual size to use (Default to 24 if null)
const defaultSize = 24;
const pagesizeValue = storedSize ? parseInt(storedSize, 10) : defaultSize;

// 3. Sync the dropdown UI with the active value
if (sizeSelector) {
    sizeSelector.value = pagesizeValue;
}

// 4. Initialize Tweakwise with the dynamic property
const listerPage = tweakwiseListerPage({
    output: "#tweakwise-output",
    cid: "1",
    pageSize: pagesizeValue // Injected here
});

// 5. Add Event Listener to update preference
if (sizeSelector) {
    sizeSelector.addEventListener('change', (e) => {
        // Save the new selection
        sessionStorage.setItem('tw-pagesize', e.target.value);
        
        // Reload to apply changes (simplest implementation)
        window.location.reload(); 
    });
}

Notes & Important Considerations

Session vs. Local Storage: We used sessionStorage here, which clears when the tab is closed. If you want the preference to persist when the user returns days later, switch to localStorage or cookies.
Performance Impact: Avoid offering excessively high page sizes (e.g., 500+ items). Large DOM trees can slow down rendering performance and increase Time to Interactive (TTI), especially on mobile devices.
Reloading: The example above uses window.location.reload() for simplicity. In a Single Page Application (SPA), you would destroy the current instance and re-initialize it, or trigger a new fetch event instead of reloading the browser.

FAQ

Q: Can I set a maximum limit for the page size? A: Yes, strictly speaking, the API accepts what you send, but you should limit the options in your <select> HTML to ensure performance. We recommend capping it at 96 or 128 items for optimal performance.

Q: Does the pageSize affect the faceting or filtering results? A: No. The pageSize only controls the size parameter in the response body (the number of products returned). The facet counts are calculated based on the total result set, regardless of how many are currently visible.

Q: Why isn't my page size updating when I change the dropdown? A: Ensure that window.location.reload() is firing or that your JS logic re-runs tweakwiseListerPage. The pageSize property is read on initialization. Changing the variable after initialization will not update the grid unless you re-trigger the instance.