Marketplace Toolbar Product Grid

Productlist3: Marketplace Toolbar Product Grid

A dense product grid with an always-visible inline filter toolbar at the top (no sidebar, no drawer). The demo toolbar holds a search box, a segmented category, a cascading subcategory select, and a searchable multi-brand combobox; below it a result count with removable active-filter chips and a sort dropdown, then a compact grid (up to 5 columns) with numbered pagination.

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/productlist3?email=YOUR_EMAIL&license_key=YOUR_KEY"

Base UI flavor

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

This installs the block, the engine (components/beste/component/product-filters.tsx), the individual filter controls, and the shadcn/ui dependencies they need.

Quick start

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

import { Productlist3, productlist3Demo } from "@/components/beste/block/productlist3";

export default function Marketplace() {
  return <Productlist3 {...productlist3Demo} />;
}

Then replace the demo with your own props. The demo self-fetches from a hosted sample API; in your app, point productsUrl at your own endpoint (see Data modes) or pass a local products array.

import { Productlist3 } from "@/components/beste/block/productlist3";

export default function Marketplace() {
  return (
    <Productlist3
      heading="Marketplace"
      pageSize={15}
      productsUrl="/api/products"
      sortOptions={[
        { label: "Featured", value: "featured" },
        { label: "Price: Low to High", value: "price-asc" },
      ]}
      filterGroups={[
        { id: "q", label: "Search", type: "search", placeholder: "Search the catalog" },
        {
          id: "category",
          label: "Category",
          type: "segmented",
          options: [
            { label: "Shoes", value: "shoes" },
            { label: "Apparel", value: "apparel" },
          ],
        },
        {
          id: "brand",
          label: "Brand",
          type: "combobox",
          multiple: true,
          options: [{ label: "Acme", value: "acme" }],
        },
      ]}
    />
  );
}

The toolbar renders the search group stretched on the left; every other group sits inline and wraps. segmented keeps its natural width, other controls get a fixed width.

Props

ProductItem

{
  title: string;
  href: string;
  brand?: string;
  price: number;
  compareAtPrice?: number;      // struck-through original price
  image: { src: string; alt: string };
  badge?: string;               // corner badge, e.g. "Sale"
  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"], color: ["black"] }. A product matches an option group when any of its attribute values is selected.

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

Cascading filters (dependsOn)

A group with dependsOn: "<parentId>" stays disabled until its parent has a selection, and its own selection clears whenever the parent changes.

• Static: tag each option with parentValue; the engine filters options by the parent selection.
• Dynamic: leave options empty and pass loadOptions to the engine to fetch them per parent selection (results are cached).

{ id: "category", label: "Category", type: "select",
  options: [{ label: "Shoes", value: "shoes" }] },
{ id: "subcategory", label: "Subcategory", type: "select", dependsOn: "category",
  options: [{ label: "Sneakers", value: "sneakers", parentValue: "shoes" }] },

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, sorting, and pagination run locally.
2. Remote (productsUrl) — the block fetches each page itself. The endpoint receives ?filters=<json>&sort=&page=&pageSize= and must return { products, totalCount }. Pair with initialProducts/initialTotalCount for an SSR-rendered first page (fetch page 1 in a server component, pass it down, and only later interactions hit the network from the client).
3. Server (mode: "server") — you own the fetching (custom caching, URL sync). Every action calls onQueryChange; you fetch and feed products + totalCount back through props.

ProductQuery

What onQueryChange and the productsUrl request encode:

{
  filters: Record<string, string[]>; // selections per group id
  sort: string;                      // current sort value (passed through verbatim in server mode)
  page: number;                      // 1-based
  pageSize: number;
}

Filter value shapes inside filters:

• Option groups (checkbox, radio, chips, segmented, swatch, toggle, select, multiselect, combobox, tree, rating, price buckets): arrays of option values, e.g. { category: ["sneakers", "hoodies"] }.
• slider / range: a single "min-max" string, e.g. { price: ["25-150"] }; either side may be empty for an open range ("50-" = 50 and up).
• search: a single string, e.g. { q: ["sneaker"] }.

Behavior notes

• Any filter or sort change resets the page to 1, and changing a group clears every group that dependsOn it.
• Active selections render as removable chips inline next to the result count, so activating filters never pushes the grid down.
• Client-side sorting understands featured (input order), price-asc, price-desc, rating; any other value keeps input order (use custom values freely in server mode).
• Loading shows a skeleton grid with the same layout, so rows do not shift when data arrives.
• Product images use a plain <img>, so no next.config images.remotePatterns setup is needed. next/link handles product links.