Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Chapter 5 — Text Components: Styled and Dynamic Text

What You’ll Build

Back in Chapter 1 you met /say for plain messages, and you were promised a fancier message command called /tellraw once you’d built up to it. This is that chapter. /tellraw sends a text component: a small piece of JSON that describes what a message says, how it looks (color, bold, italics), and what it does when a player clicks or hovers over it. Text components are how Minecraft does every bit of styled, interactive text: colored chat, clickable links, hover tooltips, and big titles on the screen.

By the end of this chapter you’ll be able to color and style text, drop in dynamic pieces that fill themselves in (a player’s name, a translated word, a score), make text clickable and hoverable, and send it all to players with /tellraw and /title. You’ll finish by building a styled, clickable welcome message and firing it off in chat to greet everyone in color.

Everything in this chapter is typed straight into the chat box of your test world, the same way you’ve been running commands since Chapter 1.

What a text component is

A text component (the wiki sometimes calls it “raw JSON text,” its older name) is the format Minecraft uses for any formatted text. They start small: in /tellraw @a {"text":"Hello"}, that {"text":"Hello"} part is a text component, the simplest one there is.

The simplest text component is just a string of text. These three are all the same message:

  • "Hello world": a plain string.
  • {"text":"Hello world"}: an object (a {} block) with one field, text.
  • ["Hello world"]: a list (a [] block) with one item in it.

So a text component can be written three ways: as a plain string, as a list, or as a compound object (the {} form). The string and list forms are just shorthand for the object form. Most of the time you’ll write the object form, because that’s the one you can attach color and clicks to.

A component can have children. There is always one root component at the top, and it can hold a list of more components in a field called extra. Here’s the key rule: children inherit the root’s formatting unless they set their own. So if the root is red, every child is red too until a child says otherwise.

The list shorthand uses this. Writing ["A", "B", "C"] is the same as {"text":"A", "extra":["B", "C"]}: the first item becomes the root, and the rest become its children. That means [{"text":"A","color":"red"}, "B", "C"] shows all three letters in red, because “B” and “C” are children of the red “A”.

Under the Hood (skippable) The whole format is recursive: a component can contain components, which can contain components, forever. That’s how a single message can mix colors, clickable words, and hover tooltips: each piece is its own little component nested inside the others. You almost never need deep nesting as a beginner, but it’s why the format can do everything from a one-word chat line to a full interactive menu.

Almost every field is optional. A text component doesn’t have to be complicated. {"text":"hi"} is a perfectly good one.

Color and style

The most common thing you’ll add is color and style. These are formatting fields you put right inside the component object, next to text.

The color field takes either one of Minecraft’s 16 named colors or a custom hex code:

  • 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.
  • A hex color like "#FF8800": a # followed by a 6-digit hexadecimal color, the same kind of code used for colors on the web. This lets you pick any color, not just the 16 named ones.

So {"text":"Danger!","color":"red"} is red, and {"text":"Sunset","color":"#FF8800"} is a custom orange.

On top of color, there are several true/false style fields. Each is a boolean: true turns it on, false turns it off.

  • bold: heavier text.
  • italic: slanted text.
  • underlined: a line under the text.
  • strikethrough: a line through the text.
  • obfuscated: scrambled, constantly-changing characters (the classic “magic” garble).

You can combine them freely. This component is bold, italic, and gold:

{"text":"Legendary Sword","color":"gold","bold":true,"italic":true}

Try It! The italic field has a sneaky use: some text is italic by default (like custom item names you’ll meet in Chapter 22). Setting "italic":false is how you turn that off later. For now, just remember that false is a real choice too, alongside true.

There’s also a font field that points at a font from a resource pack. It defaults to "minecraft:default" (the normal font), and there’s a built-in alternate font you can name as "alt". (Those are the two built-in font names; to see what the alt font actually looks like, try it in-game.) We’ll only use the built-in ones here; making your own fonts is a resource-pack topic for Chapter 30.

Dynamic content: text that fills itself in

So far our components show fixed text we typed. But components can also show dynamic content: values the game fills in when the message is sent. You choose which kind by including a special field instead of (or alongside) text. There are four kinds worth knowing now.

translate — built-in translations

The translate field shows a piece of text in the player’s own language. Minecraft ships with translation keys for nearly everything, and each player sees the message in whatever language their game is set to.

{"translate":"item.minecraft.diamond"}

That shows the word “Diamond,” translated for each player. The key item.minecraft.diamond is the identifier Minecraft uses internally for that item’s name.

Translations can have slots to fill in, written as %s in the translation text. You fill them with the with field, a list of components, one per slot:

{"translate":"%s joined the game","with":[{"text":"Steve","color":"yellow"}]}

If a key doesn’t exist, the game just shows the key text itself; you can supply a fallback field with backup text to show instead.

selector — entity names

The selector field shows the name of whatever a target selector picks (you learned selectors in Chapter 3). The game fills in the actual name(s) when the message is sent.

{"selector":"@p"}

That shows the nearest player’s name. If the selector could match more than one entity, separate names with a comma; if you want to be sure it’s exactly one, add limit=1 to the selector, like "@p[limit=1]".

score — a scoreboard value (preview)

The score field shows a number from the scoreboard, Minecraft’s system for tracking numbers per player. You’ll learn scoreboards properly in Chapter 11; here’s a preview so you recognize it. The score field is itself a small object with a name (whose score to show) and an objective (which counter):

{"score":{"name":"@s","objective":"coins"}}

That would show the running player’s value in a “coins” counter. Don’t worry about making a scoreboard yet; just know that this is how a live number gets into a message.

Under the Hood (skippable) Dynamic values are filled in once, at the moment the message is sent, a process the wiki calls resolution. A score that shows “100” stays “100” in that already-sent message even if the score later changes. Text components don’t keep updating themselves; each send is a fresh snapshot.

nbt — data from a block, entity, or storage (preview)

The nbt field shows raw data values from the game: from an entity, a block, or command storage (a place to keep data, taught in Chapter 12). It uses an NBT path (a way to point at one piece of data) and a source saying where to look:

{"nbt":"SelectedItem.id","entity":"@s","source":"entity"}

That would show the ID of the item the running player is holding. Like score, the data is filled in when the message is sent. We’re previewing this so you recognize it later; the storage side comes in Chapter 12.

Making text interactive: click and hover

Here’s where text components stop being just pretty and start being useful. Two fields make text respond to the player:

  • click_event: what happens when the player clicks the text.
  • hover_event: a tooltip shown when the player hovers the mouse over the text.

There’s also a simpler third field, insertion: when a player shift-clicks the text, the string you put here is inserted into their chat input (it adds to whatever they were typing rather than replacing it). It only works in chat messages. We won’t use it in the walkthrough, but it’s good to know it exists alongside the two big ones.

Modern Minecraft These two fields are written in snake_case: click_event and hover_event, with an underscore. A lot of older tutorials and YouTube videos from before this change write them in camelCase: clickEvent and hoverEvent, no underscore. Those no longer work in current Java Edition. If you copy an old example and the click does nothing, the underscore is the first thing to check. The same goes for the action names below: they’re snake_case too.

click_event

The click_event field is an object. Inside it, an action field names what kind of click behavior you want, and the other fields give it details. These are the available actions:

  • open_url: opens a web link in the player’s browser. Needs a url field.
  • run_command: runs a command as if the player typed it in chat. Needs a command field. The command does not need a leading / slash. (It can only run commands the player has permission for, and not ones that send chat directly.)
  • suggest_command: opens chat and fills in some text or a command, ready for the player to edit and press enter. Needs a command field.
  • copy_to_clipboard: copies text to the player’s clipboard. Needs a value field.
  • change_page: in a written book only, jumps to a page number. Needs a page field.
  • show_dialog: opens a custom pop-up screen (a dialog). Needs a dialog field. Dialogs are a whole feature of their own, covered in Chapter 39; this is just so you know the action exists.
  • custom: sends a custom event to the server (it does nothing on a normal vanilla server; it’s for servers with their own add-ons). Takes an id and an optional payload.
  • open_file: used by the game itself (for example when you take a screenshot). Servers and data packs can’t send this one, so you won’t use it.

A clickable component looks like this:

{"text":"[Click for a diamond]","color":"aqua","click_event":{"action":"run_command","command":"give @s diamond"}}

Clicking that text runs give @s diamond for the player.

hover_event

The hover_event field is also an object with an action field. The actions are:

  • show_text: shows a text component as a tooltip. The text goes in a value field. (Note: a tooltip’s own text can’t itself have working clicks or hovers; tooltips are display-only.)
  • show_item: shows an item’s tooltip, as if hovering it in your inventory. Takes an id (the item), an optional count, and optional components (extra item data, which you’ll meet in Chapter 21).
  • show_entity: shows an entity’s name, type, and UUID. Takes an id (the entity type), an optional name, and a uuid.

A hovering component:

{"text":"Hover me","color":"yellow","hover_event":{"action":"show_text","value":{"text":"Surprise!","color":"green"}}}

And you can put both click_event and hover_event on the same component: clickable and hoverable at once. You’ll do exactly that in the walkthrough.

Sending a component: /tellraw

A text component is just data, so something has to send it. The first sender is /tellraw, which you met in Chapter 1. Its full form is:

/tellraw <targets> <message>

<targets> is a player selector (it must select players, not other entities), and <message> is a text component. So everything you’ve learned in this chapter goes in the <message> slot.

A few real examples, exactly as the game accepts them. Type each into the chat box and press Enter:

/tellraw @a {"text":"I am blue","color":"blue"} /tellraw @a {"text":"Text1\nText2"} /tellraw @p {"translate":"item.minecraft.diamond"}

The second one shows a handy trick: \n inside the text starts a new line.

Big screen text: /title

/tellraw writes to chat. /title writes big text on the screen, the kind you see at the center of the display when something dramatic happens. It has three places it can put text, plus controls for timing:

/title <targets> (title|subtitle|actionbar) <text> /title <targets> times <fadeIn> <stay> <fadeOut> /title <targets> (clear|reset)

  • title: large center-screen text.
  • subtitle: a smaller line just below the title. (A subtitle only appears together with a title, so set the subtitle first, then the title.)
  • actionbar: a line of text just above the hotbar.
  • times <fadeIn> <stay> <fadeOut>: how long, in ticks (1/20 of a second), the title fades in, stays, and fades out. The defaults are 10, 70, and 20 ticks (about half a second in, three and a half staying, one second out).
  • clear removes the current title; reset puts the timing back to defaults.

In Java Edition, the <text> is a full text component, so it gets color and style just like /tellraw. This pair shows a bold title with a gray italic subtitle. Type them one after the other:

/title @a subtitle {"text":"The story begins...","color":"gray","italic":true} /title @a title {"text":"Chapter I","bold":true}

Notice the order: subtitle first, then title, because the subtitle rides along with the title that follows it.

Walkthrough: a styled welcome message

Time to put it together. You’ll greet the player with a big title on screen and a colored, clickable chat line, typing each command into the chat box of your test world.

Step 1 — the title. Type these two, in this order, so the subtitle rides along with the title:

/title @a subtitle {"text":"A grand adventure","color":"gray","italic":true} /title @a title {"text":"Welcome!","color":"gold","bold":true}

A gold “Welcome!” should fade in over a gray italic subtitle.

Step 2 — a colored chat line. Now build a greeting from several child components and send it:

/tellraw @a ["",{"text":"[Welcome] ","color":"aqua","bold":true},{"text":"Hello, "},{"selector":"@p"},{"text":"! Glad you're here."}]

Look at that line closely. It’s a lot of this chapter at once. The list starts with "" (an empty string as the root, so nothing inherits an accidental color), then a bold aqua tag, then plain text, then a selector that fills in the nearest player’s name, then more plain text.

Step 3 — make it clickable. Finally, a single component carrying both a click_event (which runs give @s diamond) and a hover_event (which shows a tooltip):

/tellraw @a {"text":"[Click here for a free diamond]","color":"green","underlined":true,"click_event":{"action":"run_command","command":"give @s diamond"},"hover_event":{"action":"show_text","value":{"text":"Yes, really — click it!","color":"yellow"}}}

You should see the green underlined line appear; hovering it shows the yellow tooltip, and clicking it hands you a diamond.

Figure (to be captured). the gold “Welcome!” title with gray italic subtitle on screen, and the colored clickable chat lines below; mouse hovering the green line shows the yellow tooltip

Modern Minecraft Right now you’re typing each of these lines by hand, which is the fastest way to see what every field does. Later you’ll save a sequence like this so it fires on its own: in a command block inside the world (Chapter 6), or as a function in a data pack (Part III) that can run the whole greeting the moment the pack loads. For now, the chat box is where you experiment.

Practice

  1. Recolor the tag. Change the [Welcome] tag in the chat line to a custom hex color of your choice (for example "#FF55AA"). Type the line again to see it.

  2. Add a help button. Send a /tellraw line that’s a clickable [Help] button. Use suggest_command (not run_command) so that clicking it fills in a command in the player’s chat instead of running it (for example suggesting /time set day). Give it a hover_event with show_text explaining what it does.

  3. An action-bar status. Send a /title @a actionbar {...} line that prints a short status message just above the hotbar in a color of your choice. Notice how the action bar behaves differently from the big center title.

  4. A translated word. Send a /tellraw that uses {"translate":"item.minecraft.diamond"} somewhere in a sentence (inside a list with other text), and confirm it shows the item’s name.

Try It! Combine this with Chapter 4’s /execute: type /execute as @a run tellraw @s {"text":"Hi!"} so the message runs once per player, with each player’s own name available to a selector inside. Think about why running it as each player changes what @s and @p mean.

What Can Go Wrong

  • You wrote clickEvent / hoverEvent and nothing happens. This is the single most common text-component mistake today, because so many older tutorials use the camelCase spelling. Current Java Edition needs the snake_case click_event and hover_event, with an underscore. Same for the action names (run_command, show_text, and so on). Fix the spelling and the click comes back to life.

  • The command reports a red JSON error. Text components are written in the JSON-like format you’ll meet properly in Chapter 8, and the same rules apply: every { needs a matching }, every [ a matching ], strings need their quotes, and there are no trailing commas after the last field. A long /tellraw line is easy to miscount, so type it carefully. The red feedback message points at roughly where the parser got confused.

  • /tellraw says it can’t find players, or refuses your selector. /tellraw and /title only target players. A selector like @e (all entities) or one that resolves to a mob will be rejected, so use @a, @p, @s (when run by a player), or @r. If no players match, the command simply has no one to message.

  • Your subtitle never shows. A subtitle only appears with a title. If you set subtitle but never send a title afterward, there’s nothing for it to ride along with. Set the subtitle first, then the title. The order in the walkthrough does this on purpose.

What You Know Now

You can build a text component: color it (named colors or #hex), style it (bold, italic, underlined, strikethrough, obfuscated), nest pieces as children that inherit formatting, and fill in dynamic content with translate, selector, and (previewed) score and nbt. You can make text interactive with click_event and hover_event, and you know they’re snake_case, unlike the old camelCase tutorials. You can send a component to chat with /tellraw and put big text on screen with /title (title, subtitle, action bar, and times), and you’ve typed out a styled, clickable welcome message of your own. Next chapter you’ll move commands off your keyboard and into the world with command blocks, so a button press can fire a message like this for you. (And later, in Chapter 11, scoreboards will make that score field come alive.)