> For the complete documentation index, see [llms.txt](https://yowsef-development.gitbook.io/yowsef-development-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yowsef-development.gitbook.io/yowsef-development-docs/menus/dynamic-lists.md).

# dynamic lists

Dynamic lists populate buttons at show-time based on live server or player state.

{% stepper %}
{% step %}

## Supported Sources

| Source           | Description                                  | Required Plugin      |
| ---------------- | -------------------------------------------- | -------------------- |
| `homes`          | The requesting player's Essentials set homes | EssentialsX          |
| `online_players` | All players currently on the server          | None                 |
| `friends`        | The player's friend list                     | None / Mock provider |
| {% endstep %}    |                                              |                      |

{% step %}

## `dynamic-buttons` (simple mode)

For the simplest cases — just a list with default button styling — use `dynamic-buttons`:

```yaml
homes-menu:
  title: "<green>🏠 Your Homes"
  type: multiAction
  columns: 2
  dynamic-buttons: homes
```

The plugin generates one styled button per home automatically. No template needed.
{% endstep %}

{% step %}

## `dynamic-list` (template mode)

For full control over how each entry looks, use `dynamic-list` with a `template` block. The plugin loops over all results from the source and renders the template for each entry, substituting `$(variable)` placeholders.

### Essentials Homes — available variables

* `$(home_name)` — name of the home (e.g. `base`, `farm`)
* `$(home_world)` — world folder name where the home is set

```yaml
homes-menu:
  title: "<green>🏠 Your Homes"
  type: multiAction
  columns: 2
  dynamic-list:
    source: "essentials:homes"
    template:
      - label: "<gold>🏠 $(home_name)"
        tooltip: "<gray>World: $(home_world)"
        width: 150
        action: static-run-command
        command: "/home $(home_name)"
  footer-buttons:
    - label: "<gray>← Back"
      width: 100
      action: back
      action-key: "dm:back"
```

### Online Players — available variables

* `$(player_name)` — username of the online player

```yaml
players-menu:
  title: "<aqua>Online Players"
  type: multiAction
  columns: 2
  dynamic-list:
    source: "online_players"
    template:
      - label: "<aqua>$(player_name)"
        tooltip: "<gray>Click to view profile"
        width: 150
        action: static-run-command
        command: "/profile $(player_name)"
```

### Friends — available variables

* `$(friend_name)` — friend's username
* `$(friend_online)` — `true` or `false`

```yaml
friends-menu:
  title: "<green>Friends"
  type: multiAction
  columns: 2
  dynamic-list:
    source: "friends"
    template:
      - label: "<yellow>$(friend_name)"
        tooltip: "<gray>Online: $(friend_online)"
        width: 150
        action: static-run-command
        command: "/msg $(friend_name) Hey!"
```

{% endstep %}

{% step %}

## Combining dynamic and static buttons

`dynamic-list` buttons render first, then `buttons`, then `footer-buttons`. Use `footer-buttons` for navigation controls so they always appear at the bottom regardless of how many dynamic entries there are:

```yaml
  dynamic-list:
    source: "essentials:homes"
    template:
      - label: "<gold>$(home_name)"
        ...
  footer-buttons:
    - label: "<yellow>➕ Set New Home"
      action: open-menu
      target: set-home-menu
    - label: "<gray>← Back"
      action: back
      action-key: "dm:back"
```

{% endstep %}
{% endstepper %}


---

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

```
GET https://yowsef-development.gitbook.io/yowsef-development-docs/menus/dynamic-lists.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.