Navbar

Responsive navigation bar with brand identity, navigation links, a CTA button, and a mobile menu. It supports three visual variants (light, dark, glass) and sticky positioning, automatically collapsing to a hamburger menu on mobile devices.

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 40px gradient circle (indigo to violet) with shadow. STRONGLY RECOMMENDED to use with brandText for professional brand identity. Supports ALL Lucide icons. Type: string. Visual impact: Icon displayed in 40px 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; ShoppingCart for e‑commerce, etc.). Security note: Only Lucide icon names are accepted; invalid names fallback to “Zap”.

brandHref

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

brandTargetPage

Target page slug for brand logo/text navigation within the same multi‑page Puck app. Type: string. Default: home. Tip: Defaults to “home” – override only if your landing page uses a different slug. If both brandTargetPage and brandHref are set, brandTargetPage takes priority (unless it is “/”). Do NOT set to “/”; use brandHref 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 with dark gray text; dark – dark gray background with white text; glass – translucent white background with backdrop blur. Tip: Use “glass” for premium look over hero images/gradients, “light” for traditional clean navigation (default), or “dark” for bold high‑contrast designs.

items

Navigation menu items (links to pages or anchor sections). Type: array. Minimum items: 0, maximum items: 8. Tip: Include 4‑6 items for desktop clarity (3‑5 for mobile‑first). Keep labels to 1‑2 words (≤10 characters). Common order: Home → Features → Pricing → About → Contact. Use “#anchor” for single‑page apps, full URLs for external links, and targetPage for multi‑page navigation.

ctaText

Call‑to‑action button text (prominent action button on right side of 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 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. Tip: Set ctaText with either ctaHref (external/anchor) OR ctaTargetPage (multi‑page navigation). If both are provided, ctaTargetPage takes priority.

stickyTop

Whether navbar stays fixed at top of viewport during scrolling. Type: boolean. Default: true. Visual impact: true – fixed with high z‑index, spacer added to prevent overlap; false – scrolls with page content. Tip: Use true for single‑page apps, multi‑page apps, and landing pages to keep navigation always accessible. Use false only for minimal designs where the navbar should not dominate screen space.

showAuthButton

Show login/logout button on far right of navbar. When enabled, shows “Sign In” for unauthenticated users or a user icon with dropdown for authenticated users. This is the ONLY way to provide login/register – never create separate login pages. Type: boolean. Default: false. Visual impact: true & not logged in – outlined “Sign In” button; true & logged in – user icon with dropdown; false – no auth button. Tip: Set true for apps with gated or protected content, admin dashboards, or any authentication requirement. Keep false for public‑only apps.

loginButtonText

Text displayed on the login button when 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.

showModeSelector

Show dark/light mode toggle button in navbar. Type: boolean. Default: false.

showCartIcon

Show shopping cart icon with badge count (for e‑commerce sites). Type: boolean. Default: false.

cartTargetPage

Target page slug for cart icon click. Type: string. Defaults to “shop”.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Type: string. Tip: Provide CSS declarations such as “background-color: #000; padding: 20px;”. Security note: Parsed by a CSS parser; tenant styles are isolated per page.

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 for BUSINESS actions (e.g., ‘Get Started’, ‘Order Now’, ‘Contact Us’) – NEVER use CTA for ‘Login’/‘Sign Up’ when showAuthButton is enabled
• 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.

Using ctaText for 'Login', 'Sign Up', 'Sign In', or 'Register' when showAuthButton is true

Why it's a problem: showAuthButton: true already renders a ‘Sign In’ button on the far right. Adding ctaText='Login' or similar creates TWO auth buttons side by side, which looks broken and confuses users.

Fix: When showAuthButton: true, use ctaText ONLY for business actions: ‘Get Started’, ‘Order Now’, ‘Book a Table’, ‘Contact Us’. Or omit ctaText entirely. NEVER duplicate auth functionality with the CTA button.