Hierarchical Taxonomy Menu
A Drupal module that creates hierarchical navigation menus from taxonomy vocabulary terms with support for images, collapsible behavior, and entity reference counting.
hierarchical_taxonomy_menu
Install
composer require 'drupal/hierarchical_taxonomy_menu:^2.0'
composer require 'drupal/hierarchical_taxonomy_menu:8.x-1.43'
Overview
Hierarchical Taxonomy Menu is a powerful Drupal module that transforms taxonomy vocabularies into fully functional hierarchical navigation menus. The module provides a configurable block that can be placed in any region of your site, automatically generating menu items from the terms in a selected vocabulary while preserving the parent-child hierarchy.
Key capabilities include the ability to display images alongside menu items (if your taxonomy terms have an image field or media image reference), collapsible and expandable menu behavior with JavaScript interactions, and dynamic block titles that update based on the current taxonomy term page. The module supports limiting the menu depth, filtering by a base term, and showing counts of nodes or commerce products that reference each term.
The module is fully translatable and respects the published status of terms per language. It includes a customizable Twig template that allows complete control over the HTML structure, making it easy to style the menu to match any design requirements. Caching options ensure optimal performance while keeping the menu content fresh.
Features
- Create hierarchical navigation menus from any taxonomy vocabulary with automatic parent-child structure preservation
- Display images next to menu items using image fields or media image references on taxonomy terms
- Configurable image sizing with pixel dimensions or image styles
- Collapsible/expandable menu behavior with JavaScript-powered expand/collapse animations
- Interactive parent mode allowing parent items to be both clickable links and toggle switches for submenus
- Dynamic block title that automatically matches the current taxonomy term name when viewing taxonomy term pages
- Control menu depth from 0 to 10 levels or unlimited sublevels
- Filter menu items by specifying a base term (by ID or name) to show only its descendants
- Dynamic base term mode that automatically sets the base term from the current taxonomy term page
- Display count of referencing nodes or commerce products next to each term
- Recursive entity count calculation that includes counts from all child terms
- Option to hide terms that have no referencing content (nodes/commerce products)
- Configurable caching with options from no caching to permanent cache
- Option to hide the entire block when the vocabulary is empty
- Full multilingual support with translation-aware term names and URLs
- Term status awareness that respects the published/unpublished state per language
- Customizable Twig template with theme suggestions per vocabulary
- BEM-style CSS classes for easy theming
- Active state highlighting for the current term in the menu
- Stay open functionality to keep the menu path expanded to the active term
Use Cases
Category Navigation Sidebar
Create a sidebar menu showing product or article categories from a taxonomy vocabulary. Users can browse content by clicking category terms, and child categories are shown in a hierarchical tree structure. Enable collapsible mode to conserve space while allowing users to expand categories of interest.
E-commerce Product Filtering
Display a product category menu with the count of available products next to each category. Enable 'Show count of referencing commerce products' and select the appropriate taxonomy reference field. Enable 'Exclude empty terms' to hide categories with no products. Users can see at a glance how many products are in each category.
Visual Category Menu with Icons
Add an image field to your taxonomy vocabulary and upload category icons or images for each term. Configure the block to display images using an image style like 'thumbnail'. The menu will show each category with its associated icon, creating a visually appealing navigation experience.
Contextual Subcategory Menu
Enable 'Dynamic Base term' to create a menu that automatically shows only the children of the current taxonomy term. When viewing a parent category page, the menu shows its subcategories. This is useful for deep category structures where you want to focus on the current location in the hierarchy.
Collapsible Documentation Navigation
For a documentation site organized by taxonomy, enable collapsible mode with 'Stay open at current taxonomy term'. The menu starts collapsed but automatically expands to show the path to the current page, helping users understand their location while keeping unrelated sections collapsed.
Multilingual Site Navigation
On a multilingual site with translated taxonomy terms, the menu automatically displays term names in the current language. The module respects per-language term status, so you can have terms published in some languages but not others, and the menu adapts accordingly.
Tips
- Use theme suggestions (hierarchical-taxonomy-menu--VOCABULARY.html.twig) to create vocabulary-specific templates with custom markup
- The block uses the 'taxonomy_term_list' cache tag, so the menu automatically updates when terms are added, edited, or deleted
- For better performance on sites with many taxonomy terms, use the cache settings to reduce database queries
- When using dynamic block title, the title only changes on taxonomy term pages - on other pages it shows the configured block title
- The 'Interactive parent' option adds a separate arrow toggle so parent items can be both links and expand/collapse triggers
- Image fields and Media image references are both supported for displaying images next to menu items
- Use 'Base term' to create multiple blocks from the same vocabulary showing different branches of the hierarchy
- The CSS classes follow BEM naming (block-taxonomymenu__*) for predictable styling
- Unpublished terms are automatically hidden from the menu based on the current language
Technical Details
Hooks 4
hook_help
Implements hook_help() to provide help text on the module's help page. Displays the contents of README.md, optionally rendered as Markdown if the Markdown module is enabled.
hook_theme
Implements hook_theme() to register the hierarchical_taxonomy_menu theme hook with its available variables.
template_preprocess_block
Implements template_preprocess_block() to dynamically set the block title to the current taxonomy term name when the dynamic_block_title option is enabled.
hook_theme_suggestions_HOOK
Implements hook_theme_suggestions_hierarchical_taxonomy_menu() to provide vocabulary-specific template suggestions.
Troubleshooting 6
Verify that the selected vocabulary contains published terms. Check if 'Hide block if output is empty' is enabled and if so, ensure there are terms to display. Also verify the base term setting is not filtering out all terms.
Ensure you selected the vocabulary option that includes the image field (e.g., 'Categories (with image: field_image)'). Verify that the image field on taxonomy terms has images uploaded. Check if image style settings are correct if using image styles.
Check browser console for JavaScript errors. Ensure the hierarchical_taxonomy_menu library is loading correctly. Verify jQuery is available on the page. The expand/collapse requires JavaScript to be enabled.
Ensure you have content (nodes or commerce products) that references the taxonomy terms. For commerce products, verify you selected the correct 'Referencing field' in block settings. Check that the referencing field exists and contains values.
The dynamic block title only works on taxonomy term pages (/taxonomy/term/ID). Ensure 'Make the block title match the current taxonomy term name' is enabled and 'Display title' is set to visible in block settings.
Verify that taxonomy terms have translations for the current language. Check that translated terms are published (status can differ per translation). Ensure the locale module is enabled and language detection is working.
Security Notes 3
- The module properly escapes term names and URLs in the template to prevent XSS vulnerabilities
- Term access is respected - unpublished terms are not shown to users without appropriate permissions
- The module uses Drupal's standard caching system with proper cache tags for security and performance