Hero

Large banner section with a 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.

description

Subtitle or description text supporting the title. Supports HTML formatting for rich text. Type: string.

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 layout with inline images on the right; use 'center' for prominent, centered hero sections with background images; use '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: Use 96px or 128px for prominent landing page heroes; 64px for normal sections; 48px or 64px for feature introductions; 32px or 48px for announcement banners 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, dramatic first impressions; avoid on internal pages, dashboards, content‑heavy pages; combine with mode='background' and high‑quality images or AnimatedGradient behind.

buttons

Call‑to‑action buttons displayed below description. Typically 1‑2 buttons for clear calls‑to‑action. Type: array (minItems: 0, maxItems: 4). Tip: Use 2 buttons (primary + secondary) on landing pages; use a single primary button for focused conversion; only use 3‑4 buttons when multiple equal‑priority actions are truly needed.

Array items are objects with the following properties:

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

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs (e.g., 'background-color: lightblue; padding: 10px;'). Type: string.

adjectives

Animated text rotator that displays rotating adjectives immediately below the title. Creates dynamic, engaging hero sections with smooth vertical scrolling animations. Type: object. 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 (string, required): Comma‑separated list of adjectives/words to rotate. Recommend 3‑6 words for optimal readability.
• speed (number, optional): Rotation speed in milliseconds. Controls how long each word is displayed before transitioning. Default: 3000. Tip: 1500‑2000 ms for energetic brands; 3000 ms (default) for balanced readability; 5000‑7000 ms for deliberate emphasis.
• animationStyle (string, optional): Animation style for word transitions. Options: slide, fade. Default: slide. Visual Impact: slide creates smooth vertical motion with opacity change (recommended); fade creates cross‑fade only (subtle, elegant). Tip: slide is the recommended default for most cases; fade is a subtle alternative for elegant designs.
• customCss (string, optional): Custom CSS styles for animated adjectives. Parsed as CSS property‑value pairs. Default color is black (#000000).

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. Image URL and mode belong inside this object (imageUrl, imageMode). Type: object.

Sub‑properties:

• type (string, optional): Effect type. Options: default, wavy, boxes. Default: default.
• imageUrl (string, optional): Image URL for background (when type='default'). Required for image‑based heroes.
• imageMode (string, optional): 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 (string, optional): Content alignment within the hero when using default effect type. Options: left, center. Default: left.
• overlayStyle (string, optional): Overlay style for background images. Options: light, dark, none. Default: light.
• wavyColors (string, optional): Comma‑separated hex colors for wave lines. Default: '#38bdf8, #818cf8, #c084fc, #e879f9, #22d3ee'.
• wavySpeed (string, optional): Wave animation speed. Options: slow, fast. Default: slow.
• wavyOpacity (number, optional): Wave opacity (0‑1). Default: 0.5.
• wavyBlur (number, optional): Blur amount in pixels. Default: 10.
• wavyBackgroundFill (string, optional): Base background color behind waves. Default: white.
• boxesBackgroundColor (string, optional): Background color for boxes grid effect. Default: '#0f172a'.
• boxesGridColor (string, optional): Color of the grid lines between boxes. Default: '#334155'.
• boxesHoverColors (string, optional): 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'.