Create custom local tasks - P1

Tan Nguyen


In Drupal, local tasks are menu tabs or action links that appear as part of a menu tab on a page. These tasks are often used to represent various operations or sub-pages within a module. Local tasks are generally placed directly above content on pages(up to two levels), but can be dynamically positioned as a block. These are mostly used on administrative pages but frontend pages like user pages or the registration/login/new password pages also use local tasks. To create custom local tasks in Drupal, you can follow these general steps:

Static local tasks

Most local tasks that you need to define will be static. See the local tasks of views module as an example.

views local tasks

You can see 4 local tasks are:

  • List (/admin/structure/views)
  • Settings (/admin/structure/views/settings)
    • Basic (/admin/structure/views/settings) has path same with Settings 
    • Advanced (/admin/structure/views/settings/advanced)

In views_ui.links.task.yml defined like this:

  route_name: entity.view.collection
  title: List
  base_route: entity.view.collection

  route_name: views_ui.settings_basic
  title: Settings
  base_route: entity.view.collection

  route_name: views_ui.settings_basic
  title: Basic
  parent_id: views_ui.settings_tab

  route_name: views_ui.settings_advanced
  title: Advanced
  parent_id: views_ui.settings_tab
  weight: 10

Keys are:

  • route_name (required): The machine name of the local task route - this also determines where it's displayed.
  • route_parameters (optional): List of parameters names and values for the route.
  • title (optional): The title of the local action. By default, it will be passed through t() and localized. Strings with spaces should use single quotes.
  • title_context (optional): context for t()
  • base_route (optional): The route where the "root" tab (generally the top, leftmost one) is displayed and which serves to group a set of tabs.
  • parent_id (optional): The plugin ID of the tab that is the parent - only relevant for 2nd level tabs. If this is set, base_route should be omitted and will be supplied from the parent
  • options (optional): The set of localized options added to an element like attributes (class, id, style, etc..).
  • weight (optional): The integer weight (lower weight tabs are further left, default is 0).

And 2 notes:

  • You must have at least 2 tabs: If you have just a one tab, then it will not be displayed.
  • You must have a default tab to see other tabs.
#This is default tab and required to display other tabs.

  route_name: entity.view.collection
  title: List
  base_route: entity.view.collection


Let's create our local tasks, for example our module name is example then the local tasks shape like this:

  • Tab 1 (Default) with route name is example.test_page1
  • Tab 2 with route name is example.test_page2
  • Tab 3 with route name is example.test_page3
    • Tab 3.1 with route name is example.test_page3_1
    • Tab 3.2 with route name is example.test_page3_2

Then example.links.task.yml should be like this:

  route_name: example.test_page1
  title: 'Tab 1'
  base_route: example.test_page1

  route_name: example.test_page2
  title: 'Tab 2'
  base_route: example.test_page1

  route_name: example.test_page3
  title: 'Tab 3'
  base_route: example.test_page1

  route_name: example.test_page3_1
  title: 'Tab 3.1'
  parent_id: example.test_page3

  route_name: example.test_page3_2
  title: 'Tab 3.2'
  parent_id: example.test_page3
  weight: 9


Add new comment

The content of this field is kept private and will not be shown publicly.

Plain text

  • No HTML tags allowed.
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.


  • Allowed HTML tags: <em> <strong> <cite> <blockquote cite> <ul type> <ol start type> <li> <dl> <dt> <dd> <p>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.
  • Use [gist:#####] where ##### is your gist number to embed the gist
    You may also include a specific file within a multi-file gist with [gist:####:my_file].

Spread the word