> For AI agents: the complete documentation index is available at /ooui-react/en/llms.txt, the full documentation bundle is available at /ooui-react/en/llms-full.txt. # Coming from OOUI ooui-react reimplements OOUI's interaction semantics and DOM contract while reusing the original theme CSS, but its API is idiomatic React. Whether you know OOUI and want to lean on that experience in a new script, or are rewriting an old, complex OOUI script, this page maps the two APIs: start with the mental model mapping, locate components by their original class names, then check the dropped capabilities and behavioral differences. ## Mental model mapping The original imperative API is uniformly expressed as declarative props in this library; see [Controlled and uncontrolled](/ooui-react/en/guide/controlled.md) for the rules: | Original | ooui-react | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `setValue` / `setDisabled` / `setPage` setters | Controlled props such as `value` / `defaultValue` / `onChange` | | `WindowManager.openWindow` / `closeWindow` | The Dialog family takes a required `open` prop only; close intent is reported via `onEscape` and other callbacks, see [Dialogs must be controlled](/ooui-react/en/guide/controlled.md#dialogs-must-be-controlled) | | `updateState` / `choose` / `toggle` events | Callback props such as `onChange` / `onChoose` / `onOpenChange` | | `OO.ui.msg` global and `OO.ui.deferMsg` | The `messages` config and `useMessage` of `OOUIProvider`, see [Global configuration](/ooui-react/en/guide/configuration.md) | | `OO.ui.isMobile()` (stub that always returns `false`) | The `isMobile` config of `OOUIProvider` | | `OO.ui.HtmlSnippet` (raw-output wrapper) | Write `ReactNode` directly; strings are escaped by default, and there is no dedicated wrapper for raw HTML — use `dangerouslySetInnerHTML` yourself and own the risk | | `OO.ui.Theme` runtime object (`getElementClasses` hooks) | None. Class names are emitted by components following wikimediaui semantics; theme styles come from site CSS. Under third-party themes such as apex a few state classes appear that the original would not output (e.g. progressive coloring on selected options) — a known deviation | | `ToolFactory` / `ToolGroupToolFactory` registration | Declarative data: pass a `tools` array to the toolbar and nest tool groups as React elements, see [Toolbar](/ooui-react/en/components/toolbar/index.md) | ## Locating components and classes Component names = original class names minus the `Widget` suffix (`ButtonWidget` → `Button`, `TextInputWidget` → `TextInput`). Four names do not survive the suffix removal and keep their original form: `SearchWidget`, `HiddenInputWidget`, `SelectFileInputWidget`, `ButtonMenuSelectWidget`. Some original classes do not map to standalone components: | Original class | Where it went | | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OO.ui.WindowManager` | Each Dialog component owns its open/close state (controlled `open`); content isolation and stacking are built in. Imperative `confirm` / `alert` / `prompt` need no manager | | `OO.ui.ActionWidget` / `ActionSet` / `OO.ui.Error` | Inlined into `ProcessDialog`: the action array, mode filtering and the error panel, see [Process dialog](/ooui-react/en/components/process-dialog/index.md) | | `OO.ui.Process` | The `onAction` async callback; rewrite `.next()` chains as one async function | | `OO.ui.OutlineControlsWidget` | Inlined into `BookletLayout`'s outline panel, see [Booklet layout](/ooui-react/en/components/booklet-layout/index.md) | | `OO.ui.SelectWidget` | [`Select`](/ooui-react/en/components/select/index.md) | | `OO.ui.PopupTagMultiselectWidget` (deprecated upstream) | Not provided; use [MenuTagMultiselect](/ooui-react/en/components/menu-tag-multiselect/index.md) | | `OO.ui` host-environment utilities (`bind` / `infuse` / `getUserLanguages` / `generateElementId` / `debounce` etc.) | Not mapped: React capabilities, `useId` and es-toolkit cover these scenarios | ## Dropped capabilities The following original capabilities are intentionally not implemented, indexed by original API name: | Original capability | What to do instead | | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `href` on `TabOption` | Not supported (the original only used it from PHP); compose link tabs yourself, see [Tab select](/ooui-react/en/components/tab-select/index.md) | | `allowLinebreaks` / `enter` on `MultilineTextInputWidget` | Line breaks are always allowed; strip them yourself when you need to forbid them, see [Multiline text input](/ooui-react/en/components/multiline-text-input/index.md) | | `config.input` / `inputWidget` on `TagMultiselectWidget` | The input is built in and cannot be replaced | | `config.input` on `LabelWidget` | Use `htmlFor` for fields with an id, otherwise let FieldLayout wire the association, see [Label](/ooui-react/en/components/label/index.md) | | `ActionSet.static.specialFlags` subclass override | Special actions are fixed to `safe` / `primary`; declare them via `flags` | | `align='inline'` downgrade check on `FieldLayout` | No automatic downgrade; make sure the field root element is inline before passing `inline` | | `flags` on plain-label options (Tab / Radio / CheckboxMultioption) | `flags` is only available on option forms with icon slots, see [Selections and options](/ooui-react/en/guide/options.md) | | Automatic URL sanitizing (`OO.ui.isSafeUrl`) | Components never rewrite `href` / `action`; sanitize untrusted URLs yourself with the exported `sanitizeUrl` (the responsibility is on the caller and the backend), see [Button](/ooui-react/en/components/button/index.md) | ## Behavioral differences at a glance These behaviors differ from the original in ways that will break or surprise you if unaddressed, indexed by component. Details live on each component page: | Component | Difference | Details | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `Message` | The close button only calls `onClose` and does not hide itself — if you ignore the callback the message cannot be dismissed | [Message](/ooui-react/en/components/message/index.md) | | Bare `Dialog` | No built-in title slot; render the title yourself and pass `aria-labelledby`, otherwise you get an unnamed dialog | [Dialog](/ooui-react/en/components/dialog/index.md) | | Dialog family | Always controlled: a required `open` prop, no `defaultOpen` | [Controlled and uncontrolled](/ooui-react/en/guide/controlled.md#dialogs-must-be-controlled) | | `confirm` / `alert` / `prompt` | The original silently drops the second call while a window is open; this library stacks them, each independently interactive | [Imperative dialogs](/ooui-react/en/components/imperative-dialogs/index.md) | | `prompt` | `textInput.value` is initial-only; it cannot be changed externally while the dialog is alive | [Imperative dialogs](/ooui-react/en/components/imperative-dialogs/index.md) | | `Toolbar` tools | Visible text and tooltip split from one `title` key into `label` + `title` (pass the old `narrowConfig.title` value as `label`) | [Toolbar](/ooui-react/en/components/toolbar/index.md) | | `Toolbar` | Do not put popup tools inside List / Menu groups: the popup anchor dies with the collapsed panel and ends up misplaced at the viewport's top-left corner | [Toolbar](/ooui-react/en/components/toolbar/index.md) | | `TagMultiselect` | Tag identity is a scalar `value`; carry objects via the `data` field and look them up by value | [Tag multiselect](/ooui-react/en/components/tag-multiselect/index.md) | | `Dropdown` / `ButtonMenuSelectWidget` | Space selects the highlighted option while open (the original ignored Space and only closed the menu via key-press click emulation) | [Dropdown](/ooui-react/en/components/dropdown/index.md) | | `Popup` | Re-evaluates the flip direction when scrolling changes clipping (the original freezes it until reopened); the popup may jump while scrolling | [Popup](/ooui-react/en/components/popup/index.md) | ## Imperative dialogs `confirm` / `alert` / `prompt` are standalone functions you can `await` from any event handler; the dialogs inherit the enclosing `OOUIProvider` configuration (messages, `isMobile`, `dir` and your own providers). Unlike the original's shared singleton manager, repeated calls stack. See [Imperative dialogs](/ooui-react/en/components/imperative-dialogs/index.md) for the runtime semantics and [Global configuration](/ooui-react/en/guide/configuration.md#imperative-dialogs) for config inheritance. ## Localization `en` is the built-in default baseline; 25 more language packs (`ooui-react/locales/`) are available as optional imports. On a MediaWiki site you can wire `mw.msg` into `messages` to follow the site language. See [Messages and i18n](/ooui-react/en/guide/configuration.md#messages-and-i18n) for the language list and setup. ## Full deviation ledger This page lists only the differences that affect usage. The complete ledger (including implementation-level trade-offs and rationale) lives in the repository's [`dev-docs/DEVIATIONS.md`](https://github.com/BearBin1215/ooui-react/blob/main/dev-docs/DEVIATIONS.md).