A WordPress block plugin that adds Priority Plus pattern functionality to core WordPress navigation block. It automatically moves navigation items that don't fit into a responsive "More" dropdown menu as the viewport narrows.
Priority Plus Navigation is a responsive design pattern that keeps all navigation items visible at wide screen sizes, but progressively moves overflow items into a "More" dropdown at smaller screen sizes. This ensures the navigation remains usable on all devices without requiring a hamburger menu or breaking the layout.
- Core Navigation Variation - Extends the standard WordPress navigation block as a variation, no need to rebuild your menus
- Automatic Overflow Detection - Intelligently calculates available space and moves items to dropdown
- Easy Conversion - Transform any Navigation block to Priority Plus Navigation via block variations
- Customizable Toggle Button - Choose label text, colors, and padding for the "More" button
- Customizable Dropdown Menu - Full control over menu appearance with live preview: colors, borders, shadows, spacing
- Responsive by Design - Uses ResizeObserver for smooth, performant resizing
- Core Navigation Integration - Automatically detects and respects "Open submenus on click" setting
- Smart Mobile Detection - Automatically disables on mobile/hamburger mode to avoid conflicts
- Submenu Accordions - Items with submenus in the dropdown become accessible accordions
- Accessible - Proper ARIA attributes and keyboard support (Escape to close)
- Block Theme Ready - Full support for block themes with alignment, spacing, and color controls
- Multiple Blocks - Use multiple Priority Plus Navigation blocks on the same page
- Future-Proof - Since it extends core navigation, it benefits from WordPress core updates
- Clone or download this repository into your WordPress plugins directory:
cd wp-content/plugins/
git clone [repository-url] priority-plus-navigation- Install dependencies:
cd priority-plus-navigation
npm install- Build the plugin:
npm run build- Activate the plugin in WordPress Admin → Plugins
The Priority Plus Navigation is available as a variation of the core Navigation block. There are two ways to use it:
- In the block editor, click the + button to add a block
- Search for "Priority Plus Navigation" or "Navigation"
- When you see the Navigation block, look for the Priority Plus Navigation variation in the block variations panel
- Select the Priority Plus Navigation variation
- Configure your navigation using the familiar WordPress navigation tools
- Customize the "More" button label and icon in the block sidebar (Priority Plus Settings panel)
- Select any existing Navigation block
- In the block toolbar or block settings, look for the block variations switcher
- Choose "Priority Plus Navigation" from the variations
- Your navigation now has Priority Plus behavior enabled!
- Select a Priority Plus Navigation block
- In the block variations switcher, choose the standard "Navigation" variation
- The Priority Plus behavior is disabled, returning to standard WordPress navigation
Note: Legacy wrapper blocks (from previous versions) will continue to work on the frontend, but are no longer available for insertion in the editor. If you have existing wrapper blocks, consider converting them to the variation approach.
When Priority Plus Navigation is active, you'll find these control panels in the block inspector sidebar under the "Styles" tab:
- Toggle Button Label: Customize the text displayed on the "More" button (default: "More")
- Text Color: Color of the button text
- Text Hover Color: Color when hovering over the button
- Background Color: Background color of the button
- Background Hover Color: Background when hovering
- Padding: Control the internal padding of the toggle button
- Customize Menu: Opens a modal with a live preview where you can customize:
- Menu Colors: Background, item hover background, item text color, item hover text color
- Menu Styles: Border (with per-side control), border radius, box shadow
- Submenu Colors: Background, item hover background, item text color, item hover text color
- Menu Items: Item padding, submenu indent, item separator
The plugin automatically detects and respects settings from the Core Navigation block:
-
Open submenus on click - When enabled in Core Navigation, submenus in the "More" dropdown become clickable accordions. When disabled, the link remains functional with a separate arrow button to toggle the submenu.
-
Overlay Menu - Controls when the responsive overlay/hamburger menu appears:
- Never: No overlay menu (Priority Plus works at all screen sizes)
- Mobile: Overlay menu appears at mobile breakpoints (Priority Plus works on desktop, disables when hamburger menu activates)
- Always: Always shows overlay menu (Priority Plus is automatically disabled and the "Always" option is visually disabled in the editor)
The block supports all standard WordPress block features:
- Alignment: Wide, Full
- Spacing: Margin, Padding
- Colors: Background, Text
Use the "Customize Menu" button in the block inspector to open a modal with a live preview. This is the easiest way to customize your dropdown menu and allows per-block customization.
For site-wide defaults, customize via your theme's theme.json. Block-level customizations will override these defaults.
{
"version": 3,
"settings": {
"custom": {
"priorityPlusNavigation": {
"dropdown": {
"backgroundColor": "#f0f0f0",
"borderColor": "#999999",
"borderWidth": "2px",
"borderRadius": "8px",
"boxShadow": "0 8px 16px rgba(0, 0, 0, 0.2)",
"itemSpacing": "1rem 1.5rem",
"itemHoverBackgroundColor": "rgba(0, 0, 0, 0.08)",
"itemHoverTextColor": "#007cba",
"multiLevelIndent": "3.5rem"
}
}
}
}
}📖 For complete styling documentation, examples, and troubleshooting, see docs/styling.md
The plugin extends the core Navigation block as a block variation:
core/navigation (with Priority Plus variation enabled)
├── core/navigation-link
├── core/navigation-submenu
├── core/page-list
└── etc.
The variation approach:
- Extends
core/navigationwith Priority Plus attributes and controls - Adds priority plus behavior via JavaScript on the frontend
- The core navigation block handles all menu functionality
- This approach is maintainable, future-proof, and integrates seamlessly with WordPress
- On page load: The script measures all navigation items
- Mobile detection: Automatically detects if WordPress is in hamburger/responsive mode and disables Priority Nav to avoid conflicts
- Overflow detection: Calculates how many items fit in available space
- Item distribution:
- Visible items stay in the main navigation
- Overflow items move to the "More" dropdown
- At least one item always remains visible
- Submenu handling: Items with submenus in the dropdown are converted to accessible accordions that respect the Core Navigation "Open on click" setting
- Responsive updates: ResizeObserver automatically recalculates on viewport changes
- Smooth transitions: Uses
requestAnimationFramefor optimal performance
- Node.js 14+ and npm
- WordPress 6.0+
- PHP 7.4+
# Install dependencies
npm install
# Start development mode with hot reload
npm run start
# Build for production
npm run build
# Lint JavaScript
npm run lint:js
# Lint CSS/SCSS
npm run lint:css
# Format code
npm run format
# Create plugin zip
npm run plugin-zippriority-plus-navigation/
├── build/ # Compiled assets (generated)
├── src/
│ ├── index.js # Editor extension entry point
│ ├── extend.js # Variation registration & block extension
│ ├── view.js # Frontend JavaScript
│ ├── style.scss # Frontend styles
│ └── block.json # Block configuration
├── priority-plus-navigation.php # Main plugin file
├── package.json # Node dependencies & scripts
└── README.md # Documentation
- Modern browsers (Chrome, Firefox, Safari, Edge)
- Uses ResizeObserver API (supported in all modern browsers)
- Falls back gracefully if JavaScript is disabled
- ARIA attributes:
aria-expanded,aria-haspopup,aria-label,aria-controls,aria-hidden - Keyboard navigation: Escape key closes dropdown and accordions
- Screen reader support: Proper semantic markup and ARIA relationships
- Focus management: Standard browser focus behavior
- Submenu accordions: Accessible accordion pattern for nested menus in dropdown
- ResizeObserver: Efficient viewport change detection
- requestAnimationFrame: Smooth, jank-free calculations
- Width caching: Minimizes layout recalculations
- Debounced recalculation: Prevents excessive computation
Priority Plus Navigation intelligently works with WordPress core navigation overlay menu settings:
- Never: Priority Plus is always active, providing responsive navigation through the "More" dropdown
- Mobile: Priority Plus works on desktop viewports and automatically disables when the hamburger menu becomes active
- Always: Priority Plus is completely disabled (not compatible), and the "Always" option appears greyed out and crossed out in the editor
The plugin detects when WordPress's overlay/hamburger menu is active by checking for the is-menu-open class on the responsive container. When this class is present, Priority Plus temporarily disables itself to avoid conflicts with the native hamburger menu.
- When using multiple Priority Plus Navigation blocks on the same page with "Open submenus on click" enabled, ensure each block has unique navigation content to avoid potential ID conflicts
- Priority Plus Navigation is not compatible with the "Always" overlay menu setting - it will automatically prevent usage and switch to "Mobile" mode
- Legacy wrapper blocks (from previous plugin versions) are no longer insertable in the editor, but will continue to function on the frontend for backward compatibility
- Added item text color controls for menu items (non-hover state)
- Added separate submenu color panel for nested accordion items
- Submenu colors include: background, item hover background, item text color, item hover text color
- Submenu background only applies to first-level submenus to prevent alpha transparency stacking
- Item separator controls for menu item dividers
- Added dropdown menu customizer modal with live preview
- Full control over menu colors: background, item hover background, item hover text
- Border customization with per-side control (top, right, bottom, left)
- Border radius and box shadow controls
- Menu item padding controls with theme spacing size support
- Submenu indent control for nested navigation
- Toggle button styling: text colors, background colors, hover states, padding
- Renamed attributes for clarity (
priorityPlus*prefix) - Improved reset functionality for all style controls
- Added intelligent overlay menu detection and compatibility
- Priority Plus now properly disables when hamburger menu is active (overlayMenu: 'mobile')
- "Always" overlay option is automatically prevented and visually disabled in editor
- Improved hamburger mode detection using
is-menu-openclass - Added overlay menu data attribute for frontend detection
- Enhanced documentation with overlay menu compatibility details
- Refactored to use block variation instead of wrapper block
- Namespaced variation name (
lumen-priority-plus-navigation) for better compatibility - Improved editor integration with
isActivedetection - Legacy wrapper blocks still supported on frontend for backward compatibility
- Priority Plus Navigation as core/navigation variation
- Customizable "More" button label and icon
- Full block theme support
- Responsive overflow detection
- Core Navigation "Open on click" integration
- Automatic hamburger mode detection
- Accessible accordion submenus in dropdown
Built with WordPress block development tools and inspired by the Priority Plus Navigation pattern.
GPL-2.0-or-later
For issues, questions, or contributions, please visit the plugin repository.