Minecraft 1.21.5 Text Component Changes Explained

Minecraft Java 1.21.5 updates how commands and data tags handle formatted text by switching from raw JSON strings to direct SNBT syntax. This guide breaks down the exact formatting changes, updated event fields, and practical command examples so you can update your worlds and servers.

Tellraw GeneratorSign Text GeneratorWritten Book Generator

From JSON Strings to Direct SNBT

The biggest change in Minecraft Java 1.21.5 is how text components are wrapped inside commands and NBT data. In older versions, you had to write text components as JSON strings enclosed in single or double quotes, often requiring you to escape inner quotation marks. Starting in 1.21.5, text components are written directly as Stringified NBT (SNBT).

With SNBT, you no longer wrap the entire text object in outer quotes, and object keys do not need quotation marks around them. However, if you still have muscle memory or existing scripts that use quoted JSON-style keys, the game will still parse them as long as the outer string quotes are removed.

Here is how a basic chat command looks in 1.21.5:

/tellraw @a {text:"Welcome to the server!",color:"gold",bold:true}

Click Events: click_event and Action Fields

Interactive text that triggers when a player clicks it has been restructured. First, the camelCase key clickEvent has been renamed to the snake_case key click_event.

Second, in older versions, every click action used a generic value field to hold its data. In 1.21.5, the field name changes depending on the specific action you choose:

Follow these examples to set up each click action in 1.21.5:

/tellraw @a {text:"Open Website",color:"aqua",click_event:{action:"open_url",url:"https://text.9minecraft.net"}}
/tellraw @a {text:"Click to Teleport",color:"green",click_event:{action:"run_command",command:"/tp @s ~ ~10 ~"}}
/tellraw @a {text:"Suggest Help Command",color:"yellow",click_event:{action:"suggest_command",command:"/help"}}
/tellraw @a {text:"Copy Server IP",color:"light_purple",click_event:{action:"copy_to_clipboard",value:"play.example.com"}}

Hover Events: hover_event and show_text

Similar to click events, hover tooltips now use snake_case. The old hoverEvent key is now written as hover_event.

When displaying a text tooltip using the show_text action, the displayed content is placed inside the value field as a direct SNBT text component.

Here is how to combine both a hover event and a click event in a single 1.21.5 command:

/tellraw @a {text:"[Claim Daily Reward]",color:"gold",hover_event:{action:"show_text",value:{text:"Click to receive a Diamond",color:"aqua"}},click_event:{action:"run_command",command:"/give @s minecraft:diamond"}}

Formatting Item Names and Lore

Back in Minecraft 1.20.5, traditional item NBT tags were replaced by item components, introducing custom_name and lore for item text. However, prior to 1.21.5, you still had to feed JSON strings into those components.

In 1.21.5, both custom_name and lore accept SNBT text components directly without outer single quotes. Notice how much cleaner the syntax is when giving a customized item:

  1. Use custom_name={...} with a single SNBT text object for the item title.
  2. Use lore=[{...},{...}] with a list of SNBT text objects for each line of description.
/give @p minecraft:diamond_sword[custom_name={text:"Blade of Embers",color:"red",italic:false},lore=[{text:"Forged in lava",color:"gray"},{text:"Legendary Weapon",color:"gold",italic:false}]]

Updating Signs and Written Books

Blocks and items that store readable text also benefit from the 1.21.5 SNBT overhaul. Previously, sign messages and book pages required deeply nested, escaped JSON strings inside NBT data. Now, sign messages and book pages are written as text components directly.

To place or modify a sign with formatted text, write the text component straight into the messages list inside front_text or back_text:

/setblock ~ ~ ~ minecraft:oak_sign{front_text:{messages:[{text:"First Line",color:"black"},{text:"Click Me",color:"blue",click_event:{action:"run_command",command:"/say Hello!"}},{text:"",color:"black"},{text:"Last Line",color:"red"}]}}

For written books, you pass text components directly into the pages list inside the written_book_content component:

/give @p minecraft:written_book[written_book_content={title:"Server Guide",author:"Admin",pages:[{text:"Welcome to the server!",color:"dark_blue",bold:true},{text:"Click here for rules",color:"dark_green",click_event:{action:"open_url",url:"https://text.9minecraft.net"}}]}]

Step-by-Step Checklist for Migrating Old Commands

If you are updating command blocks, data packs, or server plugins from an older version to Java 1.21.5, follow this checklist to fix broken text components:

  1. Strip outer quotes: Remove the single quotes ('...') or escaped double quotes wrapping your JSON text components.
  2. Unescape inner quotes: Convert escaped quotes like \" back into normal quotes " (and optionally remove quotes around keys like text and color).
  3. Rename event keys: Perform a find-and-replace in your files to change clickEvent to click_event and hoverEvent to hover_event.
  4. Update click action fields: Change the data field inside click_event from value to url (for open_url) or command (for run_command and suggest_command). Keep value for copy_to_clipboard.
  5. Verify hover tooltips: Ensure show_text inside hover_event uses the value field containing an unquoted SNBT component.

Keep in mind that older versions do not understand direct SNBT for text components and still require traditional JSON strings.

Questions

Do I have to remove the quotes around keys like "text" and "color" in 1.21.5?

No. While you must remove the outer string quotes wrapping the entire component, quoted JSON-style keys inside the SNBT object (such as {"text":"Hi","color":"red"}) will still parse properly.

Why is my run_command click event not working in Minecraft 1.21.5?

In 1.21.5, clickEvent was renamed to click_event, and the run_command action now requires the command field instead of the value field. Make sure it is written as click_event:{action:"run_command",command:"/yourcommand"}.

How do I name items with colors in 1.21.5?

Use the custom_name item component (introduced in 1.20.5) and pass an SNBT text component directly into it without single quotes, like this: /give @p stone[custom_name={text:"Magic Rock",color:"aqua"}].

Will 1.21.5 SNBT text commands work on older versions?

No. Older versions of Minecraft Java still require text components to be formatted as JSON strings wrapped in quotes and use the older camelCase clickEvent and hoverEvent keys.

Related guides

See all →