Navbar

A responsive navigation bar that displays brand identity, navigation links, an optional call‑to‑action button, and a mobile hamburger menu. It supports three visual variants (light, dark, glass) and can be fixed to the top of the viewport.

Use Cases

• Main site navigation header with brand logo and menu items
• Sticky top navigation that remains visible during scrolling
• Landing page navigation with prominent CTA button
• Glass morphism navigation bar with transparent background blur
• Mobile‑responsive navigation with hamburger menu
• Apps with authentication – shows login/logout button on far right
• Role‑based navigation – show/hide nav items based on user roles

Properties

brandText

Brand/company name displayed on left side of navbar. Type: string. Tip: Use company/product name for strong brand identity. Keep to 1‑3 words (15 characters max) for mobile layouts.

brandIcon

Lucide icon name for brand logo. Icon rendered in a 40 px gradient circle (indigo to violet) with shadow. Type: string. Visual Impact: Icon displayed in 40 px gradient circle (indigo‑violet) with shadow, appearing left of brandText. Tip: Choose an icon that matches the app theme (e.g., Zap/Rocket for tech, Cloud/Layers for SaaS, etc.). Use both brandIcon and brandText together for professional brand identity. Security Note: Only Lucide icon names are accepted; invalid names fall back to the “Zap” icon.

brandHref

Link destination for brand logo/text click. Can be an anchor link (#section), root path (/), or external URL (https://...). Type: string. Default: /. Tip: Use “/” to scroll to the top of the page (default). Use “#home” or “#top” for single‑page apps. Use a full URL for external sites.

brandTargetPage

Target page slug for brand navigation within the same multi‑page Puck app. Type: string. Default: home. Tip: Defaults to “home” – the standard landing page. Override only if your landing page uses a different slug. If both brandTargetPage and brandHref are set, brandTargetPage takes priority (unless set to “/”). Do NOT set to “/”; use brandHref instead for scroll‑to‑top behavior.

variant

Visual style variant controlling color scheme and background. Type: string. Options: light, dark, glass. Default: light. Visual Impact:

• light – White background (#ffffff), dark gray text (#111827), light gray borders. Traditional, clean look. (default)
• dark – Dark gray background (#111827), white text, dark borders. High‑contrast, bold appearance.
• glass – Translucent white background (80% opacity) with backdrop blur and subtle border. Modern, premium aesthetic that reveals content behind the navbar.

Tip: Use “glass” for premium designs over hero images/gradients, “light” for traditional apps, and “dark” for bold, creative designs.

items

Navigation menu items (simple link objects with {label, href, targetPage, visibleToRoles}). Type: array. Minimum items: 0. Maximum items: 8. Tip: Provide 4‑6 items for desktop clarity (3‑5 for mobile‑first designs). Keep labels to 1‑2 words (≤10 characters). Use “#anchor” format for single‑page apps, full URLs for external sites, and targetPage for multi‑page navigation.

Item properties

label – Link text displayed in the navigation menu. Type: string. Required.

href – Destination URL or anchor. Type: string. Optional. Use for anchor links or external URLs; prefer targetPage for multi‑page navigation.

targetPage – Target page slug for navigation within the same multi‑page app. Type: string. Optional. Takes priority over href when both are set. Use lowercase kebab‑case (e.g., “recipe-detail”).

visibleToRoles – Array of role objects that determine visibility. Type: array of objects with a “role” string. If empty or omitted, the item is visible to all users.

ctaText

Call‑to‑action button text (prominent action button on the right side of the navbar). Type: string. Tip: Use action verbs (Get, Start, Try, Book, Download) and add value words (Free, Now, Today). Keep to 2‑4 words (≤20 characters).

ctaHref

Link destination for the CTA button (anchor, relative path, or external URL). Type: string.

ctaTargetPage

Target page slug for CTA button navigation within the same multi‑page Puck app. Type: string. Interaction Rules:

• If ctaText is set but both ctaHref and ctaTargetPage are empty, the CTA button will not appear. Set ctaText with either ctaHref or ctaTargetPage.
• If both ctaHref and ctaTargetPage have values, ctaTargetPage takes priority. Use only one of them.

stickyTop

Whether the navbar stays fixed at the top of the viewport during scrolling. Type: boolean. Default: true. Visual Impact:

• true – Navbar fixed at top with z-index:50; a spacer div is added to prevent content overlap.
• false – Navbar scrolls with page content and disappears on scroll.

Tip: Use true for single‑page apps, multi‑page apps, and landing pages to keep navigation accessible. Use false only for minimal designs where the navbar should not dominate screen space.

showAuthButton

Show login/logout button on the far right of the navbar. When enabled, displays a “Sign In” button for unauthenticated users or a user icon with a dropdown (showing email and “Sign Out”) for authenticated users. Type: boolean. Default: false. Visual Impact:

• true (not logged in) – Outlined “Sign In” button matching the navbar variant.
• true (logged in) – User icon with dropdown containing email and “Sign Out”.
• false – No auth button shown.

Tip: Set true for apps with gated content, protected pages, or admin dashboards. Keep false for public‑only apps.

loginButtonText

Text displayed on the login button when the user is not authenticated. Only used when showAuthButton is true. Type: string. Default: Sign In. Tip: Use “Sign In” (default) for most apps; “Member Login” for membership sites; “Admin Login” for admin‑only interfaces.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Type: string. Security Note: Parsed by a cssParser utility; styles affect only the tenant’s own pages (multi‑tenant isolation enforced).

Best Practices

• ALWAYS include Navbar on multi‑page apps for consistent navigation
• CRITICAL DEFAULTS: stickyTop defaults to TRUE (navbar stays visible), brandTargetPage defaults to ‘home’ (landing page)
• STRONGLY RECOMMENDED: Set both brandText AND brandIcon for professional brand identity – creates visual brand presence
• Choose brandIcon that matches app theme (Zap/Rocket for tech, Cloud/Layers for SaaS, Activity/TrendingUp for analytics, Package/ShoppingCart for e‑commerce, UtensilsCrossed/ChefHat for food/recipes)
• Supports ALL Lucide icons – accepts kebab‑case (bean-off), PascalCase (BeanOff), or lowercase (zap) – automatically converts to correct format
• IMPORTANT: Choose variant based on design – ‘glass’ for modern/premium (BEST over hero images), ‘light’ (default/safe), ‘dark’ (bold/creative)
• Limit navigation items to 4‑6 links for clean, uncluttered design
• Include ONE prominent CTA button (e.g., ‘Sign Up’, ‘Get Started’, ‘Contact Us’)
• Keep navigation item labels concise (1‑2 words: ‘Home’, ‘About’, ‘Features’)

Common Mistakes

CRITICAL: Using Puck component objects {type, props, layout} in items array instead of simple link objects

Why it's a problem: Navbar items are NOT Puck components - they are simple navigation link objects with only {label, href, targetPage} properties. Using component syntax breaks the navbar rendering.

Fix: CORRECT: items: [{label: 'Home', href: '#home'}]. WRONG: items: [{type: 'Button', props: {...}}]. Never use ‘type’, ‘props’, ‘id’, or ‘layout’ keys in items array.

Not setting stickyTop=true for single-page apps with scrolling

Why it's a problem: Users lose access to navigation when scrolling down. They must scroll back to top to navigate.

Fix: Set stickyTop=true so navbar remains visible and accessible during scrolling

Setting ctaText without ctaHref or ctaTargetPage

Why it's a problem: CTA button requires both text and destination (ctaHref or ctaTargetPage). Missing destination results in no button.

Fix: Set ctaText with either ctaHref (external/anchor) or ctaTargetPage (multi-page navigation)

Using href for multi-page navigation in Puck apps

Why it's a problem: href opens in new tab or scrolls to anchor. For navigating between pages in the same app, use targetPage instead.

Fix: Use targetPage='recipes' instead of href='/recipes' for multi-page Puck apps

Too many navigation items (8+) causing mobile menu clutter

Why it's a problem: Mobile hamburger menu becomes overwhelming with too many options. Users don’t know where to click.

Fix: Limit to 4‑6 most important navigation items. Move secondary links to footer.

Using variant='glass' without hero background or gradient

Why it's a problem: Glass effect (blur/transparency) only works when content behind navbar is visible. On white background, glass effect is invisible.

Fix: Use variant='glass' only when navbar sits over hero images, gradients, or colorful backgrounds. Otherwise use 'light' or 'dark'.

Generic navigation labels like 'Page 1', 'Link 2', 'Item 3'

Why it's a problem: Non‑descriptive labels don’t communicate page purpose. Users don’t know where links go.

Fix: Use descriptive labels: 'Home', 'Features', 'Pricing', 'About', 'Contact'

Not including brandText or brandIcon

Why it's a problem: Empty left side of navbar looks unprofessional and generic. Missing visual brand identity makes app forgettable.

Fix: STRONGLY RECOMMENDED: Set BOTH brandText and brandIcon for professional appearance (e.g., brandText='RecipeHub', brandIcon='ChefHat' or 'chef-hat' or 'UtensilsCrossed'). Icon appears in gradient circle, creating memorable visual brand.

Setting brandIcon with wrong format and getting fallback Zap icon

Why it's a problem: Icon names must match Lucide format, but the component auto‑converts common formats (kebab‑case, lowercase, etc.)

Fix: Use any format – 'Zap', 'zap', 'trending-up', 'TrendingUp', 'bean off' all work. Browse https://lucide.dev/icons/ for exact icon names. Invalid names fallback to Zap icon.

Using long navigation item labels (3+ words)

Why it's a problem: Long labels cause navbar to wrap on mobile, breaking layout. Labels get truncated.

Fix: Keep labels to 1‑2 words: 'About Us' → 'About', 'Our Services' → 'Services'

Creating a separate login/register page instead of using showAuthButton

Why it's a problem: showAuthButton:true provides a complete, built‑in login/register modal. Custom login pages with email/password fields are non‑functional – they don’t connect to the auth system.

Fix: Set showAuthButton:true on Navbar. NEVER create pages with login forms. The built‑in auth modal handles login, registration, and logout automatically.