Skip to Content

TeamSection

Introduce people with responsive profile layouts, biography, avatar, social links, featured profiles, and departments.

TeamSection renders people as reusable profile cards. Use one flat member collection for a simple team, or provide department groups when the organization needs more structure.

Beta API maturity: Beta.

Installation

import {
  TeamSection,
  type BusinessProfile,
  type TeamSectionVariant,
} from "@puzzle-ui/pieces";

Variant previews

Each of the twelve variants has a separate preview. The fictional Northstar team includes a missing portrait to demonstrate the accessible avatar fallback.

grid - Show the whole team in a responsive grid.

390 × 844

cards - Give every team profile its own card surface.

390 × 844

featured - Introduce one featured member before the rest.

390 × 844

leadership - Highlight leadership and supporting profiles.

390 × 844

departments - Organize profiles by team or department.

390 × 844

horizontal - Browse profiles in a horizontal rail.

390 × 844

carousel - Keep a compact, keyboard-focusable profile carousel.

390 × 844

editorial - Give biographies an editorial profile layout.

390 × 844

compact - Fit more profiles into a smaller space.

390 × 844

asymmetric - Give a lead profile more visual weight.

390 × 844

profile - Keep profiles simple and people-first.

390 × 844

split - Balance profiles across two responsive columns.

390 × 844

API

PropTypeDescription
variantTeamSectionVariantgrid (default), cards, featured, leadership, departments, horizontal, carousel, editorial, compact, asymmetric, profile, or split.
itemsreadonly BusinessProfile[]Team members with unique IDs, name, role, and optional avatar, biography, profile link, department, and social links.
departmentsreadonly BusinessDepartment[]Optional named groups, each with a stable ID and member collection. The departments variant groups items by member department when explicit groups are absent.
featuredMemberBusinessProfile | stringOptional profile or member ID emphasized in featured and leadership layouts.
BusinessSocialLink.externalbooleanOpens a social link 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"
itemsNoempty array
departmentsNoempty array
featuredMemberNo—

Usage

<TeamSection
  variant="departments"
  title="Meet the team"
  departments={[
    {
      id: "design",
      name: "Design",
      members: [
        {
          id: "leo",
          name: "Leo Okafor",
          role: "Design director",
          biography: "He turns ambitious ideas into useful experiences.",
        },
      ],
    },
  ]}
/>

Accessibility and rendering

Member names are headings, missing avatars fall back to initials with an accessible name, and social links are native anchors. Horizontal layouts are keyboard-focusable scroll regions. Keep IDs unique and stable between renders; the component validates member and department IDs. Empty and single-member teams are supported without placeholder cards. Rendering is server compatible.

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

type TeamSectionProps = ComponentProps<typeof TeamSection>;

export function CustomizedSection(props: TeamSectionProps) {
  return <TeamSection {...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 { TeamSection } from "@puzzle-ui/pieces";

type TeamSectionProps = ComponentProps<typeof TeamSection>;

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