Navbar Pro user guide

After viewing the introduction, prepare your logos and links and place the Bric. See the settings reference to look up individual fields.

How to use it

1. Place Navbar Pro in the header

To share the navigation across the site, place one Navbar Pro in a Bloc in the upper Global Area. To use it on a single page, place it in the regular page area.

Navbar Pro provides its own fixed bar at the top of the screen. If you are replacing the standard Nav Bar, check that the standard navigation has not been left in place, creating two bars. Avoid placing multiple Navbar Pro instances on the same page.

Place it as part of the header, separately from the dedicated extension Bloc used for Math Renderer and Code Highlighter. Check its position and surrounding spacing in the preview, including the outer Bloc.

2. Add logos for light and dark appearance

Select Navbar Pro and configure Logo in the right sidebar.

1. Set Logo Light to the logo you want on a light background.
2. Set Logo Dark to the logo you want on a dark background.
3. Enter the destination for clicking the logo in Logo Link. Use / for the site home page.
4. Adjust Logo Height for the logo and Bar Height for the entire bar.

The logo width adjusts automatically to its height. The defaults are 40px for the logo and 64px for the bar. If you set the bar height below the logo height, the displayed bar is adjusted to be at least as tall as the logo.

An unset logo does not automatically fall back to the other one. Even if you use the same image for both appearances, add it to both fields. The overlay mode also affects which logo is used, so choose images that remain readable over your photos if you use Overlay.

3. Enter menu links

Under Menu, enter one item per line in Links. Separate each label and URL with a vertical bar, |.

Home|/
Apps|/apps/
Brics|/brics/
About|/about/

This is an example of the input format. Replace the labels and URLs with your actual published pages. Adding a page in Blocs does not automatically add it to this list.

For internal URLs, enter lowercase published paths beginning with /. For example, if a page is published at /about/, enter /about/. For links to other sites, you can enter URLs beginning with https://.

Current-page highlighting

A link whose path matches the open page uses the Highlight Light or Highlight Dark color. Current-page highlighting does not make the text bold.

/about/, /about, and the preview URL /about.html are treated as the same page. Queries and fragments are excluded from the current-page comparison. A /blog/ link is not highlighted as a parent item when you open /blog/post/. For internal links that should receive current-page highlighting, use paths such as /about/ rather than absolute URLs beginning with https://.

Preview and published URLs

In previews on hosts such as localhost, the Bric rewrites / to /index.html and /about/ to /about.html. On the published site, it does not convert Clean URLs to .html. External URLs, same-page fragments such as #id, paths that already have an extension, and language roots such as /ja/ are excluded from this preview conversion.

Navbar Pro does not create URL rewriting rules for your hosting server. If you use Clean URLs, configure the published site so that those URLs open the correct pages. For PHP pages or previews with a different folder structure, open the links to check their destinations.

4. Configure language links

Under Menu, Languages also accepts one language name and URL per line, separated by |. Prefix the line for the language you want to show as current on the canvas with *.

*English|/
Japanese|/ja/

On the canvas, this example displays English as the current language and sets the Japanese link to /ja/. You can change the display names. To show Japanese as the current language on the canvas, use the following.

English|/
*Japanese|/ja/

A language without a URL is also displayed without a link. Leave Languages empty to hide language links.

Use the language directory as the URL in Languages. Use / for a language without a directory and /ja/ for the ja directory.

In Preview and on the published site, Navbar Pro identifies the current language from the open URL and builds links to versions of the same page in other languages. Create those pages at the corresponding URLs in advance.

Language Position defaults to Before path, which places the language directory first. Japanese for /small-wonders/ is /ja/small-wonders/. A page with a Path, /works/small-wonders/, becomes /ja/works/small-wonders/. After path keeps the first directory as the site location. /works/small-wonders/ becomes /works/ja/small-wonders/, and that site's home /works/ becomes /works/ja/.

You can use a separate Global Area for each language or share one across all pages.

5. Choose the hamburger breakpoint

Under Behavior, use Toggle to choose the screen width at which the navigation switches to a hamburger menu. The default is LG.

Toggle	Hamburger menu	Horizontal navigation
LG	1199px or narrower	1200px or wider
MD	991px or narrower	992px or wider
SM	767px or narrower	768px or wider
XS	575px or narrower	576px or wider

Choose LG to switch earlier when your link count or logo width requires more room. Consider MD, SM, or XS to keep horizontal navigation at smaller widths. Check that all items, including the logo and language links, fit just above the breakpoint.

Opening the hamburger menu arranges the site links, appearance switch, and language links vertically. Scrolling of the page body is disabled while the menu is open. Widening the screen to the horizontal navigation range closes the open menu.

6. Configure appearance and scroll behavior

When Appearance Slider is ON, visitors can switch between light and dark appearance. Logos and links use the light and dark settings you configured under Logo and Colors. Change Appearance Label to customize the label in the mobile menu.

The initial appearance follows the operating system. Choices are saved in the browser for subsequent visits. Selecting the appearance that matches the operating system saves an automatic setting, which then follows future OS appearance changes. The interface does not offer separate light, dark, and automatic options.

The switch does not automatically recolor every background, text element, image, or custom decoration in the page body. Check that the site has suitable dark styles before enabling it. Turning Appearance Slider OFF hides the switch and disables the Bric's initial application of appearance settings.

When Scroll Hide is ON, the bar hides as you scroll down and reappears as you scroll up. It remains visible within 8px of the page top and while the menu is open. Turn Scroll Hide OFF to keep the bar visible at all times.

Saving appearance and sharing it with other pages

The default Storage Key is navbar-pro-appearance. The values auto, light, and dark are saved in the browser's localStorage.

Use the same Storage Key to share appearance preferences with other pages on the same site. To share with VitePress on the same origin, you can use vitepress-theme-appearance. This method cannot share localStorage across different domains, subdomains, protocols, or ports.

Applying appearance updates the dark class and data-bs-theme on html, the CSS color-scheme, and the dark-theme class on body. If you prepare CSS for the page body, define styles that respond to these settings.

Inside an iframe, the OS appearance check uses light appearance, so the initial appearance may differ between an embedded page and a regular page.

7. Configure an overlay over photos

Use Overlay to change the background while the bar overlaps an area such as a photo.

1. Add a class such as hero to the photo Bloc or other area you want beneath the bar.
2. Enter the same class name, such as hero, in Class under Navbar Pro's Overlay section. This is separate from the general Classes field at the top of the Bric's sidebar.
3. Select Clear, Thin white, or Thin black in Overlay.
4. Scroll to the target area in the preview and check that the logo and links remain readable against the background.

Overlay	Background while overlapping the target	Logo and link colors
Off	Regular theme background	Current appearance settings
Clear	Fully transparent	Logo Dark and light link colors for dark backgrounds
Thin white	White at 18% opacity	Logo Light and dark link colors for light backgrounds
Thin black	Black at 18% opacity	Logo Dark and light link colors for dark backgrounds

The leading . in Class is optional. If several elements use that class, the overlay applies while the bar overlaps any of them. It does not apply when Class is empty or Overlay is Off.

The regular theme background returns when the bar leaves the target area. The bar background also becomes opaque while the menu is open. When overlaying a target at the top of the page, the Bric can remove the bar's spacer, so check the layout at the page top in the preview.

8. Adjust the inner width

Under Logo, turn Limit Max Width ON to center the inner content containing the logo and links within Max Width. The default is 90rem. You can also specify CSS lengths with units, such as 1440px. A number without a unit is treated as rem, so include px if you want pixels.

When Limit Max Width is OFF, the inner content's position and width align with the inside edges of the parent column's left and right padding. The logo aligns left, and links and other controls align right. The bar itself remains fixed at the screen top; this setting does not turn it into a regular element in the page flow.

Check attachments

Navbar Pro's CSS and JavaScript are automatically registered as Attachments when you place the Bric. Check Project Attachments for a Global Area or Page Attachments for the regular page area. You normally do not need to add files manually or upload individual files from inside the Bric.

For a Global Area, open Project Settings (⌘,) and click the paperclip icon at the top. In version 1.0.11, the following two files appear as Navbar Pro attachments.

File	Purpose
navbar-pro-1.0.11.css	Styles for fixed positioning, the expanded menu, and related behavior in previews and on the published site
navbar-pro-1.0.11.js	Handles menu toggling, current-page matching, language link generation, appearance, overlays, and scrolling

Figure 1: Attachments for Navbar Pro 1.0.9 in a Global Area. Files from other Brics appear in the same list.

For a Bric in the regular page area, check the paperclip icon in Page → Settings. During export and Publish, JavaScript is placed in js/ and CSS in css/.

Before publishing

1. Check that the logo, menu, and language links fit at desktop and mobile widths.
2. Open each menu link and the logo destination. Check that only the intended current-page link is highlighted.
3. On an interior page, select a language link and check that the corresponding version of the same page opens.
4. Check menu opening and closing, and that the page body does not scroll while the menu is open.
5. Check that logos appear in both light and dark appearance and that body text and backgrounds remain readable.
6. Reload the page to check that the appearance choice is applied.
7. If you use Scroll Hide or Overlay, check the behavior when changing scroll direction and at the points where backgrounds switch.
8. Check that you can open and close the menu and navigate to links using the keyboard.

Troubleshooting

Symptom	What to check first
The logo disappears in one appearance	Check that both Logo Light and Logo Dark have an image
A hamburger menu appears on desktop	Check Toggle; the default LG setting uses the hamburger at 1199px or narrower
Horizontal links do not fit	Switch to the hamburger at a wider width, or adjust the logo height or number of links
A link does not use the current-page color	Check in a preview or on the published site, not on the canvas; use a path for the internal link and check that it matches the current path
A link fails only in the preview	Check that the .html conversion matches the actual export folder and extension
Body content becomes hard to read after switching appearance	Check that the body has dark styles; consider turning Appearance Slider OFF until they are ready
The appearance choice is not carried over to another page	Check that Storage Key and the origin match, and that browser storage is not restricted
The overlay does not change	Check that Overlay's Class field matches the target element's class, the mode is not Off, and the bar actually overlaps the target
A language link opens the wrong page or highlights the wrong language	In Preview or on the published site, check that the language directories in Languages and the Language Position setting match the actual URLs. On the canvas, check which line begins with *.
Two navigation bars appear	Check that a standard Nav Bar or another Navbar Pro is not also present

Back to Navbar Pro / Settings reference