Load More Feed With Category Pills

Productlist5: Load More Feed With Category Pills

A three-column product feed led by a row of category pills (with an "All" pill), alongside a search box and a sort dropdown in one row. Instead of pagination, a Load more button appends the next batch to the feed and a progress bar tracks how many of the total have loaded. After each batch lands, the feed scrolls to the first newly added card.

Filtering is powered by the shared product-filters engine, which installs automatically with the block.

Installation

Swap YOUR_EMAIL and YOUR_KEY for the email and license key on your account. Find your license key on your account page.

Radix flavor

npx shadcn add "https://ui.beste.co/r/productlist5?email=YOUR_EMAIL&license_key=YOUR_KEY"

Base UI flavor

npx shadcn add "https://ui.beste.co/r-base/productlist5?email=YOUR_EMAIL&license_key=YOUR_KEY"

Quick start

The installed file exports productlist5Demo alongside the block: the exact props behind the preview above. Spread it to get a working feed in one line.

import { Productlist5, productlist5Demo } from "@/components/beste/block/productlist5";

export default function Feed() {
  return <Productlist5 {...productlist5Demo} />;
}

Then replace the demo with your own props. Written out, the same setup looks like this:

import { Productlist5 } from "@/components/beste/block/productlist5";

export default function Feed() {
  return (
    <Productlist5
      heading="The edit"
      pageSize={9}
      productsUrl="/api/products"
      pillGroupId="category"
      allPillLabel="All"
      filterGroups={[
        { id: "q", label: "Search", type: "search", placeholder: "Search the edit" },
        {
          id: "category",
          label: "Category",
          type: "segmented",
          options: [
            { label: "Shoes", value: "shoes" },
            { label: "Apparel", value: "apparel" },
          ],
        },
      ]}
      sortOptions={[{ label: "Featured", value: "featured" }]}
    />
  );
}

The group whose id equals pillGroupId renders as the pill row (a leading "All" pill clears it); the search group and sort render inline in the same top row. Other filter groups in filterGroups still drive matching but are not rendered as controls, so keep this block's filterGroups focused on search + the pill facet.

Load more (append)

pageSize is the batch size, not a page window. "Load more" requests the next page and the engine appends the results to the feed (useProductFetch({ append: true })). Any filter or sort change resets to page 1 and replaces the list. The progress bar width is loaded / total, and the button hides once everything is loaded. In client mode the feed reveals page * pageSize items cumulatively; in remote/server mode it shows every batch fetched so far.

Props

ProductItem

{
  title: string;
  href: string;
  brand?: string;
  price: number;
  compareAtPrice?: number;
  image: { src: string; alt: string };
  badge?: string;
  rating?: number;
  reviewCount?: number;
  keywords?: string[];          // extra terms matched by "search"
  attributes?: Record<string, string[]>; // filterable values keyed by group id
}

attributes keys must match your filterGroups ids, e.g. { category: ["sneakers"] }.

Filter groups

Each entry in filterGroups is a ProductFilterGroup:

type ProductFilterOption = {
  label: string;
  value: string;
  count?: number;
  swatch?: string;
  parentValue?: string;
  children?: ProductFilterOption[];
};

Filter types

The pill group's type only affects how it would render as a standard control; here it is drawn as pills, and matching still uses attributes[pillGroupId].

Cascading filters (dependsOn)

A group with dependsOn: "<parentId>" stays disabled until its parent has a selection, and clears whenever the parent changes. Static: tag options with parentValue. Dynamic: leave options empty and pass loadOptions to the engine.

Filter components

Every control this block renders is an individual Beste UI filter component from the Filter category — browse, preview, and install any of them on their own there:

filter-checkbox, filter-radio, filter-chips, filter-segmented, filter-swatch, filter-toggle, filter-select, filter-multiselect, filter-combobox, filter-tree, filter-rating, filter-slider, filter-range, filter-search.

They are wired together by the hidden product-filters engine that ships with this block, so a single install pulls in every control plus the state, debounce, cascading, and query logic. To build your own layout, use the engine directly: useProductFilters + ProductFilterField (renders the right control per group) + ProductFilterChips, with matchesProductFilters and sortProducts backing client mode.

Data modes

Supply products in one of three ways:

1. Client — pass the full products array; filtering and sorting run locally, and the feed reveals a batch at a time.
2. Remote (productsUrl) — the block fetches (and appends) each batch itself. The endpoint receives ?filters=<json>&sort=&page=&pageSize= and returns { products, totalCount }. Pair with initialProducts for an SSR first batch.
3. Server (mode: "server") — you own the fetching; every action calls onQueryChange. Accumulate batches yourself and pass the full loaded list as products with totalCount.

ProductQuery

{
  filters: Record<string, string[]>; // selections per group id
  sort: string;                      // current sort value
  page: number;                      // 1-based batch number
  pageSize: number;
}

Filter value shapes inside filters: option groups → arrays of option values; slider/range → a single "min-max" string (open ends allowed, "50-" = 50 and up); search → a single string.

Behavior notes

• Any filter or sort change resets to the first batch and replaces the feed; "Load more" appends.
• After a batch loads, the feed scrolls to the first newly appended card (scroll-mt keeps a small offset).
• Client-side sorting understands featured, price-asc, price-desc, rating; other values keep input order.
• The initial load shows a skeleton grid; subsequent "Load more" batches keep the existing cards in place.
• Product images use a plain <img>, so no next.config images.remotePatterns setup is needed. next/link handles product links.