Skip to Content

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.

390 × 844

image-grid - Prioritize category imagery in a clean grid.

390 × 844

cards - Give each category a distinct card surface.

390 × 844

horizontal - Scroll through categories in a horizontal rail.

390 × 844

carousel - Move between categories with explicit controls.

390 × 844

editorial - Pair a lead category with supporting collections.

390 × 844

featured - Emphasize the category marked as featured.

390 × 844

split - Set a featured category beside a supporting list.

390 × 844

list - Present categories as full-width rows.

390 × 844

compact - Fit small category cards into a denser layout.

390 × 844

API

PropTypeDescription
variantCategoriesVariantSelects one of ten compositions; defaults to grid.
itemsreadonly CategoryItem[]Category data with stable id and title.
CategoryItem.imageCommerceImageOptional { src, alt, width?, height?, loading? } data.
CategoryItem.descriptionReactNodeOptional category description.
CategoryItem.hrefstringOptional category destination rendered as a native link.
CategoryItem.featuredbooleanMarks an item for featured layouts.
Shared section propsMarketing section propsHeader, 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.

PropRequiredDefault
variantNo"grid"
itemsYes—

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.