Skip to content

Feature guide: Belowname

Jump to bottom
NEZNAMY edited this page Aug 4, 2026 · 114 revisions

Content

About

This features gives you control over Minecraft's scoreboard objective feature with BELOW_NAME slot.
On Minecraft 1.21.11 and below, it is visible on all player entities (including NPCs). On 26.1.x, it is visible on all player entities and all named entities (such as holograms), making this feature unusable. On 26.2 and above, it only appears on entities with a score assigned (the ideal implementation).
It is only visible when the target player is within a 10-block range of the viewer (the value is configurable since Minecraft 26.1).

Example visual effect:

The displayed line is not one continuous configurable text. It consists of 2 parts (score and title) joined with a space.
The exact format is [score] + space + title (no, the space cannot be removed), where [score] is:

  • value for 1.20.2- (will show 0 on NPCs), which only supports numbers (integers)
  • fancy-value for 1.20.3+ (will show fancy-value-default on NPCs), which supports any text

As you can see, the feature still has limits, even on 1.20.3+. If you are below this version or still don't like the forced space before title, you are out of luck and cannot use this feature the way you would like to. If you have seen this feature seemingly limitless, it could be a feature that was a part of TAB, but removed later. This feature hid the original nametag and placed invisible armor stands instead. If you are interested in this kind of solution, you'll need to look into other plugins.

Configuration

The feature can be configured in config.yml under belowname-objective section.
This is how the default configuration looks:

belowname-objective:
  enabled: false
  value: "%health%"
  title: "&cHealth"
  fancy-value: "&c%health%"
  fancy-value-default: "NPC"
  disable-condition: '%world%=disabledworld'

All the options are explained in the following table.

Option name Default value Description
enabled true Enables / Disables the feature
value %health% [1.20.2-] An integer from -2147483648 to 2147483647, doesn't support decimal values. The number is always white. Supports placeholders with player-specific output, such as player health. Only visible on 1.20.2 and lower.
Note: Even if you only support 1.20.3+, you still need to configure this value to properly evaluate to a number, because the value is still sent to the client (just not displayed). You can set it to 0 for simplicity.
fancy-value &c%health% [1.20.3+] Any text, supports placeholders with per-player output. Only visible on 1.20.3+, where it completely replaces value. When evaluates to an empty string, the entire belowname is hidden for viewers using MC 26.2+ (when it was made possible).
fancy-value-default NPC [1.20.3 - 26.1.2] Default number format (fancy-value) for all player entities. fancy-value is displayed on every real player, therefore this default value will only appear on player entities which are not actual players, a.k.a. NPCs. Only visible on since 1.20.3 (the function did not exist prior) until 26.1.2 (player entities without scores no longer display any belowname since 26.2).
title Health Shared label shown after the score for every player entity. Player sees the same text on everyone (= placeholders are parsed for the viewer). Use the value/fancy-value fields for per‑player data; use title only for static labels like Health or placeholders which are supposed to be parsed for the viewing player.
disable-condition %world%=disabledworld A condition (either name of a condition or a conditional expression) that must be met for disabling the feature for players. Set to empty for not disabling the feature ever.
Note: Disabling the feature for a player means sending objective unregister packet to them, which results in player not seeing belowname on anyone anymore. It doesn't work the other way around - you cannot disable this feature on target players, only for viewers.
view-distance 10 [26.1+] How close (in blocks) to a player one must be to see their belowname. This value is configurable since Minecraft 26.1, so this option won't work on older versions.

Limitations

  • [1.12.2-] Title length is limited to 32 characters (including color codes).
  • [1.20.2-] value is limited to a white number.
  • [Bedrock] Doesn't support 1.20.3+ features (fancy-value), value will be displayed instead, just like on <1.20.3.
  • The format is a [score] + space + shared title. No, the space cannot be removed.
  • The title is the same on all players, therefore, it cannot be personalized (such as player's faction). Only [score] can be per-player.
  • It appears on all entities of player type. This includes player NPCs.

Compatibility with other plugins

TAB does not contain any sort of compatibility functionality for this feature. It will not try to prevent other plugins from applying the feature and neither will it detect it to re-add back once the other plugin removes it. Therefore, if another plugin also sends belowname objective, TAB's may not show anymore (depending on who sends it first). Make sure you do not have any other plugin sending it to ensure the feature works properly.

You can check the list of objectives registered by either commands or plugins using Bukkit API using /scoreboard objectives list.
If it contains one that could be the cause, you can unregister it by running /scoreboard objectives remove <name>. After doing so, reload TAB, so it resends its objectives again.
Note that if this was automatically generated by a plugin, it will probably be added back again.

Additional Info

Additional note 1 - Copying nametag visibility rule

The Minecraft feature is programmed to be affected by nametag visibility rule. This means that when the nametag is set to invisible, belowname will be invisible as well.

Additional note 2 - [1.8.x] Hidden on sneak

Belowname is not visible on 1.8.x clients when player is sneaking. This is client-sided behavior and cannot be changed by the server.

Additional note 3 - [26.1.2-] Visible on NPCs

Belowname objective is automatically attached to all entities of player type with the default value of 0 (<1.20.3) or value configured as fancy-value-default (1.20.3+). This includes player NPCs.

There is currently only one way to make them not visible on NPCs. From Additional note 1 - Copying nametag visibility rule we know that belowname is not visible if player's nametag is invisible. NPC plugin can take advantage of this by using teams to hide the original name and display a hologram instead.

This is how you can achieve it using the following popular NPC plugins:

  • Citizens:
    • 1 - Select the NPC (/npc select <ID> or /npc select to select the nearest NPC)
    • 2 - Hide its original nametag (which also hides belowname) using /npc name
    • 3 - Display your desired text using /npc hologram add <text> (more info)
  • FancyNpcs with FancyHolograms:
    • 1 - Create a hologram with /hologram create text <name>.
    • 2 - Link your newly created hologram with your NPC: /hologram edit <hologram name> linkWithNpc <NPC name>.
      Its original name will be hidden automatically, so you don't need to manually do it.
    • 3 - Change the NPC's name by editing your hologram's line(s): /hologram edit hi setline 1 <text>.
      You can also add more lines if you want. See FancyNpcs's wiki for more commands & info.

[26.1.x] Visible on all entities

In Minecraft version 26.1, Mojang "fixed" MC-99647, which reported that belowname is not visible on non-player entities. As a result, the belowname is now visible on all entities with a custom name (this even includes invisible armor stands, holograms and more). A new bug report was made for this: MC-307012.

This is a client-sided bug. You will experience it on 26.1.x regardless of the server version.
If your server is on 26.1.x, or you support players with this version through ViaVersion, this might be a dealbreaker for you. If that's the case, either disable this feature entirely, or set

belowname-objective:
  disable-condition: "%player-version-id%=775"

which will make 26.1.x players not see this feature on anyone (remember: disabling this feature disables it for the viewer, not target players).
This bug was fixed in Minecraft version 26.2.

Additional note 4 - Compatibility with modified clients

Sadly, this feature is suffering from bugs introduced by third party clients such as Feather and Lunar. These two completely ignore fancy-value as if it was never added into the game, even on 1.20.3+. This is just an example, and it's not limited to these two clients and this one issue. If you experience issues with the feature and believe you configured it correctly, use vanilla client to make sure it's not caused by a broken client.

Troubleshooting

This is a collection of tips to help you figure out why the feature isn't working as you expect.
To get started, run /tab dump <any player> (this feature doesn't contain per-player content in dump output) and open the generated link. Scroll down to features -> BelowName and check the content:

  • If it says BelowName: Feature is disabled, it means you disabled the feature. Enable it by setting 
    belowname-objective:
  enabled: true
  • Check the configuration section and compare it with your config file. If it's different, you either forgot to reload TAB, or uploaded the config to the wrong server (or did not upload it at all).
  • If a player cannot see belowname on anyone, check the table of players and make sure it's not because Disabled with condition is true.
  • Check the table of players for value, fancy-value and title and make sure they match your expectations. Don't forget value only supports numbers.
  • If you want to see fancy-value instead of just value's number:
    • Make sure your client is on 1.20.3+.
    • Make sure your server is on 1.20.3+ (using TAB on proxy counts as being latest).
    • Make sure you are not using a 3rd party client that removed this feature from 1.20.3+, such as Lunar or Feather.
  • Keep in mind title parses for viewer and is visible on all other players, it does not parse for each target player. Do not use placeholders with strictly per-player results in title.
  • If you have TAB on Velocity, install VelocityScoreboardAPI (and make sure it is not outdated).

Examples

Example 1 - Per-world values

This feature doesn't directly support per-world values or similar. However, this can be achieved with conditions. Let's make fancy-value conditional based on player's world. Let's make an example with 3 worlds. Check if player is in world world1, then show one text. If not, check if player is in world world2, then show another text. If not, show the final text. This can be achieved by chaining 2 conditions:

conditions:
  belowname1:
    conditions:
    - "%world%=world1"
    true: "Text to display in world world1" # Player is in world world1, display the text
    false: "%condition:belowname2%" # Player is not in world world1, check another condition
  belowname2:
    conditions:
    - "%world%=world2"
    true: "Text to display in world world2" # Player is in world world2, display the text
    false: "Text to display in other worlds" # Player is not in any of the 2 worlds

Warning

DO NOT JUST RANDOMLY PASTE THIS ENTIRE "CONDITIONS" SECTION INTO YOUR CONFIG! INSTEAD, EDIT YOUR EXISTING CONDITIONS SECTION TO PREVENT HAVING THE SECTION TWICE, HAVING SECOND ONE COMPLETELY OVERRIDE THE FIRST ONE!

Finally, use this condition as value in fancy-value:

belowname-objective:
  fancy-value: "%condition:belowname1%"

If you are under 1.20.3 and want to make value and title conditional, create two condition chains, one for each value and use them.

Note

This is just an example, the plugin is not limited to displaying different values only per world. If you want per server values on proxy, use %server% with server names. This works for any placeholder offered by TAB or by PlaceholderAPI.

Example 2 - Hiding title for 1.20.3+ players

1.20.3 has replaced value field, which is limited to a white number with value configurable as fancy-value, which has no limits. However, title field is still visible on 1.20.3+. If you support both version ranges and want to make the best out of the new functionality, you might want to not show title to 1.20.3+ players anymore, since you can fully customize the text you want to display in fancy-value.

First, let's remind ourselves what title actually is. It is actually called scoreboard title. Yes, just like the one on top of sidebar, just displayed elsewhere. This is why it displays on all players and placeholders are parsed for the viewing player. With this knowledge, all we need to do is check for player's version and only show something for <1.20.3. For this, we will use %player-version-id% placeholder, which returns the network protocol version of player's game version, which can then be compared to.

conditions:
  version:
    - "%player-version-id%>=765" # 1.20.3 is 765
  true: "" # Show empty value for 1.20.3+
  false: "Some text to display"

Warning

DO NOT JUST RANDOMLY PASTE THIS ENTIRE "CONDITIONS" SECTION INTO YOUR CONFIG! INSTEAD, EDIT YOUR EXISTING CONDITIONS SECTION TO PREVENT HAVING THE SECTION TWICE, HAVING SECOND ONE COMPLETELY OVERRIDE THE FIRST ONE!

belowname-objective:
  title: "%condition:version%"

Unfortunately, due to the limitations of this feature, there is a forced space between value/fancy-value and title, even if the title is empty. You'll either need to live with it, or put some shared text there to avoid having a space at the end.

Example 3 - Displaying health as 0-10 or in %

If you want health to display health as 0-10 instead of 0-20, you can achieve it with PlaceholderAPI:

  • %math_0_{player_health}/2% for 0-10
  • %math_0_{player_health}*5% for 0-100

Example 4 - Health bar using hearts

You can achieve this on 1.20.3+ using healthbar expansion from PlaceholderAPI:

belowname-objective:
  fancy-value: "%healthbar_healthbar%"
  title: ""
image

Sadly, there is no way to remove the forced space between fancy-value and title. You can only try to play around it by adding some static text after it, to make it look like the space is intended. Or you can just ignore the space and live with it.

Tips & Tricks

Tip 1 - Heart symbol

If you want to show health of players and display a heart symbol instead of text saying "Health", you can use this one: ❤.

belowname-objective:
  title: "&4❤"

Important

Make sure your config is saved in UTF-8 encoding to properly read the heart symbol.

Example 5 - Conditionally hiding belowname for 26.2+ viewers

Since Minecraft 26.2, belowname only appears on entities with a score. This can be used to disable the belowname on players with a condition. We are trying to achieve a condition like this: "If something, hide belowname for 26.2+ viewers".
TAB is made to reset score (= hide belowname) of target players for 26.2+ viewers (<26.2 viewers are not affected, resetting scores for them would result in fancy-value-default to be shown, which is undesirable) if fancy-value evaluated to an empty string. Therefore, we will need to make a relational condition that checks the viewer's version and returns empty string if some condition is met.
Here is an example of hiding it if target player has less than 10 health (5 hearts):

conditions:
  belowname-health:
    conditions:
      - "%viewer:player-version-id%>=776"  # 26.2 uses 776, check for viewer's version, not target player's
      - "%health%<10"  # This should check target player's health
    type: AND
    true: ""  # Viewer is on 26.2+ and target has less than 10 health, return empty string to hide it
    false: "%health%"  # Display health as normal

Then, use this condition as a relational condition (because it checks both viewer and target players):

belowname-objective:
  fancy-value: "%rel_condition:belowname-health%"

Getting started

Core features

Functions

Other

Clone this wiki locally