Skip to Content

Resource Section

Build searchable libraries of guides, downloads, templates, and webinars with caller-provided resources.

ResourceSection presents an application-provided collection with search, category filtering, download links, and a featured item. It does not host files or fetch a catalog.

Basic usage

Each resource has a stable ID, title, and link. Add download for browser downloads, a category for filtering, and a type label for the kind of resource.

390 × 844

Variants and filters

Search is a trimmed, case-insensitive substring match over title, text description, category, and type. Categories are derived from supplied items. Use searchable={false} or filterable={false} to remove either control.

grid - Browse a general-purpose resource collection.

390 × 844

featured - Lead with a recommended guide.

390 × 844

downloads - Present downloadable templates and files.

390 × 844

categories - Filter resources by subject.

390 × 844

list - Keep descriptions readable in a vertical list.

390 × 844

cards - Give each resource a distinct card.

390 × 844

library - Build a broad learning library.

390 × 844

split - Pair a featured item with supporting resources.

390 × 844

filterable - Search and filter the supplied collection.

390 × 844

webinars - Show webinar and education recordings.

390 × 844
VariantUse case
gridGeneral resource collection.
featuredLead with one featured resource.
downloadsPresent downloadable guides and files.
categoriesBrowse subject-specific resources.
listShow longer descriptions in a vertical list.
cardsSeparate resources into cards.
libraryCreate a larger learning library.
splitPair a featured item and supporting links.
filterableHighlight the search and category controls.
webinarsPresent recorded or upcoming sessions.
390 × 844

Accessibility and customization

  • Search and category controls have visible labels and native keyboard behavior.
  • Resource titles are links, downloads use the browser download attribute, and media is supplied through the optional thumbnail slot.
  • Empty results use the shared EmptyStatePanel composition; pass emptyState to add context.
  • Theme colors, borders, spacing, and card surfaces come from Puzzle tokens and UI Card/Badge.
  • The children slot can add a call to action or resource-specific explanatory content.

API

PropTypeRequiredDefaultDescription
itemsreadonly ResourceItem[]Yes—Resource records; IDs must be unique.
variantResourceSectionVariantNogridLayout variant.
featuredResourceIdstringNoFirst featured itemExplicit featured item ID.
searchablebooleanNotrueRender the search field.
filterablebooleanNotrueRender the category selector when categories exist.
emptyStateReactNodeNo—Additional no-results content.
childrenReactNodeNo—Additional content after the resources.

ResourceItem supports id, title, href, description, category, type, download, featured, thumbnail, and updatedAt.

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 { ResourceSection } from "@puzzle-ui/pieces";

type ResourceSectionProps = ComponentProps<typeof ResourceSection>;

export function SectionWrapper(props: ResourceSectionProps) {
  return <ResourceSection {...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.