> For the complete documentation index, see [llms.txt](https://xcs-plugin.gitbook.io/cursorcs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xcs-plugin.gitbook.io/cursorcs/guides/groups-and-menu-switching.md).

# groups and menu switching

This guide explains how groups work in CursorCs and when to use `apply_group` or `apply_holograms`.

This is one of the most important menu-design concepts in the plugin.

## There are two menu/group styles

### 1. Normal groups

These are the groups loaded from:

```
plugins/CursorCs/config/groups/
```

You switch to them with:

```yaml
type: "apply_group"
```

or:

```yaml
action: "apply_group"
```

### 2. Activable groups

These are hologram files in:

```
plugins/CursorCs/config/holograms/
```

that start with:

```yaml
group: "shop_menu"
```

You switch to them with:

```yaml
type: "apply_holograms"
```

or:

```yaml
action: "apply_holograms"
```

## The most important difference

### `apply_group`

Use `apply_group` when you want to update or reuse what is already on screen.

Typical use cases:

* change text
* hide/show some holograms
* move between menu states
* switch tabs
* keep existing holograms instead of rebuilding everything

This is the best option when you want to avoid menu regeneration.

### `apply_holograms`

Use `apply_holograms` when you want to load another full menu screen.

Typical use cases:

* open a different page
* replace the current screen
* replay full menu open animation
* load a completely different UI

This is the option that behaves like a real screen swap.

## In simple words

* `apply_group` = update the current UI
* `apply_holograms` = replace the current UI

If you want the safest option without rebuilding the whole menu, use `apply_group`.

If you want a fresh menu load, use `apply_holograms`.

## Example: normal group

File in `config/groups/language.yml`:

```yaml
en:
  title:
    text: "English"

  subtitle:
    text: "Welcome"
```

Clickable area:

```yaml
english_button:
  min_x: 0.10
  max_x: 0.30
  min_y: 0.10
  max_y: 0.20
  on_click:
    - type: "apply_group"
      change_to: "en"
```

This is a good choice if your menu stays mostly the same and only part of it changes.

## Example: activable group

File in `config/holograms/shop.yml`:

```yaml
group: "shop_menu"

title:
  text: "Shop"

background:
  text: "%img_shop_bg%"
```

Clickable area:

```yaml
shop_button:
  min_x: 0.10
  max_x: 0.30
  min_y: 0.10
  max_y: 0.20
  on_click:
    - type: "apply_holograms"
      change_to: "shop_menu"
```

This is a good choice when you want a full menu switch.

## Which one should you use

Use `apply_group` when:

* the same screen stays open
* you only want to change part of the content
* you want to preserve existing holograms
* you want state changes without full rebuild

Use `apply_holograms` when:

* you are opening another menu page
* you want a clean screen replacement
* you want a full menu open effect
* you want the new menu to load from its own hologram file

## Conditions and active groups

You can make clickable areas only work in one menu state:

```yaml
default_button:
  min_x: 0.10
  max_x: 0.30
  min_y: 0.10
  max_y: 0.20
  conditions:
    required_group: "default"
  on_click:
    - type: "apply_group"
      change_to: "en"
```

Then create another one that only works in `en`:

```yaml
en_button:
  min_x: 0.10
  max_x: 0.30
  min_y: 0.10
  max_y: 0.20
  conditions:
    required_group: "en"
  on_click:
    - type: "command"
      command: "say english-menu"
```

This is very useful for tabs, states, and layered UIs.

## Menu open sounds and open animations

Both menu styles can use:

* `alias`
* `sound`
* `open_animation`

Example:

```yaml
group: "shop_menu"
alias: "shop"
sound: "minecraft:ui.button.click"

open_animation:
  preset: "slide_from_right"
  duration: 0.35
  stagger_delay: 0.04
```

## Recommended design strategy

Use normal groups for:

* states
* tabs
* language switching
* progressive reveals

Use activable groups for:

* full menus
* separate pages
* different screens
* entry points opened with aliases


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://xcs-plugin.gitbook.io/cursorcs/guides/groups-and-menu-switching.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.