#tiye/react

React bindings for MoonBit

#Project Status

#API Stability and JavaScript Boundary

#Bound APIs and Types

#Core Rendering API

• render(vdom: VirtualNode, parent: @dom.Element) -> Unit - Render virtual DOM to specified parent element
• render_with_options(vdom: VirtualNode, parent: @dom.Element, options: RootOptions) -> Unit - Create and render through a configured React root
• hydrate_root(vdom: VirtualNode, parent: @dom.Element, options?: RootOptions) -> Unit - Attach React to matching server-rendered HTML
• unmount(parent: @dom.Element) -> Unit - Unmount the React root for an element
• create_portal(child: VirtualNode, parent: @dom.Element, key?: String) -> VirtualNode - Place DOM in another container while retaining React-tree context and event propagation
• render_to_string(vdom: VirtualNode, identifier_prefix?: String) -> String - Basic synchronous SSR/SSG renderer
• RootOptions::new(...) -> RootOptions - Configure identifierPrefix and caught, uncaught, and recoverable error callbacks
• ReactError::message() -> String, ReactErrorInfo::component_stack() -> String - Inspect root callback values
• component[T](f: (T) -> VirtualNode, props: T, children: Array[VirtualNode]) -> VirtualNode - Create a leaf component
• component_with_children[T](f: (T, Array[VirtualNode]) -> VirtualNode, props: T, children: Array[VirtualNode]) -> VirtualNode - Create a component that places its children
• define_component[T](render: (T) -> VirtualNode) -> ReactComponent[T] - Define a stable reusable component type with typed MoonBit props
• ReactComponent::render(props: T) -> VirtualNode - Render a reusable typed component
• ReactComponent::memo(are_props_equal?: (T, T) -> Bool) -> ReactComponent[T] - Memoize a typed component with default identity or a typed comparator
• lazy_component[T](loader: async () -> ReactComponent[T]) -> ReactComponent[T] - Lazily load and cache a typed component through Suspense
• suspense(fallback: VirtualNode, children: Array[VirtualNode]) -> VirtualNode - Display fallback UI until suspended children are ready
• component_from_js[T](component: JsObscure) -> ReactComponent[T] - Declare the typed MoonBit props contract for a trusted JavaScript component
• VirtualNode::with_key(key: String) -> VirtualNode - Assign a stable React reconciliation key without adding a DOM wrapper
• create_context[T](default_value: T) -> ReactContext[T] - Create a typed React Context
• ReactContext::provider(value: T, children: Array[VirtualNode]) -> VirtualNode - Provide a value without adding a DOM wrapper

#Hooks API

• use_state[T](initial: T) -> (T, (T) -> Unit) - State management hook
• use_context[T](context: ReactContext[T]) -> T - Read and subscribe to the nearest typed Context provider
• use_state_with_updater[T](initial: T) -> (T, (StateUpdate[T]) -> Unit) - State hook with direct and functional updates
• use_reducer_with_initial[S, A](initial: S, reducer: (S, A) -> S) -> (S, (A) -> Unit) - Reducer hook for any explicit state type
• use_reducer[S: Default, A](initial?: S, reducer: (S, A) -> S) -> (S, (A) -> Unit) - Reducer hook
• use_effect_once(effect: () -> Unit) -> Unit - Effect hook that runs only once
• use_effect_cleanup_deps(effect: () -> () -> Unit, deps: Array[JsObscure]) -> Unit - Effect hook with a cleanup function
• use_effect_once_with_cleanup(effect: () -> () -> Unit) -> Unit - One-time effect with a cleanup function
• use_effect_deps(effect: () -> Unit, deps: Array[JsObscure]) -> Unit - Effect hook with dependencies
• use_layout_effect_deps(effect: () -> Unit, deps: Array[JsObscure]) -> Unit - Layout effect hook
• use_memo_deps[A](factory: () -> A, deps: Array[JsObscure]) -> A - Memoization hook
• use_callback_deps[F](callback: F, deps: Array[JsObscure]) -> F - Callback memoization hook
• use_effect_event[F](callback: F) -> F - React 19.2 effect-only callback that reads latest state without re-subscribing an effect
• use_action_state[S, A](initial: S, action: (S, A) -> S) -> (S, (A) -> Unit, Bool) - React 19 action state, dispatch, and pending flag
• use_async_action_state[S, A](initial: S, action: async (S, A) -> S) -> (S, (A) -> Unit, Bool) - Export a MoonBit async reducer as a Promise-returning React Action
• use_optimistic[S, A](value: S, reducer: (S, A) -> S) -> (S, (A) -> Unit) - Temporary optimistic state scoped to a React Action
• use_form_status() -> FormStatus - Read pending data, method, and action from the nearest parent form
• use_callback0_deps(f: () -> Unit, deps: Array[JsObscure]) -> () -> Unit - Zero-argument callback hook
• use_ref[T](initial: T) -> ReactRef[T] - Reference hook
• use_dom_ref() -> ReactDomRef - Nullable DOM-element ref hook whose current() value is None before mount and after unmount
• use_id() -> String - Stable component-local identifier hook
• use_deferred_value[T](value: T) -> T - Deferred-value hook for non-urgent rendering
• use_transition() -> (Bool, (() -> Unit) -> Unit) - Transition state and starter hook
• start_transition(action: () -> Unit) -> Unit - Start a transition when pending state is not needed
• use_sync_external_store[T](subscribe, get_snapshot, get_server_snapshot?) -> T - Read and subscribe to a typed immutable external-store snapshot
• use_imperative_ref[T]() -> ImperativeRef[T] - Create a nullable typed ref for a custom component handle
• use_imperative_handle_deps[T](ref: ImperativeRef[T], create_handle: () -> T, deps: Array[JsObscure]) -> Unit - Expose a typed React 19 imperative handle
• obscure[T](v: T) -> JsObscure - Dependency conversion helper function

#HTML Element Bindings

• div, span, p, h1, h2, h3 - Basic text elements
• form, button, input, textarea, select, option - Form elements
• a, img, video, audio - Media and link elements
• ul, ol, li - List elements
• section, article, header, footer, nav, aside - Semantic elements
• label - Label element
• Generated table helpers: table, caption, colgroup, col, thead, tbody, tfoot, tr, th, and td
• Generated form and interactive helpers: fieldset, legend, datalist, optgroup, output, progress, meter, dialog, details, and summary
• Generated React 19 metadata helpers: title, meta, link, style_tag, and script_tag
• Generated core SVG helpers include svg, g, defs, symbol, path, circle, ellipse, rect, line, gradients, clipping/masking, text, and use_

#Event Handling

• DOMEvent type and its methods:
  • target_value() -> String - Get form element value
  • target_checked() -> Bool - Get checkbox or radio checked state
  • key() -> String, key_code() -> Int - Keyboard events
  • client_x() -> Int, client_y() -> Int - Mouse coordinates
  • prevent_default(), stop_propagation() - Event control
  • ctrl_key(), shift_key(), alt_key(), meta_key() -> Bool - Modifier key detection

#Styles and Attributes

• ElementAttrs - HTML attribute management, including typed string, boolean, integer, floating-point, and JavaScript-value setters
• ElementEvents - Event handler management
• RespoStyle - CSS styles (from @css module)
• InputType enum - Support for all HTML input types
• StateUpdate[T] - Set(value) or Update(fn(previous) { ... }) for safely deriving state from the latest React value

#Portals, Roots, and SSR Scope

• render_to_string is a synchronous react-dom/server binding.
• hydrate_root requires markup identical to the initial client tree.
• identifier_prefix must be identical in render_to_string and RootOptions::new when the tree uses use_id.
• Streaming, waiting for suspended data, async server rendering, React Server Components, and framework routing/data protocols are not provided.

import * as React from "react";
import * as ReactDOMServer from "react-dom/server";

globalThis.React = React;
globalThis.ReactDOMServer = ReactDOMServer;

#External Stores and Component Integration

#Virtual DOM Types

• VirtualNode - Base virtual node type
• VirtualElement - Virtual element type
• Text(String) - Text node

#Quick Start

import * as React from "react";
import * as ReactDOM from "react-dom";
import * as ReactDOMClient from "react-dom/client";

globalThis.React = React;
globalThis.ReactDOM = ReactDOM;
globalThis.ReactDOMClient = ReactDOMClient;

// Define your component props
struct ContainerProps {} derive(Default)

// Create a functional component
fn comp_container(_v : ContainerProps) -> @react.VirtualNode {
  let (counter, set_counter) = @react.use_state(Float::from_double(0.0))

  @react.div(
    id="container",
    style=@css.respo_style(
      color=@css.CssColor::Blue,
      font_family="Arial",
      padding=@css.CssSize::Px(10.0),
    ),
    on_click=fn(_) {
      println("clicked \{counter}")
      set_counter(counter + 1.0)
    },
    [
      @react.Fragment([@react.Text("Demo: ")]),
      @react.Text("Counter \{counter}")
    ],
  )
}

// Render to DOM
fn main {
  let window = @dom.window()
  let doc = window.document()
  let body = doc.body()
  let props : ContainerProps = Default::default()

  @react.render(
    @react.component(comp_container, props, []),
    body,
  )
  println("loaded")
}

#Features

• Type-safe virtual DOM construction
• React-style hooks (useState)
• CSS-in-JS styling support
• Event handling
• Component composition

#Development

moon check
moon test
moon info
corepack yarn install --frozen-lockfile
corepack yarn generate:dom
corepack yarn check:generated
corepack yarn build
corepack yarn test:browser

#Release

corepack yarn verify:published X.Y.Z

#License