Hero

Large banner section with heading, description, optional image, and call‑to‑action buttons. Ideal for landing pages, feature introductions, and main page banners.

Use Cases

• Landing page hero sections (centered text with background images OR left‑aligned with inline images)
• Feature introductions with side‑by‑side text and image layout (left‑aligned with inline mode)
• Main page banners with call‑to‑action buttons (any alignment)
• Announcement banners with centered content (centered with background images)

Properties

title

Main heading text displayed prominently at top of hero section. Type: string. Required.

description

Subtitle or description text supporting the title. Supports HTML formatting for rich text. Type: string. Not required. Sanitization: DOMPurify with allowed tags: p, br, strong, em, u, a, ul, ol, li, h1‑h6, blockquote, code, pre, span, div.

align

Content alignment - controls horizontal positioning of title, description, and buttons. Type: string. Options: left, center. Default: left. Visual Impact: Left alignment is versatile – works with both side‑by‑side layouts (mode='inline') and traditional background layouts (mode='background'). Center alignment creates centered text with background images (mode='background' only).
Tip: Use 'left' for side‑by‑side layouts with inline images, 'center' for prominent centered hero sections with background images, and 'left' for traditional hero sections.

padding

Vertical padding (top and bottom) controlling the height of the hero section. Ignored when fullscreen is true. Type: string. Options: 0px, 16px, 24px, 32px, 48px, 64px, 96px, 128px. Default: 64px. Visual Impact: Larger padding creates more prominent, spacious hero sections. Smaller padding for compact banners.
Tip: 96px or 128px for prominent landing page heroes; 64px for normal sections; 48px‑64px for feature introductions; 32px‑48px for announcement or compact sections.

fullscreen

When true, hero fills entire viewport (100vh) with flex‑centered content. Creates impactful, immersive landing pages. Overrides padding setting. Type: boolean. Default: false. Visual Impact: Full viewport height hero with content vertically and horizontally centered. Perfect for dramatic first impressions.
Tip: Use for landing pages, product launches, event sites, portfolios; avoid on internal pages, dashboards, or content‑heavy pages; combine with mode='background' and high‑quality images or AnimatedGradient.

buttons

Call‑to‑action buttons displayed below description. Typically 1‑2 buttons for clear calls‑to‑action. Type: array. Min items: 0. Max items: 4.
Tip: 2 buttons (primary + secondary) for landing pages; 1 primary button for focused conversion; 3‑4 buttons only when multiple equal‑priority actions are needed.

Array items (object):

• label – Button text – should be action‑oriented and concise. Type: string. Required.
• targetPage – Target page slug for internal navigation within the Puck app. Has priority over href. Type: string. Not required.
• href – Link URL for anchor links, external URLs, or fallback. Used when targetPage is not specified. Type: string. Not required.
• variant – Button visual style – primary for main action, secondary for alternative action. Type: string. Options: primary, secondary. Default: primary.

customCss

Custom CSS styles for the content container. NEVER set background, background-color, background-image, or linear-gradient here — the backgroundEffect property handles ALL backgrounds (images, wavy, boxes). Adding background styles to customCss creates an ugly colored overlay that covers the background image/effect. Use customCss ONLY for non‑background styling like borders, shadows, spacing, transforms. Type: string. Not required.
Tip: Use for borders, shadows, max‑width, opacity, text‑shadow, etc. Do not include any background‑related properties.

adjectives

Animated text rotator that displays rotating adjectives immediately below the title. Creates dynamic, engaging hero sections with smooth vertical scrolling animations. Perfect for emphasizing key brand attributes, product benefits, or value propositions. Type: object. Not required. Visual Impact: Words smoothly transition vertically with configurable speed and animation style. Default is black text matching title styling, but fully customizable with CSS.

Sub‑properties:

• words – Comma‑separated list of adjectives/words to rotate. Type: string. Required. Recommend 3‑6 words.
• speed – Rotation speed in milliseconds. Controls how long each word is displayed before transitioning. Type: number. Default: 3000.
  Tip: 1500‑2000 ms for fast‑paced brands; 3000 ms (default) for balanced rotation; 5000‑7000 ms for deliberate emphasis.
• animationStyle – Animation style for word transitions. Type: string. Options: slide, fade. Default: slide. Visual Impact: slide creates smooth vertical motion with opacity change (recommended); fade creates crossfade only (subtle, elegant).
  Tip: Use slide for most cases; fade for elegant, minimalist designs.
• customCss – Custom CSS styles for animated adjectives. Parsed as CSS property‑value pairs. Type: string. Not required.

backgroundEffect

Background visual effect for the Hero. Use 'default' for traditional image backgrounds with overlay, 'wavy' for animated canvas wave effect, or 'boxes' for interactive grid with hover effects. IMPORTANT: Image URL and mode go inside this object (imageUrl, imageMode), NOT in a separate 'image' property. Type: object. Not required.

Sub‑properties:

• type – Effect type. Options: default, wavy, boxes. Default: default.
• imageUrl – Image URL for background (when type='default'). Required for image‑based heroes. Type: string.
• imageMode – Image display mode. Options: inline, background. Default: inline. Interaction: When imageMode='inline' and align='center', the image will NOT be displayed; set align='left' for inline mode.
• align – Content alignment within the hero when using default effect type. Options: left, center. Default: left.
• overlayStyle – Overlay style for background images. Options: light, dark, none. Default: light.
• wavyColors – Comma‑separated hex colors for wave lines. Default: #38bdf8, #818cf8, #c084fc, #e879f9, #22d3ee.
• wavySpeed – Wave animation speed. Options: slow, fast. Default: slow.
• wavyOpacity – Wave opacity (0‑1). Default: 0.5.
• wavyBlur – Blur amount in pixels. Default: 10.
• wavyBackgroundFill – Base background color behind waves. Default: white.
• boxesBackgroundColor – Background color for boxes grid effect. Default: #0f172a.
• boxesGridColor – Color of the grid lines between boxes. Default: #334155.
• boxesHoverColors – Comma‑separated hex colors that appear on hover. Default: #93c5fd, #f9a8d4, #86efac, #fde047, #fca5a5, #d8b4fe.

Best Practices

• ALWAYS include Hero component on main/landing/home pages for professional appearance.
• For image‑based heroes: call search_unsplash or generate_image BEFORE creating Hero.
• CONSIDER using backgroundEffect.type='wavy' for modern SaaS/tech landing pages – creates animated wave effect without needing images.
• CONSIDER using backgroundEffect.type='boxes' for interactive futuristic landing pages – creates skewed grid with hover color effects (always use with textColor='light').
• SHOULD use animated adjectives on landing pages for dynamic, engaging brand messaging (e.g., 'Beautiful. Elegant. Unforgettable.' for weddings, 'Fast. Secure. Reliable.' for SaaS).
• For weddings/celebrations, consider pairing with FloatingElements or AnimatedGradient for emotional polish.
• For professional/SaaS apps, use subtle entrance animations via customCss if desired (avoid FloatingElements).
• NEVER use align='center' with backgroundEffect.imageMode='inline' (image won’t display due to CSS logic).
• Choose background approach: Traditional images (default) OR animated waves (wavy) for abstract/modern look.
• Side‑by‑side layouts (align='left' + mode='inline') work great for feature introductions and product showcases.
• Full‑width backgrounds (mode='background') work great for landing pages and announcement banners.
• Wavy backgrounds work great for tech startups, SaaS, and developer tools (no image needed).
• Use padding='96px' for prominent landing pages, '64px' for standard sections, '48px' for feature sections.
• Provide 1‑2 CTA buttons (primary action + optional secondary action).

Common Mistakes

Using href with anchor format for internal page navigation (e.g., href: '#dogs' or href: 'dogs')

Why it's a problem: Anchor links (#dogs) scroll to sections on the same page. Page slugs without targetPage property don’t navigate correctly.

Fix: Use targetPage property for internal navigation: {label: 'View Dogs', targetPage: 'dogs', variant: 'primary'}. Reserve href for anchor links (#section) or external URLs (https://...).

Using align='center' with backgroundEffect.imageMode='inline'

Why it's a problem: CSS logic explicitly hides inline images when content is centered.

Fix: Use align='left' with imageMode='inline' for side‑by‑side layout OR use align='center' with imageMode='background' for centered hero.

Using a separate 'image' property instead of backgroundEffect.imageUrl

Why it's a problem: The Hero component reads imageUrl from backgroundEffect, NOT from a top‑level 'image' property. Using 'image: { url, mode }' will result in no image being displayed.

Fix: Put image URL inside backgroundEffect: { type: 'default', imageUrl: 'https://...', imageMode: 'background', overlayStyle: 'light' }.

Not calling search_unsplash or generate_image before creating Hero components

Why it's a problem: Professional apps need compelling visuals. Placeholder URLs may break or look unprofessional.

Fix: ALWAYS call search_unsplash or generate_image tool first to get valid image URL, then use it in backgroundEffect.imageUrl.

Using external placeholder image URLs (https://via.placeholder.com, https://picsum.photos)

Why it's a problem: External URLs may break, have CORS issues, or look generic. AI‑generated images are more reliable and theme‑matched.

Fix: Use generate_image tool to get base64 data URLs (data:image/png;base64,...) that never break.

Using default padding='64px' for all hero sections

Why it's a problem: Landing pages need more visual impact with larger padding. Compact sections need less padding.

Fix: Use padding='96px' or '128px' for landing pages, '64px' for standard sections, '32px'/'48px' for compact banners.

Adding too many buttons (3‑4 buttons)

Why it's a problem: Too many options causes decision paralysis. Users don’t know which action to take.

Fix: Use 1‑2 buttons: one primary CTA + optional secondary action. Keep call‑to‑action focused and clear.

Generic button labels like 'Click Here', 'Submit', 'Go'

Why it's a problem: Non‑descriptive labels don’t communicate value proposition. Users don’t know what will happen.

Fix: Use action‑oriented labels that describe the outcome: 'Get Started', 'Browse Recipes', 'Download Free Trial'.

Adding background, background-color, background-image, or linear-gradient to customCss

Why it's a problem: customCss is applied to the content div which sits ON TOP of the background (image, wavy, or boxes). Any background/gradient in customCss creates an ugly colored overlay that hides the background image or effect. This is the #1 visual quality killer for Hero components.

Fix: NEVER set any background‑related CSS property in customCss. The backgroundEffect property handles ALL backgrounds. For image backgrounds, use backgroundEffect.imageUrl. For colored backgrounds, use backgroundEffect.type='wavy' with wavyBackgroundFill or type='boxes' with boxesBackgroundColor.