PlaceholderAPI, How to Make Your Own Placeholders

Why Create Custom Placeholders?

PlaceholderAPI ships with hundreds of expansion packs for popular plugins, but sometimes you need data that no existing expansion provides. Maybe you want to display a custom welcome message based on playtime, combine two existing placeholders into one, or pull data from a config file. Creating placeholderapi custom placeholders lets you fill those gaps without writing a full Java plugin.

Method 1: JavaScript Expansion

The JavaScript expansion is the easiest way to build placeholderapi custom placeholders. Install it from the eCloud, then write small scripts that return strings.

# Install the JavaScript expansion
/papi ecloud download JavaScript
/papi reload

Scripts go in plugins/PlaceholderAPI/javascripts/. Create a file called rank_greeting.js:

// rank_greeting.js
// Placeholder: %javascript_rank_greeting%
var player = BukkitPlayer;
var name = player.getName();
var group = "%luckperms_primary_group%";

if (group === "vip") {
  result = "&6[VIP] &fWelcome back, " + name + "!";
} else if (group === "admin") {
  result = "&c[Admin] &fHey " + name + ".";
} else {
  result = "&7Welcome, " + name + ".";
}

The variable result is what the placeholder returns. You can reference other placeholders inside the script by wrapping them in percent signs.

Method 2: Cloud Expansions

Before building from scratch, check if a cloud expansion already exists. PlaceholderAPI's eCloud hosts community-built expansions you can install with one command:

# Search for expansions
/papi ecloud list

# Download a specific expansion
/papi ecloud download Player
/papi reload

Each expansion registers its own placeholders. The Player expansion, for example, gives you %player_name%, %player_health%, %player_world%, and dozens more.

Method 3: Config-Based (Expansion Packs)

Some expansion packs support config-based placeholderapi custom placeholders. The "Math" expansion lets you create calculated placeholders in YAML:

# plugins/PlaceholderAPI/config.yml (Math expansion section)
math:
  kill_death_ratio:
    expression: "%statistic_kills% / (%statistic_deaths% + 1)"
    format: "#.##"

This creates %math_kill_death_ratio%, which divides kills by deaths (adding 1 to avoid division by zero) and formats to two decimal places.

Testing Your Placeholders

# Parse a placeholder for yourself
/papi parse me %javascript_rank_greeting%

# Parse for another player
/papi parse Notch %javascript_rank_greeting%

# List all registered placeholders
/papi list

Always test placeholderapi custom placeholders before using them in scoreboards or chat formats. The parse command shows you exactly what the placeholder returns.

Using Custom Placeholders in Other Plugins

Once registered, your custom placeholders work anywhere PlaceholderAPI is supported: TAB, DeluxeMenus, FeatherBoard, chat formatting plugins, and more. For example, in a TAB scoreboard config:

# TAB scoreboard.yml
lines:
  - "&eRank: %javascript_rank_greeting%"
  - "&eK/D: %math_kill_death_ratio%"

Performance Tips

• JavaScript placeholders run on the main thread. Keep scripts short and avoid loops or database calls.
• Cache results when possible by using static variables that update on a timer rather than recalculating every tick.
• Avoid nesting more than three placeholder references inside a single script.
• Use the /papi info <expansion> command to check if an expansion supports async parsing.

For initial PAPI setup, follow our How to Set Up PAPI (PlaceholderAPI) guide. To combine PAPI with Skript, see the How to Use PlaceholderAPI with Skript tutorial.

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