Quick-Shop Product Grid

Productlist4: Quick-Shop Product Grid

A product grid with a left filter sidebar where hovering any card slides up a quick-shop tray: selectable size chips plus an "Add to cart" button, without leaving the grid. Cards also show a category tag and a sale/new badge. The toolbar above the grid holds the result count with removable active-filter chips, a mobile "Filters" button, and a sort dropdown; pagination is Previous/Next.

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

Base UI flavor

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

Quick start

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

import { Productlist4, productlist4Demo } from "@/components/beste/block/productlist4";

export default function Shop() {
  return <Productlist4 {...productlist4Demo} />;
}

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

import { Productlist4 } from "@/components/beste/block/productlist4";

export default function Shop() {
  return (
    <Productlist4
      heading="Shop the collection"
      pageSize={9}
      productsUrl="/api/products"
      onAddToCart={(product, size) =>
        console.log("add", product.title, size)
      }
      filterGroups={[
        { id: "q", label: "Search", type: "search", placeholder: "Search products" },
        {
          id: "category",
          label: "Category",
          type: "checkbox",
          options: [{ label: "Shoes", value: "shoes" }],
        },
        { id: "price", label: "Price", type: "slider", min: 0, max: 300, step: 5, unit: "$" },
      ]}
    />
  );
}

Quick-shop tray

Each card reads its available sizes from product.sizes (falling back to product.attributes.size) and renders them as selectable chips on hover. Clicking "Add to cart" calls onAddToCart(product, selectedSize) (with selectedSize null if none picked). When you don't pass onAddToCart, the button logs the full product plus selected size to the console so you can see it working. The tray is a hover interaction (desktop pattern); on touch, tapping the image or title navigates to the product.

Props

ProductItem

{
  title: string;
  href: string;
  brand?: string;
  price: number;
  compareAtPrice?: number;
  image: { src: string; alt: string };
  badge?: string;
  rating?: number;
  reviewCount?: number;
  sizes?: string[];             // quick-shop chips; falls back to attributes.size
  keywords?: string[];          // extra terms matched by "search"
  attributes?: Record<string, string[]>; // filterable values keyed by group id
}

attributes keys must match your filterGroups ids. A product matches an option group when any of its attribute values is selected. The card's category tag reads attributes.category[0].

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 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, 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;                      // 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.

Behavior notes

• Any filter or sort change resets the page to 1, and changing a group clears every group that dependsOn it.
• The sidebar is hidden on mobile behind a "Filters" button that shows the active filter count.
• Client-side sorting understands featured, price-asc, price-desc, rating; other values keep input order.
• Product images use a plain <img>, so no next.config images.remotePatterns setup is needed. next/link handles product links.