# PlaceholderAPI: one placeholder syntax for every plugin on a Spigot server > PlaceholderAPI is a Spigot plugin that gives server software a single format string for pulling values out of other plugins, with the per-plugin support arriving as separate expansions. It suits server owners and plugin developers who keep scoreboards, chat formats and holograms in sync, and it adds a dependency and a failure mode to every display. **PlaceholderAPI/PlaceholderAPI** — The best and simplest way to add placeholders to your server! - 2M+ Downloads - 3.5k+ Placeholders - Repository: https://github.com/PlaceholderAPI/PlaceholderAPI - Website: https://placeholderapi.com - Stars: 977 · Forks: 285 - Language: Java - License: GPL-3.0 - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/placeholderapi-placeholderapi ## A single format string instead of one syntax per plugin A Spigot server running several plugins ends up with a display problem. A scoreboard wants the player's rank, a chat format wants their prefix, a hologram wants a balance, and each of those plugins exposes its values in its own way. The usual outcome is that a plugin author hardcodes a format, or implements a private placeholder parser per supported plugin, which multiplies the maintenance work for every new plugin that appears. PlaceholderAPI is the community answer to that. The README describes it as a plugin for Spigot servers that allows server owners to display information from various plugins with a uniform format. The audience is therefore twofold: server owners who want their scoreboards, chat formats and menus to read from the same source, and plugin developers who want to publish values once rather than implement a bespoke parser for every consumer. The format is the point of the project. Rather than each plugin exposing its own syntax, there is one format string that every display plugin understands, and the question of which plugin a particular value comes from is resolved by the expansion layer rather than by the consumer. ## Expansions carry the per-plugin knowledge, and the cloud ships them Support for a specific plugin is provided either by that plugin itself or through an expansion. The README states that there are currently over 240 expansions supporting a wide variety of plugins, naming Essentials, Factions, LuckPerms and Vault as examples. This split is the architecture: the core plugin knows the format and the resolution mechanism, while an expansion knows one plugin's data model and how to fetch a value from it. Distribution is handled through the PAPI Expansion Cloud, described as a place where expansions can be downloaded in-game, with the cloud hosted at ecloud.placeholderapi.com. Installing in-game rather than uploading a jar to the server folder is the ergonomic win, and it also means expansion versions follow the server owner rather than the core plugin release cycle. Two supporting resources matter for planning. A placeholder list at helpch.at/placeholders catalogues what is available, and a wiki carries a tutorial on creating an expansion for developers who need a plugin that is not covered yet. The README also links a CI server for the project and a bStats plugin statistics page, plus distribution pages on Spigot, Hangar and Modrinth. ## Installing it and pulling in your first expansion The documentation does not give a command line install, because there is nothing to install from a shell on the server: PlaceholderAPI is a plugin jar and it is distributed as one. The README links three distribution pages, a Spigot resource, a Hangar page and a Modrinth page, and the standard Spigot workflow of dropping the jar into the plugins folder applies. Expansions are the second step, and here the project does describe the route in-game. You download them through the PAPI Expansion Cloud, which the README says may be done in-game, so you add the expansion for the plugin whose values you want to show, restart, and then reference its placeholders in whichever plugin consumes the format. The order matters and is easy to get wrong. The core plugin has to be present and loaded before an expansion for that plugin has anything to register with, and an expansion for a plugin that is not installed on your server will have nothing to read from. Before you plan a themed scoreboard, check the placeholder list for the specific plugin you care about, since coverage is per plugin and the list is the authoritative answer to whether your values exist. ## Building the plugin from the Gradle wrapper The repository is a Gradle project written in Java, with a Kotlin build script at the root. The wrapper scripts and the build configuration sit at the top level, alongside the source tree and a config directory, and the Gradle wrapper is what makes the build reproducible across machines: ```bash gradlew gradlew.bat ``` The two launcher scripts are the Windows and Unix entry points for the same wrapper, so a contributor on either platform invokes the same build without installing Gradle globally. The build definition itself is build.gradle.kts, with settings.gradle.kts beside it and a gradle/ directory holding the wrapper configuration. The source lives under src/, which is where the plugin logic and the expansion API live, and the config/ directory at the root is separate from it. There is no published documentation of the build outputs or the exact Gradle tasks, and the README does not describe a local build procedure, so a contributor following the contributing file in .github/ is the documented route rather than the README. ## Writing an expansion when the plugin you need is missing The extension point is the interesting part of the design, because it turns the coverage problem into a solvable one. The README points developers at the wiki page on creating a placeholder expansion, which contains a detailed tutorial. An expansion supplies the mapping from a placeholder string to a value for one plugin, and the core does the resolution, formatting and caching around it. The project treats this as a first-class contribution path rather than an afterthought. There is a contributing file, the wiki documents the tutorial, and the issue tracker plus Discord support are linked from the README for people who get stuck. The API version is tracked as a badge on the README, which gives expansion authors a visible indication of which core release they are building against. The practical consequence for an adopter is that coverage is a shared burden. If the plugin you need is not covered, the options are writing the expansion yourself, asking the plugin author to expose its values through PlaceholderAPI directly, which the README notes is the other supported route, or going without the value. ## The costs a server owner is taking on Every dependency is a failure mode, and this one sits in the display path, where a broken value shows up as a visible artefact on a live server rather than as an exception in a log. Several failure modes are structural. First, coverage is partial and per plugin. An expansion for an absent plugin resolves nothing, so a placeholder can return an empty or unresolved string in production even though the configuration looks correct. Second, the placeholder data is resolved at display time, which means the freshness of a scoreboard depends on the plugin that owns the underlying value, not on PlaceholderAPI. Third, there is a maintenance cost in the relationship between versions. The core plugin and the expansions evolve independently, and a placeholder that worked in one core release may change in the next. The release notes show the pattern: version 2.12.3, released on 2026-07-03, is described as carrying bug fixes and 26.2 support, so server version compatibility is an explicit part of the release work. Fourth, this is a Spigot plugin ecosystem project. It is not a general purpose templating library, and it cannot be lifted into a non-Minecraft server stack. ## Against writing placeholders into each consumer plugin The alternative is the one most small servers already use: let each display plugin hardcode its own format strings, or implement a small private parser that knows the handful of plugins it supports. The difference in approach is where the mapping lives. In the hardcoded approach, the knowledge of how to read a LuckPerms prefix or an Essentials balance sits inside every plugin that displays it. Each consumer carries its own syntax, each syntax is a maintenance commitment, and supporting a new source plugin means touching every consumer. PlaceholderAPI inverts that. The mapping moves into an expansion that is installed once, and consumers only need to know the shared format. The cost of the inversion is dependency weight and indirection. A consumer now needs PlaceholderAPI present, an expansion installed for the source plugin, and a version combination that works, whereas the hardcoded approach has none of those requirements. For one server with one scoreboard and one static value, the simpler approach is genuinely simpler. The trade pays off when several display surfaces read from several source plugins, which is exactly the case the project was built for. ## Conclusion Adopt PlaceholderAPI if your Spigot server already runs plugins whose values you want to show in several places at once, and you are willing to manage expansions as a separate installable layer. Do not adopt it for a single hardcoded string on a small server, since the extra dependency buys little there, and do not assume every plugin is covered without checking the placeholder list, because support arrives per plugin through an expansion. Verify first that an expansion exists for each plugin you rely on, and confirm the version your server runs against is served by the same release channel, since 2.12.3 added 26.2 support and the last push was on 2026-09-12. ## FAQ ### What does PlaceholderAPI do on a Spigot server? It lets server owners display information from various plugins through one uniform format string. Support for a particular plugin comes either from that plugin itself or from a separate expansion, and there are currently over 240 expansions. ### How do I install PlaceholderAPI and its expansions? The core plugin is distributed as a jar through the Spigot, Hangar and Modrinth pages linked in the README, and is placed in the server plugins folder. Expansions are then downloaded in-game through the PAPI Expansion Cloud at ecloud.placeholderapi.com. ### How can I check whether PlaceholderAPI supports the plugin I use? The README links a placeholder list at helpch.at/placeholders that catalogues what is available. If the plugin is missing there, the other route is to write an expansion yourself following the tutorial on the project wiki. ### What licence is PlaceholderAPI released under? The repository is listed under GPL-3.0 and a LICENSE file sits at the root. Read that file for the exact terms, since a copyleft licence carries conditions for distributed derivatives. ### Which PlaceholderAPI release should I use for a recent server version? Version 2.12.3 was released on 2026-07-03 with bug fixes and 26.2 support, following 2.12.2 on 2026-02-08 and 2.12.1 on 2026-02-03. Check that release note against the server version you run before upgrading. ### Can I build PlaceholderAPI from source? Yes, the repository is a Gradle project with the wrapper scripts gradlew and gradlew.bat at the root, a build.gradle.kts build definition and sources under src/. The README does not publish the individual build tasks, so the contributing file is the better starting point. ## Sources - [License: GPL-3.0](https://github.com/PlaceholderAPI/PlaceholderAPI/blob/master/LICENSE) - [PlaceholderAPI/PlaceholderAPI on GitHub](https://github.com/PlaceholderAPI/PlaceholderAPI) - [Project website](https://placeholderapi.com) - [README](https://github.com/PlaceholderAPI/PlaceholderAPI/blob/master/README.md) - [Releases](https://github.com/PlaceholderAPI/PlaceholderAPI/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/placeholderapi-placeholderapi