Product Grid With Filter Drawer

Productlist2: Product Grid With Filter Drawer

Product catalog where every filter lives behind a single "Filters" button that opens a side drawer (Sheet): keyword search, cascading category and subcategory selects, a searchable multi-brand combobox, a size multiselect, and a segmented gender control. 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/productlist2?email=YOUR_EMAIL&license_key=YOUR_KEY"

Base UI flavor

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

This installs the block to components/beste/block/productlist2.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 productlist2Demo alongside the block: the exact props behind the preview above. Spread it to get a working catalog in one line.

import { Productlist2, productlist2Demo } from "@/components/beste/block/productlist2";

export default function ShopPage() {
  return <Productlist2 {...productlist2Demo} />;
}

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

import { Productlist2 } from "@/components/beste/block/productlist2";

export default function ShopPage() {
  return (
    <Productlist2
      heading="New season catalog"
      description="Open the filter drawer to narrow down one hundred styles."
      productsUrl="/api/products"
      pageSize={15}
      defaultSort="featured"
      sortOptions={[
        { label: "Featured", value: "featured" },
        { label: "Price: Low to High", value: "price-asc" },
        { label: "Top Rated", value: "rating" },
      ]}
      filterGroups={[
        { id: "q", label: "Search", type: "search", placeholder: "Search products" },
        {
          id: "category",
          label: "Category",
          type: "select",
          placeholder: "All categories",
          options: [
            { label: "Shoes", value: "shoes" },
            { label: "Apparel", value: "apparel" },
          ],
        },
        {
          id: "subcategory",
          label: "Subcategory",
          type: "select",
          dependsOn: "category",
          options: [
            { label: "Sneakers", value: "sneakers", parentValue: "shoes" },
            { label: "Hoodies", value: "hoodies", parentValue: "apparel" },
          ],
        },
        {
          id: "brand",
          label: "Brand",
          type: "combobox",
          multiple: true,
          searchPlaceholder: "Search brands",
          options: [
            { label: "Acme Supply", value: "acme" },
            { label: "Northwind", value: "northwind" },
          ],
        },
        {
          id: "size",
          label: "Size",
          type: "multiselect",
          options: [
            { label: "S", value: "s" },
            { label: "M", value: "m" },
          ],
        },
        { id: "price", label: "Price", type: "slider", min: 0, max: 300, step: 5, unit: "$" },
        {
          id: "gender",
          label: "Gender",
          type: "segmented",
          options: [
            { label: "Women", value: "women" },
            { label: "Men", value: "men" },
          ],
        },
      ]}
    />
  );
}

What is different from productlist1

• No sidebar and no toolbar row of controls: the toolbar holds only the result count with inline active-filter chips, a "Filters" button showing the active count, and the sort select.
• The button opens a right-side Sheet with every filterGroups entry stacked with its heading. Results update live behind the overlay; the footer offers "Clear all" and a "Show N products" close button.
• The demo shows a static cascade inside the drawer: picking a Category enables the Subcategory select, whose options are tagged with parentValue. Changing the category clears the subcategory automatically.
• Product cards use a 3:4 image, a brand eyebrow line, and an inline rating; the grid runs up to 4 columns.
• Pagination is Previous/Next with a "Page x of y" readout instead of numbered buttons.

Props

type ProductItem = {
  title: string;
  href: string;
  brand?: string;
  price: number;
  compareAtPrice?: number;
  image: { src: string; alt: string };
  badge?: string;
  rating?: number;
  reviewCount?: number;
  keywords?: string[];
  attributes?: Record<string, string[]>; // keyed by filter group id, e.g. { category: ["sneakers"] }
};

Filter groups

Each entry in filterGroups is a ProductFilterGroup.

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 (as the demo's Category → Subcategory does). 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, sorting, and pagination run locally.
2. Remote (productsUrl) — the block fetches each page itself. The endpoint receives ?filters=<json>&sort=&page=&pageSize= and returns { products, totalCount }. Pair with initialProducts for an SSR first page.
3. Server (mode: "server") — you own the fetching; every action calls onQueryChange, and you feed products + totalCount back through props.

ProductQuery

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

Behavior notes

• Any filter or sort change resets the page to 1, and changing a group clears every group that dependsOn it.
• Filters live in the drawer; the toolbar shows only the result count, inline active-filter chips, the "Filters" button (with active count), and the sort select.
• Product images use a plain <img>, so no next.config images.remotePatterns setup is needed. next/link handles product links.