# Cycle

> Cycle steps through a few fixed values, one per click, showing the current one after its label like vanilla's Graphics button. Ideal for enums.

URL: https://xichil.dev/docs/xis-mvui/v1/widgets/cycle/ · Updated: 2026-11-06 · Applies to: Fabric, Quilt, Legacy Fabric, Forge, NeoForge, MC 1.7.10 - 26.3

A button that steps through a fixed list of values, shown as "label: value" like vanilla's option buttons
(for example "Graphics: Fancy"). Each click selects the next value, wrapping around after the last. Good for a
handful of values, typically an enum.

```java
Cycle.<Mode>builder("mode")
        .label(Text.translatable("mymod.mode", "Mode"))
        .values(Arrays.asList(Mode.values()))
        .value(() -> config.mode)
        .valueText(m -> Text.translatable("mymod.mode." + m.name().toLowerCase(Locale.ROOT), m.name()))
        .onChange(m -> config.mode = m)
        .build();
```

> **Note:** Java usually can't infer the value type from a chained call, so give it explicitly: `Cycle.<Mode>builder("mode")`.

## Builder

| Method | Required | Default | Notes |
| --- | --- | --- | --- |
| `label(Supplier<Text>)` / `label(Text)` | yes | | the text before ": value" |
| `values(List<T>)` | yes | | the values in cycling order, not empty. Copied at build time. |
| `value(Supplier<T>)` | yes | | your current value; re-read on every refresh |
| `valueText(Function<? super T, Text>)` | yes | | how a value is shown after "label: " |
| `onChange(Consumer<? super T>)` | yes | | stores the newly selected value; main thread |
| `enabled`, `tooltip`, `visible` | no | | [options every widget has](https://xichil.dev/docs/xis-mvui/v1/widgets/index.md#options-every-widget-has) |

`build()` throws if a required field is missing or `values` is empty.

## Behaviour

- Values are compared with `equals`. A current value that isn't in the list shows as the first one, and the next
  click selects the second.
- Later changes to the list you passed don't show; build the screen again to offer different values.
- Use translatable text in `valueText` for enum constants, so each value can be translated.
- For long lists use a [Dropdown](https://xichil.dev/docs/xis-mvui/v1/widgets/dropdown/index.md), which has the same builder.
- **Footer:** yes.

## Test it

```java
host.click("mode");                    // selects the next value
```

Rendered as `[cycle mode] Mode: Balanced`.

## See also

- Javadoc: [Cycle](https://xichil.dev/javadoc/xis-mvui/v1/dev/xichil/mvui/Cycle.html)