> ## Documentation Index
> Fetch the complete documentation index at: https://customadvancements-wiki.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Advancement Display Field: Icons, Titles, and Frames

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

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

<ParamField body="icon" type="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.

  ```json theme={null}
  "icon": {
    "id": "minecraft:diamond"
  }
  ```

  With components:

  ```json theme={null}
  "icon": {
    "id": "minecraft:player_head",
    "components": {
      "minecraft:profile": {
        "name": "Steve"
      }
    }
  }
  ```
</ParamField>

<ParamField body="title" type="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:

  ```json theme={null}
  "title": "Back to the Roots"
  ```

  Translation key (recommended for localizable content):

  ```json theme={null}
  "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](/data/lang) for details.
</ParamField>

<ParamField body="description" type="string | object" required>
  The advancement description shown below the title in the tooltip. Accepts the same plain-string or text-component formats as `title`.

  ```json theme={null}
  "description": { "translate": "customadvancements.advancements.my_advancement.description" }
  ```
</ParamField>

<ParamField body="frame" type="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 |
</ParamField>

<ParamField body="show_toast" type="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.
</ParamField>

<ParamField body="announce_to_chat" type="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.
</ParamField>

<ParamField body="hidden" type="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.
</ParamField>

<ParamField body="background" type="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](/advancements/background-types) for all supported types and their fields.

  ```json theme={null}
  "background": {
    "type": "IMAGE",
    "location": "customadvancements:textures/screenshot.png",
    "object_fit": "COVER"
  }
  ```
</ParamField>

## 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.

```json back_to_the_roots.json (display block) theme={null}
{
  "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.

```json customadvancements/data/lang/en_us.json theme={null}
{
  "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](/data/lang) for the full guide on structuring and naming locale files.

<Note>
  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.
</Note>

For details on the `background` field, see [Background Types](/advancements/background-types).