Advancement Display Field: Icons, Titles, and Frames

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

object

required

The item displayed as the advancement’s icon in the advancement tree. Must contain at least an "id" field with a valid item resource location. The optional "components" field accepts a map of item component overrides in the same format Minecraft uses for item NBT data.

"icon": {
  "id": "minecraft:diamond"
}

With components:

"icon": {
  "id": "minecraft:player_head",
  "components": {
    "minecraft:profile": {
      "name": "Steve"
    }
  }
}

string | object

required

The advancement title displayed at the top of the tooltip. Accepts either a plain UTF-8 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.

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" }

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 rectangular frame — everyday objectives
`"goal"`	Rounded frame — mid-tier milestones
`"challenge"`	Star-shaped frame — difficult or prestigious feats

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.

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.

boolean

default:"false"

When true, this advancement is invisible in the advancement tree until the player has completed it. Use this for secret objectives or spoiler-sensitive advancements that should not be revealed prematurely.

object

Specifies the background rendered behind the advancement tree in this tab. Only meaningful on root advancements (those with no parent field); this field is silently ignored on child advancements.Custom Advancements extends this field beyond vanilla’s plain resource-location string to support images, gradients, and solid colors via a typed object. See Background Types for all supported types and their fields.

"background": {
  "type": "IMAGE",
  "location": "customadvancements:textures/screenshot.png",
  "object_fit": "COVER"
}

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": {
      "id": "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. The mod syncs these files to connected clients automatically.

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 directly to Minecraft’s component parser, so any valid component is accepted.

For details on the background field, see Background Types.

Getting Started

Creating Advancements

Configuration

Commands

Localization & Textures

Troubleshooting

Advancement Display Field: Icons, Titles, and Frames

Fields

Complete Display Example

Translation Keys

​Fields

​Complete Display Example

​Translation Keys

Fields

Complete Display Example

Translation Keys