Text components

Minecraft's rich-text format ("raw JSON text") — the content, formatting, and interactivity fields used by /tellraw, /title, /bossbar, signs, books, item names, and text_display.

On this page

Overview
Content fields
Formatting fields
click_event and hover_event (1.21.5 flattening)
Where text components are used
Complete examples
Legacy section-sign (§) codes
Sources

Overview

A text component (formerly "raw JSON text") is Minecraft's rich-text object. Since 1.21.5 1.21.5+ the wiki calls it the "text component format" and it is written in SNBT in commands/datapacks (e.g. {text:"Hello world"}), though JSON-style quoting still parses. A component can be:

a string — plain text, equivalent to {text:"…"}.
an array — a list of components; the first is the parent and the rest become its extra (children inherit the parent's formatting).
an object — a full compound with one content field plus optional styling/interactivity.

⚠ Version differences

Since 1.21.5 (25w02a/25w03a, pack_format 71): components are written in SNBT and the interactivity fields are renamed to snake_case (click_event/hover_event) with flattened payloads — the dominant breaking change (see below).
Before 1.21.5: components were written as JSON with camelCase clickEvent/hoverEvent. Old JSON still parses on 1.21.5+, but with the old shape.

Content fields

Choose exactly one content field per component. If no type field is present, the game auto-detects the content type by checking, in order: text, translate, score, selector, keybind, nbt.

Content	Field(s)	Notes
Plain text	`text`	Literal string.
Translated	`translate`, `with`, `fallback`	`with` = array of components substituted into `%s` / `%1$s` slots from the language file. `fallback` (added 1.19.4) is used when the key is missing.
Score	`score:{name, objective}`	`name` = holder (player/UUID/`*`/`@s` etc.), `objective` = scoreboard objective. Resolved server-side.
Selector	`selector`, `separator`	`selector` = target selector string; `separator` (optional) between multiple matches.
Keybind	`keybind`	e.g. `"key.jump"` — shows the player's bound key.
NBT	`nbt` + one of `block`/`entity`/`storage`, plus `interpret`, `separator`	Reads NBT at a path. `interpret:true` parses the value as a text component. `separator` joins multiple matches.

Formatting fields

All optional and inherited by children.

Field	Type	Notes
`color`	String	Named color (`red`, `gold`, `aqua`, …) or `"#RRGGBB"` hex.
`font`	String	Resource location; default `minecraft:default`.
`bold`, `italic`, `underlined`, `strikethrough`, `obfuscated`	Boolean	Style toggles.
`insertion`	String	Text inserted into chat input on shift-click (chat only).
`shadow_color`	ARGB int or `[R,G,B,A]` floats (0–1)	Per-component text-shadow color. Added 1.21.4/1.21.5-era 1.21.4+.

click_event and hover_event — the 1.21.5 flattening

This is the single biggest breaking change for text components. In 1.21.5 (25w02a/25w03a, pack_format 71) the interactivity fields were renamed to snake_case and their nested contents/value payloads were flattened into action-specific fields.

⚠ Version differences

Since 1.21.5: click_event / hover_event (snake_case) with action-specific payload fields.
Before 1.21.5: clickEvent / hoverEvent (camelCase) with a generic value (click) or nested contents (hover). Still parses on 1.21.5+.

click_event

Pre-1.21.5 — camelCase field, generic value

{"text":"Click","clickEvent":{"action":"run_command","value":"/say hi"}}

1.21.5+ — snake_case field, action-specific field

{text:"Click",click_event:{action:run_command,command:"/say hi"}}

action	pre-1.21.5 payload	1.21.5+ payload
`open_url`	`value:"https://…"`	`url:"https://…"`
`run_command`	`value:"/cmd"`	`command:"/cmd"` (leading `/` no longer required)
`suggest_command`	`value:"/cmd"`	`command:"/cmd"`
`change_page`	`value:"3"`	`page:3` (int; written books only)
`copy_to_clipboard`	`value:"text"`	`value:"text"` (unchanged)

📌 Note

Newer click actions — do not attribute to 1.21.5. The show_dialog and custom click actions arrived with the dialog system in 1.21.6+ 1.21.6+, not 1.21.5.

hover_event

Pre-1.21.5 — camelCase field, nested contents

{"text":"Hover","hoverEvent":{"action":"show_text","contents":"Tooltip!"}}

1.21.5+ — snake_case field, flattened value

{text:"Hover",hover_event:{action:show_text,value:"Tooltip!"}}

action	pre-1.21.5	1.21.5+
`show_text`	`contents:<component>`	`value:<component>`
`show_item`	`contents:{id,count,tag}`	flattened: `id:"…"`, `count:<int>`, `components:{…}`
`show_entity`	`contents:{type,id,name}`	flattened: `id:"<entity type>"`, `uuid:<string or int-array>`, `name:<component>` (note: `type`→`id`, old `id`→`uuid`)

Where text components are used

/tellraw — chat message

# 1.21.5+ SNBT form
tellraw @a {text:"Server restarting in 5 min",color:"red",bold:true}
# component with hover (1.21.5+)
tellraw @a {text:"Hover me!",hover_event:{action:show_text,value:"Secret tooltip"}}

As of 1.21.5, /tellraw messages are specified with SNBT instead of JSON (older JSON still parses).

/title — big centered title / subtitle / actionbar

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

times <fadeIn> <stay> <fadeOut> is in game ticks; defaults are 10/70/20. title clear / title reset remove/reset.

/bossbar — the boss bar name is a text component

bossbar add example:boss {text:"Boss"}
bossbar set example:boss name {text:"Epic Boss Battle",color:"red"}
bossbar set example:boss color red
bossbar set example:boss style notched_10
bossbar set example:boss players @a

Settable props: name, color (blue/green/pink/purple/red/white/yellow), max, value, players, style (progress/notched_6/10/12/20), visible.

Signs

1.20+ uses front_text/back_text compounds, each with a messages list of 4 text components, plus color and has_glowing_text.

data merge block ~ ~1 ~ {front_text:{color:"green",has_glowing_text:1b,messages:['{"text":"Line 1"}','{"text":"Line 2"}','""','""']}}

⚠ Version differences

Since 1.20: front_text/back_text with a messages list.
Before 1.20: flat Text1–Text4 strings + Color + GlowingText.

Books

The written_book_content component (1.20.5+) has pages — a list of text components (each a {raw, filtered} pair) — plus title, author, generation, resolved. Pages support change_page click events for interactive navigation.

Item names — custom_name and item_name

Both components (1.20.5+) each hold a text component.

# 1.20.5+ component syntax (pre-1.21.5 JSON-string value)
give @s diamond_sword[custom_name='{"text":"Excalibur","color":"gold","italic":false}']
# 1.21.5+ SNBT form
give @s diamond_sword[custom_name={text:"Excalibur",color:"gold",italic:false}]

custom_name = the anvil/name-tag name (italic, highest display priority); item_name = a "base" name that does not render italic and is not removed by anvils.

Entities — CustomName

A text component in CustomName plus CustomNameVisible:1b.

summon armor_stand ~ ~ ~ {CustomName:'{"text":"Guard","color":"red"}',CustomNameVisible:1b}

text_display

The text field of a text_display entity is a text component. See the Display entities page for the full entity NBT.

Complete examples

1) Clickable menu row — run a command on click, tooltip on hover (1.21.5+):

tellraw @a ["",{text:"[ ",color:"dark_gray"},{text:"TELEPORT SPAWN",color:"green",bold:true,click_event:{action:run_command,command:"/spawn"},hover_event:{action:show_text,value:{text:"Click to teleport to spawn",color:"gray"}}},{text:" ]",color:"dark_gray"}]

2) Live scoreboard readout via score content:

tellraw @a ["",{text:"Your coins: ",color:"yellow"},{score:{name:"@s",objective:"coins"},color:"gold"}]

3) Per-player translated text (client-localized) with fallback — each player sees the message in their own language if the key exists:

tellraw @a {translate:"menu.welcome",fallback:"Welcome, %s!",with:[{selector:"@s"}]}

🎩 Trick

Clickable menus. /tellraw arrays where each row carries click_event:{action:run_command,…} + hover_event build full chat UIs.

🎩 Trick

Per-player translate. translate + with:[{selector:"@s"}] renders client-side, so each player sees their own localized string / their own name without server-side string building.

💡 Best practice

On 1.21.5+ write components in SNBT and use click_event/hover_event with action-specific payloads. Keep a compatibility note if you must support pre-1.21.5 worlds (old JSON with clickEvent/hoverEvent + value/contents still parses but is the old shape).

Legacy section-sign (§) codes

The § system is deprecated but still functional. Prefer text components for anything component-shaped.

§ code	Meaning	§ code	Meaning
§0–§f	16 named colors (black … white)	§k	obfuscated
§l	bold	§m	strikethrough (Java only)
§n	underline (Java only)	§o	italic
§r	reset

Named-color map (same hex as JSON named colors): §0 black #000000, §1 dark_blue #0000AA, §2 dark_green #00AA00, §3 dark_aqua #00AAAA, §4 dark_red #AA0000, §5 dark_purple #AA00AA, §6 gold #FFAA00, §7 gray #AAAAAA, §8 dark_gray #555555, §9 blue #5555FF, §a green #55FF55, §b aqua #55FFFF, §c red #FF5555, §d light_purple #FF55FF, §e yellow #FFFF55, §f white #FFFFFF.

Where § still works (Java): server.properties, pack.mcmeta, splashes.txt, language files, world/level titles, and inside command string arguments that are not parsed as components.
Where JSON/SNBT is required: anything that takes a text component (/tellraw, /title, sign messages, book pages, custom_name, text_display, bossbar name).
Escaping § in properties/mcmeta files: write § (e.g. §5 = dark_purple).

⚠ Gotcha

In Java, a color code resets preceding format codes, so re-apply §l etc. after a color change.

Text components

Overview

Content fields

Formatting fields

click_event and hover_event — the 1.21.5 flattening

click_event

hover_event

Where text components are used

/tellraw — chat message

/title — big centered title / subtitle / actionbar

/bossbar — the boss bar name is a text component

Signs

Books

Item names — custom_name and item_name

Entities — CustomName

text_display

Complete examples

Legacy section-sign (§) codes

Sources