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, and this page is available as Markdown at /ooui-react/en/guide/usage.md.
ooui-react
  • English

      • Usage

      Installation

      npm
      yarn
      pnpm
      bun
      deno
      npm install ooui-react

      React ≥ 18 is required.

      Runtime environment

      • Browser-oriented; server-side rendering (SSR) is not supported: floating components (Popup, dropdown menus, toolbar popup panels) resolve their portal container and call createPortal during render, which throws immediately on the server where document doesn't exist. With isomorphic frameworks such as Next.js, keep these components out of the server render tree, or render them only after mounting on the client.
      • Both ESM and CJS builds are shipped, and they are separate module instances: when a Node process loads the package through both import and require, the message registry and the OOUIProvider context are not shared; bundling for browsers is unaffected.

      Outside MediaWiki sites (does anyone actually do that?), you have to load OOUI's theme CSS and the Codex design tokens yourself — as of oojs-ui 0.54, the token stylesheet must be loaded alongside it. Pick one theme stylesheet: wikimediaui is the current default, while apex is the legacy theme (some states look different between the two; the class names emitted by this library are valid under both):

      import "@wikimedia/codex-design-tokens/dist/theme-wikimedia-ui.css";
// Pick one of the themes:
import "oojs-ui/dist/oojs-ui-wikimediaui.css";
import "oojs-ui/dist/oojs-ui-apex.css";

      The OOUI theme is sized against MediaWiki's body font size of 14px; keep your host page consistent with it.

      Tip

      The navbar of this site offers a "Preview theme" switcher to view all live demos under either wikimediaui or apex. The library itself ships no styles — whatever theme you switch to is exactly how the demos will look under it.

      Using it on a MediaWiki site

      This library was built first and foremost for user gadgets on MediaWiki sites. If bundle size matters to you, use the Preact compatibility layer instead of full React.

      For working examples, see my Moegirlpedia gadgets repository:

      Declaring dependencies

      On a MediaWiki site the OOUI styles are served by its built-in oojs-ui resource modules. Load them at runtime with mw.loader.using or in your gadget's ResourceLoader definition:

      mw.loader.using([
  "oojs-ui", // base OOUI styles
  "oojs-ui.styles.icons-media", // CSS of the matching OOUI icon pack
]);

      The icon pack names are listed by group on the Icon component page.

      Mounting

      We recommend rendering into a div or a DocumentFragment, then inserting it before or after an anchor:

      index.tsx
      App.tsx
      import React from "react";
import { createRoot } from "react-dom/client";
import App from "./App";

$(async () => {
  await mw.loader.using(["oojs-ui"]);
  const fragment = document.createDocumentFragment();
  createRoot(fragment).render(<App />);
  // e.g. insert before the Recent Changes list
  document.querySelector(".mw-changeslist")!.before(fragment);
});

      Preact compatibility

      This library runs on the Preact compatibility layer (preact/compat); see the official guide for aliasing.

      • Requires Preact ≥ 10.18.
      • react-dom/client must be aliased to preact/compat/client; without it the imperative APIs (confirm / alert / prompt) fail because createRoot is not available.