Skip to Content

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.

390 × 844

list - Keep award names and years easy to scan.

390 × 844

featured - Give a featured award more visual weight.

390 × 844

badges - Present achievements as compact badges.

390 × 844

timeline - Show recognition across the years.

390 × 844

cards - Give each award a defined card surface.

390 × 844

logo-wall - Emphasize awarding organizations and marks.

390 × 844

split - Balance award details across two columns.

390 × 844

compact - Fit several awards into a compact section.

390 × 844

editorial - Tell the story behind selected recognition.

390 × 844

API

PropTypeDescription
variantAwardsSectionVariantgrid (default), list, featured, badges, timeline, cards, logo-wall, split, compact, or editorial.
itemsreadonly BusinessAward[]Awards with unique IDs, title, organization, and year; optional logo, description, link, and featured state.
featuredAwardBusinessAward | stringOptional award object or ID promoted to the lead position.
BusinessAward.externalbooleanOpens the award destination in a new browsing context with noopener noreferrer.
Shared section propsMarketingSectionBasePropsHeading, 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.

PropRequiredDefault
variantNo"grid"
itemsYes—
featuredAwardNo—

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.