The Chat Component API

Jun 22, 2021
The Chat Component API
  • The Chat Component API

    Using the BungeeCord chat API to construct messages

    The Chat Component API is the preferred way of constructing and sending messages to players or displaying them on signs or in books. Unlike plain strings with formatting codes, the Chat Component API supports Hover- and Click Events, translateable messages, keybind components and many more.
    Chat Component API Javadoc

    The Component Builder API(top)

    Working with individual Components usually turns into a small code mess with many local variables and addExtra calls. You can see a glimpse of that in the individual component's section below.
    The ComponentBuilder allows for a much easier creation of messages, as it is chainable.
    All methods (excluding append and create) work on the last part appended to the builder.
    Each append will by default inherit the previous formatting (not events), so in the following example the "!" will also be bold.
    Code (Java):
    BaseComponent[] component =
        new ComponentBuilder("Hello ").color(ChatColor.RED)
    will display "Hello world!"
    Make sure you import the correct ChatColor when developing a Spigot plugin: net.md_5.bungee.api.ChatColor

    Common Pitfalls(top)

    • Creating a direct instance of BaseComponent will not work (i.e. player.sendMessage(new BaseComponent(){};). Use one of the components listed in Basics section.
    • Using the old style color codes with components (i.e player.sendMessage(new TextComponent(net.md_5.bungee.api.ChatColor.RED + ":-("));) does not work well and can cause client-side issues. Always run legacy text through TextComponent.fromLegacyText().

    Individual Components(top)

    The components provided by the API are KeybindComponent, SelectorComponent, ScoreComponent, TextComponent, and TranslatableComponent. The simplest component to use is the TextComponent. All of these are subclasses of BaseComponent.


    Display a keybind by user's settings. Available keybind identifiers can be found in Minecraft Wiki.
    Code (Java):
    new KeybindComponent("key.jump");


    This component processes a target selector into a pre-formatted set of discovered names.
    Multiple targets may be obtained, and with commas separating each one and a final "and" for the last target. The resulting format cannot be overwritten. This includes all styling from team prefixes, insertions, click events, and hover events.
    These values are filled in by the server-side implementation and cannot be used in BungeeCord therefore.
    As of 1.12.2, a bug ( MC-56373 ) prevents full usage within hover events.
    Code (Java):
    new SelectorComponent("@p[distance=10..]");


    This component displays the score based on a player score on the scoreboard.
    The name is the name of the player stored on the scoreboard, which may be a "fake" player. It can also be a target selector that must resolve to 1 target, and may target non-player entities.
    With a book, /tellraw, or /title, using the wildcard '*' in the place of a name or target selector will cause all players to see their own score in the specified objective.
    Signs cannot use the '*' wildcard
    These values are filled in by the server-side implementation and cannot be used in BungeeCord therefore.
    As of 1.12.2, a bug ( MC-56373 ) prevents full usage within hover events.
    Code (Java):
    new ScoreComponent("Dinnerbone", "objective");


    TextComponents are used to create plain messages.

    You would create a TextComponent as follows:
    Code (Java):
    new TextComponent("Hello world!");


    TranslatableComponents are used for client side translations. It can be used to send translation keys for the client translate client side, this means you are limited to the text provided by Minecraft (see here) unless a resource pack is used to add more. Some translations support arguments with can also be TranslatableComponents (or just TextComponents).
    Code (Java):
    TranslatableComponent giveMessage = new TranslatableComponent("commands.give.success");
    TranslatableComponent item = new TranslatableComponent("");
    TextComponent username = new TextComponent("Thinkofdeath");
    This will display "Given Diamond Sword * 32 to Thinkofdeath" for a client using en_US but a client using zh_CN will see "成功将 钻石剑 * 32 给予 Thinkofdeath"

    Sending Components to player(top)

    To send any component to a player, the following code is used:

    Initialise your component:
    Code (Java):
    BaseComponent component = ...
    Code (Java):
    BaseComponent[] component = ...
    Send message in BungeeCord:
    Code (Java):
    Send message in Spigot:
    Code (Java):

    Colors and Formatting Styles(top)

    The appearance of components may be modified by applying format styles such as Color, Bold, Italic, Underline, Strikethrough, Obfuscate, and Font.

    Here is an example, using a TextComponent;
    Code (Java):
    TextComponent message = new TextComponent("Hello world");
    If this component is sent to a player it would display as "Hello world".

    Any formatting and events also apply to any sub-components unless the component overrides it. For example, amending our above example:
    Code (Java):
    TextComponent message = new TextComponent("Hello ");
    TextComponent world = new TextComponent("world");
    our component would display "Hello world!"


    There are two chat events currently in Minecraft: ClickEvent and HoverEvent. As you can expect, hovering over text supplied by a component with a HoverEvent would show a tooltip based on an action and clicking whereas clicking on text with a ClickEvent would perform a certain action.

    Here's an example for a component with both a ClickEvent with action OPEN_URL attached and a HoverEvent displaying a text:
    Code (Java):
    TextComponent message = new TextComponent("Click me");
    message.setClickEvent(new ClickEvent(ClickEvent.Action.OPEN_URL, ""));
    message.setHoverEvent(new HoverEvent(HoverEvent.Action.SHOW_TEXT, new Text("Visit the Spigot website!")));
    The ComponentBuilder allows adding events to the last added message part with the .event(new XXEvent(...)) method.

    ClickEvent actions: CHANGE_PAGE, COPY_TO_CLIPBOARD, OPEN_FILE (only client can use it itself), OPEN_URL, RUN_COMMAND, SUGGEST_COMMAND

  • Loading...
  • Loading...