> For the complete documentation index, see [llms.txt](https://simple.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simple.superiormc.cn/arcmenu-wiki/menu-configuration/menus/groups-templates.md).

# Groups and reusable templates

Groups manage multiple visible elements together. Templates save commonly used groups for reuse in other menus.

Paper, Folia, Leaf and Spigot support basic groups. Template files and editor template features are available only on Paper-based servers.

## Group structure: `group`

Define a group in `frontend` with `type: group`. Place its elements inside `children`, following the same element name → type and properties hierarchy.

```yaml
frontend:
  greeting-group:
    type: group
    offset: {x: 40, y: -20, z: 1}
    children:
      greeting-background:
        type: rectangle
        width: 60
        height: 18
        color: '#365E91'
      greeting-text:
        type: text
        content: '&fSay hello'
        size: 4
        offset: {z: 1}

backend:
  greeting-area:
    x: 40
    y: -20
    width: 60
    height: 18
    actions:
      right:
        - 'tell: &aHello!'
```

This is a menu fragment to merge into the corresponding sections of an existing file. The group has no visible content of its own; its rectangle and text form the button.

### Common properties

Groups support `offset`, `rotation`, `scale` and `visible`, affecting the entire group. Value rules are described in [Frontend element types](/arcmenu-wiki/menu-configuration/menus/frontend.md#common-properties).

| Property   | Effect on children                                                    |
| ---------- | --------------------------------------------------------------------- |
| `offset`   | Moves them together.                                                  |
| `rotation` | Rotates them around the group origin.                                 |
| `scale`    | Scales their dimensions and relative positions; supports `x` and `y`. |
| `visible`  | Hides all children when `false`.                                      |

Groups do not use `width`, `height`, `color` or `opacity`. Configure backgrounds and opacity on the relevant child elements.

### Child elements: `children`

Child positions are relative to the group origin. In the example, both the background and text are centered in the group; the text adds `z: 1` to appear in front of the background.

With translation only, the final position is the group position plus the child's offset. A group at `x: 40` with a child at `offset.x: 10` places that child at `x: 50`.

Rotation and scaling also change relative positions, so coordinates cannot simply be added when those properties are applied.

### Nested groups

`children` can contain another `type: group` to organize components such as cards or title bars. Each level is positioned relative to its parent and inherits outer changes.

Element names must be unique across the entire menu, not just the current `children` section. When copying a group, rename both the group and all its children.

## Groups and hit regions

Backend regions do not belong in a group's `children`. Configure them in the menu's top-level `backend` section.

The example's group is centered at `(40, -20)` without additional scaling or rotation. Its hit region therefore uses `x: 40`, `y: -20` and the background's dimensions.

Moving, rotating, scaling or hiding a group does not automatically update its regions. A region may still receive clicks after its group is hidden; `visible: false` alone does not disable a button.

Hit regions are rectangles aligned to the canvas and cannot be rotated through a frontend group. See [Canvas, coordinates and screen placement](/arcmenu-wiki/menu-configuration/menus/canvas.md) for coordinates and alignment.

## Template files

Templates are stored in `plugins/ArcMenu/templates/` and save one complete frontend group. They do not include hit regions, menu permissions or opening and closing events.

### Top-level fields

| Field            | Purpose                                                    |
| ---------------- | ---------------------------------------------------------- |
| `schema-version` | Configuration format; use `1`.                             |
| `id`             | Template identifier, unique within the template directory. |
| `frontend`       | Must contain exactly one root element of type `group`.     |

Template identifiers use lowercase letters, digits, underscores and hyphens, beginning with a letter or digit. The template identifier and root group name serve different purposes and need not match.

### Complete example

Save the following as `plugins/ArcMenu/templates/greeting-button.yml`:

```yaml
schema-version: 1
id: greeting-button
frontend:
  button-group:
    type: group
    children:
      button-background:
        type: rectangle
        width: 60
        height: 18
        color: '#365E91'
      button-text:
        type: text
        content: '&fSay hello'
        size: 4
        offset: {z: 1}
```

The example leaves the root group at the origin for positioning after insertion. Templates can also retain group offsets, rotation and scale, which are preserved when inserted.

After manually editing template files, run:

```
/arcmenu reload all
/arcmenu templates
```

The first command reloads templates and the second lists loaded identifiers. A regular `/arcmenu reload` does not update the template list.

## Using templates

### Through the editor

This requires `arcmenu.admin` and a compatible ArcMenu Editor installation on the administrator's client.

1. Open the target menu with `/arcmenu edit <menu-id>`.
2. Use the editor's template feature to select and insert a loaded template.
3. Adjust the new group's position, text and other properties.
4. Configure backend regions and actions for interactive components.
5. Save the menu, then open it normally to check appearance and clicks.

The editor handles element name conflicts during insertion. To save an existing component as a template, select its group and use template saving with a new identifier. Individual text or rectangle elements cannot be saved directly as group templates, and saving cannot overwrite an existing template file with the same name.

### Manual copying

Without the editor, copy the template's root group from its `frontend` section into the target menu's `frontend`. Rename any conflicting elements and configure the corresponding hit regions.

Menus have no `template` field for automatic references. Do not use a template identifier as an element type or place an entire template file in the menu directory.

Spigot can reuse manually copied groups containing supported elements, but does not load the template directory or provide editor template features.

### Later changes

Inserted groups are independent menu content. Editing or deleting a template does not automatically change existing groups; editing a menu group does not update the template.

To update existing menus consistently, edit those menus individually or insert the revised template again. Images in a template still require their image files and resource pack.

## Validation and loading

After editing menu groups, run `/arcmenu validate` and `/arcmenu reload`. Use `/arcmenu reload all` after editing template files.

Alongside appearance, check button-region positions, dimensions and hidden states. Templates reuse visible content only; interaction configuration must be maintained separately in each target menu.

## Next step

Continue with [Backend regions and click events](/arcmenu-wiki/menu-configuration/menus/backend.md) to configure hit regions and actions for grouped components.