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.
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.
featured - Lead with a recommended guide.
downloads - Present downloadable templates and files.
categories - Filter resources by subject.
list - Keep descriptions readable in a vertical list.
cards - Give each resource a distinct card.
library - Build a broad learning library.
split - Pair a featured item with supporting resources.
filterable - Search and filter the supplied collection.
webinars - Show webinar and education recordings.
| Variant | Use case |
|---|---|
grid | General resource collection. |
featured | Lead with one featured resource. |
downloads | Present downloadable guides and files. |
categories | Browse subject-specific resources. |
list | Show longer descriptions in a vertical list. |
cards | Separate resources into cards. |
library | Create a larger learning library. |
split | Pair a featured item and supporting links. |
filterable | Highlight the search and category controls. |
webinars | Present recorded or upcoming sessions. |
Accessibility and customization
- Search and category controls have visible labels and native keyboard behavior.
- Resource titles are links, downloads use the browser
downloadattribute, and media is supplied through the optional thumbnail slot. - Empty results use the shared
EmptyStatePanelcomposition; passemptyStateto add context. - Theme colors, borders, spacing, and card surfaces come from Puzzle tokens and UI
Card/Badge. - The
childrenslot can add a call to action or resource-specific explanatory content.
API
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
items | readonly ResourceItem[] | Yes | — | Resource records; IDs must be unique. |
variant | ResourceSectionVariant | No | grid | Layout variant. |
featuredResourceId | string | No | First featured item | Explicit featured item ID. |
searchable | boolean | No | true | Render the search field. |
filterable | boolean | No | true | Render the category selector when categories exist. |
emptyState | ReactNode | No | — | Additional no-results content. |
children | ReactNode | No | — | Additional content after the resources. |
ResourceItem supports id, title, href, description, category, type, download, featured, thumbnail, and updatedAt.
Related components
- Blog Section for editorial articles.
- Event Section for dated programs and sessions.
- Card and Badge provide the resource surfaces and type labels.
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.