# Component Reference

Quick reference for all 38 Puck editor components.

## Legend

- **Static**: All data entered manually in the editor — no database needed
- **Dynamic**: Can fetch data from DB (Auto mode) or accept manual input (Manual mode)
- **Editor + Server**: Has two files — an editor preview and a server-rendered version

---

## Hero & Banner (8 components)

| Component | Type | Description | Key Props |
|---|---|---|---|
| `HeroSection` | Static | Full-width hero with video/image/gradient background, overlay, CTA button | title, subtitle, tagline, bgVideo, bgImage, bgColor, gradients, button |
| `BannerCTA` | Static | Promotional banner with headline, description, background image | headline, description, bgImage, ctaText, ctaUrl |
| `HeroVideoCinematic` | Static | Cinematic hero with video or image background, gradient overlay | title, subtitle, description, bgVideo, bgImage, overlayOpacity, button |
| `HeroSlideCarousel` | Static (Editor+Server) | Multi-slide carousel with images, titles, descriptions, tags | slides[] (image, title, description, tag, linkUrl), theme |
| `HeroFullWidthSlider` | Static | Full-viewport slider with crossfade transitions, autoplay | slides[] (image, title, description, tag, linkUrl), autoplaySpeed |
| `SplitContentHero` | Static | Two-column hero with text on one side, image on the other | title, subtitle, image, imagePosition (left/right), button |
| `HeroBlogCarousel` | **Dynamic** (Editor+Server) | Carousel of latest blog articles with category badges | sectionTitle, articleCount, dataMode, manualItems[], showCategoryBadge |
| `FeaturedArticleHero` | **Dynamic** (Editor+Server) | Large featured article showcase with image overlay | dataMode, manualItems[] (use 1 entry), theme |

---

## Content (7 components)

| Component | Type | Description | Key Props |
|---|---|---|---|
| `IntroSection` | Static | Intro block with title, subtitle, body text, optional CTA | title, subtitle, body, ctaText, ctaHref, showDivider |
| `TextParagraph` | Static | Simple text content block (heading + body) | heading, body, style (standard/centered/pullquote) |
| `SectionHeading` | Static | Section header with category label, title, subtitle | categoryLabel, title, subtitle, align, anchorId, button |
| `RichText` | Static | HTML content block (for pasting formatted content) | content (HTML string) |
| `ImageBlock` | Static | Single image with optional caption | src (upload), alt, caption, fullWidth |
| `VideoEmbed` | Static | Video player (upload or URL) | url (upload), title, aspectRatio |
| `Glossary` | Static | Expandable glossary of key terms | title, terms[] (term, reading, desc) |

---

## Lists & Rankings (4 components)

| Component | Type | Description | Key Props |
|---|---|---|---|
| `RankedTopList` | Static | Ranked list of services/products with ratings, CTAs | sectionTitle, items[] (23 fields each!), link attrs |
| `ReviewSection` | Static | Service review cards with ratings, logos, pros/cons | sectionTitle, items[] (10 fields), link attrs |
| `DetailedServiceCard` | Static | Single detailed review card with radar chart, bonus info | 25+ fields including radar chart, bonus, trust |
| `ServiceDetailBlock` | Static | Detailed service breakdown with ratings, pros/cons | 15+ fields including radar, author impression |

---

## Tables (2 components)

| Component | Type | Description | Key Props |
|---|---|---|---|
| `DataTable` | Static | Generic data table with configurable columns | sectionTitle, columns[] (key, label, align), rows[] |
| `ComparisonTable` | Static | Side-by-side comparison of services/products | sectionTitle, attributes[], items[] (13 fields), itemsPerPage |

---

## Interactive (5 components)

| Component | Type | Description | Key Props |
|---|---|---|---|
| `ProcessSteps` | Static | Step-by-step process cards in a grid | sectionTitle, subtitle, columns, steps[] (icon, title, desc) |
| `StepsTimeline` | Static | Vertical timeline of steps | title, subtitle, steps[] (title, description) |
| `FAQ` | Static | Expandable FAQ accordion | title, items[] (question, answer) |
| `ProcessFlow` | Static | Numbered process flow (01, 02, 03...) | heading, steps[] (number, title, description) |
| `CommonProblems` | Static | Grid of common problems/pain points | title, subtitle, troubles[] (question, category, icon) |

---

## Cards & Showcase (5 components)

| Component | Type | Description | Key Props |
|---|---|---|---|
| `CategoryGrid` | Static | Grid of category cards with icons and links | title, subtitle, items[] (label, href, icon), button |
| `HighlightCards` | Static | Two highlight cards side by side | title, subtitle, card1/card2 (title, desc, href, icon) |
| `FeaturesGrid` | Static | Feature cards in a grid with icons | title, subtitle, features[] (title, desc, icon), button |
| `TargetAudience` | Static | Two audience-targeting cards | card1/card2 (title, desc, linkUrl, linkText) |
| `ArticleCardCarousel` | Static | Horizontal scrolling article cards | cards[] (image, title, excerpt, category, linkUrl), autoplaySpeed |

---

## Promotions & CTA (2 components)

| Component | Type | Description | Key Props |
|---|---|---|---|
| `CTAButton` | Static | Standalone call-to-action button | text, href, variant, align, showArrow |
| `AppPromoSection` | Static | App/service promotion with feature cards | title, subtitle, features[] (title, desc, icon) |

---

## Navigation (3 components)

| Component | Type | Description | Key Props |
|---|---|---|---|
| `StickyNav` | Static | Sticky navigation bar (top/bottom/inline) | position (top/bottom/inline), items[] (label, anchorId) |
| `TableOfContents` | Static | Nested table of contents with sub-items | title, showNumbers, items[] (label, anchorId, subItems[]) |
| `IconNavGrid` | Static | Grid of icon navigation links | items[] (label, href, icon), link attrs |

---

## Newsletter (2 components)

| Component | Type | Description | Key Props |
|---|---|---|---|
| `NewsletterFull` | Static | Full newsletter signup section | title, subtitle, placeholderText, buttonText |
| `NewsletterInline` | Static | Compact inline newsletter CTA | title, description, buttonText |

---

## Author (2 components)

| Component | Type | Description | Key Props |
|---|---|---|---|
| `AuthorBox` | **Dynamic** (Editor+Server) | Compact author card — fetches name, bio, avatar, role, and social links from DB | authorSlug, showBio |
| `AuthorProfile` | Static | Full author profile with avatar, bio, role, and social links | authorName, authorRole, authorBio, authorAvatar (upload), socialTwitter, socialInstagram, socialYoutube, socialLinkedin, socialWebsite |

### AuthorBox Detail
The `AuthorBox` component fetches author information from the database using `getAuthorInfo()`. If the DB returns social link fields (`socialTwitter`, `socialInstagram`, etc.), they render as icon buttons. The `authorSlug` field lets the editor user specify which author to display (defaults to the primary/default author if empty).

### AuthorProfile Detail
The `AuthorProfile` component is fully static — all data is entered in the editor. Social links are optional; only links with URLs filled in will display as icon buttons.

---

## Layout (2 components)

| Component | Type | Description | Key Props |
|---|---|---|---|
| `Spacer` | Static | Vertical space between components | height (8-256 px) |
| `Divider` | Static | Horizontal line separator | label, style (solid/dashed/dotted) |

---

## Dynamic Content (6 components)

| Component | Type | Description | Key Props |
|---|---|---|---|
| `BlogGrid` | **Dynamic** (Editor+Server) | Grid of latest blog posts | title, count, columns, dataMode, manualItems[] |
| `ArticleTrendingRanking` | **Dynamic** (Editor+Server) | Split view: trending + ranking lists | titles, counts, trendingMode, rankingMode, manualItems[] |
| `ArticleCategorySections` | **Dynamic** (Editor+Server) | Articles grouped by category | articlesPerCategory, showViewMore, dataMode, manualCategories[] |
| `FeaturedArticleSpotlight` | **Dynamic** (Editor+Server) | Spotlight on featured articles | sectionTitle, articleCount, dataMode, manualItems[] |
| `TwoColumnLayout` | **Dynamic** (Editor+Server) | Two columns: trending + most read | titles, trendDataMode, mostReadDataMode, manualItems[] |
| `BlogShowcaseGrid` | **Dynamic** (Editor+Server) | 3-column grid: articles + most read sidebar | viewAllText, mostReadCount, dataMode, manualItems[] |

---

## Common Fields Across All Components

| Field | Description | Present In |
|---|---|---|
| `theme` | Design theme selector (5 options) | Most components |
| `openInNewTab` | Link target (same/new tab) | Components with external links |
| `relAttribute` | Link rel attribute (follow/nofollow/sponsored) | Components with external links |
| `buttonText` / `buttonUrl` / `buttonStyle` | CTA button | Several components |
