# Product Grid

> A collection page grid: breadcrumb, title and collection pills over a sticky toolbar with quick filters, sort and a 2, 3 or 4 column density toggle (1 or 2 on phones). Tiles swap to a second photo on hover, swatches change the shot, badges show New and −20%, a heart saves to the wishlist, and quick add rises with sizes and confirms in place. Load more fills a progress bar.

- Slug: `product-grid`
- Category: [Commerce](https://www.assembli.design/category/commerce.md)
- Type: block
- Tags: ecommerce, product-grid, collection, category-page, product-listing, quick-add, wishlist, sort, shop
- npm dependencies: @base-ui/react, lucide-react, motion
- shadcn/ui dependencies: none
- Live preview: https://www.assembli.design/preview/product-grid
- Page: https://www.assembli.design/components/product-grid

![Product Grid preview](https://www.assembli.design/thumbnails/product-grid-light.png)

## Props

Other props pass through to the root element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `products` (required) | `ProductGridProduct[]` |  |  |
| `title` (required) | `React.ReactNode` |  |  |
| `description` | `React.ReactNode` |  |  |
| `breadcrumbs` | `{ label: string; href?: string }[]` |  |  |
| `collections` | `ProductGridCollection[]` |  | Collection pills under the title. The first one should be "All" with the value "all". |
| `defaultCollection` | `string` | `"all"` |  |
| `pageSize` | `number` | `8` | Products shown before Load more, and how many each press adds. |
| `defaultSort` | `ProductGridSort` | `"featured"` |  |
| `defaultColumns` | `2 \| 3 \| 4` | `4` | Columns on wide containers (2–4) and on phones (1–2). |
| `defaultPhoneColumns` | `1 \| 2` | `2` |  |
| `quickFilters` | `boolean` | `true` | Built-in quick filters (in stock, on sale, new, colors). |
| `filters` | `React.ReactNode` |  | Your own filter control, e.g. Product Filters in sheet mode, placed first in the toolbar. |
| `onAddToBag` | `(product: ProductGridProduct, detail: ProductGridAddDetail) => void \| Promise<u…` |  | Return a promise to show "Adding…" until it settles. |
| `defaultWishlist` | `string[]` | `[]` |  |
| `onWishlistChange` | `(ids: string[]) => void` |  |  |
| `currency` | `string` | `"USD"` |  |
| `locale` | `string` | `"en-US"` |  |

## Install

One-time setup (needs a subscription):

1. Add the registry to the project's `components.json`: `{"@assembli":{"url":"https://www.assembli.design/r/{name}.json","headers":{"Authorization":"Bearer ${ASSEMBLI_API_KEY}"}}}` (merge into `"registries"`).
2. Put an API key from https://www.assembli.design/account in `.env.local` as `ASSEMBLI_API_KEY=asm_…`.

Then install with the shadcn CLI (writes `components/product-grid/product-grid.tsx` and installs dependencies):

```bash
npx shadcn@latest add @assembli/product-grid
```

Registry item JSON: https://www.assembli.design/r/product-grid.json (send `Authorization: Bearer <api key>`)

## Code

> Component source needs an Assembli subscription ($12/month or $96/year) and an API key sent as `Authorization: Bearer <key>`. To get one without copying anything, POST https://www.assembli.design/api/agent/login (or call the MCP tool connect_account), show the user the link it returns, and poll https://www.assembli.design/api/agent/token for the key. Or subscribe at https://www.assembli.design/pricing and create a key at https://www.assembli.design/account.