Components Reference

Quick reference for all React components included in RPGReact. For detailed tutorials, see the Tutorials section.

Navigation & Selection

Chooser

File: menus/src/components/Chooser.tsx Tutorial: Using Chooser and ActorChooser

Generic selectable list with UP/DOWN/OK input handling.

Props:

• items: T[] - Array of items to display

• children: (item: T, selected: boolean, index: number) => ReactNode - Render function

• hasFocus: boolean - Whether component should accept input

• onItemSelected?(item: T, index: number) - Called on OK press

• onItemHighlighted?(item: T, index: number) - Called when selection changes

• resetSelection?: boolean - Reset to index 0 when items change

• defaultSelection?: number - Initial selection index (default: 0)

ActorChooser

File: menus/src/components/ActorChooser.tsx Tutorial: Using Chooser and ActorChooser

Party member selector using Chooser with PartyMemberFull or PartyMemberCompact.

Props:

• Extends BaseMenuScreenProps

• onActorSelected(actor: Game_Actor) - Called when actor selected

• useFullView?: boolean - Use full cards vs compact (default: false)

Layout & Structure

BaseMenuScreen

File: menus/src/components/BaseMenuScreen.tsx Tutorial: Using BaseMenuScreen

Base props interface for menu screens.

Props (BaseMenuScreenProps):

• pageData: any - Game data and commands from RMMZ

• isTestMenu: boolean - Whether in test mode

• hasFocus: boolean - Whether screen has input focus

• selected: boolean - Whether screen is selected/active

BaseModal

File: menus/src/components/BaseModal.tsx Tutorial: Using BaseModal

Modal dialog with backdrop and CANCEL key support.

Props:

• show: boolean - Whether modal is visible

• onHide() - Called when CANCEL pressed or backdrop clicked

• className?: string - Additional CSS classes

• children - Modal content

Input Components

InputNumber

File: menus/src/components/InputNumber.tsx Tutorial: Using Input Number

Numeric input with increment/decrement buttons.

Props:

• value: number - Current value

• min?: number - Minimum value (default: 0)

• max?: number - Maximum value (default: 999999)

• onChange(value: number) - Called when value changes

• hasFocus: boolean - Accept input

• className?: string

InputName

File: menus/src/components/InputName.tsx Tutorial: Using Input Name

Character name input with keyboard grid.

Props:

• initialName: string - Starting name

• maxLength: number - Maximum name length

• onConfirm(name: string) - Called when confirmed

• onCancel() - Called when canceled

• hasFocus: boolean

SelectItem

File: menus/src/components/SelectItem.tsx Tutorial: Using Select Item

Item/weapon/armor selector from party inventory.

Props:

• Extends BaseMenuScreenProps

• itemType: 'item' | 'weapon' | 'armor' - What to show

• onItemSelected(item: any) - Called when item chosen

• onCancel() - Called on cancel

Confirm

File: menus/src/components/Confirm.tsx Tutorial: Using Confirm

Global confirm dialog provider (Yes/No prompts).

Usage:

const { confirm } = useConfirm();
const result = await confirm('Are you sure?');
if (result) { /* user clicked Yes */ }

Display Components

Icon

File: menus/src/components/Icon.tsx Tutorial: Use Icons

Display icon from IconSet.png.

Props:

• icon: number - Icon index (0-based)

• className?: string

Example:

<Icon icon={64} className="w-8 h-8" />

ActorPortrait

File: menus/src/components/ActorPortrait.tsx Tutorial: Use Actor Portraits

Display actor's face/portrait image.

Props:

• actor: Game_Actor - Actor to display

• className?: string

ImageViewport

File: menus/src/components/ImageViewport.tsx

Display a subsection of a larger image (for sprite sheets).

Props:

• src: string - Image path

• viewport: { x: number, y: number, width: number, height: number } - Crop rectangle

• className?: string

Example:

<ImageViewport
  src="/img/characters/Actor1.png"
  viewport={{ x: 0, y: 0, width: 48, height: 48 }}
  className="w-12 h-12"
/>

ProgressBar

File: menus/src/components/ProgressBar.tsx

Generic progress bar component (used by XPProgresBar, ATB gauges, etc.).

Props:

• percent: number - Fill percentage (0-100)

• outerClassName?: string - Outer container classes

• innerClassName?: string - Inner bar classes

• outerStyle?: React.CSSProperties - Outer container inline styles

• innerStyle?: React.CSSProperties - Inner bar inline styles

• children?: ReactNode - Content overlaid on bar

WindowskinArrow

File: menus/src/components/WindowskinArrow.tsx

Directional arrow for quantity controls, navigation, etc.

Props:

• direction: 'up' | 'down' | 'left' | 'right' - Arrow direction

• size?: number - Size in pixels (default: 16)

• className?: string

Party Member Display

PartyMemberFull

File: menus/src/components/PartyMemberFull.tsx Tutorial: PartyMemberFull vs PartyMemberCompact

Full party member card with portrait, stats, HP/MP bars.

Props (PartyMemberProps):

• member: Game_Actor - Actor to display

• pageData: any - Game data

• isTestMenu: boolean

• hasFocus: boolean

• selected: boolean

• className?: string

PartyMemberCompact

File: menus/src/components/PartyMemberCompact.tsx Tutorial: PartyMemberFull vs PartyMemberCompact

Compact party member display (name + HP/MP only).

Props: Same as PartyMemberFull

PartyMemberReward

File: menus/src/components/PartyMemberReward.tsx

Battle results party member card with XP animation.

Props:

• Extends PartyMemberProps

• rewardExp: number - EXP gained in battle

Features:

• Animates XP bar from starting exp to final exp

• Shows level-up notifications

• Supports skip via exposed ref handle

XPProgresBar

File: menus/src/components/XPProgresBar.tsx Tutorial: Level-Up Animation System

Animated XP progress bar with level-up detection.

Props:

• partyMember: Game_Actor - Actor whose XP to display

• className: string - CSS classes

• onAnimationComplete?() - Called when animation finishes

• startExp?: number - Override starting exp

• targetExp?: number - Override target exp

Ref Handle:

• skip() - Skip animation to final state

• getLevelUpEvents(): number[] - Get levels gained

Message & Text Components

Message

File: menus/src/components/Message.tsx Tutorial: Messages, Typewriter, SpecialCodeRenderer

Display RPG Maker message text with text codes.

Props:

• text: string - Message text (may contain codes like \C[1], \N[1])

• pageData: any - Game data for code resolution

• className?: string

Typewriter

File: menus/src/components/Typewriter.tsx Tutorial: Messages, Typewriter, SpecialCodeRenderer

Text that appears character-by-character.

Props:

• text: string - Text to display

• speed?: number - Characters per second (default: 20)

• onComplete?() - Called when typing finishes

• skip?: boolean - Show all text immediately

SpecialCodeRenderer

File: menus/src/components/SpecialCodeRenderer.tsx Tutorial: Messages, Typewriter, SpecialCodeRenderer

Parse and render RPG Maker text codes (colors, icons, names).

Props:

• text: string - Raw text with codes

• pageData: any - Game data

ScrollingText

File: menus/src/components/ScrollingText.tsx

Auto-scrolling text (for credits, long messages).

Props:

• text: string - Text to scroll

• speed?: number - Scroll speed in pixels per second

• onComplete?() - Called when scrolling finishes

Utility Components

Minimap

File: menus/src/components/Minimap.tsx

Minimap display for current map.

Props:

• pageData: any - Game data

• width: number - Minimap width in pixels

• height: number - Minimap height in pixels

• className?: string

CancelButton

File: menus/src/components/CancelButton.tsx

Standard cancel/back button component.

Props:

• onClick() - Click handler

• label?: string - Button text (default: "X")

• className?: string

Notes:

• Use in overlay headers (Options/Items/Skills/Equip/Status) to trigger onHide(true) for a consistent close affordance.

• Use cancel-button--small to match tighter headers and list overlays.

• Use cancel-button--corner to overlap the modal corner without colliding with header controls.

KeyGrid

File: menus/src/components/KeyGrid.tsx

Keyboard grid for name input (used internally by InputName).

Props:

• onKeySelected(char: string) - Called when key pressed

• hasFocus: boolean

• locale?: string - Keyboard layout (default: "en_US")

Shop Components

ShopTradeList

File: menus/src/components/ShopTradeList.tsx Tutorial: Shop System

Buy/Sell item list with quantity controls.

Props:

• mode: 'buy' | 'sell' - Trade mode

• items: any[] - Items to display

• hasFocus: boolean

• pageData: any

• selectedItem: any - Currently highlighted item

• onHighlight(item) - Called when selection changes

• onActivate(item, qty, mode) - Called on OK press

• getQty(item): number - Get item quantity

• incQty(item, delta?) - Increase quantity

• decQty(item, delta?) - Decrease quantity

• canAct(item, qty): boolean - Whether action is allowed

• getUnitPrice(item): number - Price per unit

• goldData: { value, unit, unitColor } - Player's gold info

Battle-Specific Components

BattleAtb

File: menus/src/views/battle/BattleAtb.tsx

ATB gauge display for Active Time Battle systems.

BattleLog

File: menus/src/views/battle/BattleLog.tsx

Scrolling combat log.

BattleParty

File: menus/src/views/battle/BattleParty.tsx

Battle party member status display.

BattleInput

File: menus/src/views/battle/BattleInput.tsx

Battle command menu (Attack, Skill, Guard, Item).

TargetCursor

File: menus/src/views/battle/TargetCursor.tsx

Visual cursor for target selection.

SubSelectionWindow

File: menus/src/views/battle/SubSelectionWindow.tsx

Skill/Item selection submenu during battle.

See Battle System Architecture for detailed battle component documentation.

Context Providers

InputContext

File: menus/src/components/InputContext.tsx Tutorial: InputContext

Global input handling provider. Access via useInputContext().

Methods:

• addEventListener(id, mode, key, handler) - Register input handler

• removeEventListener(id) - Unregister handler

Modes:

• 'trigger' - Fire once per press

• 'repeat' - Fire repeatedly while held

Usage Tips

MobX Observers

Many components are wrapped with observer() to react to game state changes. When using these components:

// Component automatically updates when actor.hp changes
<PartyMemberFull member={actor} {...props} />

Ref Handles

Components that support skipping animations expose ref handles:

const ref = useRef<SkipHandle>(null);

<XPProgresBar ref={ref} {...props} />

// Later:
ref.current?.skip();

Focus Management

Components with hasFocus prop only accept input when focused:

// Only one component should have hasFocus=true at a time
<Chooser hasFocus={!modalOpen} {...props} />
<BaseModal show={modalOpen} {...props} />

Modal overlays should pass the parent hasFocus through to their Chooser (and gate cancel handlers on focus) so background menus stop consuming input when the overlay is open.

See Also

• Tutorials - Detailed guides for key components

• Battle System Architecture - Battle component deep dive

• State Management - Best practices for component state