Title: Proposal: allow themes to add a top-level admin-menu
Author: acosmin
Published: July 13, 2020
Last modified: July 18, 2020

---

 [  ](https://profiles.wordpress.org/acosmin/) [acosmin](https://profiles.wordpress.org/acosmin/)
2:41 pm _on_ July 13, 2020      

# Proposal: allow themes to add a top-level admin-menu

The Themes Team would like to add the following requirements and we would also like
to hear your opinions on this matter.

    ```wp-block-code
    Themes should add a page under the Appearance menu using add_theme_page. If they need to have sub-pages (like for example documentation, FAQs, donation link etc), then they are allowed to use add_menu_page and add_submenu_page, provided they follow these requirements:
     * You are allowed to create only one (1) main page using `add_menu_page`. The recommended maximum number of sub-menu pages (`add_submenu_page`) is three (3).
     * The `$position` (priority) parameter must be `null` or only occupy the spot above the Appearance page (59). Check the code example on how to set the correct priority.
     * `add_submenu_page` must be used only on the page created using `add_menu_page`.
     * If you recommend plugins via TGMPA, you are required to use the `parent_slug` configuration option (this should be the top-level page's slug).
     * Core UI patterns must be used. You are not allowed to style the menu & submenu page links in any way. The admin color scheme must remain the same.
     * Use only monochromatic icons. It must account for the admin color scheme.
     * The title must be kept short and not include spam.
     * Child themes are allowed to add one extra sub-page or remove the parent's pages and add its own.
    ```

Before you start mentioning that this will be abused and it’s an open door for spam,
please consider these:

 * You can only have one theme active, which means there can only be one top-level
   link and it will not occupy that much screen real estate.
 * Themes are not allowed to add a panel with information to the blockBlock Block
   is the abstract term used to describe units of markup that, composed together,
   form the content or layout of a webpage using the WordPress editor. The idea 
   combines concepts of what in the past may have achieved with shortcodes, custom
   HTML, and embed discovery into a single consistent API and user experience. editor
   sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used
   by WordPress themes to display information that is not a part of the main content.
   It is not always a vertical column on the side. It can be a horizontal rectangle
   below or above the content area, footer, header, or any where in the theme./tools
   panel. Besides, the CustomizerCustomizer Tool built into WordPress core that 
   hooks into most modern themes. You can use it to preview and modify many of your
   site’s appearance settings. will be used less and less and theme authors need
   to have a visible way to list their theme’s documentation & information.

If you need more info, please check [add_menu_page](https://developer.wordpress.org/reference/functions/add_menu_page/)
and [add_submenu_page](https://developer.wordpress.org/reference/functions/add_submenu_page/).

_Added 15th July by [@williampatton](https://profiles.wordpress.org/williampatton/)_

For additional context about this idea we had a conversation in slackSlack Slack
is a Collaborative Group Chat Platform [https://slack.com/](https://slack.com/).
The WordPress community has its own Slack Channel at [https://make.wordpress.org/chat/](https://make.wordpress.org/chat/)
about this that started from this message and continued for quite some time – partially
async.

[https://wordpress.slack.com/archives/C02RP4Y3K/p1594225597110800](https://wordpress.slack.com/archives/C02RP4Y3K/p1594225597110800)(
slack account required)

_Added July 18th by [@acosmin](https://profiles.wordpress.org/acosmin/)_

After a few discussions and taking [@greenshady](https://profiles.wordpress.org/greenshady/)‘
s ideas into consideration, we’ve decided to:

 * remove the sub-pages limit, we recommend using a maximum of three (3)
 * the menu page priority can either be `null` or only occupy the position above
   the Appearance page. That’s 60 – 1, 59. This will also help users know where 
   to look for this page. You can use this code to make sure your page will always
   be after Appearance:

    ```wp-block-code
    function prefix_admin_menu() {
    	$menus = $GLOBALS[ 'menu' ];
    	$priority = array_filter( $menus, function( $item ) { 
    		return 'themes.php' === $item[2];
    	} );
    	$priority = ! empty( $priority ) && 1 === count( $priority ) ? key( $priority ) - 1 : null;

    	add_menu_page(
    		__( 'Theme Name Title', 'textdomain' ),
    		__( 'Theme Name', 'textdomain' ),

    		'edit_theme_options',
    		'theme-options.php',
    		'',
    		'dashicons-admin-customizer',
    		$priority
    	);
    }
    add_action( 'admin_menu', 'prefix_admin_menu' );
    ```

If you have suggestions on how to improve this code snippet, please do it in the
comments.

### Share this:

 * [  Threads ](https://make.wordpress.org/themes/2020/07/13/proposal-allow-themes-to-add-a-top-level-admin-menu/?share=threads)
 * [  Mastodon ](https://make.wordpress.org/themes/2020/07/13/proposal-allow-themes-to-add-a-top-level-admin-menu/?share=mastodon)
 * [  Bluesky ](https://make.wordpress.org/themes/2020/07/13/proposal-allow-themes-to-add-a-top-level-admin-menu/?share=bluesky)
 * [  Facebook ](https://make.wordpress.org/themes/2020/07/13/proposal-allow-themes-to-add-a-top-level-admin-menu/?share=facebook)
 * [  X ](https://make.wordpress.org/themes/2020/07/13/proposal-allow-themes-to-add-a-top-level-admin-menu/?share=x)
 * [  LinkedIn ](https://make.wordpress.org/themes/2020/07/13/proposal-allow-themes-to-add-a-top-level-admin-menu/?share=linkedin)

 * [Login to Reply](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fmake.wordpress.org%2Fthemes%2F2020%2F07%2F13%2Fproposal-allow-themes-to-add-a-top-level-admin-menu%2F%23respond&locale=en_US)

 1.  ![](https://secure.gravatar.com/avatar/27c0751de5ed93222d17118b8e8b3ea1f97be0c79dafaa270e454df903f1afd1?
     s=32&d=mm&r=g)
 2.   [kevinhaig](https://profiles.wordpress.org/kevinhaig/)  4:24 pm _on_ July 13,
     2020
 3.  Theme related stuff belongs under the Appearance menu. That is what the top level
     menu is for really. Nothing has changed since the past decision was made to not
     allow top level theme pages.
 4.  Now the Theme Page currently resides under the Appearance menu and I don’t really
     understand how a decline in CustomizerCustomizer Tool built into WordPress core
     that hooks into most modern themes. You can use it to preview and modify many 
     of your site’s appearance settings. use will prevent visibility of theme stuff.
     The customizer is just an Options APIAPI An API or Application Programming Interface
     is a software intermediary that allows programs to interact with each other and
     share data in limited, clearly defined ways. and Theme pages will still be under
     Appearance. Is the Appearance coreCore Core is the set of software required to
     run WordPress. The Core Development Team builds WordPress. menu going away?
 5.  It’s about better exposure for up sell in the end, which I find surprising is 
     not mentioned in the above post.
 6.  I believe that any user that wants to read documentation or Upgrade to Pro knows
     where to go…..if not Customizer which will be here for a while….then the Theme
     Page. The main reason for this request is to provide more exposure for up sell
     which will just lead to more spam…..which I am against.
 7.  Now if theme documentation is the main purpose of this then I would I would have
     no problem with a top level page if limited to one page and only a simple “Upgrade
     to Pro” at the top of the page. Authors can then up sell their theme on their 
     own site. A simple “Upgrade to Pro” link also is simpler to moderate…while “no
     obtrusive up sell” is purely subjective. We all know the squeaky wheel rule where
     authors seem to think the bigger and bolder the up sell, the better chance of 
     an up grade.
 8.  So if documentation is really the primary concern, let’s limit the up sell to 
     a simple “Upgrade to Pro” link which would let the users easily connect to the
     Author Theme Up Sell page for more details, and at the same time ensure the top
     level Theme Page remains spam free.
 9.  ![](https://secure.gravatar.com/avatar/6a97b9fdf799797b7e29604f11d3c6ba1da31e57f4fdb9f76dba09cb052770b1?
     s=32&d=mm&r=g)
 10.  [Joy](https://profiles.wordpress.org/joyously/)  5:58 pm _on_ July 14, 2020
 11. Do we have to repeat here all our arguments already made in SlackSlack Slack is
     a Collaborative Group Chat Platform [https://slack.com/](https://slack.com/). 
     The WordPress community has its own Slack Channel at [https://make.wordpress.org/chat/](https://make.wordpress.org/chat/)?
     Or are you going to judge this by the comments received here alone?
      I have no
     idea how decisions are made these days.
 12. Since the Theme Repository is not a marketplace, and we don’t want our policies
     to imply that it is, then any argument about usage patterns in the admin is moot.
     The admin is also not a marketplace.
 13. _Since_ there is only one active theme, it is an anti-pattern to have anything
     theme related outside of the Appearance menu. Users have been trained for years
     to expect that theme stuff belongs there. It would be a detriment to the users
     and their habits to put it anywhere else. We also have a rule (perhaps it isn’t
     written down) that the theme should not affect the admin, but only the theme page
     in the admin. I think changing the admin menu is affecting the admin, which themes
     shouldn’t be doing.
 14. Given that there have been years of experience to arrive at the current rule, 
     that should not be thrown away in an instant. There are good reasons why it exists
     in the first place.
 15. ![](https://secure.gravatar.com/avatar/0eff1a02b114621a84d70475314dd69b6bfc43994c699bf1c652082a015e06eb?
     s=32&d=mm&r=g)
 16.  [Rinku Y](https://profiles.wordpress.org/rinkuyadav999/)  7:01 am _on_ July 15,
     2020
 17. i think you should also mention that child themes are not allowed to do above.**
     only parent themes** are allow to add one parent menu and sub menus.
 18.  * ![](https://secure.gravatar.com/avatar/eb5d081232974bf03b5342543996762577822cf6c5f5e61d0200ed7a413a145a?
        s=32&d=mm&r=g)
      *  [acosmin](https://profiles.wordpress.org/acosmin/)  8:19 am _on_ July 15, 
        2020
      * Thanks! Good point.
      * ![](https://secure.gravatar.com/avatar/2016673465d9e645e763c634f4920e60b2d197239e44b2897f660562d9bb8ce0?
        s=32&d=mm&r=g)
      *  [codewatchers](https://profiles.wordpress.org/codewatchers/)  5:59 pm _on_
        August 2, 2020
      * Does that mean Child Themes creators aren’t allowed to add some documentation/
        donation link? That looks quite unfair.
 19. ![](https://secure.gravatar.com/avatar/eb5d081232974bf03b5342543996762577822cf6c5f5e61d0200ed7a413a145a?
     s=32&d=mm&r=g)
 20.  [acosmin](https://profiles.wordpress.org/acosmin/)  8:20 am _on_ July 15, 2020
 21. Updated the requirement with these 2 points:
 22. >  * If you recommend plugins via TGMPA, you are required to use the `parent_slug`
     >    configuration option (this should be the top-level page’s slug). Also, this
     >    counts to your sub-pages limit.
     >  * Child themes are allowed to add one extra sub-page or remove the parent’s
     >    pages and add its own.
 23. ![](https://secure.gravatar.com/avatar/8013a62d7397c006bae48b96d6832a573ea71a7d5d3597fe584210567b508c05?
     s=32&d=mm&r=g)
 24.  [Justin Tadlock](https://profiles.wordpress.org/greenshady/)  10:28 pm _on_ July
     15, 2020
 25. It would help to, at minimum, link to the previous discussions so that those new
     to this conversation get the full context.
 26.  * ![](https://secure.gravatar.com/avatar/d401f6723c24ce90038075be6a7990d02d2d7480fa3735f3697832fe393557d5?
        s=32&d=mm&r=g)
      *  [williampatton](https://profiles.wordpress.org/williampatton/)  10:39 pm _on_
        July 15, 2020
      * Good callout, I added a link to where conversation started. Thanks for suggesting
        this 🙂
 27. ![](https://secure.gravatar.com/avatar/dc27e41fbaecda47fe965166a9c6438f6dcb496316ee13316f9f8b0cfb718a60?
     s=32&d=mm&r=g)
 28.  [Nelmedia](https://profiles.wordpress.org/nelmedia/)  9:42 pm _on_ July 17, 2020
 29. I’m not a theme developer, but I’m a little surprise about this topic… I guess
     what you ask is only to be able to do it “legally”… because I’ve seen many themes
     that do add one, if not two, top-level menus…
      Personnally, as a user, I have 
     nothing against it… Most if not all the themes I use now are basic and therefore
     the Appearance menu is enough, but for some bigger themes (Asana, Jupiter, etc.)
     I don’t see it as negative to have their own menu… After all, IF the rules are
     well followed, it’s just one more menu… A lot of plugins do that and we don’t 
     argue “all plugins settings should be under plugins”… And if there is something
     that can become messy, it’s way more plugins than themes…
 30. ![](https://secure.gravatar.com/avatar/21b59213db15e407893dd9ecbd6fc389b7886133e886fdddeec48deaafc4ebc0?
     s=32&d=mm&r=g)
 31.  [andreiglingeanu](https://profiles.wordpress.org/andreiglingeanu/)  10:00 pm 
     _on_ July 17, 2020
 32. In most cases, companion plugins move the theme’s menu item to the 1st level anyway
     🙂
 33. ![](https://secure.gravatar.com/avatar/eb5d081232974bf03b5342543996762577822cf6c5f5e61d0200ed7a413a145a?
     s=32&d=mm&r=g)
 34.  [acosmin](https://profiles.wordpress.org/acosmin/)  11:27 am _on_ July 18, 2020
 35. Updated the post with some changes.
 36. ![](https://secure.gravatar.com/avatar/6a97b9fdf799797b7e29604f11d3c6ba1da31e57f4fdb9f76dba09cb052770b1?
     s=32&d=mm&r=g)
 37.  [Joy](https://profiles.wordpress.org/joyously/)  3:35 pm _on_ July 19, 2020
 38. The team has often complained that there are too many requirements, yet here you
     are swapping one requirement for 8. It seems like a regression to me.

### Leave a Reply 󠀁[Cancel reply](https://make.wordpress.org/themes/2020/07/13/proposal-allow-themes-to-add-a-top-level-admin-menu/?output_format=md#respond)󠁿

You must be [logged in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fmake.wordpress.org%2Fthemes%2F2020%2F07%2F13%2Fproposal-allow-themes-to-add-a-top-level-admin-menu%2F&locale=en_US)
to post a comment.

This site uses Akismet to reduce spam. [Learn how your comment data is processed.](https://akismet.com/privacy/)

# Post navigation

[← Gutenberg + Themes: Week of July 6, 2020](https://make.wordpress.org/themes/2020/07/10/gutenberg-themes-week-of-july-6-2020/)

[Block-based Themes Meeting Agenda for July 15, 2020 →](https://make.wordpress.org/themes/2020/07/14/block-based-themes-meeting-agenda-for-july-15-2020/)