Filterable Product Grid

Productlist1: Filterable Product Grid

Product listing section with a filter sidebar, sorting, pagination, active filter chips, and a mobile filter toggle. Filtering is powered by the shared product-filters engine, which installs automatically with this block. It works in two modes: fully client-side on a dataset you pass in, or server-driven where every user action emits a query object for your backend.

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

Base UI flavor

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

This installs the block to components/beste/block/productlist1.tsx, the engine to components/beste/component/product-filters.tsx, the 14 individual filter controls next to it, and the shadcn/ui dependencies they need.

Quick start

The installed file exports productlist1Demo alongside the block: the exact props behind the preview above, self-fetching from a hosted sample API. Spread it to get a working grid in one line.

import { Productlist1, productlist1Demo } from "@/components/beste/block/productlist1";

export default function ShopPage() {
  return <Productlist1 {...productlist1Demo} />;
}

Then replace the demo with your own props. The example below runs in client mode: pass the full dataset and filtering, sorting, and pagination all run locally, no callbacks needed.

import { Productlist1 } from "@/components/beste/block/productlist1";

export default function ShopPage() {
  return (
    <Productlist1
      heading="Shop all products"
      pageSize={9}
      sortOptions={[
        { label: "Featured", value: "featured" },
        { label: "Price: Low to High", value: "price-asc" },
      ]}
      filterGroups={[
        {
          id: "category",
          label: "Category",
          type: "checkbox",
          options: [
            { label: "Sneakers", value: "sneakers", count: 4 },
            { label: "T-Shirts", value: "t-shirts", count: 3 },
          ],
        },
        { id: "price", label: "Price", type: "slider", min: 0, max: 300, step: 5, unit: "$" },
      ]}
      products={[
        {
          title: "Velocity Running Sneakers",
          href: "/products/velocity-sneakers",
          price: 129,
          compareAtPrice: 159,
          image: { src: "/img/velocity.jpg", alt: "Red running sneakers" },
          badge: "Sale",
          rating: 4.8,
          reviewCount: 214,
          keywords: ["running", "red"],
          attributes: { category: ["sneakers"] },
        },
        // ...
      ]}
    />
  );
}

Key rule for client mode: each product's attributes object must be keyed by the same id values you use in filterGroups. A product matches a group when any of its attribute values is selected. Products without the attribute are filtered out once the group has a selection.

Props

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

Filter groups

Each entry in filterGroups is a ProductFilterGroup. Option-based groups match product.attributes[id].

type ProductFilterGroup = {
  id: string;
  label: string;
  type?: string;
  options?: ProductFilterOption[];
  min?: number;
  max?: number;
  step?: number;
  unit?: string;
  placeholder?: string;
  searchPlaceholder?: string;
  clearLabel?: string;
  multiple?: boolean;
  dependsOn?: string;
};

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 clears whenever the parent changes. Static: tag options with parentValue. Dynamic: leave options empty and pass loadOptions to the engine.

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

ProductQuery

What onQueryChange and the productsUrl request encode:

{
  filters: Record<string, string[]>; // selections per group id
  sort: string;                      // current sort value
  page: number;                      // 1-based
  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.

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.

Remote mode (productsUrl): the easiest server-driven setup

Point the block at an endpoint and it fetches its own data on every filter, sort, and page action. The endpoint receives ?filters=<json>&sort=&page=&pageSize= and must return { products, totalCount }. Filter semantics by group id: q is word search, price gets "min-max" range strings, rating a minimum threshold, everything else attribute-value arrays (this repo's /api/dummy-productlist route is a reference implementation with 100 products).

// Client-only: first page loads with a spinner
<Productlist1 productsUrl="/api/products" pageSize={20} filterGroups={...} />

For an SSR first page, fetch page 1 in a server component and pass it down; the block then skips the initial client fetch and only subsequent interactions hit the network from the client:

// app/shop/page.tsx (server component)
export default async function ShopPage() {
  const res = await fetch(
    "https://your-site.com/api/products?filters={}&sort=featured&page=1&pageSize=20",
    { cache: "no-store" }
  );
  const data = await res.json();
  return (
    <Productlist1
      productsUrl="/api/products"
      initialProducts={data.products}
      initialTotalCount={data.totalCount}
      pageSize={20}
      filterGroups={/* ... */ []}
    />
  );
}

Server mode (mode: "server"): full control

If you want to own the fetching yourself (custom caching, URL sync), use server mode; the component owns only the UI state and you feed data back through props:

"use client";

import { useCallback, useEffect, useState } from "react";
import { Productlist1 } from "@/components/beste/block/productlist1";

const PAGE_SIZE = 12;

export function CatalogPage() {
  const [products, setProducts] = useState([]);
  const [totalCount, setTotalCount] = useState(0);
  const [isLoading, setIsLoading] = useState(true);

  const fetchProducts = useCallback(async (query) => {
    setIsLoading(true);
    const params = new URLSearchParams({
      sort: query.sort,
      page: String(query.page),
      pageSize: String(query.pageSize),
      filters: JSON.stringify(query.filters),
    });
    const res = await fetch(`/api/products?${params}`);
    const data = await res.json();
    setProducts(data.products);
    setTotalCount(data.totalCount);
    setIsLoading(false);
  }, []);

  useEffect(() => {
    // Initial load: the component does not emit a query on mount
    fetchProducts({ filters: {}, sort: "featured", page: 1, pageSize: PAGE_SIZE });
  }, [fetchProducts]);

  return (
    <Productlist1
      mode="server"
      products={products}
      totalCount={totalCount}
      isLoading={isLoading}
      pageSize={PAGE_SIZE}
      onQueryChange={fetchProducts}
      filterGroups={/* same as client mode */ []}
      sortOptions={[{ label: "Featured", value: "featured" }]}
    />
  );
}

Server mode notes:

• products is treated as the already filtered, sorted, current page. No client-side processing happens.
• totalCount drives the "Showing x-y of z" text and the number of pagination buttons. Without it, pagination assumes a single page.
• Sort values are passed through verbatim, so you can use any backend sort keys (e.g. "newest", "bestselling"), not just the four built-in ones.
• The component does not call onQueryChange on mount. Do the initial fetch yourself (see the useEffect above).
• Search and min/max range inputs debounce onQueryChange by 300ms. All other actions emit immediately.

Behavior notes

• Any filter or sort change resets the page to 1, and changing a group clears every group that dependsOn it.
• In client mode, sorting understands exactly four values: "featured" (input order), "price-asc", "price-desc", and "rating". Other values fall back to input order.
• Clicking the active radio, segmented, or rating option clears that group.
• Active selections render as removable chips inline in the toolbar row (next to the "Showing x-y of z" text) with a "Clear all" action, so activating filters does not push the grid down.
• On screens below lg, the sidebar is hidden behind a "Filters" button that shows the active filter count.
• Prices render with a hardcoded $ prefix on product cards. Change the two ${product.price} spots in the grid markup if you need another currency.

Requirements

• Next.js (uses next/link). Product images render with a plain <img>, so no next.config images.remotePatterns setup is needed for remote hosts.
• Rendered as a client component ("use client"), so it composes into any App Router page.
• Non-negative numeric prices. Range parsing splits on -, so negative prices are not supported.