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.
cards - Give every team profile its own card surface.
featured - Introduce one featured member before the rest.
leadership - Highlight leadership and supporting profiles.
departments - Organize profiles by team or department.
horizontal - Browse profiles in a horizontal rail.
carousel - Keep a compact, keyboard-focusable profile carousel.
editorial - Give biographies an editorial profile layout.
compact - Fit more profiles into a smaller space.
asymmetric - Give a lead profile more visual weight.
profile - Keep profiles simple and people-first.
split - Balance profiles across two responsive columns.
API
| Prop | Type | Description |
|---|---|---|
variant | TeamSectionVariant | grid (default), cards, featured, leadership, departments, horizontal, carousel, editorial, compact, asymmetric, profile, or split. |
items | readonly BusinessProfile[] | Team members with unique IDs, name, role, and optional avatar, biography, profile link, department, and social links. |
departments | readonly 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. |
featuredMember | BusinessProfile | string | Optional profile or member ID emphasized in featured and leadership layouts. |
BusinessSocialLink.external | boolean | Opens a social link 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 | No | empty array |
departments | No | empty array |
featuredMember | No | — |
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.