Custom Header Links

:discourse2: Summary Custom Header Links allows you to easily add custom text-based links to the header.
: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




(due to very limited space I don’t recommend adding more than one link on mobiles)


Adding links is straightforward. Every link needs 6 items. You enter comma delimited values in this order:

link text, link title, URL, view, target, hide on scroll

Link text: the text for the link.
Link title: the text that shows when the link is hovered.
URL: The path for the link (can be relative).
View: vdm = desktop and mobile, vdo = desktop only, vmo = mobile only.
Target: blank = opens in a new tab, self = opens in the same tab.
Hide on scroll: remove = hides the link when the title is expanded on topic pages keep = keeps the link visible even when the title is visible on topic pages.

If you’re not sure what hide on scroll does, here’s an example:

Most Liked and Privacy are set to keep and so they remain visible. The other links are set to remove, and so are hidden when the title expands in the header. This only affects topic pages.

Links position: This setting allows you to change the default layout so links will appear on the left near the logo instead of on the right. Note that when positioned to the left, links will automatically be hidden when scrolling within topics to make room for the topic title.

How can i add custom hamburger menu
Use categories or tags to structure a multilingual community
Display StatusPage status on as a header link
Control CSS based on user's logged in state
Header Submenus
Is anyone here using their Discourse instance as their entire website?
How to fire on every footer load (or page load?)
Custom links above header bar
Custom Header Links (icons)
Pre seeded posts all missing - Missing Terms of Service, FAQ and Privacy pages
Dropdown header links in the existing Header
Add a "curated personal learning" page for users
Redirect search icon to search page
Possible to change main logo URL?
2021: The Year in Review
How to add breadcrumb?
How to add contact us page?
Navigation bar above all post
Adding link to blog on main page
Best place(s) to link back to a non-forum homepage?
How can I add a new button to the topbar?
⬇️ Dropdown Header
How to fix logo size?
Links into the header block
Customize the header with links, icons, or menus
(Superseded) Add header menu links
Privacy Policy does't meet Google's requirements
Show "new topic" when not logged in
Link on Top header to Go to Home page of main site
How to finely scroll out custom header?
Can I add a icon and link back to my homesite at the top bar
Header Submenus
Custom Header links was automatically hide when scrolling topic page contents
Link behavior inconsistent
How to add a "button" which composes a pre-filled topic
Where to place project external URL?
Change destination of logo link
External header links are not opening in a new tab
How to split the forum into two main parts (general/groups) and how to display only subcategories I can create a new post in?
Add secondary url / embed into Wordpress
How can I add a button to the header?
Showing categories statically above most recent posts
Add a global header between Discourse & Website
Custom Header Links (icons)
How to make custom setting type
Is it possible to have users' job titles next to their names on posts?
Link to find all deleted posts by all users in a particular period
Embedding a whole Discourse forum on another site in an <iframe>
Dropdown links in existing Header
Insert Link to External Website

Hi Joe, when I add a link to the header that leads to a restricted category, the user that is not allowed to see it gets an error message instead of a 404. Is it possible to fix this? And maybe - as requested above - it makes sense to add a new parameter to show links only for certain group members?

1 Like

What’s the best way to customise the formatting of the link text? It looks like editing the CSS isn’t the best approach because the changes will be lost when the plugin’s updated.

I’d like to make it bold & change the text colour to match the site’s theme which will help it blend in.

At the moment the link looks like this -

& I’d like it to look like this -

It’d be useful to be able to customise the text depending on the theme too. I have a dark theme & a light theme with different colour fonts for each. I’d like to set the colour of the text to match the theme.

You need to create a new theme component with your changes and then add it in the same main themes where is the Custom Header Links


Thanks! I’ve done that now & it worked like a charm.

Out of interest, how does the site choose which CSS to use? If the standard theme component contains CSS that will set the font colour to $header_primary -

.headerLink {
  list-style: none;
  a {
    padding: 6px 10px;
    color: $header_primary;
    font-size: $font-up-1;

then how does it know to use the CSS from my new component instead?

.headerLink {
  list-style: none;
  a {
    color: #7A7A7A;

I just pushed some updates to this component

Not currently no, but we have this component if you prefer icons

No plans to add those as parameters to the settings as I’m trying to keep those short.

However, links will now have CSS classes added to them based on their text. So a link with the text “Most Viewed” would have the class most-viewed added to it.

You can then use these styles to hide it for anons

.anon {
  .headerLink.most-viewed {
    display: none;

If you want it to only be visible to anons, you can use

html:not(.anon) {
  .headerLink.most-viewed {
    display: none;

this is beyond the scope of this component.

Merged, thanks for that :+1:

Thanks for this :+1: Can you please have a look at the new changes and update the PR? I’m fine with adding icons as long as it maintains backwards compatibility and the icons are not required.

See the bit above about how links now have CSS classes. You’ll be able to use something similar with the user’s primary group name since that’s also added as a CSS class to the <body> tag.

CSS stands for cascading style sheet. Cascading here is the key.

If you write two CSS rules with the same specificity, whatever comes last will always apply.


body {
  background: red;

body {
  background: green;

if you use the CSS above, the <body> tag will end up with a green background because that rule came later so it overrides whatever comes before it - again, this only works if the specificity is the same.

If the specificity is not the same, whatever rule that’s more specific will apply regardless of the order. So, your CSS works because it’s loaded after the CSS from the component and it’s as specific.


This component is great, but I believe it lacks an important feature: the ability to move a link to the hamburger menu when, on mobile, it is hidden from the header. Indeed, in most cases, I think removing the link entirely breaks the UI.

Because I urgently needed this feature, I did a fork:

However, I would love to see this in the official component.

You can see a demo here (check this page both on desktop and mobile).


Thank you for sharing your work @syl :+1:

The goals of this component are pretty clear, it allows you to add links to the header with as little work as possible. As such, there are no plans to move the desktop-only links to the hamburger menu on mobile.

We’re generally very careful not to introduce any breaking changes, so it’s definitely feasible for you to maintain a fork of the component, but it’s not something that I would recommend.

That said, if you’re OK with some links being in the hamburger menu on mobile, then it follows that said links are not of the utmost importance and wouldn’t need to be in the desktop header in the first place. Have you considered using the Custom hamburger menu links component for these links alongside this component?

Such a setup would allow to you add the most important links in the header, while keeping less important ones tucked away in the hamburger menu on both desktop and mobile.


This isn’t the end of the world but it would be good if text wrapping for topic titles (which is the default behaviour) kicked in when the text hits a header link, rather than the title becoming “…”

The behaviour is the same for the topic title in the header whether you have this component installed or not. Long titles are truncated and an ellipsis is added at the end.

We never wrap the topic title in the header because the header has a fixed height and there isn’t enough space to display a multiline title and the topic’s category and tag information on a third line below that.

Of course, when you add links with this component, you will by definition reduce the space left for the title to display in. The component gives you a lot of control over what links to keep visible in the header if you’re on a topic page and the title is visible in the header.

That bit is covered in the installation instruction in the OP under “Hide on scroll”.


This plugin is amazing – I’m not good at plugins, so don’t know how to branch off of it myself, but I feel that Discourse has a nice “simplicity” feel to it – it would be great to support images/icons.

Here is a ghetto way of how I achieved a Discord icon:


(Minus the color saturation – HDR screenshot bugs are the worst)


After installed, make a new CSS component, or edit the theme directly:

Here is what I used –

    color: white;
        background-image: url('');
        background-repeat: no-repeat;
        background-size: 22px;
            color: rgba(0, 0, 0, 0);
            text-decoration: none;
                box-shadow: 0px 2px lightgray;

  • I had issues with hover effects, so a bottom box shadow on hover is the best I got, since these are images instead of unicode:


  • I named the above example d because you have to name it something. I make the font 0 opacity, so it gets hidden, but d allows me to utilize the d class.

  • Is there a way to do this? Probably. But this is the ghetto way to bring about ideas until something better reveals itself :slight_smile:


First of all this is a theme component, not a plugin. It is better to specify this before users get confused and try to install it like a plugin.

The second thing is, why you use this theme component instead of Iconified Header Links which serves the purpose of adding icons to the menu? :open_mouth:


Heck, that’s why I didn’t make a component – I’m still learning the terms.

Because it’s not cool enough to show up in that last of lazy-link-install components, I suppose ;D if the text links should be there, I wish the icons were there, too! It’s pretty awesome looking. Gonna check it out now.

EDIT: Works wonderfully.


It would be very nice to add another option other than vdm, vdo, vmo.

All of those mean that the header will appear at some point in the main task bar. It would be an excellent function, opening a whole new layer of functionality, if there was a 4th option so we could set menu items to only appear in the burger menu.

I suspect that’s a small tweak too :slight_smile:

To make sure what i’m saying is clear, i have pages like ‘team and partners’ which aren’t main menu items and should never appear in the main menu, but i would love for them to be in the burger menu along with other secondary menu links.


This works beautifully! It seems to disappear for me on an individual private messages page, though.

Replying to myself, this can be achieved using this plugin: Custom hamburger menu links

It seems defunct to have two plugins, when this one is already capable of putting menu links into the burger menu, and just needs a tiny tweak to unlock that functionality.

@Johani is that something you plan to add to this plugin? or is it better for those wanting to put menu links in the burger menu to build around your other plugin that i linked above?


I find the custom header links and burger links menus conflict with each other preventing admins from accessing the admin menu.

the use case we have, which i think is fairly common, is that we have a set number of links in the menu, yet on mobile there isn’t room for all of them. We resolve this by hiding some when the phone is held in portrait mode.

in this scenario a project like ours needs the ability to move some links into the menu when the phone is in portrait mode on a mobile (as we can do with the burger menu plugin). We also nee

1 Like

Great component.
Just what we were looking for: a way to show a simple menu with links to external pages and internal ones.

But we are having some trouble with it in mobiles. Is it a bug?
In a mobile -while displaying the forum in vertical view- there is no enough place for the menu and the standard buttons (search, site menu and user menu).
So the system hides that menus that are essential to forum navigation.

A user that is not connected cannot even connect, as he can not see the login button.

In horizontal view in the mobile everything seems to work OK.

If there is no place to put the header links, the component should show only the permanent (tagged as keep) ones and if there is no room either, just don’t show any link.
It is preferible to not showing the essential system menus.

Alternatively, if there is no room, the links could be displayed as a drop down list.

No, it is not that the links are note important, but impossible is impossible.
In the mobile in vertical position there is too few space, and the menu links are of less importance than the user menu, the hamburger itself or the login button.
So they should dissapear or be moved a a drop down list or the hamburger.

But in horizontal view there is enough space, so they should be showed.

Current implementation don’t let you decide to show them in other way in portrait mode or set different links in portrait or landscape mode in mobiles.

I’ve added a setting to this theme that allows the links to be displayed to the left as well. Due to the title position, these links are automatically hidden when scrolling within a topic.