Index

Generic info

1. Intro
2. Errors
3. JSON Structure
4. Unicode & escape sequences

In-game features

5. /tellraw
6. /title
7. Books
8. Signs
9. Advancements

Text component

10. Text input

11. Text styling

12. Event listeners

13. Adding text

Additional usage info

14. Inheritance
15. Senders & origins

16. /trigger

Conclusion

17. Q&A
18. External links
19. Conclusion

Generic info

Intro

Errors

[spoiler]Insert command here[/spoiler]

You can check for valid JSON using a generic validator such as JSONLint.

JSON structure

{
    "text": "",
    "translate": "",
    "with": [],
    "score": {
        "name": "",
        "objective": "",
        "value": ""
    },
    "selector": "",
    "keybind": "",
    "color": "",
    "bold": false,
    "italic": false,
    "underlined": false,
    "strikethrough": false,
    "obfuscated": false,
    "insertion": "",
    "clickEvent": {
        "action": "",
        "value": ""
    },
    "hoverEvent": {
        "action": "",
        "value": ""
    },
    "extra": []
}

Unicode & escape sequences

/tellraw @a {"text":"\u00B6"}

\n

"Newline" character, pushing text to the next line. While with signs it can be used, the text pushed to the next line will not be visible.

/tellraw @a ["Line 1\nLine 2"]

\" and \' and \\

Allows the usage of quotation marks nested within quotation marks, such as NBT data for various click/hover events, as well as backslashes as literal characters rather than as an escape sequence.

/tellraw @a ["This text is \"quoted\". Backslash: \\"]

Note that for nested quotes, deeper-nested quotation marks will need to be escaped further. The formula to obtain the number of backslashes needed is (2 * [current backslashes]) + 1. For example, if a quotation mark is needed as a literal value, but is already inside a set of quotes that has 1 backslash, 3 backslashes are needed in order to use the quotation marks:

/summon Creeper ~ ~1 ~ {CustomName:"the \"quoted\" text"}

/tellraw @a {"text":"Click","clickEvent":{"action":"run_command","value":"/testfor @e[type=Creeper] {CustomName:\"the \\\"quoted\\\" text\"}"}}

The next depth would be 7, then 15, and so on.

\t and \b and \f and \r

None of these escape characters can be used with the text component.

In-game features

/tellraw

/tellraw [player] [text component]

/tellraw @a {"text":"Hello","color":"red","italic":true}

Unavailable features:

1. "open_file" click event.
2. "change_page" click event.

/title

/title [player] [title|subtitle] [text component]

/title @a subtitle {"text":"The smaller subtitle","color":"red","italic":true}
/title @a title {"text":"The larger title","color":"red","italic":true}

Unavailable features:

1. All event listeners.

Books

/give @p minecraft:written_book 1 0 {title:"",author:"",pages:["{\"text\":\"Page 1\",\"italic\":true}"]}

Unavailable features:

1. insertion event listener.
2. open_file click event.
3. suggest_command click event.

Signs

/setblock ~ ~1 ~ minecraft:standing_sign 0 replace {Text1:"[\"Top text\"]",Text2:"[\"\"]",Text3:"[\"\"]",Text4:"[\"Bottom text\"]"}

Unavailable features:

1. insertion event listener.
2. open_file click event.
3. open_url click event.
4. suggest_command click event.
5. change_page click event.
6. All hover events.

Advancements

{
    "display": {
        "title": {"text":"This is the title.","color":"blue"},
        "description": {"translate":"custom.locale.key","with":[{"keybind":"key.inventory"}]},
        "icon": {
            "item": "minecraft:crafting_table"
        }
    },
    "criteria": {
        "custom_test_name": {
            "trigger": "minecraft:impossible"
        }
    }
}

Unavailable features:

1. Score text.
1. Selector text.
2. All event listeners.

Text component

Text input

/tellraw @a {"text":""}

Alternatively, if within an array of text components (such as from instantiation or via extra), a lone string will act as text.

/tellraw @a ["String 1",{"text":"","extra":["String 2"]}]

"text"

Basic text with no parsing other than escape sequence support. Target selectors are not parsed using this option.

/tellraw @a {"text":"String"}

If specifying a lone string within an array of text components (such as from instantiation or via extra), the input will be parsed as the text option.

/tellraw @a ["String 1","String 2"]
/tellraw @a {"text":"String 1","extra":["String 2"]}

"translate"

Sends input through the translation parser, useful for multi-lingual support. The input is expected to be the language key (e.g. gui.toTitle), but if the key is invalid it will be parsed as though it were the key's value instead. The output shown will be dependent on the player's language setting, unless the key is invalid.

/tellraw @a {"translate":"gui.toTitle"}

Example, showing that invalid key results in input being parsed as output.

/tellraw @a {"translate":"Text inserted here"}

Conversion flags & "with"

Minecraft's language files support the usage of several conversion flags, which are placeholders for text. For example:

commands.generic.entity.invalidType=Entity type '%s' is invalid

%s is the placeholder, which is text to be inserted at a later point. While the language files support the use of a handful of different conversion flags, all flags are converted to %s or %#$s. See here for a more in-depth explanation of placeholders, but be aware that Minecraft implements them manually and thus not all are available.

The with array will hold the extra data to be inserted. Example, where the %s placeholder is replaced with "Creeper":

/tellraw @a {"translate":"commands.generic.entity.invalidType","with":["Creeper"]}

Conversion flags are also supported when specifying an invalid key, but be aware that the game is expecting only %s or %#$s. No other conversion flag will work for those cases.

/tellraw @a {"translate":"Insert a %s here.","with":["STRING"]}

custom.key = Insert %s and %s, followed by %s.

/tellraw @a {"translate":"custom.key","with":["STRING1", "STRING2"]}

Output = Insert STRING1 and STRING2, followed by .

custom.key = Insert %1$s and %2$s, followed by %1$s and %s.

/tellraw @a {"translate":"custom.key","with":["STRING1", "STRING2"]}

Output = Insert STRING1 and STRING2, followed by STRING1 and STRING1.

"with" & text components

The records inside with may also be text components. Availability will vary between in-game features, as usual. For example, the following replaces %s with a parsed target selector:

/tellraw @a {"translate":"Nearest player: %s","with":[{"selector":"@p"}]}

"score"

Displays the value of a score based on a playerscore on the scoreboard. The score object holds three keys: name, objective, and value.

A bug (see MC-56373) currently prevents full usage within hover events ("value" does work).

"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 place of a name/selector will cause all players will see their own score in the specified objective. Signs cannot use the wildcard.

"objective" is the objective to find the player's score from.

"value" stores the processed value so that the score does not need to be re-evaluated. If defined, this value is used instead of a processed score.

Example, where all players are shown the score of the nearest player in the "TEST" objective:

/tellraw @a {"score":{"name":"@p","objective":"TEST"}}

Example, where all players will see their own score in the "TEST" objective:

/tellraw @a {"score":{"name":"*","objective":"TEST"}}

Example, where a score is not processed due to value being present and will instead display "hello":

/tellraw @a {"score":{"name":"@p","objective":"TEST","value":"hello"}}

"selector"

Processes a target selector into a pre-formatted set of discovered names, complete with event listeners where applicable. Multiple targets may be obtained, with commas separating each one and a final "and" for the last target.

The resulting formatting cannot be overwritten. This includes all styling from team prefixes, insertion event for entity & player names, clickEvents for player names, and hoverEvents for entity & player names.

A bug (see MC-56373) prevents it from working in hover events.

Example, assuming there are 3 creepers:

/tellraw @a {"selector":"@e[type=Creeper]"}

"keybind"

Shows the player their corresponding key for a keybind. The following is a list of valid keybinds:

Example, showing the player their key for dropping an item (defaulting to Q):

/tellraw @a {"keybind":"key.drop"}

Text styling

"color"

Choose from a set of pre-determined colors that will be applied to the text. Defaults to "white". List of colors and their IDs:



Example, where the text is colored "red":

/tellraw @a {"text":"Hello","color":"red"}

"reset" may be used to reset the color to default.

/tellraw @a {"text":"Hello","color":"red","extra":[{"text":" there","color":"reset"}]}

"bold"

Boolean; increases text thickness. Defaults to "false".

/tellraw @a {"text":"Hello","bold":true}

"italic"

Boolean; emphasises text. Defaults to "false".

/tellraw @a {"text":"Hello","italic":true}

"underlined"

Boolean; underlines text. Defaults to "false".

/tellraw @a {"text":"Hello","underlined":true}

"strikethrough"

Boolean; adds a strikethrough in the middle of text. Defaults to "false".

/tellraw @a {"text":"Hello","strikethrough":true}

"obfuscated"

Boolean; causes text to cycle through random letters (example: ). Defaults to "false".

/tellraw @a {"text":"Hello","obfuscated":true}

Event listeners

"insertion"

When the player holds SHIFT and left-clicks text, the insertion event listener will fire. This will append text to the player's current chat input, provided their chat is open. This is restricted to /tellraw only.

/tellraw @a {"text":"Shift-click","insertion":"/say Hello"}

"clickEvent"

When the player left-clicks /tellraw or book text, or right-clicks on a sign, the clickEvent listener will fire.

For signs, all clickEvents must be at the root of inheritance. Clicking on a sign activates the listener for all of the Text1/Text2/Text3/Text4 tags, thus the maximum number of clickEvents on a sign is 4.

The event is stored within a clickEvent object, with an action string holding the type of event and a value holding the various relevant values that corresponds with the action.

List of clickEvents

The following is a list of all possible clickEvents that can be used.

/tellraw @a {"text":"Click","clickEvent":{"action":"open_url","value":"http://google.com"}}

/tellraw @a {"text":"Click","clickEvent":{"action":"run_command","value":"/say Must be OP'd to run this command"}}

/setblock ~ ~1 ~ minecraft:standing_sign 0 replace {Text1:"{\"text\":\"\",\"clickEvent\":{\"action\":\"run_command\",\"value\":\"say Does not need to be OP'd to run this command. Sender bias: @e[c=1] .\"}}",Text2:"[\"\"]",Text3:"[\"\"]",Text4:"[\"\"]"}

/setblock ~ ~1 ~ minecraft:standing_sign 0 replace {CommandStats:{SuccessCountName:"@p",SuccessCountObjective:"OBJ"},Text1:"{\"text\":\"\",\"clickEvent\":{\"action\":\"run_command\",\"value\":\"testfor @e[r=3]\"}}",Text2:"[{\"text\":\"\",\"clickEvent\":{\"action\":\"run_command\",\"value\":\"execute @p[score_OBJ_min=3] ~ ~ ~ say 3 entities around the sign.\"}}]",Text3:"[\"\"]",Text4:"[\"\"]"}

/tellraw @a {"text":"Click","clickEvent":{"action":"suggest_command","value":"Text replaced"}}

/give @p minecraft:written_book 1 0 {title:"",author:"",pages:["{\"text\":\"Go to Page 2\",\"clickEvent\":{\"action\":\"change_page\",\"value\":\"2\"}}","[\"Page 2\"]","[\"Page 3\"]"]}

"hoverEvent"

When the player hovers over /tellraw or book text with their mouse pointer, the hoverEvent listener will fire.

The event is stored within a hoverEvent object, with an action string holding the type of event and a value holding the various relevant values that corresponds with the action.

List of hoverEvents

The following is a list of all possible hoverEvents that can be used.

1. show_text
2. show_achievement
3. show_item
4. show_entity

show_text

Shows a tooltip populated by a text component, though could also just be a simple string.

Unavailable features:

1. All event listeners.
2. "score" text, though an explicit "value" will work.
3. "selector" text.

See MC-56373 for issues concerning "score" and "selector".

/tellraw @a {"text":"Hover","hoverEvent":{"action":"show_text","value":"Basic string"}}

/tellraw @a {"text":"Hover","hoverEvent":{"action":"show_text","value":["",{"text":"Text\n","color":"green","underlined":true},"component"]}}

show_achievement

Displays a pre-formatted achievement tooltip. May also show pre-formatted statistics tooltips, though will only show the statistic name. The wiki has a list of valid achievement IDs here, as well as statistic IDs here.

Achievements will be prefixed by "achievement." while statistics are prefixed by "stat.".

/tellraw @a {"text":"Hover","hoverEvent":{"action":"show_achievement","value":"achievement.openInventory"}}

/tellraw @a {"text":"Hover","hoverEvent":{"action":"show_achievement","value":"stat.walkOneCm"}}

The following shows the pre-formatted text template:



The first line will be the achievement or stat name, dependent on the string provided from "value".

The second line will either show "Achievement" or "Statistic" depending on the language setting, which is translated from the following keys in the language file:

stats.tooltip.type.achievement=Achievement
stats.tooltip.type.statistic=Statistic

The third line will display a description, which is only used for achievements.

If the value is not a valid achievement or statistic, it will instead display "Invalid statistic/achievement!".

show_item

Parses NBT input into an item and displays the result.

The value is a string and must have nested quotation marks escaped. Must be valid NBT input starting with an unnamed compound. Note that if Advanced Tooltips is shown (F3 + H), extra data will be shown as it normally would.

/tellraw @a {"text":"Hover","hoverEvent":{"action":"show_item","value":"{id:\"minecraft:stone\",tag:{display:{Lore:[\"Lore line 1\",\"Lore line 2\"]}}}"}}

If either the item data is invalid (wrong item ID, "Count" tag not 1+) or the NBT data is syntactically incorrect, "Invalid Item!" is shown instead.

show_entity

An advanced tooltip displaying an entity's name, type, and UUID. Advanced tooltips must be enabled to view (F3 + H). Note that this is not targeting any existing entities, but is instead just creating dummy text.

The value is a string and must have nested quotation marks escaped. The value is NBT input of a specific structure, rather than entity data, but none of the following tags are required and can simply be blank:

{

    name:"CustomName",

    type:"ArmorStand",

    id:"00000000-0000-0000-0000-000000000000"

}

None of the tags are required, but the game will render a line for both "name" and "id". "type" will only have a line dedicated to it if it's defined. The input does not need to be valid.

"name" is essentially the "CustomName" tag of the entity. "type" is the entity's savegame ID and will be appended by the corresponding numerical ID (90 (AKA Pig) if invalid). "id" is the UUID pair of the entity (determined by "UUIDLeast" and "UUIDMost" tags).

/tellraw @a {"text":"Hover","hoverEvent":{"action":"show_entity","value":"{name:\"Skylinerw\",type:\"Creeper\",id:\"00000000-0000-0000-0000-000000000000\"}"}}



/tellraw @a {"text":"Hover","hoverEvent":{"action":"show_entity","value":"{name:\"Skylinerw\",id:\"Not a valid UUID\"}"}}

If the NBT data is syntactically invalid, "Invalid Entity!" will be displayed instead.

Adding text

"extra"

The "extra" array will accept a list of text components and strings. This tag is used in order to create more text with their own options. Note that the text components here will inherit from a parent first, but each are their own separate child. See Inheritance for more info.

For example, the following results in the parent ("First") being red, while its children ("Second" and "Third") inherit that property and are also red. The first child ("Second") set itself to be bold, unlike its parent, while the second child ("Third") does not change any properties that it inherited.

/tellraw @a {"text":"First","color":"red","extra":[{"text":"Second","bold":true},"Third"]}

Array structure

A text component can instead be instantiated as an array rather than an object. This essentially allows one to skip using the "extra" tag entirely, and can also save on characters as it becomes quicker to nullify a parent.

/tellraw @a ["First","Second","Third"]

Note that the first record defined will be marked as the parent, and all other records will inherit from that parent. For example, the following causes the first record ("Parent") to be the parent set to red, while the second record ("Child") inherits everything from the first record and will also be red.

/tellraw @a [{"text":"Parent","color":"red"},"Child"]

A quick way to skip over the first record as the parent to avoid any unwanted inheritance is to simply input an empty string.

/tellraw @a ["",{"text":"Child1","color":"red"},{"text":"Child2","underlined":true}]

Additional usage info

Inheritance

/tellraw @a {"text":"Parent"}

The following shows a parent, with absolutely everything inside the "extra" tag being a child (including any "grandchildren" and so on).

/tellraw @a {"text":"Parent","extra":["Child1","Child2"]}

When instantiating as an array, the first record will be the parent while all other records are the children.

/tellraw @a ["Parent","Child1","Child2"]

Each child can be a parent to their own children, and only their children will inherit their properties (as well as any properties inherited by a grandparent and so on). The following shows a parent that is bold, a child that inherits boldness and has the italic property, and a grandchild that is both bold, italic, and has its own property of being red.

/tellraw @a {"text":"First","bold":true,"extra":[{"text":"Second","italic":true,"extra":[{"text":"Third","color":"red"}]}]}

/tellraw @a [{"text":"First","bold":true},{"text":"Second","italic":true,"extra":[{"text":"Third","color":"red"}]}]

/tellraw @a [{"text":"First","bold":true},[{"text":"Second","italic":true},{"text":"Third","color":"red"}]]

The following demonstrates that siblings do not inherit from one another. While the parent is bold and causes both its children to be bold, the first child will be italic while the second child is underlined (and not italic).

/tellraw @a {"text":"Parent","bold":true,"extra":[{"text":"Child1","italic":true},{"text":"Child2","underlined":true}]}

/tellraw @a [{"text":"Parent","bold":true},{"text":"Child1","italic":true},{"text":"Child2","underlined":true}]

Senders & origins

Initial parsing

When parsing the "selector" tag or the "name" tag in the "score" object, and if there is a command sender available, sender bias will apply, forcing them to always be the target.

This occurs when an entity runs a command (such as a player running the /tellraw or /title commands directly, or via the /execute command) or when the player opens a book for the first time.

For example, the following will cause all entities to say their own name no matter what:

/execute @e ~ ~ ~ /tellraw @a {"selector":"@e[c=1]"}

This functionality is not available for signs as they do not have a sender to work from, and instead their selectors will parse without a sender bias from the blockspace that they are placed at.

run_command clickEvents

When a player activates a run_command event, they will be marked as the command sender as they are naturally the ones running the command. However, there is a key difference with signs: while /tellraw and books will use the player's current coordinates as the origin, clickEvents in signs will instead use the sign's coordinates as the origin, while still setting the clicking player as the command sender for sender bias to apply.

For example, the following will cause the clicking player to set a block above the sign, rather than above themselves, and to always say their own name:

/setblock ~ ~1 ~ minecraft:standing_sign 0 replace {Text1:"[{\"text\":\"\",\"clickEvent\":{\"action\":\"run_command\",\"value\":\"setblock ~ ~1 ~ minecraft:stone\"}}]",Text2:"[\"\"]",Text3:"[\"\"]",Text4:"[{\"text\":\"\",\"clickEvent\":{\"action\":\"run_command\",\"value\":\"say @e[c=1]\"}}]"}

This can be used very effectively in order to know exactly which sign the player had clicked while still being able to target the clicking player.

/trigger

/trigger [trigger-objective] [add|set] [value]

Players that run this command will only be capable of targeting their own objective, noted by the lack of a target selector in the syntax.

In order for the command to modify a score, the objective itself must use the "trigger" objective-type. This objective-type has a special feature in that it will be 'locked' in order to prevent being modified. This occurs when the value is modified by the /trigger command, though do note that if a player is not tracked in the objective they will still be considered 'locked'. Example:

/scoreboard objectives add OBJECTIVE trigger
/scoreboard players add @a OBJECTIVE 0

The player's "OBJECTIVE" score will be enabled by default in this case. Changing their score with /scoreboard does not unlock the objective for the player, but because the player had never run /trigger yet, it will be enabled.

The following will cause the player to change their score to 1, and thus locking the objective for that player. The player will not be able to run /trigger to modify that score until they are unlocked.

/trigger OBJECTIVE set 1

The /scoreboard command can be used to unlock the objective.

/scoreboard players enable @a OBJECTIVE

The /execute command can be used to forcibly change a player's score by causing them to run /trigger. This can be useful to automatically lock a player's objective without waiting for them to run the command themselves. For example, the following will not change their score but will lock it:

/execute @a ~ ~ ~ /trigger OBJECTIVE add 0

Example usage with /tellraw:

/tellraw @a {"text":"Click","clickEvent":{"action":"run_command","value":"/trigger OBJECTIVE set 1"}}

The clicking player will set their "OBJECTIVE" score to 1 if it is enabled for that player, and if so, will then become disabled.

Conclusion

Q&A

External links

Conclusion