CommerceCategory
Category preview cards ('shop by category'): a responsive grid of category cards (image + name + optional product count). Cards link to the category page when href is set. Presentational and theme-driven.
Installation
pnpm dlx @hex-core/cli add commerce-categoryUsage
import { CommerceCategory } from "@/components/ui/commerce-category"Shop-by-category grid
Three category cards with images and product counts.
import { CommerceCategory } from "@hex-core/components";
<CommerceCategory
title="Shop by category"
categories={[
{ name: "Bags", href: "/c/bags", productCount: "24 items", image: <img src="/c/bags.jpg" alt="Canvas tote bags" /> },
{ name: "Accessories", href: "/c/accessories", productCount: "48 items", image: <img src="/c/accessories.jpg" alt="Leather accessories" /> },
]}
/>Variant values
columnsCards per row on desktop.| Value | Description |
|---|---|
threedefault | Three across. |
four | Four across. |
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
categoriesrequired | object | — | ReadonlyArray<{ name; href?; image?: ReactNode; productCount? }>. Categories to render. Set href to make the whole card a link. |
title | ReactNode | — | Optional section heading above the grid. |
columns | enum | three | Cards per row on ≥lg: 'three' or 'four'. |
className | string | — | Additional classes applied to the root <section>. |
AI Guidance
When to use
Use on the storefront homepage to surface top-level categories. Pair with commerce-product-grid below for featured products. For deeper filtering, use commerce-category-filters on the category page.
When not to use
Don't use for product cards (use commerce-product-grid) or in-page filters (use commerce-category-filters). Don't show all categories — pick 3–8 most-shopped.
Common mistakes
- Omitting alt text on category images so the grid isn't screen-reader navigable.
- Mixing image aspect ratios — the card uses 4/3; supply consistently cropped images.
- Stale productCount values — either keep them live or omit the field.
Accessibility
When href is set the card is a single anchor with an accessible name from the category name. Images need alt text describing the category.
Related components
Token budget: 843
Verified against @hex-core/components@1.14.0