MiniMessage: easy formatted text

MiniMessage lets you write colorful, clickable Minecraft text as simple tags, like <green>Hello <bold>world. On this page you will learn every tag you need, how to put player names and numbers into messages safely, how to keep messages in a messages.yml file, and how to convert old &a color codes.

What MiniMessage is

On the previous page you built formatted text in Java: Component.text("Hi", NamedTextColor.GREEN).append(...). That is precise, but a long message turns into a long chain of method calls. MiniMessage is a second way to make the exact same component. You write the text with tags in angle brackets, a bit like HTML on a web page, and the library turns it into a component for you.

1<gold>Welcome, <aqua><bold>Steve</bold></aqua>! <gray>Type <yellow>/help</yellow> to start.

• An opening tag such as <gold> switches a style on. Everything after it uses that style.
• A closing tag with a slash, such as </bold>, switches it off again. You may leave closing tags out at the very end of a message.
• Some tags take values after a colon, such as <gradient:red:blue> or <click:run_command:/spawn>.

Sending MiniMessage from your plugin

There are two ways to turn MiniMessage text into something a player sees. Both are in this listener, which greets every player who joins:

1package com.example.minimessagefirst;2 3import net.kyori.adventure.text.Component;4import net.kyori.adventure.text.minimessage.MiniMessage;5import net.kyori.adventure.text.minimessage.tag.resolver.Formatter;6import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;7import org.bukkit.Bukkit;8import org.bukkit.entity.Player;9import org.bukkit.event.EventHandler;10import org.bukkit.event.Listener;11import org.bukkit.event.player.PlayerJoinEvent;12 13public final class JoinGreeter implements Listener {14 115    private static final MiniMessage MINI_MESSAGE = MiniMessage.miniMessage();16 17    @EventHandler18    public void onJoin(PlayerJoinEvent event) {19        Player player = event.getPlayer();20 221        player.sendRichMessage("<green>Welcome to the server!");22 323        Component greeting = MINI_MESSAGE.deserialize(424            "<gradient:gold:yellow><bold>Hello</bold></gradient> <aqua><name></aqua>, there are <white><online></white> players online.",625            Placeholder.unparsed("name", player.getName()),726            Formatter.number("online", Bukkit.getOnlinePlayers().size()));827        player.sendMessage(greeting);28 29        player.sendRichMessage(30            "<gray>Your name is <name>.",31            Placeholder.unparsed("name", player.getName()));32    }33}

The registration lines are the same as in Events and listeners:

1package com.example.minimessagefirst;2 3import org.bukkit.plugin.java.JavaPlugin;4 5public final class MiniFirstPlugin extends JavaPlugin {6 7    @Override8    public void onEnable() {9        getServer().getPluginManager().registerEvents(new JoinGreeter(), this);10    }11}

What Steve sees when he joins and one other player is online:

How tags work

Opening and closing

Tags nest like boxes. A closing tag closes the matching opening tag, and any tag that was opened after it:

1<red>This is red, <blue>this is blue</blue> and red again, <bold>bold and red</bold>.2<gold><bold>Everything</gold> after the gold closing tag is plain again.

Two more tools for taking styles away: <reset> clears everything at once, and a negated tag with an exclamation mark, such as <!bold>, switches just that one style off for the rest of the text. The negated form is also how you turn off the italics that item names get by default: <!italic>My sword.

Arguments and quotes

A colon separates a tag's arguments. When an argument contains a colon, a space or another tag, wrap it in single or double quotes:

1<hover:show_text:'<red>Careful, this is <bold>hot</bold>!'>Point at me2<click:run_command:'/msg Steve hello there'>Click to greet Steve

When MiniMessage does not understand a tag

MiniMessage never crashes on a typo. A tag it does not know is simply printed as text, and a closing tag with nothing to close is printed too. So if you see <gren> in chat, you misspelled a tag name. The old color codes are also not understood: &6Hello shows up as the letters &6Hello.

Showing a real angle bracket

To show a literal < that is not a tag, put a backslash in front of it. In a Java string the backslash itself must be doubled, because Java also uses the backslash as its own escape character:

1player.sendRichMessage("Type \\<name> to fill in a name");

For text you do not control, use the tools in the placeholder section below instead of escaping by hand.

The tags

These are all the tags a beginner needs. Every example below is MiniMessage, then what the player sees.

Colors

Use the 16 named colors (black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white) as tags, or a hex color. Hex is six digits after a hash sign: <#ff8800>. The long form <color:#ff8800> is the same. The exact colors are in the table on Text and colors with Adventure.

1<red>Red <#ff8800>orange <color:aqua>aqua <#7f5af0>violet

Decorations

Reset and newline

1<gold><bold>Title<reset> back to plain<newline><gray>A second line (you can also write br)

Gradient, rainbow and transition

These three change the color from letter to letter:

• <gradient:red:blue> fades between two or more colors. You can list as many as you like, with names or hex codes.
• <rainbow> runs through all rainbow colors. <rainbow:!> runs it backwards.
• <transition:red:blue:0.5> gives the whole text one color that sits partway between the two. The last number, from 0 to 1, says how far. It is useful for animations where your code changes the number every tick.

1<gradient:#7f5af0:#2cb67d><bold>Nebula Network</bold></gradient>2<rainbow>Every letter is a different color</rainbow>3<gradient:red:gold:green>A three color gradient</gradient>4<transition:red:blue:0.5>Exactly halfway</transition>

Click

The first value is the action, and the second is what it works on. These are the same actions as on the previous page:

Hover

<hover:show_text:'...'> shows a tooltip, and the tooltip can contain tags too. <hover:show_item:diamond_sword:1> shows an item's real tooltip. Put a hover and a click on the same text by nesting them:

1<click:run_command:/spawn><hover:show_text:'<gray>Teleports you to <green>spawn'><green>[Go to spawn]</hover></click>

Key, lang, font and insertion

• <key:key.jump> shows the key the player really uses for jumping, even if they changed it. Use it in tutorials: "Press <key:key.jump> twice to fly".
• <lang:item.minecraft.diamond_sword> shows a vanilla name in the player's own language, like a translatable component.
• <font:uniform> switches the font. The names come from the resource pack; uniform, alt and illageralt are built into the game.
• <insert:Steve> pastes "Steve" into the chat box when a player shift-clicks the text.

1Press <yellow><key:key.jump></yellow> twice to fly.2You found a <aqua><lang:item.minecraft.diamond_sword></aqua>!3<insert:Steve>Shift-click my name

Placeholders: filling in names, numbers and more

Most messages contain something that changes: a player name, a score, a time. A placeholder is a gap you write as a tag, like <name>, and fill in from Java. You give MiniMessage a TagResolver, an object that says "when you see the tag name, put this here". Paper's sendRichMessage and MiniMessage's deserialize both accept any number of resolvers after the text.

Why unparsed matters: players can type tags

MiniMessage tags are just text, so a player can type them too. If you paste player text into your message as parsed, the player gets to use every tag, including the dangerous ones. Here is a chat feature that does this wrong:

1player.sendRichMessage(2    "<gray>Steve says: <msg>",13    Placeholder.parsed("msg", playerTypedText));

The fix is a one-word change. With unparsed, the tags stay as visible letters and do nothing:

1player.sendRichMessage(2    "<gray>Steve says: <msg>",13    Placeholder.unparsed("msg", playerTypedText));

The rule is simple: use unparsed for everything you did not write yourself. Use parsed only for text that comes from you or from your server's owner.

Two helpers fit nearby jobs. MiniMessage.miniMessage().escapeTags(text) puts backslashes in front of every tag so it can be pasted into a message safely, and MiniMessage.miniMessage().stripTags(text) removes all tags and keeps only the words:

1MiniMessage mini = MiniMessage.miniMessage();2String escaped = mini.escapeTags("<red>hi");3String stripped = mini.stripTags("<red>hi <bold>there</bold>");

After these two lines, escaped holds \<red>hi and stripped holds hi there.

Keeping messages in a messages.yml file

Messages hidden inside Java code are hard to change: every edit needs a rebuild. Server owners like to change wording, colors and languages, so most plugins keep their messages in a file next to the jar. The usual name is messages.yml. This is the file of the demo plugin:

11prefix: "<gradient:#7f5af0:#2cb67d><bold>Nebula</bold></gradient> <dark_gray>|</dark_gray> "22welcome: "<green>Welcome, <white><player></white>! <gray>There are <white><online></white> players online."33announce: "<gold><bold>Announcement</bold></gold> <gray>from <sender>:</gray> <yellow><message>"4usage: "<red>Usage: /announce your message here"5reloaded: "<green>Messages reloaded."6convert-usage: "<red>Usage: /convertcolors followed by old text with ampersand codes"7converted: "<gray>Converted, click to copy: <text>"

YAML quoting matters. Wrap every message in double quotes, because MiniMessage text has colons, angle brackets and sometimes single quotes, which YAML would otherwise misread. If you need a double quote inside, use single quotes for the outside. How YAML files work is explained on Configuration files.

A small helper class loads the file once, and then every part of the plugin asks it for a message by key:

1package com.example.minimessagedemo;2 3import java.io.File;4import java.io.IOException;5import java.io.InputStream;6import java.io.InputStreamReader;7import java.nio.charset.StandardCharsets;8import java.util.logging.Level;9import net.kyori.adventure.audience.Audience;10import net.kyori.adventure.text.Component;11import net.kyori.adventure.text.minimessage.MiniMessage;12import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver;13import org.bukkit.configuration.file.YamlConfiguration;14import org.bukkit.plugin.java.JavaPlugin;15 16public final class Messages {17 118    private static final String FILE_NAME = "messages.yml";19    private static final MiniMessage MINI_MESSAGE = MiniMessage.miniMessage();20 21    private final JavaPlugin plugin;22    private final File file;23    private YamlConfiguration yaml = new YamlConfiguration();24 25    public Messages(JavaPlugin plugin) {26        this.plugin = plugin;27        this.file = new File(plugin.getDataFolder(), FILE_NAME);28        reload();29    }30 31    public void reload() {32        if (!file.exists()) {233            plugin.saveResource(FILE_NAME, false);34        }335        YamlConfiguration loaded = YamlConfiguration.loadConfiguration(file);36        try (InputStream bundled = plugin.getResource(FILE_NAME)) {37            if (bundled != null) {438                loaded.setDefaults(YamlConfiguration.loadConfiguration(new InputStreamReader(bundled, StandardCharsets.UTF_8)));39            }40        } catch (IOException exception) {41            plugin.getLogger().log(Level.WARNING, "Could not read the bundled " + FILE_NAME, exception);42        }43        yaml = loaded;44    }45 546    public Component component(String key, TagResolver... resolvers) {647        String template = yaml.getString("prefix", "") + yaml.getString(key, key);48        return MINI_MESSAGE.deserialize(template, resolvers);49    }50 751    public void send(Audience audience, String key, TagResolver... resolvers) {52        audience.sendMessage(component(key, resolvers));53    }54 55    public void broadcast(String key, TagResolver... resolvers) {856        plugin.getServer().broadcast(component(key, resolvers));57    }58}

The /announce command

Now everything comes together. /announce Server restart in five minutes broadcasts the text with a gradient prefix, the sender's name and a gold heading. Staff with a special permission may use MiniMessage tags in their announcement. Everyone else's text is inserted safely:

1package com.example.minimessagedemo;2 3import io.papermc.paper.command.brigadier.BasicCommand;4import io.papermc.paper.command.brigadier.CommandSourceStack;5import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;6import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver;7import org.bukkit.command.CommandSender;8 19public final class AnnounceCommand implements BasicCommand {10 11    private static final String FORMAT_PERMISSION = "minimessagedemo.announce.format";12 13    private final Messages messages;14 15    public AnnounceCommand(Messages messages) {16        this.messages = messages;17    }18 19    @Override20    public void execute(CommandSourceStack source, String[] args) {221        CommandSender sender = source.getSender();322        if (args.length == 0) {23            messages.send(sender, "usage");24            return;25        }26 427        String text = String.join(" ", args);528        TagResolver message = sender.hasPermission(FORMAT_PERMISSION)629            ? Placeholder.parsed("message", text)30            : Placeholder.unparsed("message", text);31 732        messages.broadcast("announce", message, Placeholder.unparsed("sender", sender.getName()));33    }34 35    @Override836    public String permission() {37        return "minimessagedemo.announce";38    }39}

That preview shows an announcement from a staff member who typed the rainbow tag themselves. The plugin class registers three commands and a join listener, and the listener sends the welcome message from the file. They are all in the downloadable project. This is the part of plugin.yml that declares the three permissions (/announce, formatting in announcements, and /mmreload):

1name: MiniMessageDemo2version: '1.0.0'3main: com.example.minimessagedemo.MiniDemoPlugin4api-version: '26.3'5description: A /announce command with a gradient prefix and safe placeholders, messages from messages.yml, and a legacy color converter.6permissions:7  minimessagedemo.announce:8    description: Lets a player use /announce.29    default: op110  minimessagedemo.announce.format:11    description: Lets /announce use MiniMessage tags in the text.12    default: op13  minimessagedemo.reload:14    description: Lets a player use /mmreload.15    default: op

Download the demo as a Gradle project, or open the code in the Compile Lab.

Converting old & color codes

Old plugins and old configs use codes such as &6[VIP] &fSteve. MiniMessage does not read them. You can convert a message in two ways:

• By hand or with a tool. Paste the old text into the MiniMessage Studio and rewrite it with tags. For short messages this takes a minute.
• With code. Read the old text with the legacy serializer from the previous page, which makes a component, then write that component back out as MiniMessage with MiniMessage.miniMessage().serialize(component). The /convertcolors command in the demo does exactly this:

26@Override27public void execute(CommandSourceStack source, String[] args) {28    if (args.length == 0) {29        messages.send(source.getSender(), "convert-usage");30        return;31    }32 133    Component parsed = LEGACY.deserialize(String.join(" ", args));234    String converted = MiniMessage.miniMessage().serialize(parsed);335    Component copyable = Component.text(converted, NamedTextColor.WHITE)36        .hoverEvent(HoverEvent.showText(Component.text("Copy to clipboard", NamedTextColor.GRAY)))37        .clickEvent(ClickEvent.copyToClipboard(converted));438    messages.send(source.getSender(), "converted", Placeholder.component("text", copyable));39}

The conversions it makes:

Mistakes to avoid

• Using Placeholder.parsed for player text. Players can then add click events and fake messages. Use unparsed.
• A placeholder name that does not match. <player> in the text needs Placeholder.unparsed("player", ...).
• Naming a placeholder like a tag. <b>, <i>, <red> and <key> are already taken.
• Unquoted YAML. A message like welcome: <green>Hi breaks the file. Always wrap messages in quotes.
• Putting a placeholder inside a tag argument with unparsed. In <click:run_command:'/tp <who>'>, only parsed placeholders are filled in. Use a parsed placeholder only for text you trust, such as a player name you checked yourself, or build the click in Java and insert it with Placeholder.component.
• Forgetting that a closing tag also closes everything opened after it. <gold>a<bold>b</gold>c makes b bold and gold, and c plain.
• Using old & codes in MiniMessage text. They are not read. Convert them.

9@Override10public void execute(CommandSourceStack source, String[] args) {11    if (args.length == 0) {12        source.getSender().sendRichMessage("<red>Usage: /rainbow some text");13        return;14    }15 116    String text = String.join(" ", args);17    source.getSender().sendRichMessage(218        "<bold><rainbow><text></rainbow></bold>",319        Placeholder.unparsed("text", text));20}

1<gold><bold>[Shop]</bold></gold> <gray>Prices are in diamonds.

Recap

• MiniMessage writes components as text with tags: <gold> switches on, </gold> switches off, <!bold> negates one style.
• Send it with sender.sendRichMessage(text, resolvers...), or get a component with MiniMessage.miniMessage().deserialize(text, resolvers...).
• Colors, decorations, reset, newline, gradient, rainbow, transition, click, hover, key, lang, font and insert cover almost everything.
• Placeholders fill in gaps. Use Placeholder.unparsed for anything a player controls, parsed only for your own text, component for ready-made components and Formatter.number for numbers.
• Keep message texts in messages.yml, quoted, with a shared prefix, so server owners can edit them without rebuilding.
• Convert old & codes once, with the MiniMessage Studio or LegacyComponentSerializer plus MiniMessage#serialize.

Quick quiz

Next steps

• Titles, action bars, boss bars and sounds: more places to show MiniMessage text.
• Configuration files: everything about YAML and the config API.
• MiniMessage Studio: try any tag live.
• Project: Chat formatter and filter: where unparsed placeholders protect a real chat.