Skip to main content

ui

The catalog, with a row per registered addon

@bedrock-core/ui writes Minecraft Bedrock screens in JSX and compiles them into the resource pack.

Beta

@bedrock-core/ui is in beta: the API can change between releases. Pin exact versions and read the changelog before upgrading.

What is @bedrock-core/ui?​

A screen is a component. You write it with JSX, flexbox props and hooks, and the build compiles it once into the JSON UI that ships in the pack. At runtime nothing sends a layout: showing a screen sends its title and the values that changed, and the client draws it from the pack it already holds.

The root selects the host: <Screen> is an action form, <Form> a native modal, and <Container> an entity or block container screen. <Experimental_OreUI> adds a player-owned Ore presentation with live controls and version-matched Windows client resources. Components use the interaction mechanism their host provides. See Hosts.

For a pre-themed component set matching vanilla Minecraft's look, see @bedrock-core/ore-styled. It is optional — pick it up for batteries-included visuals, skip it to style every primitive yourself.

Localization is built in rather than bolted on: <Text> takes literal and localized children on the same channel, so one screen serves every language at once. See i18n.

Install​

npm install @bedrock-core/ui

A world also needs compatible shared assets. Minor releases supply a new pack; unchanged library patches reuse the existing one. Installation covers both, and the CLI scaffolds them wired together.

Your first screen​

A screen lives in a *.screen.tsx file under BP/ui and default-exports its component. The ui-compiler stage discovers these entries and also supports screens under BP/scripts.

packs/BP/ui/welcome.screen.tsx
import { Button, Panel, Screen, Text } from '@bedrock-core/ui';

export default function Welcome(): JSX.Element {
return (
<Screen>
<Panel padding={10} gap={8}>
<Text>{'Welcome to Bedrock UI'}</Text>

<Button onPress={() => console.warn('pressed')}>
<Text>{'Press me'}</Text>
</Button>
</Panel>
</Screen>
);
}

Show it to a player with render():

packs/BP/scripts/main.ts
import { render } from '@bedrock-core/ui';
import Welcome from '../ui/welcome.screen';
import { world, type Entity, type Player, type ButtonPushAfterEvent } from '@minecraft/server';
import { MinecraftEntityTypes } from '@minecraft/vanilla-data';

const isPlayer = (source: Entity): source is Player => source.typeId === MinecraftEntityTypes.Player;

world.afterEvents.buttonPush.subscribe(({ source }: ButtonPushAfterEvent): void => {
if (isPlayer(source)) {
render(Welcome, source);
}
});

Builder registers compiled screens automatically. Installation covers the build and required resource packs.

What you get​

Compiled geometry — @bedrock-core/flexbox solves the layout against a fixed 320 × 210 canvas. Compiled controls retain their authored geometry; runtime layout passes can still measure content for wrapping and composition.

Refusals with names — each host declares what every kind of component becomes on it. A <Slider> outside a <Form> or a <Slot> outside a container screen fails the build, in that host's own words, instead of drawing something inert.

Screens other addons can show — a static screen is described by its title, its entry values and one target per press. Publish that table and a realm running none of your script still shows your screens, because the layout is in the pack every client holds.

Switches that cost nothing — <Tabs> and <Disclosure> change what is drawn entirely on the client. No press, no re-present, no payload.

Differences from React​

A @minecraft/server-ui form cannot be mutated while open, so a state change never repaints it: the player sees a new snapshot when they press. A container screen has no such limit.

A compiled screen's shape is also frozen. State probes detect changing text and appearance values; <List max> reserves rows and visible carries a branch's visibility. maxLength only limits literal text. State covers what those values cost.

If you are new to React, react.dev/learn is the place to start.

Next steps​

  • Lint components and hooks — check addon sources with the UI package's ESLint preset
  • Installation — the package, the render pack and the tsconfig.json entries
  • Hosts — the three screens and what each can carry
  • Components — every built-in component
  • Hooks — state, effects and the Minecraft-specific hooks
  • Compiler — how a screen becomes JSON UI
  • API — render(), contexts and the compiled-screen registry