People Grid
alphav0.3.0Responsive grid of person cards — avatar with initials fallback, name, title, per-card links, and a custom item renderer.
Context
Use for conference speakers, team / about-us pages, board / committee lists, contributor grids, podcast guests, course instructors, judge lineups. Migration origin: kasder kas-social-front-v0 events/[id]/page.tsx Konuşmacılar (Speakers) block. The `getInitials` helper is reusable for mention chips, comment headers, contact rows.
Installation
pnpm dlx shadcn@latest initpnpm dlx shadcn@latest add @ilinxa/people-gridAdd -fixtures for dummy data:
pnpm dlx shadcn@latest add @ilinxa/people-grid-fixturesCLI can't resolve @ilinxa? The namespace is listed in the official shadcn registry directory, so current CLIs need no configuration. If yours can't resolve it (older or pinned versions, self-hosted mirrors), register it manually in components.json:
"registries": {
"@ilinxa": "https://ui.ilinxa.com/r/{name}.json"
}Preview
Konuşmacılar
Prof. Dr. Ahmet Yılmaz
Şehir Plancısı
Dr. Elif Kaya
Çevre Mühendisi
Mehmet Demir
Akıllı Şehir Uzmanı
Demo source
"use client"; import { AtSign, BadgeCheck, Briefcase, Globe } from "lucide-react";import { Tabs, TabsContent, TabsTrigger } from "@/components/ui/tabs";import { SwipeTabsList } from "@/components/site/swipe-tabs-list";import { PeopleGrid } from "./people-grid";import { dummyBoard, dummyRtlPeople, dummySpeakers, dummyTeam, dummyTurkishPeople,} from "./dummy-data"; const speakerSocial: Record< string, { handle?: string; work?: string; site?: string }> = { s1: { handle: "#", work: "#" }, s2: { work: "#", site: "#" }, s3: { handle: "#", site: "#" },}; export default function PeopleGridDemo() { return ( <Tabs defaultValue="default" className="w-full"> <SwipeTabsList> <TabsTrigger value="default">Default (TR)</TabsTrigger> <TabsTrigger value="initials">Initials fallback</TabsTrigger> <TabsTrigger value="columns">Columns 2-5</TabsTrigger> <TabsTrigger value="linked">Linked + actions</TabsTrigger> <TabsTrigger value="custom">Custom renderItem</TabsTrigger> <TabsTrigger value="slots">Slots + locale (TR)</TabsTrigger> <TabsTrigger value="rtl">RTL</TabsTrigger> </SwipeTabsList> {/* 1. Default — kasder Konuşmacılar verbatim */} <TabsContent value="default" className="mt-6"> <div className="max-w-4xl mx-auto"> <PeopleGrid heading="Konuşmacılar" items={dummySpeakers} columns={3} /> </div> </TabsContent> {/* 2. Initials fallback — names only, no images */} <TabsContent value="initials" className="mt-6"> <div className="max-w-4xl mx-auto space-y-2"> <p className="text-sm text-muted-foreground"> No <code>image</code> fields — falls back to{" "} <code>getInitials(name)</code>. Note titles (Dr./Prof./Mr./Ms./etc.) are skipped when computing initials. </p> <PeopleGrid heading="Board of Directors" items={dummyBoard} columns={5} avatarSize="md" /> </div> </TabsContent> {/* 3. Columns variants — 2 / 3 / 4 / 5 stacked */} <TabsContent value="columns" className="mt-6"> <div className="max-w-5xl mx-auto space-y-10"> <p className="text-sm text-muted-foreground"> Same 6-person team rendered with <code>columns</code> 2 / 3 / 4 / 5. All grids start at <code>grid-cols-1</code> on mobile and scale up at sm/md/lg breakpoints. For wider columns (<code>4</code> / <code>5</code>), pair with{" "} <code>avatarSize="sm"</code> or{" "} <code>"md"</code> for narrow containers. </p> <PeopleGrid heading="2 columns (lg avatar)" headingAs="h3" items={dummyTeam} columns={2} avatarSize="lg" /> <PeopleGrid heading="3 columns (lg avatar — kasder default)" headingAs="h3" items={dummyTeam} columns={3} avatarSize="lg" /> <PeopleGrid heading="4 columns (md avatar)" headingAs="h3" items={dummyTeam} columns={4} avatarSize="md" /> <PeopleGrid heading="5 columns (sm avatar, start-aligned)" headingAs="h3" items={dummyTeam} columns={5} avatarSize="sm" alignment="start" /> </div> </TabsContent> {/* 4. Linked — entire card is a link */} <TabsContent value="linked" className="mt-6"> <div className="max-w-4xl mx-auto space-y-2"> <p className="text-sm text-muted-foreground"> Each card has <code>href</code> — entire card surface is clickable. Tab to a card and you'll see the focus-visible ring covering the whole rectangle. Polymorphic{" "} <code>linkComponent</code> works with NextLink / RemixLink / etc. </p> <PeopleGrid heading="Speakers" items={dummySpeakers.map((s) => ({ ...s, href: `/speakers/${s.id}`, }))} columns={3} /> </div> </TabsContent> {/* 5. Custom renderItem — speakers with social links */} <TabsContent value="custom" className="mt-6"> <div className="max-w-4xl mx-auto space-y-2"> <p className="text-sm text-muted-foreground"> <code>renderItem</code> — full per-card takeover. Here: append a social-link row beneath the title. </p> <PeopleGrid heading="Konuşmacılar" items={dummySpeakers} columns={3} renderItem={(item) => { const social = speakerSocial[item.id]; return ( <div className="text-center"> <div className="w-24 h-24 rounded-full overflow-hidden border-4 border-primary/20 mx-auto mb-3"> {item.image && ( <img src={item.image} alt="" loading="lazy" className="w-full h-full object-cover" /> )} </div> <h3 className="font-semibold text-foreground"> {item.name} </h3> <p className="text-sm text-muted-foreground mb-2"> {item.title} </p> {social && ( <div className="flex justify-center gap-2 text-muted-foreground"> {social.handle && ( <a href={social.handle} aria-label={`${item.name} social handle`} className="hover:text-primary" > <AtSign aria-hidden="true" className="w-4 h-4" /> </a> )} {social.work && ( <a href={social.work} aria-label={`${item.name} professional profile`} className="hover:text-primary" > <Briefcase aria-hidden="true" className="w-4 h-4" /> </a> )} {social.site && ( <a href={social.site} aria-label={`${item.name} personal website`} className="hover:text-primary" > <Globe aria-hidden="true" className="w-4 h-4" /> </a> )} </div> )} </div> ); }} /> </div> </TabsContent> {/* 6. Slots + locale — Turkish casing, action button, verified badge */} <TabsContent value="slots" className="mt-6"> <div className="max-w-4xl mx-auto space-y-2"> <p className="text-sm text-muted-foreground"> <code>locale="tr"</code> upper-cases initials the Turkish way (ilker → İY, şule → ŞÇ). <code>renderBadge</code> and{" "} <code>renderActions</code> sit above the card link, so clicking them never navigates. Tab order: slots, then the card link. </p> <PeopleGrid heading="Ekip" items={dummyTurkishPeople.map((p) => ({ ...p, href: `/ekip/${p.id}` }))} columns={3} locale="tr" renderBadge={(item) => item.id === "tr1" ? ( <BadgeCheck role="img" aria-label="Doğrulanmış" className="w-4 h-4 text-primary" /> ) : null } renderActions={(item) => ( <button type="button" className="rounded-md border border-border bg-card px-3 py-1 text-sm hover:bg-muted" > {item.id === "tr2" ? "Takip et" : "Bağlan"} </button> )} /> </div> </TabsContent> {/* 7. RTL — logical alignment, mirrored grid */} <TabsContent value="rtl" className="mt-6"> <div dir="rtl" lang="ar" className="max-w-4xl mx-auto space-y-2"> <p className="text-sm text-muted-foreground"> Inside <code>dir="rtl"</code>: the grid flows right to left and start-aligned cards align to the right. </p> <PeopleGrid heading="الفريق" items={dummyRtlPeople} columns={3} alignment="start" locale="ar" renderActions={() => ( <button type="button" className="rounded-md border border-border bg-card px-3 py-1 text-sm hover:bg-muted" > متابعة </button> )} /> </div> </TabsContent> </Tabs> );} Usage
When to use
Reach for PeopleGrid when you need a section heading + responsive grid of person cards (round avatar + name + title) — for conference speakers, team / about-us pages, board / committee lists, contributors, podcast guests, course instructors, judge lineups. Avatar gracefully falls back to initials when image is missing.
Upgrading to 0.3.0
- Card names are now one heading level below the section (
h2section →h3cards; 0.2.0 always renderedh4). PasscardHeadingAs="h4"to keep the old output. - The avatar
altnow defaults to""(decorative — the name is the heading right beside it). SetimageAltper item to restore a text alternative (0.2.0 used the name).
Minimal example
import { PeopleGrid } from "@/components/people-grid";
<PeopleGrid
heading="Konuşmacılar"
items={event.speakers.map((s, i) => ({
id: String(i),
name: s.name,
title: s.title,
image: s.image,
}))}
columns={3}
/>;Public helper kernel — getInitials
The initials helper is exported as a pure function. Reuse it in mention chips, comment headers, contact rows, presence badges:
import { getInitials } from "@/components/people-grid";
getInitials("Dr. Ahmet Yılmaz") // → "AY"
getInitials("Prof. Dr. Elif Kaya") // → "EK"
getInitials("Madonna") // → "M"
getInitials("") // → "?"
// Locale-aware casing (string shorthand or options object)
getInitials("ilker yılmaz", "tr") // → "İY"
getInitials("Sayın Ali Veli", { honorifics: ["sayın"] }) // → "AV"
getInitials("", { fallback: "·" }) // → "·"
// Default honorifics skipped: Dr., Prof., Mr., Mrs., Ms., Sr., Jr.
// (a custom list or RegExp replaces them). First grapheme, not first UTF-16 unit.Columns × avatar size
All grids start at grid-cols-1 on mobile and scale up at sm/md/lg breakpoints based on columns:
columns=2— 1 col mobile, 2 col sm:+columns=3— 1 col mobile, 2 col sm:, 3 col md:+columns=4— 1 col mobile, 2 col sm:, 4 col md:+columns=5— 1 col mobile, 2 col sm:, 3 col md:, 5 col lg:+
For columns: 4 or 5 in narrow containers, pair with avatarSize: "sm" or "md" — large avatars (w-24 h-24) at 4-5 columns need ~600px+ to render without crowding. Defaults (columns: 3, avatarSize: "lg") match kasder and work everywhere down to mobile.
Avatar fallback
Items without image render an initials circle with bg-primary/10 text-primary font-semibold. The component handles common honorifics (Dr./Prof./Mr./etc.) by skipping them when computing initials:
<PeopleGrid
heading="Board of Directors"
items={[
{ id: "1", name: "Dr. Sara Ahmed", title: "Chair" }, // → "SA"
{ id: "2", name: "Prof. James O'Neill", title: "Vice-Chair" }, // → "JO"
{ id: "3", name: "Madonna", title: "Director" }, // → "M"
]}
// no image fields — all render with initials
/>Polymorphic linkComponent
import NextLink from "next/link";
<PeopleGrid
heading="Our Team"
items={team.map((m) => ({ ...m, href: `/team/${m.slug}` }))}
linkComponent={NextLink}
columns={4}
/>When hrefis supplied, the entire card becomes clickable via the overlay-link pattern. The link's accessible name = the person's name (via aria-labelledby) — screen reader announces just the name, not the flattened title/image-alt.
Action + badge slots
<PeopleGrid
heading="Ekip"
locale="tr"
items={people}
renderBadge={(p) => (p.verified ? <VerifiedMark /> : null)}
renderActions={(p) => <Button onClick={() => follow(p.id)}>Takip et</Button>}
/>Slots sit above the card link, so clicking them never navigates. Tab order per card: badge, actions, then the card link. They apply to the default card only — renderItem replaces the whole card.
Custom renderItem
<PeopleGrid
items={speakers}
renderItem={(person) => (
<div className="text-center">
<Avatar src={person.image} />
<p className="font-semibold">{person.name}</p>
<p className="text-sm text-muted-foreground">{person.title}</p>
<SocialLinks links={person.social} />
</div>
)}
/>Empty state
Empty items → renders emptyState if provided, else <p role="status"> with labels.emptyText(default "No people to display.").
Notes
- Renders
<ul role="list">; sectionaria-labelledbyresolves to the heading id (viauseId) when heading is supplied. - Heading defaults to
h2(people grids are top-level page sections — Speakers, Team, Contributors); card names default to one level below it (cardHeadingAsoverrides). - No
framedprop — people grids are typically standalone page sections, not nested cards. Wrap externally if you need card chrome. - Initials fallback is
aria-hidden; the name in the adjacent card heading is what screen readers announce. - Hover-color transition on the name is gated via
motion-safe:— reduced-motion users see static text.
Features
- Responsive grid — columns 2/3/4/5 with built-in breakpoint scaling (all start at 1 col mobile)
- Avatar size variants (sm/md/lg)
- Alignment (center/start)
- Card heading one level below the section heading by default (h2 -> h3); cardHeadingAs overrides (h3-h6)
- renderActions / renderBadge slots on the default card, raised above the card link so their clicks never navigate (tab order: badge, actions, card link)
- locale prop — locale-aware initials casing (tr: ilker yılmaz -> İY)
- Image pass-through: imageWidth / imageHeight / imageSrcSet / imageSizes, decoding=async; avatar alt defaults to empty (decorative), imageAlt overrides
- Initials fallback when image is missing — handles Dr./Prof./etc. honorifics
- Public getInitials(name, locale | { locale, honorifics, fallback }) helper — grapheme-safe, locale-aware, custom honorifics
- Polymorphic per-card link via linkComponent + per-item href (overlay-link pattern)
- Custom renderItem slot for full per-person takeover
- Optional section heading with configurable level (h2/h3/h4, default h2)
- Soft-failure on optional fields (title / image / imageAlt / href)
- labels.emptyText with an undefined value keeps its default; defaultPeopleGridLabels exported (DEFAULT_PEOPLE_GRID_LABELS kept as a deprecated alias)
- Empty state slot + labels.emptyText fallback
- <ul role='list'> semantics + section aria-labelledby
- aria-labelledby on per-card link → accessible name = person's name only
- Memoised card (React.memo)