AwardsSection
Share awards and recognition with the awarding organization, year, logo, description, and external destination.
AwardsSection presents recognition as cards, badges, timelines, or a logo wall. Award details and destinations are supplied by the application.
Beta API maturity: Beta.
Installation
import {
AwardsSection,
type BusinessAward,
type AwardsSectionVariant,
} from "@puzzle-ui/pieces";Variant previews
Each of the ten variants has a separate preview, using fictional creative and hospitality awards.
grid - Display recognition in a responsive grid.
list - Keep award names and years easy to scan.
featured - Give a featured award more visual weight.
badges - Present achievements as compact badges.
timeline - Show recognition across the years.
cards - Give each award a defined card surface.
logo-wall - Emphasize awarding organizations and marks.
split - Balance award details across two columns.
compact - Fit several awards into a compact section.
editorial - Tell the story behind selected recognition.
API
| Prop | Type | Description |
|---|---|---|
variant | AwardsSectionVariant | grid (default), list, featured, badges, timeline, cards, logo-wall, split, compact, or editorial. |
items | readonly BusinessAward[] | Awards with unique IDs, title, organization, and year; optional logo, description, link, and featured state. |
featuredAward | BusinessAward | string | Optional award object or ID promoted to the lead position. |
BusinessAward.external | boolean | Opens the award destination in a new browsing context with noopener noreferrer. |
| Shared section props | MarketingSectionBaseProps | Heading, actions, root element, native section 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 | — |
featuredAward | No | — |
Usage
<AwardsSection
variant="timeline"
title="Recognition"
items={[
{
id: "studio-award",
title: "Independent Studio of the Year",
organization: "Design Guild",
year: 2025,
description: "Recognizing thoughtful work and lasting impact.",
href: "https://example.com/awards/studio",
external: true,
},
]}
/>Accessibility and rendering
Award names and organization names remain visible if a logo is absent. Provide useful alt text for informative logo images. Cards use semantic articles, award years are displayed as text, and links remain native anchors. The logo-wall variant uses a labeled list. IDs must be unique and stable. The component has no award-provider integration and renders on the server.
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 { AwardsSection } from "@puzzle-ui/pieces";
type AwardsSectionProps = ComponentProps<typeof AwardsSection>;
export function CustomizedSection(props: AwardsSectionProps) {
return <AwardsSection {...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 { AwardsSection } from "@puzzle-ui/pieces";
type AwardsSectionProps = ComponentProps<typeof AwardsSection>;
export function SectionWrapper(props: AwardsSectionProps) {
return <AwardsSection {...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.