A responsive header component that provides primary navigation, branding, and utility controls for Lighthouse applications. Collapses into an offcanvas panel on smaller viewports.
When to Use
- As the main site header to provide consistent branding and primary navigation across multiple pages
- To include essential utility links, user authentication controls (login/logout, user profile), or a site-wide search trigger
- When the application layout requires a persistent top bar that adapts to mobile viewports
When Not to Use
- For secondary, in-page navigation — use
QNav, breadcrumbs, or tabs instead - If the header only needs a brand logo with no navigation — a simpler custom header is more appropriate
- For step-by-step navigation within a wizard — use
QStepperinstead
Component Anatomy
- Brand area — displays the application logo and/or title; links to
brandTo - Navigation links — rendered from
navItems; supports nested dropdowns - Toggler button — visible on mobile, opens the offcanvas navigation panel
- Start slot — custom content placed after the brand, before nav links
- End slot — custom content anchored to the right of the navbar
Default
Only the title prop is required (it can be an empty string). Nav items are rendered when navItems is provided.
Slot "brand-image"
Content placed to the left of the brand title. Empty by default — typically used for a logo image.
Slot "start"
Content rendered after the brand, before the nav links. Replaces the default navigation when provided.
Slot "end"
Content anchored to the far right of the navbar. Empty by default.
Slot "offcanvas"
Content rendered inside the offcanvas panel. Defaults to the vertical nav menu when navItems is provided.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | "" | Text displayed as the brand/title in the navbar. |
brandTo | string | RouteRecordRaw | "/" | Route for the brand link. |
navItems | RouteRecordRaw[] | [] | Navigation items rendered as nav links. |
hideNav | boolean | false | Hides the navigation links. |
hideNavChildren | boolean | false | Hides child navigation items in the horizontal nav. |
hideToggler | boolean | true | Hides the mobile toggle button. |
hideOffcanvas | boolean | false | Hides the offcanvas panel. |
container | Breakpoint | "fluid" | "xl" | Bootstrap container breakpoint for the navbar content. |
sticky | boolean | false | Makes the navbar sticky at the top of the viewport. |
disabled | boolean | false | Disables the entire navbar. |
closeOffcanvasOnNavClick | boolean | true | Closes the offcanvas panel when a nav item is clicked. |
togglerIcon | string | "bi-list" | Bootstrap Icons class for the toggler button icon. |
offcanvasNavClass | string | "" | Additional CSS classes applied to the offcanvas navigation. |
class | string | null | Additional CSS classes applied to the navbar root element. |
Slots
| Slot | Description |
|---|---|
brand-image | Content to the left of the brand title (typically a logo). Empty by default. |
brand-title | Replaces the default brand title text. Receives title as a slot prop. |
start | Content after the brand, before nav links. Replaces the default nav when provided. |
end | Content anchored to the right of the navbar. Empty by default. |
offcanvas | Content inside the offcanvas panel. Defaults to the vertical nav menu. |
Accessibility
- The navbar uses a semantic
<nav>element — if multiple nav landmarks appear on a page, provide distinctaria-labelattributes to differentiate them - Navigation links must have descriptive text or
aria-labelattributes - The mobile toggler button's
aria-expandedandaria-controlsstates are managed automatically by the component - When
stickyis enabled, ensure the navbar height is accounted for viascroll-padding-topso keyboard-focused elements are not hidden behind it