Advancement Display Field: Icons, Titles, and Frames

Configure the display object for a Custom Advancements JSON file — icon, title, description, frame type, toast, chat announcement, and hidden state.

The display object controls every visual aspect of an advancement: the icon shown in the tree, the title and description in the tooltip, the frame style around the icon, whether a toast notification pops up on completion, and whether the chat broadcasts the unlock. For root advancements it also carries the background field that fills the tab panel behind the advancement tree.

Fields

icon · object · required

The item displayed as the advancement’s icon in the advancement tree and in the toast notification. Must contain at least an "item" field with a valid item resource location — any item from Minecraft or from another loaded mod works.

"icon": {
  "item": "minecraft:diamond"
}

With NBT data:

"icon": {
  "item": "minecraft:diamond_sword",
  "nbt": "{CustomModelData:1}"
}

nbt · string

Optional NBT string applied to the icon item, written inside the icon object. Use it to display a specific item variant, such as one with custom model data or a custom name. The value is a single SNBT string, so any quotes inside it must be escaped.

title · string | object · required

The advancement title displayed at the top of the tooltip and on the tab header for root advancements. Accepts either a plain string or a Minecraft text component object.

Plain string:

"title": "Back to the Roots"

Translation key (recommended for localizable content):

"title": { "translate": "customadvancements.advancements.my_advancement.title" }

If you use a translate key you must supply the matching string in a language file. See Language Files for details.

description · string | object · required

The advancement description shown below the title in the tooltip. Accepts the same plain-string or text-component formats as title.

"description": { "translate": "customadvancements.advancements.my_advancement.description" }

frame · string · default: "task"

The frame style drawn around the icon in the advancement tree. Controls the visual emphasis of the advancement.

Value	Appearance
"task"	Standard square frame — everyday objectives
"goal"	Rounded frame — mid-tier milestones
"challenge"	Star-shaped frame — difficult or prestigious feats

show_toast · boolean · default: "true"

Whether a toast notification slides in from the top-right corner of the screen when the player earns this advancement. Set to false for silent advancements such as root nodes that complete immediately on login.

announce_to_chat · boolean · default: "true"

Whether the server broadcasts a chat message to all players when someone earns this advancement. Set to false for internal progression steps or root advancements that fire on every login.

hidden · boolean · default: "false"

When true, this advancement stays invisible in the advancement tree until the player has completed it. Use it for secret objectives, Easter eggs, or spoiler-sensitive story beats.

"display": {
  "icon": { "item": "minecraft:ender_pearl" },
  "title": "???",
  "description": "You found the secret.",
  "frame": "challenge",
  "hidden": true
}

background · string

The texture drawn behind the advancement tree in this tab, written as a plain resource location string. Required on root advancements (those with no parent field) — a root advancement without it is rejected by the loader. On child advancements the field is ignored; they inherit their root’s background.

"background": "customadvancements:textures/logo.png"

See Background Types for vanilla texture options, custom textures, and how the image is tiled.

Complete Display Example

The following shows a fully populated display block combining all available fields. It is drawn from the back_to_the_roots.json example file shipped with the mod.

back_to_the_roots.json (display block)

{
  "display": {
    "announce_to_chat": true,
    "description": {
      "translate": "customadvancements.advancements.back_to_the_roots.description"
    },
    "frame": "task",
    "hidden": false,
    "icon": {
      "item": "minecraft:rotten_flesh"
    },
    "show_toast": true,
    "title": {
      "translate": "customadvancements.advancements.back_to_the_roots.title"
    }
  }
}

Translation Keys

When you use { "translate": "some.key" } for a title or description, you must provide the actual string in a language file placed at customadvancements/data/lang/<locale>.json.

customadvancements/data/lang/en_us.json

{
  "customadvancements.advancements.back_to_the_roots.title": "Back to the roots",
  "customadvancements.advancements.back_to_the_roots.description": "Kill a zombie with rotten flesh!"
}

See Language Files for the full guide on structuring and naming locale files.

Minecraft text components support color, formatting, click events, and hover text — the same rich-text JSON format used in signs, books, and chat messages. Custom Advancements passes the title and description values straight to Minecraft’s component parser, so any valid component is accepted.

For details on the background field, see Background Types.