CategoriesSection
Organize ecommerce category links into responsive image grids, featured collections, lists, and carousels.
CategoriesSection displays structured category data for a storefront. Each category can supply an image, title, description, destination, and featured emphasis.
Beta API maturity: Beta.
Installation
import {
CategoriesSection,
type CategoryItem,
} from "@puzzle-ui/pieces";Variant previews
Every variant is shown in its own preview using fictional Morrow Home collections.
grid - Browse category cards in a responsive grid.
image-grid - Prioritize category imagery in a clean grid.
cards - Give each category a distinct card surface.
horizontal - Scroll through categories in a horizontal rail.
carousel - Move between categories with explicit controls.
editorial - Pair a lead category with supporting collections.
featured - Emphasize the category marked as featured.
split - Set a featured category beside a supporting list.
list - Present categories as full-width rows.
compact - Fit small category cards into a denser layout.
API
| Prop | Type | Description |
|---|---|---|
variant | CategoriesVariant | Selects one of ten compositions; defaults to grid. |
items | readonly CategoryItem[] | Category data with stable id and title. |
CategoryItem.image | CommerceImage | Optional { src, alt, width?, height?, loading? } data. |
CategoryItem.description | ReactNode | Optional category description. |
CategoryItem.href | string | Optional category destination rendered as a native link. |
CategoryItem.featured | boolean | Marks an item for featured layouts. |
| Shared section props | Marketing section props | Header, root element, theme, native attributes, and children. |
Required and default values
Requiredness follows the exported TypeScript type. A dash means no component-level default is applied; variant-specific requirements are described in the API table above.
| Prop | Required | Default |
|---|---|---|
variant | No | "grid" |
items | Yes | — |
Usage
const categories: CategoryItem[] = [
{
id: "lighting",
title: "Lighting",
description: "Soft light for considered rooms.",
image: {
src: "/collections/lighting.jpg",
alt: "Pendant lighting over a dining table",
},
href: "/collections/lighting",
featured: true,
},
{ id: "textiles", title: "Textiles", href: "/collections/textiles" },
];
<CategoriesSection
variant="image-grid"
title="Shop by room and ritual"
items={categories}
/>;Missing images use a placeholder. Category cards and links are presentational; the component does not query categories or rewrite destinations.
Accessibility
Category titles remain headings and destinations are native anchors. Give informative category images meaningful alternative text; use an empty alternative for decorative images. The carousel has explicit previous/next buttons, and the horizontal rail can receive keyboard focus.
Data and business logic
The application supplies category names, descriptions, images, links, and featured state. No product catalog or remote category data is requested.
Customization
Use the component's className and documented slots to adapt the composition. Prefer a caller-provided ReactNode for media, actions, or controls rather than adding domain behavior to the section.
import type { ComponentProps } from "react";
import { CategoriesSection } from "@puzzle-ui/pieces";
type CategoriesSectionProps = ComponentProps<typeof CategoriesSection>;
export function CustomizedSection(props: CategoriesSectionProps) {
return <CategoriesSection {...props} className={[props.className, "brand-section"].filter(Boolean).join(" ")} />;
}Responsive behavior
Use the preview device selector to review mobile, tablet, and desktop widths. The built-in variant controls section structure; ensure application-provided media, form controls, and children can shrink or wrap without horizontal overflow. Use the existing responsive breakpoints in scoped CSS when the consuming layout needs a product-specific adjustment.
Theme support
The section consumes semantic variables from @puzzle-ui/theme and inherits active or scoped themes. Wrap the application with Theme, and use semantic roles such as text, surface, border, and primary for local overrides. Avoid hard-coded colors, spacing, radii, and shadows.
.brand-section {
color: var(--puzzle-color-text);
background: var(--puzzle-color-surface);
border-color: var(--puzzle-color-border);
}Composition
Compose this section with the UI primitives named in its API and use the documented slots for consumer-owned controls or media. Keep data fetching, routing, validation, permissions, and persistence in the application. The children slot is intended for additional content that belongs with this section, not as a substitute for its typed data model.
TypeScript example
The package exports this component from its root. Derive a wrapper's exact prop type from the public component rather than widening it:
import type { ComponentProps } from "react";
import { CategoriesSection } from "@puzzle-ui/pieces";
type CategoriesSectionProps = ComponentProps<typeof CategoriesSection>;
export function SectionWrapper(props: CategoriesSectionProps) {
return <CategoriesSection {...props} />;
}Framework compatibility
The section is router-independent. Static compositions can be server-rendered; place callback-driven interactions in the framework's client boundary. See Next.js and TanStack Start integration for runnable framework examples and SSR guidance.