In Drupal 8, I want to add a menu item to the Admin Toolbar with a submenu, with different links.

How can I do it?

3 Answers 3


You can add items to the admin toolbar in two ways:

As content:

In ui /admin/structure/menu/manage/admin

or in code:

$item = \Drupal\menu_link_content\Entity\MenuLinkContent::create([
  'link' => ['uri' => 'internal:/<front>'],
  'title' => 'Front Page',
  'menu_name' => 'admin',

Or in static configuration files:

  title: Administration
  route_name: system.admin
  weight: 9
  menu_name: admin
  title: Content
  description: 'Find and manage content.'
  route_name: system.admin_content
  parent: system.admin
  weight: -10
  route_name: system.admin_structure
  parent: system.admin
  description: 'Administer blocks, content types, menus, etc.'
  title: Structure
  weight: -8
  route_name: system.themes_page
  title: Appearance
  description: 'Select and configure themes.'
  parent: system.admin
  weight: -6

This is the start of system.links.menu.yml, which defines the admin menu as we know it from D8. You can add your own entries in mymodule.links.menu.yml.


To add an item to the top row, use the hook mymodule_toolbar(). This is an example from the tour module:

 * Implements hook_toolbar().
function tour_toolbar() {
  $items = [];
  $items['tour'] = [
    '#cache' => [
      'contexts' => [

  if (!\Drupal::currentUser()->hasPermission('access tour')) {
    return $items;

  $items['tour'] += array(
    '#type' => 'toolbar_item',
    'tab' => array(
      '#type' => 'html_tag',
      '#tag' => 'button',
      '#value' => t('Tour'),
      '#attributes' => array(
        'class' => array('toolbar-icon', 'toolbar-icon-help'),
        'aria-pressed' => 'false',
    '#wrapper_attributes' => array(
      'class' => array('tour-toolbar-tab', 'hidden'),
      'id' => 'toolbar-tab-tour',
    '#attached' => array(
      'library' => array(
 return $items;
  • 1
    Thanks @4k4 but when I try to add it through the UI the item doesn't appear in the first level of the Administer option of the toolbar.
    – jmzea
    Commented Sep 23, 2016 at 9:45
  • 2
    To get an item in the top row, you have to use a hook. I put an example in the answer.
    – 4uk4
    Commented Sep 23, 2016 at 9:57
  • 1
    thank you for your answers, in the end I'm going to use the module [Toolbar Menu] (drupal.org/project/toolbar_menu) that adapts to what I need.
    – jmzea
    Commented Sep 23, 2016 at 10:39
  • Also worth to have a look at the devel module and their implementation of hook_toolbar and a ToolbarHandler.
    – leymannx
    Commented Dec 22, 2017 at 14:26
  • @4k4: Where do you add the first code? Commented Jan 26, 2018 at 17:53

For all who wonder where they may put code from previous answer – You can use it in MYMODULE.install for example

function MYMODULE_install(){
    $item = \Drupal\menu_link_content\Entity\MenuLinkContent::create([
      'link' => ['uri' => 'internal:/admin/link'],
      'title' => 'Link title',
      'menu_name' => 'admin',

In Drupal 9 a top menu item and submenu items can be added in the my_module.links.menu.yml

See here the example from group.links.menu.yml

  title: 'Groups'
  description: 'Find and manage groups, group types and group settings.'
  route_name: 'entity.group.collection'
  parent: 'system.admin'
  weight: 3

And then to add submenu items, use the menu link you defined above as parent

  title: 'Example submenu'
  description: 'Example description'
  route_name: my_route.name
  parent: 'system.admin_group'
  weight: 0

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.