Formatter Expansion

The formatter expansion contains various placeholders that allow you to format numbers and text.

Download expansion

/papi ecloud download formatter

Statistics

Fetching data...
If this text doesn't change, check that you allow javascript to be executed.

Source Code

The Source code of this expansion is available on Codeberg

Placeholders

• Number
  • %formatter_number_format[_[locale]:[pattern]]_<number>%
  • %formatter_number_from:<time_unit>_to:<time_unit>_<number>%
  • %formatter_number_round[_[precision]:[rounding_mode]]_<number>%
  • %formatter_number_shorten[_<rounding_mode>]_<number>%
  • %formatter_number_time[_<time_unit>]_<number>%
• Text
  • %formatter_text_capitalize[_<option>]_<text>%
  • %formatter_text_length_<text>%
  • %formatter_text_lowercase_<text>%
  • %formatter_text_replace_[target]_[replacement]_<text>%
  • %formatter_text_substring_[start]:[end]_<text>%
  • %formatter_text_uppercase_<text>%

External Placeholders support

Placeholders from other expansions can be used by using the {<identifier>_<value>} pattern instead of the usual %<identifier>_<value>% pattern.

Using Percent Symbol (%) and Underscores (_) in placeholder

Due to how PlaceholderAPI handles placeholders can you not use the percent symbol in formatter. In addition can underscores also not be used as they can mess up the handling by the expansion.
To still be able to use these characters does the formatter expansion offer two special placeholders named {{prc}} and {{u}} respectively, which get replaced by their respective values.

Warning

You cannot use {{prc}} to use %<identifier>_<value>% placeholders in formatter. The expansion parses bracket-placeholders before converting its own placeholders.

Config Options

The following Configuration options can be found in the config.yml of PlaceholderAPI under the expansions -> formatter section.

formatting.pattern

Type	Default
String	#,###,###.##

The Pattern that should be used for the formatting placeholder.
Uses the special Pattern Characters of the DecimalFormat class in Java.

formatting.locale

Type	Default
String	en-US

The language and optional Country code to use.

Warning

You have to use - instead of _ for the country code option (i.e. en-US instead of en_US).

---

shorten.thousands

Type	Default
String	{{number}}K

Format used to indicate thousands. {{number}} will be replaced with the shortened number.

shorten.millions

Type	Default
String	{{number}}M

Format used to indicate millions. {{number}} will be replaced with the shortened number.

shorten.billions

Type	Default
String	{{number}}B

Format used to indicate billions. {{number}} will be replaced with the shortened number.

shorten.trillions

Type	Default
String	{{number}}T

Format used to indicate trillions. {{number}} will be replaced with the shortened number.

shorten.quadrillions

Type	Default
String	{{number}}Q

Format used to indicate quadrillions. {{number}} will be replaced with the shortened number.

shorten.quintillions

Type	Default
String	{{number}}Qi

Format used to indicate quintillions. {{number}} will be replaced with the shortened number.

shorten.sextillion

Type	Default
String	{{number}}Sx

Format used to indicate sextillion. {{number}} will be replaced with the shortened number.

shorten.septillions

Type	Default
String	{{number}}Sp

Format used to indicate septillions. {{number}} will be replaced with the shortened number.

shorten.octillions

Type	Default
String	{{number}}Oc

Format used to indicate octillions. {{number}} will be replaced with the shortened number.

shorten.nonillions

Type	Default
String	{{number}}No

Format used to indicate nonillions. {{number}} will be replaced with the shortened number.

shorten.decillions

Type	Default
String	{{number}}Dc

Format used to indicate decillions. {{number}} will be replaced with the shortened number.

shorten.pattern

Type	Default
String	###.#

The Pattern that should be used for the shortened number.
Uses the special Pattern Characters of the DecimalFormat class in Java.

shorten.rounding_mode

Type	Default
String	half-up

The rounding mode to use for the shortened number.

Available modes

• up
  Rounds away from zero. Always increases the digit prior to a non-zero discarded fraction.
  Examples:

  • -1.5 -> -2
  • -1.1 -> -2
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 2
  • 1.5 -> 2

• down
  Rounds towards zero. Always decreases the digit prior to a non-zero discarded fraction.
  Examples:

  • -1.5 -> -1
  • -1.1 -> -1
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 1
  • 1.5 -> 1

• ceiling
  Rounds towards positive infinity. Always rounds up if number is positive, otherwise rounds down.
  Examples:

  • -1.5 -> -1
  • -1.1 -> -1
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 2
  • 1.5 -> 2

• floor
  Rounds towards negative infinity. Always rounds down if number is positive, otherwise rounds up.
  Examples:

  • -1.5 -> -2
  • -1.1 -> -2
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 1
  • 1.5 -> 1

• half-up
  Rounds to nearest neighbour unless both neighbours are equidistant in which case it rounds up. This is what you're commonly teached in school.
  Examples:

  • -1.5 -> -2
  • -1.1 -> -1
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 1
  • 1.5 -> 2

• half-down
  Rounds to nearest neighbour unless both neighbours are equidistant in which case it rounds down.
  Examples:

  • -1.5 -> -1
  • -1.1 -> -1
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 1
  • 1.5 -> 1

• half-even
  Rounds to nearest neighbour unless both neighbours are equidistant in which case it rounds to nearest even neighbour (Up if digit to the left is odd, else down).
  Examples:

  • -1.5 -> -2
  • -1.1 -> -1
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 1
  • 1.5 -> 2

---

time.condensed

Type	Default
Boolean	false

Whether the value returned by the time placeholder should not contain spaces.

time.includeZeroDays

Type	Default
Boolean	false

Whether the value returned by the time placeholder should include zero days.

time.includeZeroHours

Type	Default
Boolean	false

Whether the value returned by the time placeholder should include zero hours.

time.includeZeroMinutes

Type	Default
Boolean	false

Whether the value returned by the time placeholder should include zero minutes.

time.includeZeroSeconds

Type	Default
Boolean	false

Whether the value returned by the time placeholder should include zero seconds.

time.includeZeroMilliseconds

Type	Default
Boolean	false

Whether the value returned by the time placeholder should include zero milliseconds.

time.days

Type	Default
String	{{number}}d

Format used to display days in the time placeholder. {{number}} will be replaced by the number of days.

time.hours

Type	Default
String	{{number}}h

Format used to display hours in the time placeholder. {{number}} will be replaced by the number of hours.

time.minutes

Type	Default
String	{{number}}m

Format used to display minutes in the time placeholder. {{number}} will be replaced by the number of minutes.

time.seconds

Type	Default
String	{{number}}s

Format used to display seconds in the time placeholder. {{number}} will be replaced by the number of seconds.

time.milliseconds

Type	Default
String	{{number}}ms

Format used to display milliseconds in the time placeholder. {{number}} will be replaced by the number of milliseconds.

time.belowZeroOutput

Type	Default
String	{{number}}

Sets the output that should be returned for the time placeholder when the provided number is less than zero.

• {{number}} will be replaced by the actual number.
• "null" will return null causing PlaceholderAPI to see the placeholder as invalid and return it as-is.

---

rounding.precision

Type	Default
Number	0

Number of decimals that should be displayed.

rounding.mode

Type	Default
String	half-up

The rounding behaviour that should be used by the rounding placeholder.

Available modes

• up
  Rounds away from zero. Always increases the digit prior to a non-zero discarded fraction.
  Examples:

  • -1.5 -> -2
  • -1.1 -> -2
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 2
  • 1.5 -> 2

• down
  Rounds towards zero. Always decreases the digit prior to a non-zero discarded fraction.
  Examples:

  • -1.5 -> -1
  • -1.1 -> -1
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 1
  • 1.5 -> 1

• ceiling
  Rounds towards positive infinity. Always rounds up if number is positive, otherwise rounds down.
  Examples:

  • -1.5 -> -1
  • -1.1 -> -1
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 2
  • 1.5 -> 2

• floor
  Rounds towards negative infinity. Always rounds down if number is positive, otherwise rounds up.
  Examples:

  • -1.5 -> -2
  • -1.1 -> -2
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 1
  • 1.5 -> 1

• half-up
  Rounds to nearest neighbour unless both neighbours are equidistant in which case it rounds up. This is what you're commonly teached in school.
  Examples:

  • -1.5 -> -2
  • -1.1 -> -1
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 1
  • 1.5 -> 2

• half-down
  Rounds to nearest neighbour unless both neighbours are equidistant in which case it rounds down.
  Examples:

  • -1.5 -> -1
  • -1.1 -> -1
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 1
  • 1.5 -> 1

• half-even
  Rounds to nearest neighbour unless both neighbours are equidistant in which case it rounds to nearest even neighbour (Up if digit to the left is odd, else down).
  Examples:

  • -1.5 -> -2
  • -1.1 -> -1
  • -1.0 -> -1
  • 1.0 -> 1
  • 1.1 -> 1
  • 1.5 -> 2

Changelog

Please see the CHANGELOG.md file on Codeberg for the latest changes.

---

Last update: 05. October 2025 ()