MiniMessage is a text serialization format designed for the Minecraft ecosystem, specifically integrated through the Adventure library. It allows developers and server administrators to create complex, rich text components using a human-readable, tag-based string format. Unlike the legacy formatting codes that relied on section symbols (§) or ampersands (&), MiniMessage utilizes angle brackets (<tag>) to define styles, colors, and interactive events.

This format has become the industry standard for modern Minecraft server software such as Paper, Velocity, and Folia. It solves long-standing issues with nested formatting, color bleeding, and the lack of support for modern features like Hexadecimal colors and multi-stop gradients.

Core Mechanics of MiniMessage Syntax

The foundation of MiniMessage is its tag-based structure. Every stylistic choice or functional element is wrapped in tags, making it highly intuitive for anyone familiar with HTML or XML.

Opening and Closing Tags

To apply a style, a string is wrapped in an opening tag and a corresponding closing tag. For example, <red>Message</red> renders the word "Message" in red. The format is case-insensitive, meaning <RED>, <Red>, and <red> are treated identically, though lowercase is the recommended convention for maintainability.

Self-Closing Tags

For elements that do not contain text content, such as a line break, MiniMessage supports self-closing tags. Using <newline/> inserts a break without requiring a closing tag. This is particularly useful in configuration files where space and clarity are paramount.

Strict Mode and Parsing Logic

By default, the MiniMessage parser is lenient. If a tag is left unclosed, the parser automatically closes it at the end of the string. However, developers can enable "Strict Mode." In this mode, all tags must be closed in the reverse order they were opened (LIFO - Last In, First Out). Strict mode is often preferred in production environments to prevent layout breaking or unintended styling leaks in complex chat interfaces.

Colors and Decoration Standards

MiniMessage provides a robust system for visual customization, ranging from simple named colors to precise Hexadecimal values.

Standard Named Colors

MiniMessage supports all sixteen original Minecraft colors. These include:

  • Primary Colors: <red>, <blue>, <green>, <yellow>.
  • Secondary Colors: <aqua>, <gold>, <light_purple>, <white>.
  • Dark Variants: <dark_red>, <dark_blue>, <dark_green>, <dark_aqua>, <dark_gray>, <dark_purple>.
  • Grayscale: <gray>, <black>.

Hexadecimal and RGB Support

For modern servers utilizing "True Color" (introduced in Minecraft 1.16), MiniMessage supports Hex codes. The syntax is <#rrggbb>. For example, <#ff5555>Custom Red</#ff5555>. This allows for millions of color combinations, enabling precise branding for server networks.

Decoration Tags

Decorations can be toggled on and off. The standard decorations include:

  • Bold: <b> or <bold>
  • Italic: <i>, <italic>, or <em>
  • Underlined: <u> or <underlined>
  • Strikethrough: <st> or <strikethrough>
  • Obfuscated: <obf> or <obfuscated>

To disable a specific decoration within a nested string without resetting the entire format, the negation syntax is used: <!bold>. This effectively "turns off" the bold attribute for the subsequent text.

Interactive Elements and Events

One of the most powerful features of the MiniMessage format is the ability to embed interactivity directly into strings. This eliminates the need for complex JSON objects when defining chat menus or informational tooltips.

Click Events

Click events allow a player to interact with a chat message. The syntax follows the structure <click:action:value>.

  • Run Command: <click:run_command:/spawn>Click to teleport</click>. This executes the command as the player.
  • Suggest Command: <click:suggest_command:/msg >Message staff</click>. This populates the player's chat bar without sending the command.
  • Open URL: <click:open_url:https://example.com>Visit Website</click>.
  • Copy to Clipboard: <click:copy_to_clipboard:12345>Copy ID</click>.

Hover Events

Hover events display additional information when a player mouses over the text.

  • Show Text: <hover:show_text:'<red>Alert!'>Warning</hover>. Note that the value can contain further MiniMessage tags, allowing for styled tooltips.
  • Show Item: Used to display item tooltips. This usually requires NBT data or item IDs.
  • Show Entity: Displays entity information, including type and UUID.

Advanced Visual Effects

Beyond static colors, MiniMessage introduces dynamic visual effects that were previously impossible or extremely difficult to implement with legacy codes.

Gradients

The <gradient> tag creates a smooth transition between multiple colors.

  • Two-Tone: <gradient:red:blue>Symmetric Transition</gradient>
  • Multi-Stop: <gradient:#ff0000:#00ff00:#0000ff>RGB Flow</gradient>
  • Directional Control: You can specify the phase of the gradient to shift the colors along the string.

Rainbow and Transitions

The <rainbow> tag applies a cycling spectrum across the text. This is often used for "Donator" ranks or special announcements. The <transition> tag is similar to a gradient but is optimized for animated components where the color shifts over time based on a provided phase or ratio.

Shadow Control

In recent versions of the Adventure library, MiniMessage supports the <shadow> tag. This allows developers to modify the color and alpha of the text shadow, which is useful for creating high-contrast UI elements in custom fonts.

MiniMessage for Developers: Integration and API

Integrating MiniMessage into a Java project requires the Adventure library. The primary entry point is the MiniMessage class.

Deserialization

To convert a MiniMessage string into a Component (the object Minecraft uses to render text), use the following: