@vaadin-component-factory/vcf-nav
v1.1.3
Published
Vaadin Component Factory component for navigation menus. This component is a stepping stone towards an official Vaadin component. Please provide feedback through issues in this repository.
Downloads
2,838
Keywords
Readme
vcf-nav
Vaadin Component Factory component for navigation menus. This component is a stepping stone towards an official Vaadin component. Please provide feedback through issues in this repository.
Features
- Navigation with a label can be collapsible
- Navigation items can have prefix and suffix content, for example, icons and badges
- Hierarchial items. A parent item can be without a path (non-navigable)
- Supports keyboard and screen reader navigation
Missing features (things that will be added in the official component):
- Material theme
- Localization support (to provide a custom text for the expand/collapse button of a navigation item)
- TypeScript types
Potential feature additions:
- Horizontal variant (“navigation bar”), with sub-items in a popup
- Icon-only variant (“navigation rail”), with sub-items in a popup
- [insert your idea]
Usage
HTML
<vcf-nav collapsible>
<span slot="label">Main menu</span>
<vcf-nav-item path="/dashboard">
<vaadin-icon icon="vaadin:chart" slot="prefix"></vaadin-icon>
Dashboard
<span theme="badge primary" slot="suffix" aria-label="(2 new items)">2</span>
</vcf-nav-item>
<vcf-nav-item>
<vaadin-icon icon="vaadin:folder-open" slot="prefix"></vaadin-icon>
Parent
<vcf-nav-item path="/child1" slot="children">
Child 1
</vcf-nav-item>
<vcf-nav-item path="/child2" slot="children">
Child 2
</vcf-nav-item>
</vcf-nav-item>
</vcf-nav>
Java
NOTE: The Java classes are not included in this repository. You can get them by downloading a starter project from start.vaadin.com.
AppNav nav = new AppNav("Main menu");
nav.setCollapsible(true);
AppNavItem dashboard = new AppNavItem("Dashboard", "/dashboard");
dashboard.setIcon(new Icon(VaadinIcon.CHART));
Span newItems = new Span("2");
newItems.getElement().setAttribute("aria-label", "(2 new items)");
newItems.getElement().getThemeList().add("badge primary");
newItems.getElement().setAttribute("slot", "suffix");
dashboard.getElement().appendChild(newItems.getElement());
AppNavItem parent = new AppNavItem("Parent");
parent.setIcon(new Icon(VaadinIcon.FOLDER_OPEN));
AppNavItem child1 = new AppNavItem("Child 1", "/child1");
AppNavItem child2 = new AppNavItem("Child 2", "/child2");
parent.addItem(child1, child2);
nav.addItem(dashboard, parent);
Styling
This component does not utilize the Vaadin ThemableMixin
interface, and therefore does not allow you to easily inject styles into its shadow DOM.
The component is meant to be styled using standard CSS features. Regular “light DOM” styling works for most things, and the ::part()
selector for more detailed styling.
Example:
frontend/themes/[mytheme]/styles.css
html {
--vcf-nav-child-indent: var(--lumo-space-m);
}
vcf-nav {
padding: 0;
font-size: var(--lumo-font-size-m);
color: var(--lumo-body-text-color);
}
vcf-nav::part(label) {
text-transform: uppercase;
font-size: var(--lumo-font-size-xs);
}
vcf-nav-item::part(item) {
border-inline-start: 2px solid transparent;
}
vcf-nav-item[active]::part(item) {
border-inline-start-color: var(--lumo-primary-color);
}
<vcf-nav>
Parts
::part(label)
The <summary>
element that displays the label of the navigation menu.
::part(label)::after
The expand/collapse icon of the label element. Defaults to var(--lumo-icons-dropdown)
.
State attributes
[collapsible]
Indicates that the navigation menu is user-collapsible and the pseudo element for the expand/collapse icon is visible.
[collapsed]
Indicates that the navigation menu has been collapsed and the navigation items are hidden.
<vcf-nav-item>
NOTE: the navigation item applies styles to any prefix element with a class name that contains
"icon"
, assuming all such elements are meant to be the item icon.
Parts
::part(item)
The <a>
element that contains the item label and prefix and suffix content.
::part(toggle-button)
The <button>
element which contains the expand/collapse icon, if the item has child items.
::part(toggle-button)::before
The expand/collapse icon. Defaults to var(--lumo-icons-dropdown)
.
::part(children)
The <slot>
element that contains any child items. Can be styled visually.
State attributes
[active]
Indicates that the item is currently the active/visible view in the application. This attribute is automatically set based on the current path/URL.
[child-active]
Indicates that a child item of this navigation item is currently active.
[expanded]
Indicates that the child items of this navigation item are visible.
Custom properties
--vcf-nav-child-indent
The amount of visual indentation of child items. Can be set globally in the html
element. Defaults to var(--lumo-space-l)
.