How to create a custom control panel section in Craft CMS

Oscar de la Hera Gomez
A flower that represents Craft CMS, beneath it sits the text "Custom Control Panel Section."

A step by step guide for creating a custom control panel section in Craft CMS as part of a Module or Plugin.

The following tutorial walks you through how to create a Craft CMS control panel section within a plugin or module, through the example of a plugin. It builds on top of our Open Source Craft CMS starter project which can be found at the repository below.

We recommend that you download or clone our Open Source starter project, check out the tutorial/plugin branch and complete the steps below. The changes can be found on the tutorial/cp-section.

git clone

Step One: Setup the Control Panel Section

A screenshot of our Craft CMS starter project showing the new Control Panel section.

There are two ways to setup a control panel section:

  • Set the hasCpSection boolean in your plugin to true.
  • Register a Control Panel Navigation item programatically.

Both are detailed below.

A | Set the hasCpSection boolean to true

In your Plugin.php, set the hasCpSection boolean to true using the following line.

public bool $hasCpSection = true;

This will tell Craft CMS that your plugin behaves as a control panel section and will route your requests to the handle (i.e. within your extra of your plugin's composer.json.

i.e. craftcmsstarterplugin in plugins/craft-cms-starter-plugin/src/composer.json line 30, will take you to

If you wish to change this url with flexibility, we recommend you set $hasCpSection to false and register a CP navigation item using the method detailed below.

B | Register a new CP Navigation Item

This method can be used to add any number of navigation items to your Craft CMS through a plugin or module.

To begin add the Event, RegisterCpNavItemsEvent and Cp Variable functionality to the top of your plugin or module, through the following lines:

use yii\base\Event;

use craft\events\RegisterCpNavItemsEvent;

use craft\web\twig\variables\Cp;

Subsquently, in your plugin's init function setup your even using the code similar to the one below.

Please replace the following items:

  • section-url with the url that you wish you control panel to have as section-url would lead to admin/section-url.
  • Section Label with the title that you wish the item to have
  • @mynamespace/path/to/icon.svg with the path to your icon.

Step Two: Setup the page

A screenshot of VSCode showing how to setup the template with the code below.

If you press the control panel section that appears you will get an error that looks like this:

A sample 404 error that occurs when clicking on the Control Panel navigation item if the template has not been setup correctly.

To fix this create an index.twig file within the templates folder of the plugin or module root folder. We recommend copying the code below to make it function as a standard Craft CMS Control Panel Section.

Please note that index.twig will lead to your standard handle (e. craftcmsstarterplugin in plugins/craft-cms-starter-plugin/src/composer.json line 30, will take you to

A different file, let's say file_name.twig, will be a page for a url equal to handle/file_name (i.e.

If you select the navigation item now it will look like this:

A screenshot of Craft CMS showing our Control Panel section working as expected.

Looking to add a custom icon or a UI to the control panel section? Follow the tutorial linked below.

Any Questions ?

We are actively looking for feedback on how to improve this resource. Please send us a note to with any thoughts or feedback you may have.

delasign logo

Book a Free Consultation.

An icon of an email.

Click here to email us.

Fill in the details below to book a free consultation or to let us know about something else. Whatever it is, we are here to help.

How can we help you ?

Contact Details