Contextual link

Contextual links are shortcut menus that Drupal shows next to a part of the page, such as a block, a menu or a node, so a permitted user can edit or configure that part in place. They come from the core Contextual Links module, they sit behind a pencil icon, and a user needs the Use contextual links permission to see them.

How they work in Drupal 11

The User Guide explains that contextual links take you to some of the same pages as the administrative menu, but they sit near the content they affect. They stay hidden until activated. With default theme styling, a pencil icon shows that links are present, and clicking it reveals them. You activate the icon by hovering over the area with the mouse. With the Toolbar module, you can also click its Edit button at the right end of the top bar to activate all links on the page.

The standard installation profile of Drupal 11.4 enables the module, but its install list names Navigation rather than Toolbar, so a fresh standard site has no toolbar Edit button. The permission has the machine name access contextual links and the title Use contextual links. Core's toolbar button, when Toolbar is present, is added only for users who hold it.

For developers, the core of the system is the group. A module lists links in mymodule.links.contextual.yml, each with a title, a route_name and a group. A render array opts in with #contextual_links, naming the group and the route parameters. The theme template must print title_suffix, where the links are placed. Other modules can change links with hook_contextual_links_alter(), change their definitions with hook_contextual_links_plugins_alter(), or change the rendered element with hook_contextual_links_view_alter().

Example

Core's block module declares two links in the block group: Configure block, which opens the block edit form, and Remove block, which opens the delete form. Hover over a placed block, click the pencil and choose Configure block. The node module does the same with Edit and Delete.

Common mistakes

• Forgetting title_suffix. A custom template that does not print it never shows the links.
• Using a route that cannot resolve. Only routes that become a full path from the given route parameters belong in a group.

For marketing and content teams

Contextual links are the fastest way to fix a typo in a block, adjust a menu or open the edit form of the node you are reading. If a colleague sees the pencil and you do not, ask an administrator whether your role has the permission.

Sources

• Drupal User Guide: Concept: Administrative Overview
• Drupal.org: Providing module-defined contextual links
• Drupal API: Menu system topic (menu.api.php)
• Drupal core 11.4.10: contextual.permissions.yml
• Drupal core 11.4.10: contextual.api.php
• Drupal core 11.4.10: standard.info.yml
• Drupal core 11.4.10: block.links.contextual.yml