Navigation

Navigation Menu

Site navigation whose buttons show panels of links on click, hover or the keyboard.

Class nameTypeDescription
navigation-menuplf:navigation-menuComponentThe navigation landmark
navigation-menu-listplf:navigation-menu-listPartThe top-level list
navigation-menu-itemplf:navigation-menu-itemPartA top-level item
navigation-menu-linkplf:navigation-menu-linkPartA top-level link
navigation-menu-triggerplf:navigation-menu-triggerPartA button that opens a panel
navigation-menu-iconplf:navigation-menu-iconPartAn SVG icon; an icon class there doesn't need it
navigation-menu-chevronplf:navigation-menu-chevronPartYour own icon, in place of the drawn chevron; turns over while open
navigation-menu-contentplf:navigation-menu-contentPartA panel
navigation-menu-groupsplf:navigation-menu-groupsPartColumns of link groups
navigation-menu-headingplf:navigation-menu-headingPartA group's heading
navigation-menu-linksplf:navigation-menu-linksPartA panel's list of links
navigation-menu-entryplf:navigation-menu-entryPartA link in a panel
navigation-menu-textplf:navigation-menu-textPartAn entry's title and description
navigation-menu-titleplf:navigation-menu-titlePartAn entry's title
navigation-menu-descriptionplf:navigation-menu-descriptionPartAn entry's description
navigation-menu-content-megaplf:navigation-menu-content-megaModifierA wide panel

Author the buttons hidden and the panels visible: without JavaScript every panel shows as a nested list of links.

Disabled

A button with disabled or aria-disabled="true" does not open its panel.

JavaScript

Navigation Menu needs JavaScript. The Full script (pelatform-ui.min.js) starts every component on page load, with no code of your own; with ESM imports, call init() yourself, as in Installation. For markup you add later, see Dynamic content.

<link rel="stylesheet" href="pelatform-ui.min.css">
<link rel="stylesheet" href="icons/icons.min.css">
<script src="pelatform-ui.min.js" defer></script>
<link rel="stylesheet" href="pelatform-ui.prefixed.min.css">
<link rel="stylesheet" href="icons/icons.prefixed.min.css">
<script src="pelatform-ui.min.js" defer></script>
Attribute Purpose
data-plf-navigation-menu Marks the <nav>, named with aria-label or aria-labelledby
data-plf-navigation-menu-trigger Each disclosure <button>, authored hidden
aria-controls Optional, on a button: its panel’s id; by default the panel is the element right after the button
data-plf-open-delay Milliseconds of hover before opening, from 0 to 60000; 200 by default
data-plf-close-delay Milliseconds before closing once the pointer leaves, from 0 to 60000; 150 by default
data-plf-placement On the <nav>: top, bottom (default), left or right
data-plf-align On the <nav>: start (default), center or end
aria-current="page" The current link; set it yourself
Method Behavior
PLF.NavigationMenu.getOrCreateInstance(element, options) Returns the instance, creating it for valid markup. options can set openDelay and closeDelay
PLF.NavigationMenu.getInstance(element) Returns the instance or null
instance.open(panelId) Opens the panel with this id, closing another. Returns false when already open, unknown, unavailable or canceled
instance.close(reason) Closes the open panel; reason is api (the default), trigger, keyboard or pointer. Returns false when none is open or canceled
instance.getState() Returns {openPanel, openDelay, closeDelay}; openPanel is an id or null
instance.destroy() Closes without events, removes listeners and shows every panel again
Event When
plf:navigation-menu:before-open Before a panel opens; cancelable
plf:navigation-menu:open After a panel opens
plf:navigation-menu:before-close Before a panel closes; cancelable
plf:navigation-menu:close After a panel closes

Each event’s detail:

Property Value
instance The Navigation Menu instance
reason api, trigger, keyboard or pointer
trigger The button or the followed link, or null from a method, Escape or leaving the menu
panel The panel that opens or closes
previousPanel The replaced panel, or null when panel replaces none
Key Action
Enter, Space On a button, toggles its panel
Down Arrow, Up Arrow On a button, open its panel at the first or last link; in a panel, move to the next or previous link
Left Arrow, Right Arrow Move between top-level links and buttons, or between the links in a panel
Home, End Move to the first or last top-level item, or link in a panel
Escape Closes the panel and returns focus to its button
Tab, Shift+Tab Follow the page order; leaving a panel closes it

React

NavigationMenu from @pelatform/react renders this navigation with the script’s click, hover and keyboard behavior, and each NavigationMenuItem with a trigger keeps its panel’s state, or the application sets it with open.

Prop Values Default
placement top, right, bottom, left bottom
align start, center, end start
openDelay Milliseconds of hover before opening 200
closeDelay Milliseconds before closing once the pointer leaves 150
open on NavigationMenuItem true while its panel is open, which the application changes in onOpenChange Its own state
defaultOpen on NavigationMenuItem true starts open when the application does not set open false
onOpenChange on NavigationMenuItem (open, reason), called when its panel opens or closes: trigger (its button or a followed link), keyboard (a key or the focus leaving) or pointer (a hover, the pointer leaving or a press outside) None
mega on NavigationMenuContent true for a wide panel false

The parts:

Part Element
NavigationMenuList A ul with navigation-menu-list
NavigationMenuItem An li with navigation-menu-item, which holds a link, or a trigger and its panel
NavigationMenuLink An a with navigation-menu-link
NavigationMenuTrigger A button with navigation-menu-trigger, which opens its panel
NavigationMenuContent A div with navigation-menu-content: the panel
NavigationMenuGroups A div with navigation-menu-groups
NavigationMenuHeading A p with navigation-menu-heading
NavigationMenuLinks A ul with navigation-menu-links
NavigationMenuEntry An a with navigation-menu-entry, in which an Icon needs no class
NavigationMenuText A span with navigation-menu-text
NavigationMenuTitle A span with navigation-menu-title
NavigationMenuDescription A span with navigation-menu-description

Other props are the element’s own, className and ref included; a router’s link takes className="navigation-menu-link" or "navigation-menu-entry".

Variable Default
--plf-navigation-menu-width 18rem, or 36rem on mega panels; capped to the viewport
--plf-navigation-menu-padding Space 2 (8px)
--plf-navigation-menu-bg, --plf-navigation-menu-color Elevated surface and text
--plf-navigation-menu-border --plf-color-border-subtle
--plf-navigation-menu-radius Large radius (8px)
--plf-navigation-menu-shadow Medium shadow
--plf-navigation-menu-hover-bg --plf-color-surface-muted; also open buttons and the current link
--plf-navigation-menu-icon-size Control icon size (16px)

Built with Pelatform UIv0.1.0

Components

Getting started

Foundations

Components

Actions

Data display

Navigation

Feedback

Data input

Layout

Advanced

Integrations

Blocks

Application

Authentication

Icons