PlaceholderAPI Complete Setup Guide: Installing Expansions and Using Placeholders in Plugins

PlaceholderAPI (PAPI) is the universal placeholder system for Paper and Spigot servers. It allows any plugin to expose variables — player balance, rank name, online count, health, custom statistics — that any other plugin can display. Without PlaceholderAPI, every scoreboard plugin, hologram plugin and chat formatter would need to hard-code support for every economy plugin, permission plugin and stat tracker separately. With PAPI, they all get everything through a single API call.

Installation

Drop PlaceholderAPI into plugins/ and restart. No configuration is needed for the core plugin. Confirm it is running:

/papi version

How placeholders work

A placeholder is a string wrapped in percent signs, like %player_name% or %vault_eco_balance%. When a plugin that supports PAPI encounters one of these strings, it calls PAPI, which looks up the registered expansion for that prefix (everything between % and the first underscore), and returns the real value.

So %vault_eco_balance% works because:

1. The Vault expansion is installed and registered with PAPI.
2. PAPI identifies vault as the expansion prefix.
3. PAPI asks the Vault expansion to resolve eco_balance for the player.
4. The expansion queries Vault's economy API and returns the balance as a string.

Installing expansions

Most placeholders come from expansions — separate jars or registered handlers that you install alongside PlaceholderAPI. There are two ways to install them:

From the eCloud (online repository)

/papi ecloud list all           # browse available expansions
/papi ecloud search vault       # search for a specific expansion
/papi ecloud download Vault     # download and install
/papi reload                    # reload PAPI to activate

You can also install multiple at once:

/papi ecloud download Vault Player LuckPerms Essentials

Manual installation

Download the expansion jar and place it in plugins/PlaceholderAPI/expansions/. Then /papi reload.

Essential expansions to install

These are the expansions most servers need:

• Player — player stats: %player_name%, %player_health%, %player_max_health%, %player_level%, %player_exp%, %player_ping%, %player_world%, %player_gamemode%.
• Vault — economy: %vault_eco_balance%, %vault_eco_balance_formatted%, %vault_group%, %vault_prefix%, %vault_suffix%.
• LuckPerms — permissions data: %luckperms_prefix%, %luckperms_suffix%, %luckperms_primary_group%, %luckperms_context_<key>%.
• Server — server stats: %server_online%, %server_max_players%, %server_tps%, %server_uptime%, %server_ram_used%.
• Essentials — if using EssentialsX: %essentials_afk%, %essentials_godmode%, %essentials_vanished%, %essentials_homes_count%.
• MVdWPlaceholderAPI — if you use FeatherBoard or other MVdW plugins.

Testing placeholders

Before embedding a placeholder in a plugin config, always test it:

/papi parse me %vault_eco_balance%
/papi parse me %player_name%
/papi parse PlayerName %luckperms_primary_group%

/papi parse me tests a placeholder on yourself. /papi parse <name> tests it on another player. If the placeholder returns the raw string (e.g. %vault_eco_balance% instead of a number), the expansion is not installed, not loaded, or the underlying plugin (Vault in this case) is not running.

Using PAPI placeholders in plugin configs

Not every plugin supports PAPI out of the box. Check whether your plugin says "PlaceholderAPI support" in its documentation. Plugins with native PAPI support parse placeholders automatically. Plugins without native support need a hook.

EssentialsXChat

EssentialsXChat supports PAPI natively. In plugins/Essentials/config.yml:

chat:
  format: '&8[%luckperms_primary_group%&8] &r{DISPLAYNAME}&8: &f{MESSAGE}'

Note: EssentialsX uses its own {TOKENS} for some things and PAPI %placeholders% for others. Both work in the same format string.

CMI Holograms

CMI supports PAPI in hologram text. Create a hologram with:

/cmi hologram add TopBalance &cTop Players
&f%vault_eco_balance%

TAB plugin

TAB (scoreboard/tablist plugin) has deep PAPI integration. In plugins/TAB/config.yml:

header: "&aWelcome, %player_name%!"
footer: "&7Balance: &e$%vault_eco_balance_formatted%"

Scoreboards with BoardGUI or Featherboard

lines:
  - "&aBalance: &f$%vault_eco_balance_formatted%"
  - "&7Online: &f%server_online%/%server_max_players%"
  - "&7Ping: &f%player_ping%ms"
  - "&7World: &f%player_world%"

Creating custom placeholders with a simple expansion

You can create custom placeholders without a full plugin by using the JavaScript expansion (eCloud: /papi ecloud download JavaScript). Create a file in plugins/PlaceholderAPI/javascripts/:

File: rank_color.js

var group = BukkitServer.getPlayer(player.getName()).then(function(p) {
  return p;
});
// Return a color code based on group
var groupName = PlaceholderAPI.setPlaceholders(player, '%luckperms_primary_group%');
switch(groupName) {
  case 'mvp+': return '&6';
  case 'mvp': return '&e';
  case 'vip+': return '&b';
  case 'vip': return '&a';
  default: return '&7';
}

Use it in configs as %javascript_rank_color%.

Relational placeholders

Some expansions support relational placeholders — placeholders that take two players as context. These are used in plugins that show information about another player relative to the current player (e.g., whether two players are friends). Relational placeholders use the format %rel_expansion_identifier%.

PAPI with Skript

The PlaceholderAPI Skript addon lets you use PAPI placeholders directly in Skript scripts:

on join:
  set {_balance} to placeholder "vault_eco_balance" of player
  send "&aYour balance: &f$%{_balance}%" to player

Troubleshooting PAPI

• Placeholder returns raw text: Expansion not installed or not loaded. Run /papi list to see installed expansions. Run /papi reload to reload them.
• Placeholder returns wrong value: The underlying plugin (Vault, LuckPerms, etc.) is not configured correctly. Test with /papi parse to isolate.
• Plugin does not parse placeholders: The plugin does not natively support PAPI. Check if there is a PAPI hook or addon for that plugin, or use a plugin that forwards parsed text.
• Server lag spikes: Some expansions query databases or APIs on every placeholder call. The Server expansion TPS placeholder is particularly known for this. Cache expensive placeholders in the plugin consuming them if possible.

Common use cases summary

• Scoreboard with live balance, ping and online count.
• Tablist header/footer with server TPS.
• Holograms on market stalls showing top seller or current price.
• Chat format showing rank, balance display, AFK status.
• Join message personalised to player rank and playtime.
• NPC dialogue that greets the player by name and shows their balance.

See these configs in action: Astroworld MC, IP play.astroworldmc.com, Java + Bedrock.