> 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/scrollbars-and-hotbar.md).

# scrollbars and hotbar

This guide explains how to build scrollbar-style menus using CursorCs hotbar actions.

This is useful for:

* class lists
* shop lists
* language lists
* menu carousels
* vertical selectors

If you want the full field reference, see [Clickable Areas](/cursorcs/guides/clickable-areas.md).

## How scrollbar scrolling works

CursorCs can react when the player changes hotbar slot while the cursor is inside a clickable area.

That means you can create a rectangle that behaves like a scroll zone:

* moving the hotbar forward scrolls one way
* moving the hotbar backward scrolls the other way

This is configured with `hotbar:`.

## Basic scrollbar example

This is the simplest vertical scrollbar:

```yaml
shop_scrollbar:
  min_x: 0.10
  max_x: 0.60
  min_y: -0.30
  max_y: 0.10
  hotbar:
    enabled: true
    on_step_forward:
      - type: "move"
        hologram: "shop_list"
        mode: "cumulative"
        offset_y: -0.02
        duration: 0.08
        interpolation: "linear"
    on_step_backward:
      - type: "move"
        hologram: "shop_list"
        mode: "cumulative"
        offset_y: 0.02
        duration: 0.08
        interpolation: "linear"
```

This makes `shop_list` move up and down as the player scrolls.

## Recommended scrollbar mode

For scrollbars, the most useful mode is:

```yaml
mode: "cumulative"
```

Why:

* each scroll step adds movement
* the scrollbar keeps its current position
* it feels like a real list

Other available modes:

* `cumulative`
* `absolute`
* `precise`

In most scrollbar cases, use `cumulative`.

## Moving multiple holograms together

In real menus, a scrollbar usually needs to move:

* image cards
* item icons
* text labels

You can move all of them together:

```yaml
class_scroll_area:
  min_x: -0.89
  max_x: 0.62
  min_y: -0.19
  max_y: 0.11
  hotbar:
    enabled: true
    reset_accumulator_on_area_exit: false
    on_step_forward:
      - type: "move"
        holograms:
          - "class2"
          - "class3"
          - "class4"
          - "class5"
          - "classtext1"
          - "classtext2"
          - "classtext3"
          - "classtext4"
        mode: "cumulative"
        offset_y: -0.3
        duration: 0.12
        interpolation: "ease_out"
    on_step_backward:
      - type: "move"
        holograms:
          - "class2"
          - "class3"
          - "class4"
          - "class5"
          - "classtext1"
          - "classtext2"
          - "classtext3"
          - "classtext4"
        mode: "cumulative"
        offset_y: 0.3
        duration: 0.12
        interpolation: "ease_out"
```

This keeps the icons and their labels in sync.

## Limiting how far the list can move

To prevent a list from moving too far, use:

* `min_offset_y`
* `max_offset_y`

Example:

```yaml
class_scroll_area:
  min_x: -0.89
  max_x: 0.62
  min_y: -0.19
  max_y: 0.11
  hotbar:
    enabled: true
    on_step_forward:
      - type: "move"
        holograms:
          - "class2"
          - "class3"
          - "class4"
          - "class5"
        mode: "cumulative"
        offset_y: -0.3
        min_offset_y: -0.3
        max_offset_y: 0.0
        duration: 0.12
        interpolation: "ease_out"
    on_step_backward:
      - type: "move"
        holograms:
          - "class2"
          - "class3"
          - "class4"
          - "class5"
        mode: "cumulative"
        offset_y: 0.3
        min_offset_y: -0.3
        max_offset_y: 0.0
        duration: 0.12
        interpolation: "ease_out"
```

This means:

* the list can go down by `-0.3`
* the list cannot go above its original position

This is perfect when the top element should only move down until it reaches the visible slot.

## Scroll only in one menu state

Scrollbars often belong to a specific menu.

You can restrict them with `required_group`:

```yaml
class_scroll_area:
  min_x: -0.89
  max_x: 0.62
  min_y: -0.19
  max_y: 0.11
  conditions:
    required_group: "en"
  hotbar:
    enabled: true
    on_step_forward:
      - type: "move"
        hologram: "class_list"
        mode: "cumulative"
        offset_y: -0.1
```

This prevents the scrollbar from reacting outside the `en` menu state.

## Adding sound while scrolling

Scrollbars can also play sounds:

```yaml
class_scroll_area:
  min_x: -0.89
  max_x: 0.62
  min_y: -0.19
  max_y: 0.11
  hotbar:
    enabled: true
    on_step_forward:
      - type: "sound"
        sound: "minecraft:ui.button.click"
        volume: 0.7
        pitch: 1.05
      - type: "move"
        hologram: "class_list"
        mode: "cumulative"
        offset_y: -0.1
    on_step_backward:
      - type: "sound"
        sound: "minecraft:ui.button.click"
        volume: 0.7
        pitch: 0.95
      - type: "move"
        hologram: "class_list"
        mode: "cumulative"
        offset_y: 0.1
```

## Adding small animations while scrolling

You can combine scrollbar movement with micro animations:

```yaml
class_scroll_area:
  min_x: -0.89
  max_x: 0.62
  min_y: -0.19
  max_y: 0.11
  hotbar:
    enabled: true
    on_step_forward:
      - type: "preset_animation"
        hologram: "scroll_handle"
        preset: "nudge_down"
        duration: 0.10
        intensity: 0.04
      - type: "move"
        hologram: "class_list"
        mode: "cumulative"
        offset_y: -0.1
```

## Useful hotbar fields

Common fields:

* `enabled`
* `sequence_timeout_ms`
* `cycle_steps`
* `reset_accumulator_on_area_exit`
* `on_step_forward`
* `on_step_backward`
* `on_cycle_forward`
* `on_cycle_backward`

Most scrollbar setups only need:

* `enabled`
* `reset_accumulator_on_area_exit`
* `on_step_forward`
* `on_step_backward`

## When to use `reset_accumulator_on_area_exit`

Use:

```yaml
reset_accumulator_on_area_exit: true
```

if you want the scrollbar to reset after leaving the area.

Use:

```yaml
reset_accumulator_on_area_exit: false
```

if you want the list to keep its scroll position.

For most menus, `false` feels better.

## Practical design tips

* Move all related holograms together, not just the image.
* Clamp the movement with `min_offset_y` and `max_offset_y`.
* Use `required_group` if the scrollbar only belongs to one state.
* Add a small sound to make scrolling feel responsive.
* Use larger scroll steps like `0.3` for row-by-row menus.
* Use smaller scroll steps like `0.02` or `0.05` for smoother lists.


---

# 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/scrollbars-and-hotbar.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.