Placeholders & Live Text
Placeholders are text tokens NxGui replaces with live values when it draws a label or runs a command. NxGui resolves them in a fixed order: its own %nxgui_…% tokens first, then %player%, then PlaceholderAPI (if installed) for everything else.
The complete list
| Placeholder | Resolves to | Needs PAPI? |
|---|---|---|
%player% | The viewing player's username | No — always works |
%nxgui_arg_<name>% | An open-command argument the player typed (see below) | No |
%nxgui_<inputKey>% | The text a player typed into an Input box with that key | No |
%nxgui_<elementKey>% | A live component value: 0–100 for a progress bar / slider, true/false for a toggle / checkbox | No |
%state% | Element command only: the toggle / checkbox's new state (true/false) | No |
%value% | Element command only: the slider value as 0–100 | No |
%valueRaw% | Element command only: the slider value as an exact 0.000–1.000 | No |
%player_name%, %vault_eco_balance%, %statistic_…%, … | Anything from PlaceholderAPI and its expansions | Yes |
Note: %player% is built in; %player_name% is a PlaceholderAPI placeholder — they look alike but only %player% works without PAPI installed.
Argument placeholders — %nxgui_arg_<name>%
When a screen has an open command with arguments (Screen settings → Open command), each argument the player types becomes available two ways. Say your screen profile has a command /profile with a player argument named target:
/profile Notch
→ %nxgui_arg_target% == "Notch"- Use it in any text, command or another placeholder:
&fViewing &e%nxgui_arg_target%, or feed it to PAPI —%vault_eco_balance_%nxgui_arg_target%%-style nesting works because NxGui resolves its own tokens first. - Read it in logic with Get Variable → scope
session, namearg_<name>(herearg_target). The argument name is exactly what you set in the editor. - Arguments live in the session — they persist across in-place screen switches and clear when the menu closes. Number arguments arrive as numbers, everything else as text.
/vault <player> admin screen, a /profile <player> lookup, a /shop <category> jump. The argument flows into your labels, your Run Command nodes, and your open requirements.Element value placeholders — exact formats
Two ways to read a component's live value, with different formats — pick by where you're writing:
| Context | Toggle / Checkbox | Slider / Progress |
|---|---|---|
Anywhere — %nxgui_<key>% | true / false | 0–100 (whole percent) |
That element's own command — %state% | true / false | — |
That element's own command — %value% | — | 0–100 |
That element's own command — %valueRaw% | — | 0.000–1.000 |
%state%, %value% and %valueRaw% only substitute inside the Commands of the very element they belong to (they carry that element's just-changed value). To read another element's value from anywhere, use %nxgui_<thatKey>%, or in logic the Get Element Value node. Captured Input-box text is also readable via Get Element Value and the On Input trigger.
Where placeholders resolve
Everywhere text flows through NxGui:
- Text elements — labels re-resolve on the screen's refresh cycle.
- Element commands — plus the element-only
%state%/%value%/%valueRaw%. - Logic text inputs — Run Command, Send Message, Webhook body, and the Placeholder node (which resolves any of the above and outputs both Text and a parsed Number).
- Dynamic element sources — Player Head, Player Model, and QR Code all accept a placeholder (e.g. a leaderboard entry) as their source.
- Open requirements — the placeholder compare, its value, and the deny message.
Refresh cadence
Open screens re-resolve the placeholders in their text every placeholders.refresh-seconds (default 20). Override per screen in its settings — 0 = only on open. For a single fast-updating label, prefer an Every X Seconds → Set Element Text logic loop over cranking the whole screen's rate. (Placeholders inside commands resolve at the moment the command runs, not on the refresh clock.)
The anchor problem (and fix)
In-game text is centered on its position, so when %vault_eco_balance% changes from 100 to 1,000,000 the text grows in both directions and the left edge drifts. Set the text's Placeholder anchor to Left (or Right for right-aligned columns) and NxGui pins that edge on every refresh — stat rows stay perfectly aligned. The design canvas always shows the literal design text; anchoring is runtime behavior.
Design for variable width
- Placeholders are measured at their literal design length — leave room for the longest realistic value.
- Two-column stat grids beat three-column when values can be long.