Navigation bars

Links within navigational containers are automatically marked as .up-current if they point to the current page.

This helps highlighting current menu sections using CSS.

Marking links as current

Let's look at a simple menu with two links:

<nav> <!-- mark-phrase "up-nav" -->
  <a href="/foo">Foo</a>
  <a href="/bar">Bar</a>
</nav>

When the browser location changes to /foo, the first link is marked as .up-current:

<nav>
  <a href="/foo" class="up-current">Foo</a> <!-- mark-phrase "up-current" -->
  <a href="/bar">Bar</a>
</nav>

When the browser location changes to /bar, the first link loses its .up-current class. Now the second link is marked as .up-current:

<nav>
  <a href="/foo">Foo</a>
  <a href="/bar" class="up-current">Bar</a> <!-- mark-phrase "up-current" -->
</nav>

Defining navigational containers

Standard <nav> elements are always considered navigational containers:

<nav> <!-- mark-phrase "nav" -->
  <a href="/foo">Foo</a>
  <a href="/bar">Bar</a>
</nav>

If you cannot use a <nav> element, you can also set the [up-nav] attribute on an arbitrary tag instead:

<div up-nav> <!-- mark-phrase "up-nav" -->
  <a href="/foo">Foo</a>
  <a href="/bar">Bar</a>
</div>

You may also assign [up-nav] to an individual link instead of an navigational container:

<a href="/foo" up-nav>Foo</a> <!-- mark-phrase "up-nav" -->

Matching containers can opt out of .up-current assignment by setting an [up-nav=false] attribute:

<nav up-nav="false"> <!-- mark-phrase "false" -->
  <a href="/foo">Foo</a>
  <a href="/bar">Bar</a>
</nav>

You can configure additional selectors to automatically match your navigation components in up.status.config.navSelectors:

up.status.config.navSelectors.push('.navbar')

Updating `.up-current` classes

The .up-current class is toggled automatically within all content that Unpoly renders. For example, when Unpoly follows a link, submits a form or renders from a script, any newly inserted hyperlinks will get .up-current if they point to the current URL. When the render pass changes history, existing links will be updated to reflect the new location.

To toggle .up-current on content that you manually inserted without Unpoly, use up.hello().

What is current?

The URL shown in the browser's address bar is generally considered the "current" location.

A link matches the current location (and is marked as .up-current) if it matches either:

the link's [href] attribute
the link's [up-href] attribute on a faux hyperlink
the link's URL alias

Any #hash fragments will be ignored in both link attributes and in the current location.

Highlighting links for multiple URLs

You often want to highlight a link for multiple URLs. For example a link to a Users section might open a list of users, but should also be "current" for the new user form.

To build this, set an [up-alias] attribute to any URL that should also be highlighted as .up-current. The link below will be highlighted at both /users and /users/new locations:

<nav>
  <a href="/users" up-alias="/users/new">Users</a>
</nav>

To pass more than one alternative URLs, set comma-separated values:

<nav>
  <a href="/users" up-alias="/users/new, /users/online">Users</a>
</nav>

You can also use a URL pattern:

<nav>
  <a href="/users" up-alias="/users/*">Users</a>
</nav>

Layers have separate locations

When no overlay is open, the current location is the URL displayed in the browser's address bar.

While overlays are open, Unpoly tracks a separate location for each layer. When a link is placed in an overlay, the current location is the location of that overlay, even if that overlay doesn't have visible history.

Styling current links

Unpoly applies no default styling to .up-current links. Use your own CSS instead:

.up-current {
  font-weight: bold;
  background-color: yellow;
}

If you have already have a CSS class for current links that you want to reuse, you can tell Unpoly about it:

up.status.config.currentClasses.push('.my-current')

Unpoly will set all configured classes on a current link:

<nav>
  <a href="/foo" class="up-current my-current">Foo</a> <!-- mark-phrase "up-current selected" -->
  <a href="/bar">Bar</a>
</nav>

Accessibility considerations

When a link is marked as .up-current, Unpoly also assigns an [aria-current] attribute to convey the emphasis to assistive technologies:

<nav>
  <a href="/foo" class="up-current" aria-current="page">Foo</a> <!-- mark-phrase "aria-current" -->
  <a href="/bar">Bar</a>
</nav>

When using a non-<nav> element with [up-nav], we recommend to also set a [role=navigation] attribute to define a navigation landmark:

<div up-nav role="navigation"> <!-- mark-phrase "navigation" -->
  <a href="/foo">Foo</a>
  <a href="/bar">Bar</a>
</div>

API Navigation bars