Custom Top Navigation Links

:discourse2: Summary Custom Top Navigation Links allows you to add links to Discourse top navigation.
:eyeglasses: Preview Preview on
:hammer_and_wrench: Repository Link
:open_book: New to Discourse Themes? Beginner’s guide to using Discourse Themes

Install this theme component





A navigation link needs three things

  • Name
  • Description
  • Path or URL

Name is the text for the link that shows up on the menu. Description shows up when you hover the name like this:

Path/URL is where you want the link to go.

You can add links as semicolon delimited values in theme settings following this order


URL can also be relative like






Categories in "top menu"?
How to make some categories like Bugs and Features here visible in top menu?
How to add breadcrumb?
Add /groups to top nav
What about adding tags in the top menu?
Simple Unread List Plugin (discourse-simple-unread)
Adding link to blog on main page
How to add an icon in a navigation link?
Missing category and tags breadcrumbs
How can I add a link to the top menu area?
Why we can't add groups to top menu
How to add links on home page menu to other site?
Traditional multi level hierarchy vs flat discourse hierarchy
Ordering topics - how do the links work?
Force Mobile Homepage
Automatically fill category with topics? "Best of" category?
How to add new button in different color
Docs: Add link to top menu
New Theme: Tag-Pages Navigation
Topic list sidebar navigation
Where can I see posts created by me?
Discourse Docs (Documentation Management)
Showing categories statically above most recent posts
Custom nav items no longer showing after recent update
Add /groups to top nav
Displaying all non-solved topics
Add topics-sorted-by-create-time to `top menu`
Categories Customization
Volunteer Activities - a simple setup for non-hierarchical collaboration
Discourse Docs (Documentation Management)
Link to find all deleted posts by all users in a particular period
Reply reminder - Remind users to reply to new users topics with zero replies
How to add a topic in top nav in a specific category?
What is the proper way to extend categories route and filter topics?
Following tags and top feed for followed tags
Show latest list sorted by creation date
Following tags and top feed for followed tags
Change Topic List home router - from Latest to Following
A playful approach to category moderation
How can I add a menu item
Can we add "Groups" to top menu?
A "Votes" option for the top menu in main page
Adding a chat link in the top navigation links?
Add a specific class for wikis (when first post) at the topic list level


You’re most welcome.

So, because this theme extends the native navigation functionality in Discourse these features will not be available right away.

Sub-menus are not within the scope of this theme and even if I get something to work it would not be optimal. I think a separate theme component works better for this.

As far as opening links in a new tab, the assumption is that your navigation links will point to pages on your site and so there’s no built-in functionality to open top nav links in a new tab. However, you can do something like:

:warning: This is very rudimentary

<script type="text/discourse-plugin" version="0.8.18">
api.onPageChange(() => {
  $("#navigation-bar a").each(function() {
    var a = new RegExp("/" + + "/");
    if (!a.test(this.href)) {
      $(this).attr("target", "_blank");

What this will do is check if a nav link points to an external site and then opens it in a new tab instead. This could be vastly improved but will have to do until I have a bit more time to refine it.

New features!

Thanks to incredible contributions by @simon :fire: This component will now automatically check the page you’re on and highlight it. This matches the native behaviour in Discourse.

That’s the short story.

Now here’s the long (really long) version of this:

A bit more details about Latest / Top.

To make this easier to follow let’s use Theme creator as an example.

You visit theme creator and you get this:

The nav menu has 3 items, Latest, Top and Categories. Notice the highlight is on Latest.

The paths for those items are:


So far so good, now let’s go into the Movies category:

Now you see the category dropdown indicates that the current category is Movies and that highlight is on Latest. But there’a very big difference here.

These “Latest” and “Top” nav links are not the same from before. They are relative to the current category. Here’s what the paths look like:


This means that clicking Latest while in the Movies category shows you the latest in it and not on the top-level like /latest does

So why do I need to know any of this?

Well, let’s continue with theme creator. Let’s say I install this component and add a Movies link to the top navigation like so - notice the highlight is on the top level Latest or ( /latest )

Clicking this link takes you to /c/movies

So the category dropdown shows we’re on Movies and the new nav link is highlighted indicating that we’re on Movies.

So what happens if you click on latest now? This:

The category drop-down points to Movies, highlight points to latest and the Movies nav link is not highlighted This is the type of thing that will make Steve Krug think, which I hear he doesn’t like to do too much :sweat_smile:

The actual path is /c/movies/l/latest which means latest in movies. The same applies with Top.

So, now that you’ve read through all of that, you’re in a good position to make a judgement based on your needs.

Do you need the per-category filters of Top and Latest in the top nav? Or will top-level Latest and Top (/latest & /top) and using these be enough for your community?

So let’s say you’re OK with removing per-category filters from the navigation menu, what then?

Enter Minimal mode!

I’ve added two new settings in this version:

Hide dropdowns will hide these two:


And Hide default links will hide the default Latest and Categories links from the nav menu

I’ve kept those two separate because you might want to hide one but keep the other option visible.

So, let’s see what everything looks like with both on, but before we do that,

you have to change one of your site settings top_menu to look like this (same order!):

New and Unread are 100% optional, but Latest has to be #1 and Categories #2 for this to work right.

Here’s the result:

I don’t know about you but that looks too minimal to me :sweat_smile:

Now we have to create our own navigation. The placeholder or default for the links setting looks like this:

Latest;topics with recent posts;/latest
Categories;all topics grouped by category;/categories
Top;the most active topics in the last year, month, week or day;/top

This is enough to restore those three. You can then add more links.

Let’s go back to the theme creator example:

Let’s say I leave the three “default” values from above and I add two more links. One for the Movies category and one for the Art tag.

Here’s what that would look like:

The path is /latest and shows top-level latest posts.

Now let’s click on the Movies category:

So far so good, we’re on /c/movies and the the nav link for Movies is highlighted.

Now here’s where things change.

Clicking either Latest or Top now will take you to the top-level Latest and Top pages

So you end up going to /latest instead of /c/movies/l/latest and the same for Top.

The same thing happens with tag link “Art” that we added:

This is a lot less confusing and like I mentioned you can still use these filters inside categories / tags :

And if you prefer to keep the dropdowns if you have a large number of categories and tags, there’s no harm in that as well. Just disable the hide_dropdowns setting and things will look like this:

Clicking Latest above will still take you to top-level /latest just like the previous example.

That’s all. You’re now ready to make an informed decision based on your needs.

Update the theme and hack away!

Please let me know if anything is not clear enough.


I will always worship your work and depth of explanation, @Johani :heart:


would this also allow me to remove the default ones ?

The plugin works wonderfully on desktop, but it seems to be behaving strangely on mobile. When it is enabled on mobile, clicking the nav link dropdown would remove the header and reload the page without giving you the option to select another nav link. Anyone else experiencing the issue?


I use this theme component. One of the items in the menú points to a category and I would like to inform the unread topics for this category.


Instead of Agora I would like Agora (3) for an user who has three unread topics in this category (same behaviour as standard link “Unread”).

Any idea?

Thanks in advance.

I’d like to build a minimal navigation as outlined in the instructions above, but the menu doesn’t show up as intended whenever I navigate to a category page (/c/…)

The settings are:

Screenshot from 2021-03-30 14-28-39

And the menu shows as such:

Screenshot from 2021-03-30 14-20-43

But whenever I navigate to the last item (/c/curso), the menu only shows:

Screenshot from 2021-03-30 14-22-37

This happens when I navigate to other category pages as well (/c/…) Also independent of hiding dropdowns or default links.

Edit: I just tested it on a fresh installation with nothing else modified and get the same result. When navigating to a route with /c/, the related menu item is not highlighted and the first menu items are not rendered.

1 Like

I’m using this component again on another instance and still have the same issue.

So the component hides the first two nav items with CSS, using the :child pseudo selector. But the “Category” link is only rendered on global lists and not on category lists. So it will then hide the item that comes third on global lists.

I don’t know how to best avoid that. Maybe just drop the setting to hide the default items, as one has to use custom CSS to make it work anyways? Or make a change to core, so the Category-link always shows? In fact, I don’t really grasp the logic why the Category-link disappears when in category lists.

I’m in a Business Plan hosted Discourse and this is not working, I think.

First I tried entering the information for the link as indicated in the instructions:

Comma delimited in this order: link text, link title, URL, view, target, hide on scroll

This did not work. I however noticed how @nolo above wrote it using ; instead of commas and with no spaces. That did make something happen but that something looked liked this:

So the link was added all the way on the top and not next to the other top nav items.

I would be great for my team to make it work. I’m trying to use the Discourse Assign plugin and I thought it would be nice to have a top nav link to all the topics assigned to the current user ( )

there are only 3 settings, but you giving it more which might be an issue.


But the instructions in the component onced installed are much longer:

But I did try as you just said with just name;description;URL
assigned;topics assigned to you;

And it did not work:

try adding this

assigned;topics assigned to you;/latest?assigned=me
1 Like

Hold on, you confusing the two different components.

Custom Header Links & Nav Links Component

Nav Links is the one you looking for


LOL, you are right @IAmGav :sweat_smile: Nevermind, everything works, fake news.


Along with:

  • Hide all (Category & tags) dropdowns

Would it be possible to add:

  • Hide Categories dropdown
  • Hide Tags dropdown

So that each can be hidden separately or together?

There are some warnings/errors after update to 2.9.0.beta2.
Maybe it was before 2.9.0 as I never pay attention earlier.

[Warning] [THEME 6 ‘Nav Links Component’] – “To prevent errors in tests, add a pluginId key to your modifyClass call. This will ensure the modification is only applied once.” (application-02f34826699ddd1471a048c99dbf7e34.js, line 4135, x2)

Does someone know how I could add a tag link that is actually relative to the current route? I’d like to use a tag About and offer it as a top link it to an About-topic relative to the category a user is in.

E.g. user is in category /c/feedback/7. Choosing About will direct to /tags/c/feedback/7/about.

1 Like

I’d like to use the component on an instance but various behavior is not working:

  • When using “hide default links” it’s hiding the first two child items (Latest and Categories). But when one navigates to a category, the default “Categories”- Link is already not shown in the menu. Then this setting hides an additional navigation item, the otherwise third in line.

Screenshot from 2022-05-10 18-29-05

  • I added a menu item for a direct category link (/c/game-talk). When I navigate to it, it doesn’t get an active class and is not highlighted. Instead, the “Latest” link is highlighted and has an active class. This is not the default “Latest” link though, but one I added through the component (only linking to /latest)

  • Actually, the “Latest” link does not get an active class either when it is not named “Latest”. So the active class on the current route doesn’t seem to work at all because of the component. This is the view on /latest but with another name for the Latest-link:

Just installed 2.9.0.beta5 and now the 3 menu items I created with this plugin are not visible anymore. They’re still clickable, but not rendered in full. The 3 menu items are at the top of this forum.

Also reported here:


Quick question-
Trying to create this and make the url ?order=created so users can browse recent topics.

This works perfectly fine on desktop but fails on mobile- the navigation-bar just reloads and won’t show the dropdown menu.