# Xi's Multiversion UI Lib docs

> Build mod menus once with plain Java widgets and run them on Minecraft 1.7.10 to 26.3 across every major loader.

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

Xi's Multiversion UI Lib (mod id `xis_mvui`) lets a mod describe its menus with plain Java widgets and run
them on every Minecraft version from 1.7.10 to 26.3, on Fabric, Quilt, Legacy Fabric, Forge and NeoForge.
Your mod compiles against one small API jar that has no Minecraft classes in it. At runtime the library
picks the backend for the running game and draws your widgets with that version's own GUI classes, so
menus look like vanilla everywhere.

```java title="MyMenu.java"
public Screen create(UiHost host) {
    return MenuScreen.builder("main")
            .title(Text.translatable("mymod.title", "My Mod"))
            .add(Toggle.builder("sounds")
                    .label(Text.translatable("mymod.sounds", "Sounds"))
                    .value(() -> config.sounds)
                    .onChange(v -> config.sounds = v)
                    .build())
            .footer(Button.builder("done").label(UiTexts.DONE).onPress(host::back).build())
            .build();
}
```

## Key facts

| | |
| --- | --- |
| Package | `dev.xichil.mvui` (test fixtures: `dev.xichil.mvui.fake`) |
| Maven repository | `https://maven.xichil.dev` |
| API artifact | `dev.xichil.mvui:xis-mvui-api:1.0.0`, as `compileOnly` (never bundle it) |
| Library mod id | `xis_mvui` (`MultiversionUi.MOD_ID`) |
| Java | the API is Java 8, so code compiled against it runs on every supported version |
| Side | client only; on a dedicated server the library does nothing |
| Entry point | `MultiversionUi.register(modId, name, screenFactory)`, once, on the client, at startup |
| Javadoc | [MultiversionUi](https://xichil.dev/javadoc/xis-mvui/v1/dev/xichil/mvui/MultiversionUi.html) and every other class |

## Start here

1. [Installation](https://xichil.dev/docs/xis-mvui/v1/getting-started/installation/index.md): add the Maven repository and the API dependency, declare
   the dependency in your mod metadata, and run a dev client.
2. [Your first menu](https://xichil.dev/docs/xis-mvui/v1/getting-started/first-menu/index.md): build and register a working menu in five steps.
3. [Build one mod for every loader](https://xichil.dev/docs/xis-mvui/v1/guides/multiversion-mod/index.md): structure a mod so one codebase ships to
   Fabric, Quilt, Forge and NeoForge, from 1.7.10 to 26.3.

## All pages

**Guides** (how to do one task):

- [Build one mod for every loader](https://xichil.dev/docs/xis-mvui/v1/guides/multiversion-mod/index.md): shared code, one jar per loader family.
- [Register your menu](https://xichil.dev/docs/xis-mvui/v1/guides/registering/index.md): where to call `register` on each loader.
- [Open your menu](https://xichil.dev/docs/xis-mvui/v1/guides/opening-menus/index.md): the Options button, the mod list's Config button, your own key or button.
- [Several screens and dialogs](https://xichil.dev/docs/xis-mvui/v1/guides/navigation/index.md): `host.open`, `back`, `close` and `ConfirmDialog`.
- [Slow work: files and network](https://xichil.dev/docs/xis-mvui/v1/guides/async-work/index.md): `runAsync` and `StatusLine`.
- [Validate what players type](https://xichil.dev/docs/xis-mvui/v1/guides/validation/index.md): validators, error lines and disabling Save.
- [Translate your menu](https://xichil.dev/docs/xis-mvui/v1/guides/translations/index.md): `Text`, lang files and `UiTexts`.
- [Save and load settings](https://xichil.dev/docs/xis-mvui/v1/guides/saving-config/index.md): where the values live and when to write them.
- [Read and write options.txt](https://xichil.dev/docs/xis-mvui/v1/guides/game-options/index.md): `GameBridge` for options-profile mods.
- [Key bindings](https://xichil.dev/docs/xis-mvui/v1/guides/keybinds/index.md): `Keybind`, `Key`, storing keys, checking them in game.
- [Test menus without Minecraft](https://xichil.dev/docs/xis-mvui/v1/guides/testing/index.md): `FakeHost` in JUnit.

**Concepts** (how it works):

- [State and refresh](https://xichil.dev/docs/xis-mvui/v1/concepts/state-and-refresh/index.md): the mod owns the values; when suppliers are re-read.
- [Ids](https://xichil.dev/docs/xis-mvui/v1/concepts/ids/index.md): the rules for screen and entry ids, and the ids widgets reserve.
- [Threads](https://xichil.dev/docs/xis-mvui/v1/concepts/threads/index.md): what runs on the main thread and what may not.
- [Failure isolation](https://xichil.dev/docs/xis-mvui/v1/concepts/failure-isolation/index.md): what happens when your code throws.
- [Backends and versions](https://xichil.dev/docs/xis-mvui/v1/concepts/backends/index.md): how the library picks the code for the running game.

**Widgets**: [which widget to use](https://xichil.dev/docs/xis-mvui/v1/widgets/index.md), then one page each:
[Button](https://xichil.dev/docs/xis-mvui/v1/widgets/button/index.md), [Label](https://xichil.dev/docs/xis-mvui/v1/widgets/label/index.md), [StatusLine](https://xichil.dev/docs/xis-mvui/v1/widgets/status-line/index.md),
[Toggle](https://xichil.dev/docs/xis-mvui/v1/widgets/toggle/index.md), [Checkbox](https://xichil.dev/docs/xis-mvui/v1/widgets/checkbox/index.md), [Cycle](https://xichil.dev/docs/xis-mvui/v1/widgets/cycle/index.md),
[Dropdown](https://xichil.dev/docs/xis-mvui/v1/widgets/dropdown/index.md), [SelectList](https://xichil.dev/docs/xis-mvui/v1/widgets/select-list/index.md), [Slider](https://xichil.dev/docs/xis-mvui/v1/widgets/slider/index.md),
[NumberField](https://xichil.dev/docs/xis-mvui/v1/widgets/number-field/index.md), [TextInput](https://xichil.dev/docs/xis-mvui/v1/widgets/text-input/index.md),
[MultiLineInput](https://xichil.dev/docs/xis-mvui/v1/widgets/multi-line-input/index.md), [StringListEditor](https://xichil.dev/docs/xis-mvui/v1/widgets/string-list-editor/index.md),
[Keybind](https://xichil.dev/docs/xis-mvui/v1/widgets/keybind/index.md), [ColorPicker](https://xichil.dev/docs/xis-mvui/v1/widgets/color-picker/index.md), [Section](https://xichil.dev/docs/xis-mvui/v1/widgets/section/index.md).

**Examples** (complete, copyable):

- [A settings menu](https://xichil.dev/docs/xis-mvui/v1/examples/settings-menu/index.md): a config class, a properties file, toggles, sliders and sections.
- [A list manager](https://xichil.dev/docs/xis-mvui/v1/examples/list-manager/index.md): a `SelectList` with Add, Rename and Delete screens.
- [A multi-loader mod](https://xichil.dev/docs/xis-mvui/v1/examples/multi-loader-mod/index.md): every file of a mod that ships for all loaders.

## Players and server admins

The [wiki](https://xichil.dev/wiki/xis-mvui/v1/index.md) explains how to install the library and use its menus.