<vcf-anchor-nav>

Web Component for easily creating layouts with sticky anchor navigation tabs and content sections.

• Automates the linking of tabs and sections.
• Smooth scrolls to section on tab click and sets the URL hash.
• Scrolls to URL hash on load (preserve selected tab on refresh).

Important information about versioning

Component versions 23.x were deprecated in order to follow Semanting Versioning practices. Please use latest version 2.x for Vaadin 23+ and version 3.x for Vaadin 24.5.

Since version 4.0.0

• The component has been migrated to Lit
• When the application does not load the Aura or Lumo theme, the component uses a minimal set of functional styles that provide a foundation for a custom theme.
• ThemableMixin has been removed from the component, and injecting styles into the component's shadow root using registerStyles is no longer supported. Use global CSS to style the component using part names and CSS variables instead.

Compatibility

• Version 1.x.x -> Vaadin 14+
• Version 2.x.x -> Vaadin 23+
• Version 3.x.x -> Vaadin 24.5.x (improved accessibility)
• Version 4.x.x -> Vaadin 25

Installation

Install vcf-anchor-nav:

npm i @vaadin-component-factory/vcf-anchor-nav --save

Usage

Once installed, import it in your application:

import '@vaadin-component-factory/vcf-anchor-nav';

Add <vcf-anchor-nav> element and <vcf-anchor-nav-section>s to the page.

<vcf-anchor-nav>
  <h1 slot="header">Header</h1>
  <vcf-anchor-nav-section name="One"> ... </vcf-anchor-nav-section>
  <vcf-anchor-nav-section name="Two"> ... </vcf-anchor-nav-section>
  <vcf-anchor-nav-section name="Three"> ... </vcf-anchor-nav-section>
</vcf-anchor-nav>

TypeScript

The package ships type declarations next to every module, so the import above needs no // @ts-ignore and no local declare module. Both element classes are exported by name, and both tag names are added to HTMLElementTagNameMap, so document.createElement() and querySelector() return the typed element:

import {
  AnchorNavElement,
  AnchorNavSectionElement
} from '@vaadin-component-factory/vcf-anchor-nav';

const nav = document.querySelector('vcf-anchor-nav')!; // AnchorNavElement
nav.smoothScroll = true;

// The custom events are typed too.
nav.addEventListener('selected-changed', event => {
  console.log(event.detail.id, event.detail.index);
});
nav.addEventListener('sections-ready', event => {
  event.detail.forEach((section: AnchorNavSectionElement) => console.log(section.name));
});

console.log(AnchorNavElement.is, AnchorNavElement.version);

Every module is also reachable as a subpath import, for example @vaadin-component-factory/vcf-anchor-nav/src/vcf-anchor-nav-section.js, which is useful when only the section element is needed.

Running demo

1. Fork the vcf-anchor-nav repository and clone it locally.

2. Make sure you have npm installed.

3. When in the vcf-anchor-nav directory, run npm install to install dependencies.

4. Run npm start to open the demo.

Releasing

Releases are cut from master with a clean working tree:

npm run release 4.0.2

The script rewrites static get version(), commits, tags via npm version, pushes and publishes to npm and to GitHub Packages. It refuses to run from a dirty tree, from another branch, or when the tag already exists, and it reports which registries already have the version if one of them rejects the publish. npm run lint fails when the version declared in the sources has drifted from package.json.

Server-side API

This is the client-side web component. If you are looking for the server-side (Java) API for the Vaadin Platform, it can be found here: Anchor Nav

License

Apache License 2.0