--- url: https://ooui-react.pages.dev/en/guide/usage.md --- > For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt. # Usage ## Installation ```sh [npm] npm install ooui-react ``` ```sh [yarn] yarn add ooui-react ``` ```sh [pnpm] pnpm add ooui-react ``` ```sh [bun] bun add ooui-react ``` ```sh [deno] deno add npm: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, 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): ```js 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](#preact-compatibility) instead of full React. For working examples, see [my Moegirlpedia gadgets repository](https://github.com/BearBin1215/MoegirlPedia): - [`src/gadgets/AdvancedSearch`](https://github.com/BearBin1215/MoegirlPedia/tree/master/src/gadgets/AdvancedSearch) - [`src/gadgets/DynamicRecentChanges`](https://github.com/BearBin1215/MoegirlPedia/tree/master/src/gadgets/DynamicRecentChanges) - [`src/gadgets/FileInspector`](https://github.com/BearBin1215/MoegirlPedia/tree/master/src/gadgets/FileInspector) ### 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: ```ts 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](https://ooui-react.pages.dev/en/components/icon/index.md#all-icons). ### Mounting We recommend rendering into a `div` or a `DocumentFragment`, then inserting it before or after an anchor: **index.tsx** ```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(); // e.g. insert before the Recent Changes list document.querySelector(".mw-changeslist")!.before(fragment); }); ``` **App.tsx** ```tsx import { Button } from "ooui-react"; function App() { return ; } export default App; ``` ## Preact compatibility This library runs on the Preact compatibility layer (`preact/compat`); see the [official guide](https://preactjs.com/guide/getting-started/#aliasing-react-to-preact) for aliasing. - Requires Preact ≥ 10.18; both 10.x and 11.x are supported. - `react-dom/client` must be aliased to `preact/compat/client`; without it the imperative APIs (`confirm` / `alert` / `prompt`) fail because `createRoot` is not available. ## Working with AI This docs site is built with `llms` support: besides the copy-Markdown and open-in-ChatGPT/Claude entries under each page title, two plain-text files for LLMs are published alongside the site on every build: - [llms.txt](https://ooui-react.pages.dev/en/llms.txt): an index file with descriptions and links for every page on the site ``` https://ooui-react.pages.dev/en/llms.txt ``` - [llms-full.txt](https://ooui-react.pages.dev/en/llms-full.txt): the entire English site content merged into one file ``` https://ooui-react.pages.dev/en/llms-full.txt ``` The Chinese site publishes the same files at the root: `/llms.txt` and `/llms-full.txt`. When citing a single page, appending `.md` to its URL also gives you the plain-Markdown version of that page. Copy whichever link fits your use case and hand it to your agent. --- url: https://ooui-react.pages.dev/en/guide/ooui.md --- > For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt. # Coming from OOUI ooui-react reimplements OOUI's interaction semantics and DOM structure 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 concept mapping, locate components by their original class names, then check the dropped capabilities and behavioral differences. ## Concept mapping The original imperative API is uniformly expressed as declarative props in this library; see [Controlled and uncontrolled](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/en/components/toolbar/index.md) | ## Locating components and classes Component names = original class names minus the `Widget` suffix (`ButtonWidget` → `Button`, `TextInputWidget` → `TextInput`). A few names do not work after the suffix is removed and keep their original form: `SearchWidget`, `HiddenInputWidget`, `SelectFileInputWidget`, `ButtonMenuSelectWidget`. Some original classes do not map to standalone components; here is how they are handled: | Original class | How it is handled | | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/en/components/booklet-layout/index.md) | | `OO.ui.SelectWidget` | [`Select`](https://ooui-react.pages.dev/en/components/select/index.md) | | `OO.ui.PopupTagMultiselectWidget` (deprecated upstream) | Not provided; use [MenuTagMultiselect](https://ooui-react.pages.dev/en/components/menu-tag-multiselect/index.md) | | `OO.ui` host-environment utilities (`bind` / `infuse` / `getUserLanguages` / `generateElementId` / `debounce` / `Keys` / `MouseButtons` etc.) | Not mapped: React's own 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](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/en/components/dialog/index.md) | | Dialog family | Always controlled: a required `open` prop, no `defaultOpen` | [Controlled and uncontrolled](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/en/components/imperative-dialogs/index.md) | | `prompt` | `textInput.value` is initial-only; it cannot be changed externally while the dialog is alive | [Imperative dialogs](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/en/components/toolbar/index.md) | | `Toolbar` | Do not put popup tools inside List / Menu groups: the popup anchor becomes invalid once the panel collapses, and the popup ends up misplaced at the viewport's top-left corner | [Toolbar](https://ooui-react.pages.dev/en/components/toolbar/index.md) | | `TagMultiselect` | Tag identity is a scalar `value`; carry objects in the `data` field and look them up by value | [Tag multiselect](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/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](https://ooui-react.pages.dev/en/components/imperative-dialogs/index.md) for the runtime semantics and [Global configuration](https://ooui-react.pages.dev/en/guide/configuration.md#imperative-dialogs) for config inheritance. ## Localization `en` is the built-in default baseline; 222 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](https://ooui-react.pages.dev/en/guide/configuration.md#messages-and-i18n) for the language list and setup.

## Full list of deviations

This page lists only the differences that affect usage. The complete list (including implementation-level trade-offs and rationale) is in the repository's [`dev-docs/DEVIATIONS.md`](https://github.com/BearBin1215/ooui-react/blob/main/dev-docs/DEVIATIONS.md).



---
url: https://ooui-react.pages.dev/en/guide/basics.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Common props

This page is the shared premise for every component page; it covers the prop rules and where props are written that **all components have in common**. Component-specific props are documented on each component's own page.

## Prop pass-through

Components forward any prop this library does not declare straight onto the rendered root element, so `className`, `id`, `style`, `data-*`, `aria-*`, `onClick` and the like can be written directly:

```tsx preview
import { Button } from "ooui-react";

function App() {
  return (
    
      
      
    
  );
}

export default App;
```

- If a component always writes a given prop onto the root element itself, pass-through won't take effect — for example, `aria-disabled` on most components is derived from the `disabled` prop and can't be set by hand.
- The native `defaultValue` / `defaultChecked` are not written to the DOM by pass-through.

## Refs and inner elements

`ref` points at the root element. To reach an inner element or pass props to it, use the channel the component exposes:

| Channel                        | Points at / does                                                                       | Provided by                                                                                                                                                          |
| ------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputRef`                     | The inner `` / ``                                                     | The input family (`TextInput`, `NumberInput`, `MultilineTextInput`, `ComboBoxInput`, `SearchInput`, `CheckboxInput`) and the file `input` of `SelectFileInputWidget` |
| `inputProps`                   | Props for the inner input element                                                      | `TextInput`, `NumberInput`, `ComboBoxInput`                                                                                                                          |
| `buttonProps`                  | Props for the inner button                                                             | `SelectFileInputWidget` (select button), `CopyTextLayout` (copy button)                                                                                              |
| `textInputProps`               | Props for the text field                                                               | `CopyTextLayout`                                                                                                                                                     |
| `menuProps`                    | Props for the menu                                                                     | `ButtonMenuSelectWidget`                                                                                                                                             |
| `iconProps` / `indicatorProps` | Props for the icon / indicator element                                                 | `Button`, `TextInput`                                                                                                                                                |
| `anchorRef` / `anchorProps`    | The inner focusable `<a>` (a Button's root is a `<span>`, so focus must go through it) | `Button`                                                                                                                                                             |

## Common props

| Prop            | Description                                                                                            | Type                 | Default |
| --------------- | ------------------------------------------------------------------------------------------------------ | -------------------- | ------- |
| `disabled`      | Whether the component is disabled                                                                      | `boolean`            | `false` |
| `flags`         | Extra flags; allowed values are listed on each component page                                          | `string \| string[]` | —       |
| `className`     | Appended to the root element, merged with the component's own class list                               | `string`             | —       |
| `id`            | The root element's id                                                                                  | `string`             | —       |
| `title`         | Tooltip text; falls back to the label text when the label is visually hidden                           | `string`             | —       |
| `accessKey`     | Access key; written to the element and appended to `title` as `[key]`                                  | `string`             | —       |
| `tabIndex`      | Tab order; pass `null` to make the element completely unfocusable (no `tabindex` attribute is emitted) | `number \| null`     | `0`     |
| Everything else | `aria-*`, `data-*`, `style`, event handlers                                                            | Native attributes    | —       |

Components with a label (`Button`, `TextInput`, etc.) also have `label` (the label text) and `invisibleLabel` (hidden visually but kept as the accessible name); the semantics are covered in the notes below.

A few notes:

- **`disabled` emits `aria-disabled`, not the native `disabled`**: a disabled element can still be focused and read out; the native `disabled` is only set on real form controls.
- **`disabled` means something different on some layout containers**: on `FieldLayout` it applies to the field itself; `FieldsetLayout` uses a native `<fieldset disabled>`, which also disables every control in the group; pure layout containers (`PanelLayout`, `StackLayout`, etc.) have no `disabled`.
- **Where `title` and `accessKey` are written varies by component**: on most components they are written to the root element, in the Button family to the inner anchor, and in the input family to the inner `<input>`. Before pairing `title` with an `aria-*` attribute, check the placement notes on the component page.
- **The `title` label fallback follows later label changes**: when the label is visually hidden and `title` is not given, the label text is used as the fallback; this library recomputes that fallback from the current `label` / `invisibleLabel` on every render, so changing the label later updates `title` too.{/* deviations: dev-resolve-title-rerender */}
- **`label` accepts any renderable ReactNode**: renderable nodes such as `0` count as having a label, while booleans count as having none.{/* deviations: dev-label-reactnode */}
- **`tabIndex={null}` removes the `tabindex` attribute**: the element becomes completely unfocusable, and programmatic focus does not work either — unlike `-1`, which stays out of the Tab order but remains programmatically focusable.{/* deviations: dev-tabindex-null */}
- **Not every component has `flags`**: each accepts different flags depending on its form (e.g. `Button`'s `primary` / `progressive`, `Icon`'s color variants); see the component pages.

## Keyboard and accessibility

Keyboard interaction, focus management and `aria` attributes match the original OOUI; the specific keys are documented on each component page.



---
url: https://ooui-react.pages.dev/en/guide/controlled.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Controlled and uncontrolled

Most components' "current value" can be held by you (controlled) or kept by the component itself (uncontrolled).

## Controlled channels

| Channel    | Props                                     | Used by                                                                                      |
| ---------- | ----------------------------------------- | -------------------------------------------------------------------------------------------- |
| Value      | `value` / `defaultValue` / `onChange`     | Inputs, selects, tag inputs, file pickers, and the active item of layouts                    |
| Open state | `open` / `defaultOpen` / `onOpenChange`   | `Popup`, `PopupButton`, `ButtonMenuSelectWidget`, toolbar popups and a tool's `popup` config |
| Checked    | `checked` / `defaultChecked` / `onChange` | `CheckboxInput`, `RadioInput`, `ToggleButton`, `ToggleSwitch`                                |

For the option data convention shared by the select family (`value`
, group headings, `labelText`
, disabled propagation, etc.), see [Selection and options](https://ooui-react.pages.dev/en/guide/options.md)
. 
## How control is decided

**Passing `value` (or `checked`) makes it controlled**, and the component renders exactly the value you pass; if you don't pass it, the component keeps its own internal state, with `defaultValue` used only as the initial value.

```tsx preview
import { useState } from "react";
import { Button, ToggleSwitch } from "ooui-react";

function App() {
  const [on, setOn] = useState(false);

  return (
    <div style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 12 }}>
      {/* Controlled: the value is held outside */}
      <ToggleSwitch checked={on} onChange={(checked) => setOn(checked)} />
      {/* Uncontrolled: the component remembers its own state */}
      <ToggleSwitch defaultChecked />
      <Button disabled={!on} onClick={() => setOn(false)}>
        Reset
      </Button>
    </div>
  );
}

export default App;
```

Don't flip `value` back and forth between a value and `undefined` — that's a mode change, which isn't supported.

## Callback signatures

Value callbacks are uniformly **value-first**:

```ts
type ChangeHandler<T, P extends EventTarget = HTMLElement> = (
  value: T,
  event?: ChangeEvent<P>,
) => void;
```

Most cases only use the first argument (`onChange={setValue}` is enough). The second argument is the native event that triggered the change, and **is only provided by the input components**.

Callbacks that don't follow this signature:

| Component                      | Callback                     | Signature                                            |
| ------------------------------ | ---------------------------- | ---------------------------------------------------- |
| `ToggleSwitch`, `ToggleButton` | `onChange`                   | `(checked: boolean) => void`                         |
| `SelectFileInputWidget`        | `onChange`                   | `(files: File[]) => void`                            |
| `SearchWidget`                 | `onQueryChange` / `onChoose` | The query value / the chosen result                  |
| `Message`                      | `onClose`                    | `() => void`, fired when the close button is clicked |

"Choose" callbacks that are easy to confuse:

- The `Select` family offers both `onChange` (the selected value changed; re-selecting the same item doesn't fire) and `onChoose` (fires on every choice, including repeats). When `clearOnChoose` is true, only `onChoose` fires and the selected value doesn't change — handy for command menus.
- `SearchWidget` has no `onChange`; query changes go through `onQueryChange`.

## Dialogs must be controlled

`Dialog`
, `MessageDialog`
 and `ProcessDialog`
 only have `open`
 (required), with no `defaultOpen`
: opening and closing are driven by your state, and close actions notify you through callbacks. 
| Callback          | When it fires                                                        |
| ----------------- | -------------------------------------------------------------------- |
| `onEscape`        | ESC is pressed (when `escapable` is true)                            |
| `onPrimaryAction` | Ctrl / Cmd + Enter is pressed                                        |
| `onReady`         | The opening animation ends, so you can perform actions like focusing |

`MessageDialog` also has `onOk` / `onCancel`, and `ProcessDialog` also has `onAction`; see their component pages.

## When the controlled value isn't among the options

The `value` you pass in sometimes matches no entry in `options`, for example when an option is removed, the initial value is wrong, or the options load asynchronously and aren't there yet on the first render. How components respond:

| Components                                                                         | When no option matches                                                               | Write back via `onChange`?                                                                     |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `IndexLayout`, `BookletLayout`, `StackLayout`, `DropdownInput`, `RadioSelectInput` | Automatically show a fallback item (usually the first selectable one), never a blank | Yes: they hand the fallback value back through `onChange` so your state catches up with the UI |
| `Select`, `Dropdown`, `TagMultiselect`, `MenuTagMultiselect`                       | Select nothing and render your value as-is                                           | No                                                                                             |

For the first group, suppose `options` are `a` and `b` but you pass `value="c"`:

```tsx
const options = [
  { value: "a", label: "A", children: "Panel A" },
  { value: "b", label: "B", children: "Panel B" },
];

// `c` is not among the options
<IndexLayout value="c" onChange={setTab} options={options} />
```

The component shows `a`
 (the fallback) and calls `onChange("a")`
 to tell you "this is what actually took effect". Update your state to `a`
 and `value`
 and the UI line up again. The same invalid value is written back only once, so ignoring the callback won't cause it to fire repeatedly. 
The second group follows your `value` exactly: no match means nothing is selected, and the UI shows that the current value has no match; whether to correct it is up to you.



---
url: https://ooui-react.pages.dev/en/guide/options.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Selection and options

[Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md) covers how the value flows between the components and your state; this page covers how to write both ends of that value — the option data convention shared by the Select family. It applies to:

- Selection lists: `Select`, `OutlineSelect`, `TabSelect`, `ButtonSelect`, `ButtonMenuSelectWidget`
- Tag inputs: `TagMultiselect`, `MenuTagMultiselect`
- Form fields: `DropdownInput`, `RadioSelectInput`, `CheckboxMultiselectInput`
- Inputs with candidates: `ComboBoxInput`, `SearchWidget` (its result set)

Each component only adds its own props on top of this convention (such as `OutlineSelect` levels or the `fixed` tag flag); see the component pages for specifics.

## Option data

`options` is an array of option objects:

- **Items with a `value` are selectable options.** `value` is always a `string | number`, and doubles as the selected-state match key and the list key.
- **Items without a `value` render as group headings** (not selectable, skipped by keyboard navigation), supported by the components that have a group form (`Select`, `OutlineSelect`, `Dropdown`, `ButtonMenuSelectWidget`, etc.).
- Option text goes in `children`; tag inputs use `label`, see below.
- **The selected state is never declared in the options** — the component computes it from `value` and the current value, so the option data stays plain data.

```tsx preview
import { Select } from "ooui-react";

function App() {
  return (
    <Select
      defaultValue="orange"
      aria-label="Fruit"
      options={[
        { value: "apple", children: "Apple" },
        { value: "orange", children: "Orange" },
        { value: "banana", children: "Banana", disabled: true },
        { children: "Berries" },
        { value: "grape", children: "Grape" },
        { value: "melon", children: "Melon" },
      ]}
    />
  );
}

export default App;
```

The `Berries` item above has no `value`, so it renders as a group heading.

## Options of tag inputs

The options of `TagMultiselect` / `MenuTagMultiselect` serve as both **the tag itself** and **the menu candidates**. The convention matches the previous section, plus a few dedicated fields:

```tsx
import { Icon, MenuTagMultiselect } from "ooui-react";

<MenuTagMultiselect
  options={[
    { value: "bold", label: "Bold", icon: "bold" },
    // For rich label content, prefix filtering and backfill need the plain-text form labelText
    {
      value: "code",
      label: (
        <>
          <Icon icon="code" /> Code
        </>
      ),
      labelText: "Code",
    },
    // data carries arbitrary extra data, independent of the identity value
    { value: "link", label: "Link", data: { openInNewTab: true } },
    { value: "lock", label: "Lock", fixed: true },
  ]}
/>
```

- **`label` accepts a `ReactNode`** (matching the original's rich content support), and defaults to displaying `value`. Tag options use `label` rather than `children`.
- **`labelText` is the plain-text form of `label`**, used for filtering menu candidates by typed prefix and for backfilling the input when a tag is selected or edited. When `label` is a string it defaults to the string itself; for rich content you must provide `labelText` explicitly — without it the option **does not participate in prefix filtering** (backfill falls back to `String(value)`), and a development warning is emitted once. {/* deviations: dev-tag-label-labeltext */}
- **`data` carries arbitrary extra data.** A tag's identity is always the scalar `value` (keeping the controlled array serializable and diffable), and `onChange` returns scalar values too; when you need an object to travel with a tag, put it in `data` and look it back up by `value` in your own `options` array. {/* deviations: dev-tag-value-data */}
- Tags with `fixed: true` are fixed (no close button, cannot be removed), and drag-to-reorder never moves them before the fixed block. {/* deviations: dev-tag-fixed */}

## Disabled

- An option's own `disabled` disables that single item.
- Component-level `disabled` applies differently depending on the component: **list/group forms** (`Select`, `TabSelect`, `ButtonSelect`, `RadioSelect`, `CheckboxMultiselect`) disable every option in the group as well, and the group state wins — an option cannot opt back in inside a disabled group; **popup trigger forms** (`Dropdown`, `ComboBoxInput`, `ButtonMenuSelectWidget`) disable the trigger (nothing opens, keyboard is off), while each item inside the menu is governed by its own `disabled`.

## Icons and flags

Option forms with icon slots (menu/outline/button options and group headings) support `icon`
 and `flags`
: `icon`
 takes an icon name (see [Icon](https://ooui-react.pages.dev/en/components/icon/index.md)
), and `flags`
 tint the icon (`progressive`
, `destructive`
, etc.). Plain-text options (the items of `TabSelect`
, `RadioSelect`
, `CheckboxMultiselect`
) have no icon slot and do not support these fields. 
## Keyboard and focus

- **Arrow keys** move between options: direct-select forms (`TabSelect`, `ButtonSelect`, `RadioSelect`) select on keypress; menu forms (the menus of `Dropdown` etc.) move the highlight, and Enter / Space choose.
- **Home / End / PageUp / PageDown** jump to the ends or page through: enabled by default in menu forms, available on a standalone `Select` via `handleNavigationKeys`; `listWrapsAround` controls whether navigation wraps at the ends.
- **Prefix jump**: typing characters jumps by option text prefix (1.5 s buffer); tag inputs filter candidates by prefix.
- **Focus never enters the list**: focus stays on the control (or trigger element), with the highlighted item linked via `aria-activedescendant`; the list root is not in the Tab order by default — the same listbox pattern as the original OOUI. **Exception**: the direct-select forms (`TabSelect`, `ButtonSelect`) keep their group root in the Tab order (focus rests on the whole group), and a click moves focus into the group root automatically (the original leaves focus where it was, so the arrow keys do not respond — this library follows the ARIA APG instead). {/* deviations: dev-directselect-focus */}
- Direct-select forms (`TabSelect`, `ButtonSelect`) point `aria-activedescendant` at the selected item from the first frame when an initial value is present (the original only writes the attribute on the first re-selection). {/* deviations: dev-directselect-activedescendant */}
- During input method **composition**, the confirming Enter and arrow keys for candidate selection never trigger selection, opening or submission by mistake. {/* deviations: dev-ime-guard */}

## See also

- What happens when the controlled value is not among the options: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md#when-the-controlled-value-isnt-among-the-options)
- The division of labor between `onChange` and `onChoose` (fired on every choice): [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md#callback-signatures)



---
url: https://ooui-react.pages.dev/en/guide/configuration.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Global configuration

`OOUIProvider` carries the cross-component global settings: copy, where popups mount, mobile mode, access-key display and so on. Just wrap a layer around your app; without it, components work with their defaults. For wiring up component copy and site messages, see [Messages and i18n](#messages-and-i18n).

## Usage

```jsx
import { OOUIProvider } from "ooui-react";
import zhHans from "ooui-react/locales/zh-hans";

root.render(
  <OOUIProvider messages={zhHans}>{app}</OOUIProvider>,
);
```

It also works without a wrapper: English copy, popups mounted to `document.body`, non-mobile mode, text direction resolved from the anchor element, and viewport spacing of 0.

## Options

| Option               | Description                                                              | Type                                         | Default                  |
| -------------------- | ------------------------------------------------------------------------ | -------------------------------------------- | ------------------------ |
| `messages`           | Message override map; see [Messages and i18n](#messages-and-i18n)        | `Partial<Record<MessageKey, MessageValue>>`  | English                  |
| `getPortalContainer` | The container popups mount into; takes the popup's anchor element        | `(trigger: HTMLElement) => HTMLElement`      | `document.body`          |
| `isMobile`           | Mobile-mode switch                                                       | `boolean`                                    | `false`                  |
| `dir`                | Text direction of popups                                                 | `'ltr' \| 'rtl'`                             | Resolved from the anchor |
| `viewportSpacing`    | Viewport spacing counted when a popup hugs the edge or clamps its height | `number` or a per-edge object                | 0 on each edge           |
| `getAccessKeyLabel`  | Display text for access keys                                             | `(accessKey: string) => string \| undefined` | The raw key              |

## Popup container

`getPortalContainer` decides where popups (dropdown menus, popup panels, `Popup`) mount. By default they mount to `document.body`; **popups inside a dialog** mount to that dialog's container, so they stack and are isolated along with the dialog.

Once this option is set, it always wins — including popups inside a dialog, in which case those popups are no longer isolated with the dialog and stacking is left to the container. The container should not establish a new positioning context (popups are absolutely positioned against page coordinates). 
## Mobile mode

When `isMobile`
 is on, some components switch to a mobile form: `TabSelect`
 scrolls the selected item to the center, `IndexLayout`
 / `BookletLayout`
 stop auto-focusing, and dialogs and dropdowns use the mobile layout. It defaults to `false`
; the host can wire up `matchMedia`
 and decide for itself before passing it in. 
## Text direction

By default it resolves from the anchor element's text direction, so **setting `dir="rtl"` on the page or a container is enough**; most cases need no configuration here.

You only need to set `dir` explicitly when a popup mounts outside the content area and the anchor's direction doesn't represent the popup's (for example, when the popup mounts into a container outside the site's content area).

## Viewport spacing

`viewportSpacing` is the spacing on all four sides counted when a popup hugs the edge, clamps its height or flips. When the site has a fixed header or similar floating element, use it to avoid overlap, e.g. `viewportSpacing={{ top: 48 }}`. It defaults to 0 on each edge.

## Access-key label

`getAccessKeyLabel`
 gives the display text for an access key in `title`
. Unset, it shows as `Save [s]`
; once set, it can show a site-local chord: 
```tsx preview
import { Button, OOUIProvider } from "ooui-react";

function App() {
  return (
    <OOUIProvider getAccessKeyLabel={(key) => `Alt+Shift+${key}`}>
      <Button accessKey="s" title="Save">
        Save
      </Button>
    </OOUIProvider>
  );
}

export default App;
```

## Messages and i18n

Some places — message dialogs, the file picker and so on — have copy, in English by default. Pass a language pack via `messages`
 to switch, and changes to `messages`
 take effect immediately. 
```tsx preview
import { useState } from "react";
import type { MessageKey, MessageValue } from "ooui-react";
import { Button, OOUIProvider, SelectFileInputWidget } from "ooui-react";
import ja from "ooui-react/locales/ja";
import ru from "ooui-react/locales/ru";
import zhHans from "ooui-react/locales/zh-hans";

type Locale = "zh-hans" | "en" | "ja" | "ru";

const LOCALES: Array<{
  value: Locale;
  label: string;
  messages?: Partial<Record<MessageKey, MessageValue>>;
}> = [
  { value: "zh-hans", label: "简体中文", messages: zhHans },
  { value: "en", label: "English" },
  { value: "ja", label: "日本語", messages: ja },
  { value: "ru", label: "Русский", messages: ru },
];

function App() {
  const [locale, setLocale] = useState<Locale>("en");
  const pack = LOCALES.find((item) => item.value === locale);

  return (
    <OOUIProvider messages={pack?.messages}>
      <div style={{ display: "grid", gap: 16, justifyItems: "start" }}>
        <div style={{ display: "flex", gap: 8 }}>
          {LOCALES.map((item) => (
            <Button
              key={item.value}
              active={item.value === locale}
              onClick={() => setLocale(item.value)}
            >
              {item.label}
            </Button>
          ))}
        </div>
        <SelectFileInputWidget />
      </div>
    </OOUIProvider>
  );
}

export default App;
```

### Supported languages

Language packs follow the languages of the original OOUI `dist/i18n`: 222 in total, imported by MediaWiki language code (`ooui-react/locales/<code>`); language packs are loaded on demand and don't affect each other's bundle size. `en` is the built-in default baseline, always part of the main bundle, and doesn't need importing; any key missing from a pack falls back to its English default, key by key.

Languages without an upstream translation for the messages this library uses (`crh-cyrl` / `crh-latn` / `vo`) and the translation-documentation pseudo-language `qqq` are not included. The full set of codes is in the installed package under `ooui-react/dist/locales/`.

For right-to-left languages such as Arabic, Hebrew and Persian, the page or container text direction is covered in [Text direction](#text-direction).

### Overriding individual messages

`messages` is merged key by key, so pass only the keys you want to change and the rest keep their original copy:

```jsx
<OOUIProvider messages={{ "ooui-dialog-message-accept": "Got it" }}>
```

Key names follow OOUI's message names; the full list is in the built-in language pack (`ooui-react/locales/en` in the npm package). With nested `OOUIProvider`s the inner one wins, so you can mount a language pack on the outer layer and override just a few messages on the inner one.

### Using it on a MediaWiki site

MediaWiki ships OOUI's own messages under the same key names as this library, so you don't need a language pack — just wire up the site's `mw.msg` to follow the site language. Write values as functions so they resolve only when read:

```jsx
<OOUIProvider
  messages={{
    "ooui-dialog-message-accept": () => mw.msg("ooui-dialog-message-accept"),
    "ooui-dialog-message-reject": () => mw.msg("ooui-dialog-message-reject"),
  }}
>
```

Only the keys you provide go through site messages; the rest fall back to English, so wire up just the copy actually used in the UI. Imperative dialogs (`confirm` / `alert` / `prompt`) are rendered by `OOUIProvider`'s host and inherit this same mapping — no separate registration needed.

## Imperative dialogs

`confirm` / `alert` / `prompt` are standalone functions — import them and `await` from any event handler, with no hook or extra mounting:

```tsx
const ok = await confirm("Delete this?", { title: "Delete" });
```

As long as the call sits under an `OOUIProvider`
, the dialog **inherits its config automatically**
 (copy, `isMobile`
, `dir`
, and your own Providers), with no manual injection; with nested Providers it uses the outermost one. 
Without an `OOUIProvider` it renders with English defaults; to change copy in that case use the module-level `registerMessages`:

```js
import { registerMessages } from "ooui-react";

registerMessages({ "ooui-dialog-message-accept": "OK" });
```

For return values, options and runtime semantics, see [Imperative dialogs](https://ooui-react.pages.dev/en/components/imperative-dialogs/index.md).

## Reading the config

The effective config can be read outside components too:

| Hook                                            | Returns                                                                                 |
| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
| `useOOUIConfig`                                 | The full merged config object                                                           |
| `useMessage(key, ...params)`                    | The current text of one message (`OOUIProvider` > `registerMessages` > English default) |
| `useIsMobile` / `useDir` / `useViewportSpacing` | The effective value of the matching option                                              |
| `useAccessKeyLabel(accessKey)`                  | The display text for an access key                                                      |

## Nesting

Inner overrides outer, and `messages` is merged key by key: mount a language pack on the outer layer and override just a few messages on the inner one.

## FAQ

**The imperative dialog's copy didn't change?** Make sure the `confirm` / `alert` / `prompt` call sits under an `OOUIProvider` — the dialog is rendered by that Provider's host and inherits its `messages`. Only when there's no `OOUIProvider` at all do you need `registerMessages` — see [Imperative dialogs](#imperative-dialogs).

**The whole tree re-renders after switching language?** Pass a stable reference for `messages` (such as a module-level constant imported from `ooui-react/locales/*`); an inline object literal creates a new object on every render.



---
url: https://ooui-react.pages.dev/en/components/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Component overview

This library reimplements OOUI in React. Components follow the original class hierarchy and fall into four families — **widgets, layouts, dialogs and toolbars** — 60 in total.

Components **ship no styles**: they only output DOM and `oo-ui-*` class names identical to the original. Load the OOUI stylesheets first, as described in [Usage](https://ooui-react.pages.dev/en/guide/usage.md); the props shared by every component are covered in [Common props](https://ooui-react.pages.dev/en/guide/basics.md).

## Widgets


- [Button](https://ooui-react.pages.dev/en/components/button/index.md) icons, indicators, labels and link forms
- [ToggleButton](https://ooui-react.pages.dev/en/components/toggle-button/index.md) a button that toggles between pressed and unpressed
- [ToggleSwitch](https://ooui-react.pages.dev/en/components/toggle-switch/index.md) switch
- [ButtonGroup](https://ooui-react.pages.dev/en/components/button-group/index.md) groups several buttons; can be disabled as a whole
- [PopupButton](https://ooui-react.pages.dev/en/components/popup-button/index.md) a button that opens a popup on click
- [Popup](https://ooui-react.pages.dev/en/components/popup/index.md) the popup layer itself
- [Label](https://ooui-react.pages.dev/en/components/label/index.md) standalone text label
- [Icon](https://ooui-react.pages.dev/en/components/icon/index.md) icon
- [Indicator](https://ooui-react.pages.dev/en/components/indicator/index.md) indicator (an "expand" or "required"-style marker)
- [ProgressBar](https://ooui-react.pages.dev/en/components/progress-bar/index.md) progress bar
- [Message](https://ooui-react.pages.dev/en/components/message/index.md) inline message notice (with a close button)

### Input


- [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md) single-line text input
- [MultilineTextInput](https://ooui-react.pages.dev/en/components/multiline-text-input/index.md) multi-line text input
- [NumberInput](https://ooui-react.pages.dev/en/components/number-input/index.md) number input (with step buttons)
- [SearchInput](https://ooui-react.pages.dev/en/components/search-input/index.md) search input (with a clear indicator)
- [SearchWidget](https://ooui-react.pages.dev/en/components/search-widget/index.md) a search input with a persistent results list
- [ComboBoxInput](https://ooui-react.pages.dev/en/components/combo-box-input/index.md) combo box — type to filter or pick from a dropdown
- [CheckboxInput](https://ooui-react.pages.dev/en/components/checkbox-input/index.md) a single checkbox
- [RadioInput](https://ooui-react.pages.dev/en/components/radio-input/index.md) a single radio button
- [SelectFileInputWidget](https://ooui-react.pages.dev/en/components/select-file-input-widget/index.md) file picker (including a drop-zone form)

### Selection

For the option data convention (`value`, group headings, and the tag inputs' `label`/`labelText`/`data`), see [Selection and options](https://ooui-react.pages.dev/en/guide/options.md).


- [Select](https://ooui-react.pages.dev/en/components/select/index.md) select list (the inner layer of a dropdown or menu)
- [Dropdown](https://ooui-react.pages.dev/en/components/dropdown/index.md) dropdown select
- [OutlineSelect](https://ooui-react.pages.dev/en/components/outline-select/index.md) select list with hierarchical indentation
- [TabSelect](https://ooui-react.pages.dev/en/components/tab-select/index.md) tab-style select
- [ButtonSelect](https://ooui-react.pages.dev/en/components/button-select/index.md) button-style select
- [ButtonMenuSelectWidget](https://ooui-react.pages.dev/en/components/button-menu-select/index.md) command menu triggered by a button
- [CheckboxMultiselect](https://ooui-react.pages.dev/en/components/checkbox-multiselect/index.md) checkbox group
- [RadioSelect](https://ooui-react.pages.dev/en/components/radio-select/index.md) radio group
- [TagMultiselect](https://ooui-react.pages.dev/en/components/tag-multiselect/index.md) tag input (free entry)
- [MenuTagMultiselect](https://ooui-react.pages.dev/en/components/menu-tag-multiselect/index.md) tag input (with a candidate menu)

### Form submission

A set of field widgets that submit natively with a `<form>`, used together with `FormLayout`.


- [ButtonInput](https://ooui-react.pages.dev/en/components/button-input/index.md) submit button
- [DropdownInput](https://ooui-react.pages.dev/en/components/dropdown-input/index.md) dropdown select field
- [CheckboxMultiselectInput](https://ooui-react.pages.dev/en/components/checkbox-multiselect-input/index.md) checkbox group field
- [RadioSelectInput](https://ooui-react.pages.dev/en/components/radio-select-input/index.md) radio group field
- [HiddenInputWidget](https://ooui-react.pages.dev/en/components/hidden-input-widget/index.md) a field submitted with the form but never shown

## Layouts


- [Layout](https://ooui-react.pages.dev/en/components/layout/index.md) layout base class
- [PanelLayout](https://ooui-react.pages.dev/en/components/panel-layout/index.md) panel with padding
- [PageLayout](https://ooui-react.pages.dev/en/components/page-layout/index.md) overall page layout
- [StackLayout](https://ooui-react.pages.dev/en/components/stack-layout/index.md) stacks panels, showing one at a time
- [BookletLayout](https://ooui-react.pages.dev/en/components/booklet-layout/index.md) multiple panels with tabs (booklet-style)
- [IndexLayout](https://ooui-react.pages.dev/en/components/index-layout/index.md) multiple panels with an index area and search
- [TabPanelLayout](https://ooui-react.pages.dev/en/components/tab-panel-layout/index.md) a single tab panel
- [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md) field wrapper with a label and help text
- [FieldsetLayout](https://ooui-react.pages.dev/en/components/fieldset-layout/index.md) field grouping (can be disabled as a whole)
- [ActionFieldLayout](https://ooui-react.pages.dev/en/components/action-field-layout/index.md) a field with an accompanying inline action button
- [FormLayout](https://ooui-react.pages.dev/en/components/form-layout/index.md) form container
- [HorizontalLayout](https://ooui-react.pages.dev/en/components/horizontal-layout/index.md) arranges several items horizontally
- [MenuLayout](https://ooui-react.pages.dev/en/components/menu-layout/index.md) overall menu layout
- [CopyTextLayout](https://ooui-react.pages.dev/en/components/copy-text-layout/index.md) read-only text field with a copy button

## Dialogs


- [Dialog](https://ooui-react.pages.dev/en/components/dialog/index.md) dialog base class (controlled `open`)
- [MessageDialog](https://ooui-react.pages.dev/en/components/dialog/index.md) message dialog (OK / Cancel)
- [ProcessDialog](https://ooui-react.pages.dev/en/components/process-dialog/index.md) dialog with a multi-step flow and an error panel
- [`confirm` / `alert` / `prompt`](https://ooui-react.pages.dev/en/components/imperative-dialogs/index.md) imperative dialogs (no React tree needed)

## Toolbars


- [Toolbar](https://ooui-react.pages.dev/en/components/toolbar/index.md) toolbar container
- [BarToolGroup](https://ooui-react.pages.dev/en/components/toolbar/index.md) button-style tool group
- [ListToolGroup](https://ooui-react.pages.dev/en/components/toolbar/index.md) list-style tool group
- [MenuToolGroup](https://ooui-react.pages.dev/en/components/toolbar/index.md) menu-style tool group
- [LabelToolGroup](https://ooui-react.pages.dev/en/components/toolbar/index.md) static label group within a toolbar



---
url: https://ooui-react.pages.dev/en/components/button/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Button

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Button) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ButtonWidget.html "OO.ui.ButtonWidget")

The basic button component, and also the button base for [ToggleButton](https://ooui-react.pages.dev/en/components/toggle-button/index.md), [PopupButton](https://ooui-react.pages.dev/en/components/popup-button/index.md), [ButtonMenuSelectWidget](https://ooui-react.pages.dev/en/components/button-menu-select/index.md) and other components.

## Basic usage

```tsx preview
import { useState } from "react";
import { Button } from "ooui-react";

function App() {
  const [count, setCount] = useState(0);

  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <Button onClick={() => setCount((n) => n + 1)}>Click me</Button>
      <span>Clicked {count} times</span>
    </div>
  );
}

export default App;
```

## Icons and indicators

`icon` takes an icon name (see [Icon](https://ooui-react.pages.dev/en/components/icon/index.md)), `indicator` takes one of the four indicators (see [Indicator](https://ooui-react.pages.dev/en/components/indicator/index.md)). They render on opposite ends of the label.

When the label is icon-only, turn on `invisibleLabel`: the label is visually hidden but kept as the accessible name, and `title` falls back to the label text when not given explicitly.

```tsx preview
import { Button } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <Button icon="check">Done</Button>
      <Button icon="trash" flags="destructive">
        Delete
      </Button>
      <Button indicator="down">Expand</Button>
      <Button icon="search" invisibleLabel>
        Search
      </Button>
    </div>
  );
}

export default App;
```

## Flags and variants

`flags` affect color and icon tinting, `framed={false}` switches to the unframed form, and `active` marks a selected/activated state.

```tsx preview
import { Button } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8, flexWrap: "wrap" }}>
      <Button>Default</Button>
      <Button flags="progressive">Continue</Button>
      <Button flags={["primary", "progressive"]}>Save</Button>
      <Button flags="destructive">Delete</Button>
      <Button framed={false} flags="destructive">
        Unframed delete
      </Button>
      <Button active>Active</Button>
    </div>
  );
}

export default App;
```

A framed button inverts as a whole when `primary`, active, or disabled, and the icon and indicator invert with it; otherwise it is tinted by the color flag in `flags`. The available color flags are `progressive`, `destructive`, `invert`, `error`, `warning` and `success`.

## As a link

Given `href`, the inner `<a>` becomes a navigable link and `target` chooses where it opens. `rel` defaults to `nofollow`; when using `target="_blank"` you should add `noopener` yourself.

```tsx preview
import { Button } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <Button href="https://www.mediawiki.org">MediaWiki</Button>
      <Button href="https://www.mediawiki.org" target="_blank" rel={["nofollow", "noopener"]}>
        Open in a new tab
      </Button>
    </div>
  );
}

export default App;
```

:::warning Security note
This component does not sanitize `href`
 (it bypasses the original `OO.ui.isSafeUrl`
), and React does not block dangerous schemes such as `javascript:`
 at runtime either. **Links of untrusted origin (e.g. concatenated from user input) must have their protocol validated by you first**
, otherwise this is an XSS; when you want component-level sanitizing, use the exported `sanitizeUrl`
. 
:::
## Disabled

`disabled` outputs `oo-ui-widget-disabled` and `aria-disabled` (not the native `disabled`); the button then ignores clicks, its `tabindex` becomes `-1`, and `href` no longer takes effect. Inside a `ButtonGroup`, the group-level disabled state propagates to the buttons in it.

```tsx preview
import { Button } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <Button disabled>Disabled</Button>
      <Button icon="check" disabled>
        Disabled (with icon)
      </Button>
    </div>
  );
}

export default App;
```

## Focus and keyboard

- The focusable element is the inner `<a>`; the root `<span>` is not focusable. To focus the button manually, use `anchorRef` (the component `ref` points to the outer `<span>`).
- Enter / Space trigger `onClick`; `onKeyPress` prevents Space from scrolling the page whenever a click handler is present.
- The pressed state (`oo-ui-buttonElement-pressed`) is maintained by the component in JS (including keyboard press and release). The `pressed` prop is OR-ed with it, for cases like "keep the button pressed while its associated menu is open".
- `title` and `accessKey` go on the inner `<a>`; when `title` is not given and the label is hidden it falls back to the label text, and when `accessKey` is present a key hint is appended to `title` (the chord text can be localized via [OOUIProvider](https://ooui-react.pages.dev/en/guide/configuration.md#access-key-label)).

## API

| Prop                           | Description                                                                                                                                                                                     | Type                                      | Default        |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------- |
| `children`                     | Button label                                                                                                                                                                                    | `ReactNode`                               | —              |
| `icon`                         | Leading icon name                                                                                                                                                                               | `string`                                  | —              |
| `indicator`                    | Trailing indicator                                                                                                                                                                              | `'up' \| 'down' \| 'clear' \| 'required'` | —              |
| `flags`                        | Extra flags (color and button-specific form)                                                                                                                                                    | `ButtonFlag \| ButtonFlag[]`              | `[]`           |
| `framed`                       | Whether it has a border                                                                                                                                                                         | `boolean`                                 | `true`         |
| `active`                       | Whether it is in the active state                                                                                                                                                               | `boolean`                                 | `false`        |
| `invisibleLabel`               | Label visually hidden (kept as accessible name)                                                                                                                                                 | `boolean`                                 | `false`        |
| `disabled`                     | Whether disabled (incl. the owning `ButtonGroup`'s group disable)                                                                                                                               | `boolean`                                 | `false`        |
| `href`                         | Link target (written on the inner `<a>`)                                                                                                                                                        | `string`                                  | —              |
| `target`                       | Where the link opens                                                                                                                                                                            | `string`                                  | —              |
| `rel`                          | The inner `<a>`'s `rel` (an array is joined by spaces)                                                                                                                                          | `string \| string[]`                      | `['nofollow']` |
| `title`                        | Tooltip text for the inner `<a>`                                                                                                                                                                | `string`                                  | —              |
| `accessKey`                    | Access key                                                                                                                                                                                      | `string`                                  | —              |
| `tabIndex`                     | Tab order; `null` means the attribute is omitted                                                                                                                                                | `number \| null`                          | `0`            |
| `pressed`                      | Controlled pressed state (OR-ed with the internal press flow)                                                                                                                                   | `boolean`                                 | —              |
| `onClick`                      | Click handler (also fired by Enter / Space)                                                                                                                                                     | `(ev: ButtonClickEvent) => void`          | —              |
| `anchorRef`                    | Ref to the inner `<a>` element                                                                                                                                                                  | `Ref<HTMLAnchorElement>`                  | —              |
| `anchorProps`                  | Extra props for the inner `<a>`; `role`, `tabIndex`, `aria-disabled`, etc. are taken over by the component and take priority                                                                    | `HTMLAttributes<HTMLAnchorElement>`       | —              |
| `iconProps` / `indicatorProps` | Extra props for the icon / indicator element                                                                                                                                                    | `object`                                  | —              |
| `...rest`                      | Native `span` props (`className`, `id`, `data-*`, etc.) passed straight to the root; `aria-label` / `aria-labelledby` / `aria-pressed` are the exception — they go on the inner focusable `<a>` | `HTMLAttributes<HTMLSpanElement>`         | —              |

`ButtonFlag` is `'progressive' | 'destructive' | 'invert' | 'error' | 'warning' | 'success' | 'primary' | 'safe' | 'back' | 'close'`; the first six decide tinting, the last four are button-specific form flags.



---
url: https://ooui-react.pages.dev/en/components/toggle-button/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# ToggleButton

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ToggleButton) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ToggleButtonWidget.html "OO.ui.ToggleButtonWidget")

A toggle button: a [Button](https://ooui-react.pages.dev/en/components/button/index.md) that can be "pressed / unpressed".

## Basic usage

The on/off state uses the `checked` / `defaultChecked` / `onChange` channels, and `onChange`'s first argument is the new boolean state. A pressed button shows the active (highlighted) look.

```tsx preview
import { useState } from "react";
import { ToggleButton } from "ooui-react";

function App() {
  const [highlight, setHighlight] = useState(false);

  return (
    <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
      <ToggleButton icon="highlight" checked={highlight} onChange={setHighlight}>
        Highlight
      </ToggleButton>
      <ToggleButton icon="star" defaultChecked>
        Favorite (uncontrolled, pressed initially)
      </ToggleButton>
      <span>Highlight: {String(highlight)}</span>
    </div>
  );
}

export default App;
```

## Unframed form

Like Button it supports `framed={false}` and the various `flags`, commonly used for grouped toggles in a toolbar.

```tsx preview
import { ToggleButton } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <ToggleButton icon="bold" defaultChecked>
        Bold
      </ToggleButton>
      <ToggleButton icon="italic">
        Italic
      </ToggleButton>
      <ToggleButton framed={false} icon="link" defaultChecked>
        Unframed
      </ToggleButton>
    </div>
  );
}

export default App;
```

## How it differs from Button

ToggleButton borrows Button's appearance but has **no link capability**: `href` / `target` / `rel` / `anchorRef` are not accepted, and `active`, `onClick` and `aria-pressed` are driven by the toggle state and not exposed. Use [Button](https://ooui-react.pages.dev/en/components/button/index.md) to "run an action once on click", and this component to "express a persistent on/off state".

## API

| Prop             | Description                                                              | Type                                      | Default |
| ---------------- | ------------------------------------------------------------------------ | ----------------------------------------- | ------- |
| `children`       | Button label                                                             | `ReactNode`                               | —       |
| `checked`        | Whether pressed (controlled; passing it enables controlled mode)         | `boolean`                                 | —       |
| `defaultChecked` | Initial toggle state for uncontrolled use                                | `boolean`                                 | `false` |
| `onChange`       | Toggle-state change callback (returns only the new state)                | `(checked: boolean) => void`              | —       |
| `icon`           | Leading icon name                                                        | `string`                                  | —       |
| `indicator`      | Trailing indicator                                                       | `'up' \| 'down' \| 'clear' \| 'required'` | —       |
| `flags`          | Extra flags (color and button-specific form)                             | `ButtonFlag \| ButtonFlag[]`              | `[]`    |
| `framed`         | Whether it has a border                                                  | `boolean`                                 | `true`  |
| `invisibleLabel` | Label visually hidden (kept as accessible name)                          | `boolean`                                 | `false` |
| `disabled`       | Whether disabled (incl. the owning `ButtonGroup`'s group disable)        | `boolean`                                 | `false` |
| `tabIndex`       | Tab order                                                                | `number \| null`                          | `0`     |
| `...rest`        | Button's remaining non-link props, passed straight to the button element | `object`                                  | —       |

`onChange` is a toggle callback and does not follow the value-first `ChangeHandler` signature (see [Controlled and uncontrolled · Callback signatures](https://ooui-react.pages.dev/en/guide/controlled.md#callback-signatures)).

## See also

- Button's base capabilities and icon / indicator: [Button](https://ooui-react.pages.dev/en/components/button/index.md)
- The switch form: [ToggleSwitch](https://ooui-react.pages.dev/en/components/toggle-switch/index.md)
- Arranging buttons into a group: [ButtonGroup](https://ooui-react.pages.dev/en/components/button-group/index.md)



---
url: https://ooui-react.pages.dev/en/components/toggle-switch/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# ToggleSwitch

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ToggleSwitch) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ToggleSwitchWidget.html "OO.ui.ToggleSwitchWidget")

A toggle switch. It has no text label of its own — when you need one, wrap it with [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md).

## Basic usage

The on/off state uses the `checked` / `defaultChecked` / `onChange` channels, and `onChange`'s first argument is the new boolean state.

```tsx preview
import { useState } from "react";
import { ToggleSwitch } from "ooui-react";

function App() {
  const [on, setOn] = useState(true);

  return (
    <div style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 12 }}>
      <ToggleSwitch checked={on} onChange={setOn} />
      <div>Current state: {on ? "on" : "off"}</div>
      <ToggleSwitch defaultChecked />
    </div>
  );
}

export default App;
```

## With FieldLayout

Give the field its text label through [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md). Clicking the label **flips the switch directly** and focuses it (unlike most fields where clicking the label only focuses the control — this is `ToggleSwitchWidget`'s overridden behavior in the original).

```tsx preview
import { ToggleSwitch, FieldLayout } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 280 }}>
      <FieldLayout label="Email notifications" align="inline">
        <ToggleSwitch defaultChecked />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## Interaction

- Click (left button only) toggles; after focusing with `Tab`, use **Space / Enter** to toggle.
- The confirming Enter during input method **composition** does not toggle the switch.
- `disabled` outputs `aria-disabled` (not the native `disabled`); the switch then can't be clicked or focused, and clicking the label won't flip it either.

## API

| Prop             | Description                                                                        | Type                             | Default |
| ---------------- | ---------------------------------------------------------------------------------- | -------------------------------- | ------- |
| `checked`        | Whether on (controlled; passing it enables controlled mode)                        | `boolean`                        | —       |
| `defaultChecked` | Initial toggle state for uncontrolled use                                          | `boolean`                        | `false` |
| `onChange`       | Toggle-state change callback (returns only the new state)                          | `(checked: boolean) => void`     | —       |
| `disabled`       | Whether disabled                                                                   | `boolean`                        | `false` |
| `tabIndex`       | Tab order                                                                          | `number \| null`                 | `0`     |
| `...rest`        | Native `div` props (`className`, `id`, `aria-*`, etc.) passed straight to the root | `HTMLAttributes<HTMLDivElement>` | —       |

There is no `children`, `label` or `icon` slot — the switch is a purely graphical control, and any text goes through [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md). `onClick` / `onKeyDown` are used internally for toggling and cannot be overridden.

## See also

- The button-form toggle: [ToggleButton](https://ooui-react.pages.dev/en/components/toggle-button/index.md)
- Laying out a labeled field: [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md)
- The controlled-value convention: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md)



---
url: https://ooui-react.pages.dev/en/components/button-group/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# ButtonGroup

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ButtonGroup) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ButtonGroupWidget.html "OO.ui.ButtonGroupWidget")

A button group: it lines up several [Button](https://ooui-react.pages.dev/en/components/button/index.md) elements so adjacent ones connect head-to-tail into a single block.

## Basic usage

```tsx preview
import { Button, ButtonGroup } from "ooui-react";

function App() {
  return (
    <ButtonGroup>
      <Button icon="bold">Bold</Button>
      <Button icon="italic">Italic</Button>
      <Button icon="link">Link</Button>
    </ButtonGroup>
  );
}

export default App;
```

## Mixing in toggle buttons

A group can hold both plain buttons and [ToggleButton](https://ooui-react.pages.dev/en/components/toggle-button/index.md) elements, common in editor toolbars.

```tsx preview
import { Button, ButtonGroup, ToggleButton } from "ooui-react";

function App() {
  return (
    <ButtonGroup>
      <ToggleButton icon="bold">Bold</ToggleButton>
      <ToggleButton icon="italic">Italic</ToggleButton>
      <Button icon="highlight" flags="destructive">
        Clear formatting
      </Button>
    </ButtonGroup>
  );
}

export default App;
```

## Group-level disable

Setting `disabled` on the group **propagates it to every button inside**, so you don't have to set each one.

```tsx preview
import { Button, ButtonGroup } from "ooui-react";

function App() {
  return (
    <ButtonGroup disabled>
      <Button>Copy</Button>
      <Button>Cut</Button>
      <Button>Paste</Button>
    </ButtonGroup>
  );
}

export default App;
```

:::note Difference from the original
The original has no group-level disabled propagation — each child button would have to be disabled one by one; this library passes the group's `disabled`
 down through a React context. A button's effective `disabled`
 is the OR of its own state and its group's. 
:::
## API

| Prop       | Description                                                                                                                                                                           | Type                             | Default |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------- |
| `children` | Buttons in the group ([Button](https://ooui-react.pages.dev/en/components/button/index.md) / [ToggleButton](https://ooui-react.pages.dev/en/components/toggle-button/index.md), etc.) | `ReactNode`                      | —       |
| `disabled` | Group-level disable, propagated to the buttons inside                                                                                                                                 | `boolean`                        | `false` |
| `...rest`  | Native `div` props (`className`, `id`, `data-*`, etc.) passed straight to the root                                                                                                    | `HTMLAttributes<HTMLDivElement>` | —       |

## See also

- Buttons within the group: [Button](https://ooui-react.pages.dev/en/components/button/index.md), [ToggleButton](https://ooui-react.pages.dev/en/components/toggle-button/index.md)
- Common pass-through and `ref` rules: [Common props](https://ooui-react.pages.dev/en/guide/basics.md)



---
url: https://ooui-react.pages.dev/en/components/popup/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Popup

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Popup) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.PopupWidget.html "OO.ui.PopupWidget")

A floating panel anchored to an element, with automatic positioning and flipping — suited to on-demand content such as annotations and tooltips; for button-triggered cases use [PopupButton](https://ooui-react.pages.dev/en/components/popup-button/index.md) directly.

## Basic usage

A Popup never opens itself — visibility is driven by `open`: use a button as the `container` anchor and toggle `open` on click. `autoClose` closes on clicks outside the popup and trigger (or Escape), and `autoCloseIgnore` excludes the trigger from the "outside click" test.

```tsx preview
import { useRef, useState } from "react";
import { Button, Popup } from "ooui-react";

function App() {
  const anchorRef = useRef<HTMLSpanElement>(null);
  const [open, setOpen] = useState(false);

  return (
    <div style={{ padding: 60 }}>
      <Button ref={anchorRef} indicator="down" onClick={() => setOpen((o) => !o)}>
        Open popup
      </Button>
      <Popup
        open={open}
        onOpenChange={setOpen}
        container={anchorRef}
        autoClose
        autoCloseIgnore={anchorRef}
        padded
        width={220}
        position="below"
      >
        Popup content goes here. Clicking blank space, pressing Escape, or tabbing out all close it.
      </Popup>
    </div>
  );
}

export default App;
```

## Positioning and flipping

- `position` is `below` (default), `above`, `before` (left) or `after` (right).
- `align` controls alignment on the anchor: `center` (default), `forwards` / `backwards` (logical, switch physical side with writing direction / RTL), or `force-left` / `force-right` (always the physical side, never flipping).
- `autoFlip` (on by default) flips to the opposite side when there's no room; `anchor` (on by default) draws the arrow pointing at the anchor.
- When space is tight the popup is clipped/clamped to the visible area (or nearest scroll container); `containerPadding` sets the clamp inset (default 10px), and `hideWhenOutOfView` (on by default) hides the popup while the anchor scrolls out of view (without changing `open`).

:::note Differences from OOUI
The flip direction is re-evaluated when scrolling changes the clipping (the original keeps it fixed until the popup is reopened), so the popup may jump while scrolling. 
:::
The most common tweaks: `position` for the popup direction, and `anchor={false}` to drop the arrow.

```tsx preview
import { useRef, useState, type ReactNode } from "react";
import { Button, Popup } from "ooui-react";

function TriggerPopup({
  children,
  buttonLabel,
  position = "below",
  anchor = true,
}: {
  children: ReactNode;
  buttonLabel: string;
  position?: "above" | "below" | "before" | "after";
  anchor?: boolean;
}) {
  const anchorRef = useRef<HTMLSpanElement>(null);
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button ref={anchorRef} onClick={() => setOpen((o) => !o)}>
        {buttonLabel}
      </Button>
      <Popup
        open={open}
        onOpenChange={setOpen}
        container={anchorRef}
        autoClose
        autoCloseIgnore={anchorRef}
        padded
        width={200}
        position={position}
        anchor={anchor}
      >
        {children}
      </Popup>
    </>
  );
}

function App() {
  return (
    <div style={{ display: "flex", gap: 32, flexWrap: "wrap", padding: "72px 8px 8px" }}>
      <TriggerPopup buttonLabel="Open above" position="above">
        position="above"
      </TriggerPopup>
      <TriggerPopup buttonLabel="Open right" position="after">
        position="after"
      </TriggerPopup>
      <TriggerPopup buttonLabel="No arrow" anchor={false}>
        anchor={false}
      </TriggerPopup>
    </div>
  );
}

export default App;
```

## Head and footer

`head` enables a header with `icon` + `label` + a top-right close button (`hideCloseButton` hides it); `footer` is the bottom area. The close button, outside clicks and Escape all report intent through `onOpenChange(false)`.

```tsx preview
import { useRef, useState } from "react";
import { Button, Popup } from "ooui-react";

function App() {
  const anchorRef = useRef<HTMLSpanElement>(null);
  const [open, setOpen] = useState(false);

  return (
    <div style={{ padding: 60 }}>
      <Button ref={anchorRef} indicator="down" onClick={() => setOpen((o) => !o)}>
        With header
      </Button>
      <Popup
        open={open}
        onOpenChange={setOpen}
        container={anchorRef}
        autoClose
        autoCloseIgnore={anchorRef}
        head
        icon="info"
        label="Hint"
        padded
        width={240}
        footer={<div style={{ padding: 8 }}>Footer note text</div>}
      >
        A header with icon, title and close button; custom content in the footer.
      </Popup>
    </div>
  );
}

export default App;
```

## Hover trigger

Hover tips (term explanations, hover cards) are a common Popup scenario: open/close is driven entirely by the anchor's `mouseenter` / `mouseleave`, with `autoClose={false}` turning off the outside-click and Escape channels. Implementation points: the popup is portalled out of the anchor's subtree, so moving the mouse toward it fires the anchor's `mouseleave` first — delay the close briefly and cancel it once the pointer enters the popup; and wrap the popup content in an element with its own mouse handlers so hovering the popup keeps it open.

```tsx preview
import { useRef, useState } from "react";
import { Popup } from "ooui-react";

function App() {
  const anchorRef = useRef<HTMLSpanElement>(null);
  const hideTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
  const [open, setOpen] = useState(false);

  const show = () => {
    if (hideTimer.current) clearTimeout(hideTimer.current);
    setOpen(true);
  };
  const hideLater = () => {
    hideTimer.current = setTimeout(() => setOpen(false), 150);
  };

  return (
    <p style={{ padding: "56px 8px 8px" }}>
      ooui-react is a React{" "}
      <span
        ref={anchorRef}
        onMouseEnter={show}
        onMouseLeave={hideLater}
        style={{ textDecoration: "underline dotted", cursor: "help" }}
      >
        reimplementation
        <Popup
          open={open}
          onOpenChange={setOpen}
          container={anchorRef}
          position="above"
          autoClose={false}
          padded
          width={250}
        >
          <div onMouseEnter={show} onMouseLeave={hideLater}>
            A React reimplementation of OOUI (oojs-ui); it stays open while you hover the term or the popup itself.
          </div>
        </Popup>
      </span>
      {" "}
      of OOUI, reusing the original theme styles directly.
    </p>
  );
}

export default App;
```

## API

| Prop                                | Description                                                                       | Type                                                                     | Default    |
| ----------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------- |
| `open`                              | Whether open (controlled; Popup never opens itself)                               | `boolean`                                                                | —          |
| `defaultOpen`                       | Initial open state for uncontrolled use                                           | `boolean`                                                                | `false`    |
| `onOpenChange`                      | Open-state change callback (close button / outside click / Escape / tab-out)      | `(open: boolean) => void`                                                | —          |
| `container`                         | Anchor container (`ref` or element); defaults to the body's top-left when omitted | `RefObject<HTMLElement \| null> \| HTMLElement \| null`                  | —          |
| `position`                          | Popup direction                                                                   | `'above' \| 'below' \| 'before' \| 'after'`                              | `'below'`  |
| `align`                             | Alignment (logical values flip with RTL; `force-*` stay physical)                 | `'center' \| 'forwards' \| 'backwards' \| 'force-left' \| 'force-right'` | `'center'` |
| `anchor`                            | Whether to draw the arrow pointing at the anchor                                  | `boolean`                                                                | `true`     |
| `autoClose`                         | Auto-close on outside click / Escape                                              | `boolean`                                                                | —          |
| `autoCloseIgnore`                   | Elements ignored by the auto-close test (e.g. the trigger)                        | `RefObject<HTMLElement \| null> \| HTMLElement \| null`                  | —          |
| `autoFlip`                          | Flip to the opposite side when it doesn't fit                                     | `boolean`                                                                | `true`     |
| `hideWhenOutOfView`                 | Temporarily hide while the anchor is scrolled out of view                         | `boolean`                                                                | `true`     |
| `containerPadding`                  | Clamp inset (px)                                                                  | `number`                                                                 | `10`       |
| `head`                              | Render a head (icon + label + close button)                                       | `boolean`                                                                | `false`    |
| `hideCloseButton`                   | Hide the close button alongside `head`                                            | `boolean`                                                                | —          |
| `padded`                            | Whether the content has padding                                                   | `boolean`                                                                | `false`    |
| `icon` / `label` / `invisibleLabel` | Head icon / title / visually-hidden title                                         | —                                                                        | —          |
| `width` / `height`                  | Popup size (px)                                                                   | `number \| string`                                                       | `320` / —  |
| `footer`                            | Bottom-area content                                                               | `ReactNode`                                                              | —          |
| `disabled`                          | Whether disabled                                                                  | `boolean`                                                                | `false`    |
| `...rest`                           | Native `div` props (`className`, `id`, `data-*`, etc.) on the popup root          | `HTMLAttributes<HTMLDivElement>`                                         | —          |

## See also

- The lower-effort trigger: [PopupButton](https://ooui-react.pages.dev/en/components/popup-button/index.md)
- Dropdown select (a floating menu inside): [Dropdown](https://ooui-react.pages.dev/en/components/dropdown/index.md)
- Global config (popup portal container, viewport spacing, direction): [OOUIProvider](https://ooui-react.pages.dev/en/guide/configuration.md)



---
url: https://ooui-react.pages.dev/en/components/popup-button/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# PopupButton

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/PopupButton) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.PopupButtonWidget.html "OO.ui.PopupButtonWidget")

A popup button: clicking the [Button](https://ooui-react.pages.dev/en/components/button/index.md) toggles a [Popup](https://ooui-react.pages.dev/en/components/popup/index.md) anchored to it, with built-in close on clicking outside the button and popup. For most "click a button, show a floating panel" cases use this instead of setting up Popup's anchoring and open state by hand.

## Basic usage

```tsx preview
import { PopupButton } from "ooui-react";

function App() {
  return (
    <div style={{ padding: 40 }}>
      <PopupButton
        icon="language"
        defaultOpen
        popupContent={
          <div style={{ padding: 12 }}>Put anything in the popup, e.g. a note or a group of controls.</div>
        }
      >
        Options
      </PopupButton>
    </div>
  );
}

export default App;
```

## Controlled open state

To drive visibility from outside, use `open` / `onOpenChange`; the button, outside clicks, the close button and Escape all call `onOpenChange`.

```tsx preview
import { useState } from "react";
import { PopupButton } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <div style={{ display: "flex", alignItems: "center", gap: 12, padding: 40 }}>
      <PopupButton
        open={open}
        onOpenChange={setOpen}
        head
        label="Color"
        padded
        popupContent={<div style={{ padding: 12 }}>A popup with a titled header and close button.</div>}
      >
        Pick color
      </PopupButton>
      <span>open is: {String(open)}</span>
    </div>
  );
}

export default App;
```

## Popup positioning

The popup props `position` / `align` / `anchor` / `autoFlip` / `width` / `height` / `padded` / `head` / `footer` / `container` are forwarded to the inner Popup (same meaning as [Popup](https://ooui-react.pages.dev/en/components/popup/index.md)). By default the button is the anchor and the popup opens below.

## API

| Prop                                                                                                                                                                          | Description                                                                                                | Type                             | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------- | ------- |
| `children`                                                                                                                                                                    | Button label                                                                                               | `ReactNode`                      | —       |
| `popupContent`                                                                                                                                                                | Popup body                                                                                                 | `ReactNode`                      | —       |
| `open`                                                                                                                                                                        | Whether the popup is open (controlled)                                                                     | `boolean`                        | —       |
| `defaultOpen`                                                                                                                                                                 | Initial open state for uncontrolled use                                                                    | `boolean`                        | `false` |
| `onOpenChange`                                                                                                                                                                | Open-state change callback (button / outside click / close button / Escape)                                | `(open: boolean) => void`        | —       |
| `onClick`                                                                                                                                                                     | Button click callback (fires before toggling open state)                                                   | `(ev: ButtonClickEvent) => void` | —       |
| `label`                                                                                                                                                                       | Popup head label, rendered with `head` (`children` is the button label; the two are separate)              | `ReactNode`                      | —       |
| `icon` / `flags` / `framed` / `title` / `accessKey` / `invisibleLabel` / `disabled`                                                                                           | Button-side props, same meaning as [Button](https://ooui-react.pages.dev/en/components/button/index.md)    | —                                | —       |
| `position` / `align` / `anchor` / `autoFlip` / `head` / `hideCloseButton` / `padded` / `width` / `height` / `footer` / `container` / `hideWhenOutOfView` / `containerPadding` | Popup-side props forwarded to the inner [Popup](https://ooui-react.pages.dev/en/components/popup/index.md) | —                                | —       |

Besides the button border, `framed` also switches the popup's framed / frameless appearance. `label` is passed to the popup head and `invisibleLabel` applies to the button side only — in the original `PopupButtonWidget` both belong to the button, with the popup configured independently. `active`, `autoClose` and `autoCloseIgnore` are managed internally and cannot be overridden.

## See also

- The underlying floating layer: [Popup](https://ooui-react.pages.dev/en/components/popup/index.md)
- A button that opens a command menu: `ButtonMenuSelectWidget`
- Common pass-through and `ref` rules: [Common props](https://ooui-react.pages.dev/en/guide/basics.md)



---
url: https://ooui-react.pages.dev/en/components/icon/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Icon

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Icon) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.IconWidget.html "OO.ui.IconWidget")

The basic icon component.

## Basic usage

```tsx preview
import { Icon } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Icon icon="image" title="image" />
      <Icon icon="alert" title="alert" />
      <Icon icon="add" title="add" />
      <Icon icon="arrowDown" title="arrowDown" />
    </div>
  );
}

export default App;
```

Icon names come from the OOUI theme's icon set; the full list and grouping are in ["All icons"](#all-icons) at the end of the page, and the upstream reference is the [icons page of the OOUI demos](https://doc.wikimedia.org/oojs-ui/master/demos/?page=icons).

## Variants

`flags` hit the theme's image-variant classes (`oo-ui-image-{flag}`) to tint the icon. `invert` targets dark backgrounds and requires you to supply a dark backdrop.

```tsx preview
import { Icon } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Icon icon="alert" flags="progressive" title="progressive" />
      <Icon icon="alert" flags="destructive" title="destructive" />
      <span style={{ display: "inline-block", background: "#222", padding: "4px 8px" }}>
        <Icon icon="alert" flags="invert" title="invert" />
      </span>
      <Icon icon="alert" flags="error" title="error" />
      <Icon icon="alert" flags="warning" title="warning" />
      <Icon icon="alert" flags="success" title="success" />
    </div>
  );
}

export default App;
```

## Disabled state

`disabled` outputs `oo-ui-widget-disabled` and `aria-disabled`, and emits the `oo-ui-widget` class chain per the original `Widget`.

```tsx preview
import { Icon } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Icon icon="image" title="Normal" />
      <Icon icon="image" disabled title="Disabled" />
    </div>
  );
}

export default App;
```

## API

| Prop       | Description                                                                                    | Type                              | Default |
| ---------- | ---------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
| `icon`     | Icon name, taken from the theme icon set                                                       | `string`                          | —       |
| `flags`    | Extra flags, output via `oo-ui-flaggedElement-{flag}` and `oo-ui-image-{flag}`                 | `IconFlag \| IconFlag[]`          | `[]`    |
| `disabled` | Whether disabled                                                                               | `boolean`                         | `false` |
| `...rest`  | Native `span` props (`className`, `title`, `aria-*`, events, etc.) passed straight to the root | `HTMLAttributes<HTMLSpanElement>` | —       |

`IconFlag` is `'progressive' | 'destructive' | 'invert' | 'error' | 'warning' | 'success'`.

## All icons

Click an icon to copy its name.


293 icons

### Icons – movement

arrowDownarrowNextarrowPreviousarrowUpcollapsedownTriangledraggabledraggableHorizontaldraggableVerticaldraggableXYdoubleChevronEnddoubleChevronStartexpandmovefirstlastnextprevioussortVerticalupTriangle

### Icons – content

articlearticlesarticleAddarticleCheckarticleDisambiguationarticleNotFoundarticleSearcharticlesSearcharticleRedirectasteriskdatabasediedownloadfolderPlaceholderhistoryinfoinfoFilledmergeqrCoderobotshareshareAndroidshareIOSspecialPagestabstagupdateuploadwindow

### Icons – alerts

alertbellbellOutlineerrorlevelNonelevelOnelevelTwolevelThreelivemessagenoticespeechBubblespeechBubbleAlertspeechBubbleAddspeechBubblessuccesstray

### Icons – interactions

addbrowsercancelcheckcheckAllclearclockcloseconfigureellipsisverticalEllipsisfeedbackfilterfunnelfunnelMatchhandheartheartOutlinehelphelpNoticehelpNoticeFilledhomekeykeyboardlightbulblightbulbOutlinelightbulbDashedlogInlogOutmagicWandnetworknetworkOffnewWindowpageSettingspowerprinterreloadrestartrotatesearchsettingssubtract

### Icons – moderation

bookmarkOutlinebookmarkblockblockOutlineunBlockflagunFlaglockunLockrestorestarhalfStarunStartrashpushPinongoingConversationsuggestedInvestigations

### Icons – editing-core

editeditLockeditUndolinkunLinklinkExternallinkSecureredoundo

### Icons – editing-styling

biggersmallersubscriptsuperscriptboldhighlightitalicstrikethroughunderlinetextLanguagetextDirLTRtextDirRTLtextStyle

### Icons – editing-functions

functionfunctionArgumentinstanceliteral

### Icons – editing-list

indentlistBulletlistNumberedoutdent

### Icons – editing-advanced

alignCenteralignLeftalignRightattachmentcalendarcodecopycutdiffshieroglyphimageLayoutBasicimageLayoutFrameimageLayoutFramelessimageLayoutThumbnaillabFlasklanguagelayoutmarkupmathematicsmathematicsDisplayBlockmathematicsDisplayDefaultmathematicsDisplayInlinenewlinenoWikiTextocroutlinepalettepastepuzzlequotessandboxsearchCaseSensitivesearchDiacriticssearchRegularExpressionsignaturespecialCharactertabletableAddColumnAftertableAddColumnBeforetableAddRowAftertableAddRowBeforetableCaptiontableMergeCellstableMoveColumnAftertableMoveColumnBeforetableMoveRowAftertableMoveRowBeforetemplateAddtranslationwikiText

### Icons – editing-citation

bookjournalnewspaperreferencereferenceExistingreferences

### Icons – media

camerachartchartBarchartLinechartPiechartScatterexitFullscreenfullScreenimageimageAddimageBrokenimageLockimageGallerymicrophonemusicalScorepausepictureInPictureplaystopsubtitlethreeDimensionalvolumeDownvolumeOffvolumeUpzoomInzoomOut

### Icons – location

globemapmapPinmapPinAddmapTrail

### Icons – user

bookmarkListuserAdduserAnonymoususerAvataruserAvatarOutlineuserBlockeduserChatuserContributionsuserGroupuserMentoruserPagesuserRightsuserTalkuserTemporaryuserTemporaryLocationwatchlist

### Icons – layout

menurecentChangestextFlowtextSummaryviewCompactviewDetails

### Icons – accessibility

appearancebrighthalfBrightnotBrighteyeeyeClosedmoonlargerTextsmallerTextuniversalDesignvisionSimulator

### Icons – wikimedia

logoCClogoCodexlogoMediaWikilogoMetaWikilogoWikibookslogoWikidatalogoWikifunctionslogoWikimedialogoWikimediaCommonslogoWikimediaDiscoverylogoWikinewslogoWikipedialogoWikiquotelogoWikisourcelogoWikispecieslogoWikiversitylogoWikivoyagelogoWiktionary


---
url: https://ooui-react.pages.dev/en/components/indicator/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Indicator

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Indicator) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.IndicatorWidget.html "OO.ui.IndicatorWidget")

An indicator component, usually rendered inside other components to convey a specific meaning.

## Basic usage

Four values: `up`, `down`, `clear` (the close cross) and `required` (the required asterisk).

```tsx preview
import { Indicator } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Indicator indicator="up" title="up" />
      <Indicator indicator="down" title="down" />
      <Indicator indicator="clear" title="clear" />
      <Indicator indicator="required" title="required" />
    </div>
  );
}

export default App;
```

## Disabled state

`disabled` outputs `oo-ui-widget-disabled` and `aria-disabled`; the theme fades the indicator.

```tsx preview
import { Indicator } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Indicator indicator="down" title="Normal" />
      <Indicator indicator="down" disabled title="Disabled" />
    </div>
  );
}

export default App;
```

## Structure

The component renders a single `<span>`; `ref` points to it and undeclared props pass through to that element. An indicator is a text-free decorative glyph — when you need a screen reader to convey its meaning, give the host element an `aria-label`.

## API

| Prop        | Description                                                                                    | Type                                      | Default |
| ----------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- | ------- |
| `indicator` | Indicator kind                                                                                 | `'up' \| 'down' \| 'clear' \| 'required'` | —       |
| `disabled`  | Whether disabled                                                                               | `boolean`                                 | `false` |
| `...rest`   | Native `span` props (`className`, `title`, `aria-*`, events, etc.) passed straight to the root | `HTMLAttributes<HTMLSpanElement>`         | —       |



---
url: https://ooui-react.pages.dev/en/components/label/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Label

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Label) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.LabelWidget.html "OO.ui.LabelWidget")

A standalone form label, for when you need to place a label on its own.

## Associating a form control

Clicking the label to focus/activate the control relies on the native `<label>`
's `htmlFor`
 association. The channel depends on the component — an `id`
 written to the wrong element fails silently: 
- **TextInput family** (including MultilineTextInput, NumberInput, ComboBoxInput, etc.): `id` is written to the root div; to reach the native input, pass it through `inputProps={{ id }}`.
- **CheckboxInput / RadioInput**: there is no `inputProps` channel — use the dedicated `inputId` prop, which is written directly to the native `<input>`.

Inside a form, [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md) handles this automatically; no manual wiring needed.

:::note Prefer FieldLayout in forms
In a form, the layout, alignment and click-to-focus linkage of "label + control" are usually handled by [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md); writing `htmlFor`/`id` by hand suits free-form composition.
:::

```tsx preview
import { CheckboxInput, Label, TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <Label htmlFor="label-demo-username">Username</Label>
      <TextInput inputProps={{ id: "label-demo-username" }} placeholder="Click the label above to focus this input" />
      <Label htmlFor="label-demo-agree">Agree to the terms</Label>
      <CheckboxInput inputId="label-demo-agree" />
    </div>
  );
}

export default App;
```

## Visual hiding and title

`invisibleLabel` hides the label content visually (clipped, not removed — screen readers still announce it). `title` falls back to the label text when not given explicitly.

```tsx preview
import { Label } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Label>Regular label</Label>
      <Label invisibleLabel>Screen-reader-only label</Label>
    </div>
  );
}

export default App;
```

## Disabled state

`disabled` outputs `oo-ui-widget-disabled` and `aria-disabled`; the theme dims the label.

```tsx preview
import { Label } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Label>Regular label</Label>
      <Label disabled>Disabled label</Label>
    </div>
  );
}

export default App;
```

## Structure

The component renders a single `<label>`; the `ref` points to it, and undeclared props (`htmlFor`, `title`, events, etc.) pass straight through to that element.

## API

| Prop             | Description                                                                                      | Type                               | Default |
| ---------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------- | ------- |
| `children`       | Label content                                                                                    | `ReactNode`                        | —       |
| `invisibleLabel` | Hide the label visually (kept as accessible name)                                                | `boolean`                          | `false` |
| `disabled`       | Whether disabled                                                                                 | `boolean`                          | `false` |
| `...rest`        | Native `label` props (`htmlFor`, `title`, `className`, events, etc.) passed straight to the root | `HTMLAttributes<HTMLLabelElement>` | —       |

## See also

- Label layout and association for form fields: [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md)
- Inline labels built into input components: the "Label" section of [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md)



---
url: https://ooui-react.pages.dev/en/components/progress-bar/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# ProgressBar

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ProgressBar) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ProgressBarWidget.html "OO.ui.ProgressBarWidget")

A progress bar.

## Determinate progress

`progress`
 takes a 0–100 number; out-of-range values are clamped to `[0, 100]`
 (the original doesn't clamp — a `NaN`
 produces an invalid width and attribute value). 
```tsx preview
import { useState } from "react";
import { Button, ProgressBar } from "ooui-react";

function App() {
  const [progress, setProgress] = useState(40);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <ProgressBar progress={progress} />
      <div style={{ display: "flex", gap: 8 }}>
        <Button onClick={() => setProgress((p) => Math.max(0, p - 10))}>-10</Button>
        <Button onClick={() => setProgress((p) => Math.min(100, p + 10))}>+10</Button>
      </div>
    </div>
  );
}

export default App;
```

## Indeterminate progress

`progress={false}` (also the default) means "in progress" with an unknown total: the fill indicates activity with a sliding animation and reports no specific value.

```tsx preview
import { ProgressBar } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 320 }}>
      <ProgressBar />
    </div>
  );
}

export default App;
```

## Advancing with an async task

A common pattern is to start at indeterminate progress and switch to a determinate value once quantifiable progress is available.

```tsx preview
import { useEffect, useState } from "react";
import { Button, ProgressBar } from "ooui-react";

function App() {
  const [state, setState] = useState<"idle" | "starting" | "running" | "done">("idle");
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    if (state !== "running") {
      return;
    }
    const timer = setInterval(() => {
      setProgress((p) => {
        if (p >= 100) {
          setState("done");
          return 100;
        }
        return p + 10;
      });
    }, 300);
    return () => clearInterval(timer);
  }, [state]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <ProgressBar
        progress={state === "starting" || state === "idle" ? false : progress}
      />
      <Button
        disabled={state === "starting" || state === "running"}
        onClick={() => {
          setProgress(0);
          setState("starting");
          setTimeout(() => setState("running"), 800);
        }}
      >
        Start task
      </Button>
    </div>
  );
}

export default App;
```

## API

| Prop       | Description                                                                                                                                             | Type                             | Default |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------- |
| `progress` | Progress percentage (0–100, clamped); `false` is indeterminate (sliding animation), and non-finite values (e.g. `NaN`) are treated as indeterminate too | `number \| false`                | `false` |
| `disabled` | Whether disabled                                                                                                                                        | `boolean`                        | `false` |
| `...rest`  | Native `div` props (`className`, `id`, `aria-label`, etc.) passed straight to the root                                                                  | `HTMLAttributes<HTMLDivElement>` | —       |

The bar is read-only and not focusable; it announces the value through `aria-valuenow` / `aria-valuemin` / `aria-valuemax`. With determinate progress `aria-valuenow` is the clamped value; with indeterminate progress it is omitted. To give the bar an accessible name, use `aria-label`.

## See also

- Common pass-through and `ref` rules: [Common props](https://ooui-react.pages.dev/en/guide/basics.md)



---
url: https://ooui-react.pages.dev/en/components/message/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Message

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Message) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MessageWidget.html "OO.ui.MessageWidget")

An inline notice, with `notice` / `error` / `warning` / `success` types.

## Basic usage

The type picks the default icon and color scheme; override it with `icon`.

```tsx preview
import { Message } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <Message>Notice: everything looks fine</Message>
      <Message type="success">Success: saved</Message>
      <Message type="warning">Warning: you are about to exceed the quota</Message>
      <Message type="error">Error: saving failed, please retry</Message>
      <Message icon="help">Custom icon (overrides the type default)</Message>
    </div>
  );
}

export default App;
```

## Inline form

`inline` renders a borderless inline notice for embedding in running text; the block form (default) has a border and padding. Inline messages never render a close button.

```tsx preview
import { Message } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <Message inline>Inline: this is an inline notice</Message>
      <Message inline type="error">
        Inline error: this is an inline error
      </Message>
    </div>
  );
}

export default App;
```

## Close button

:::warning Differences from OOUI
In the original, clicking the close button hides the message itself; here `onClose`
 only reports the click and the component holds no visibility state — **you must unmount or hide the message in the callback**
, otherwise the message cannot be dismissed. 
:::
```tsx preview
import { useState } from "react";
import { Button, Message } from "ooui-react";

function App() {
  const [visible, setVisible] = useState(true);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      {visible ? (
        <Message type="warning" showClose onClose={() => setVisible(false)}>
          Click the × to close (unmounted by onClose)
        </Message>
      ) : (
        <Button onClick={() => setVisible(true)}>Show again</Button>
      )}
    </div>
  );
}

export default App;
```

## API

| Prop             | Description                                                                                  | Type                                            | Default      |
| ---------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------ |
| `children`       | The message text                                                                             | `ReactNode`                                     | —            |
| `type`           | Message type (invalid values fall back to `notice`)                                          | `'notice' \| 'error' \| 'warning' \| 'success'` | `'notice'`   |
| `icon`           | Custom icon, overrides the type default                                                      | `string`                                        | type default |
| `inline`         | Inline display (`false` renders a bordered block message)                                    | `boolean`                                       | `false`      |
| `showClose`      | Whether to show the close button (not rendered when `inline`)                                | `boolean`                                       | `false`      |
| `onClose`        | Close-button click handler; the component never hides itself — unmount/hide the message here | `() => void`                                    | —            |
| `invisibleLabel` | Hide the text visually but keep it as the accessible name                                    | `boolean`                                       | `false`      |
| `disabled`       | Whether disabled (outputs `aria-disabled`)                                                   | `boolean`                                       | `false`      |
| `...rest`        | Native `div` props (`className`, `id`, `data-*`, etc.) passed straight to the root           | `HTMLAttributes<HTMLDivElement>`                | —            |

Accessibility: `type="error"` renders as `role="alert"` (assertive announcement); the other types use `aria-live="polite"`.

## See also

- Errors rendered inside the error panel: [ProcessDialog](https://ooui-react.pages.dev/en/components/process-dialog/index.md)
- The value-passing convention (`onClose` only reports the close request; visibility belongs to the caller): [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md)



---
url: https://ooui-react.pages.dev/en/components/text-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# TextInput

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/TextInput) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.TextInputWidget.html "OO.ui.TextInputWidget")

A single-line text input, and also the base for input components such as [MultilineTextInput](https://ooui-react.pages.dev/en/components/multiline-text-input/index.md), [NumberInput](https://ooui-react.pages.dev/en/components/number-input/index.md) and [SearchInput](https://ooui-react.pages.dev/en/components/search-input/index.md).

## Basic usage

Passing `value` makes it controlled; otherwise the component maintains its own input state and `defaultValue` is only the initial value. `onChange` uses the value-first signature — the first argument is the new string value.

```tsx preview
import { useState } from "react";
import { TextInput } from "ooui-react";

function App() {
  const [text, setText] = useState("");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <TextInput value={text} onChange={setText} placeholder="Controlled input" />
      <div>Current value: {text || "(empty)"}</div>
      <TextInput defaultValue="Uncontrolled; the component remembers what you type" />
    </div>
  );
}

export default App;
```

## Type

`type` decides both the `<input>`'s `type` attribute and the root's `oo-ui-textInputWidget-type-{type}` class. It is limited to the theme-styled whitelist `text`, `password`, `email`, `url`, `number`, `search`; an invalid value falls back to `text`.

```tsx preview
import { TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <TextInput type="password" defaultValue="secret" labelPosition="before" label="Password" />
      <TextInput type="email" placeholder="you@example.com" />
    </div>
  );
}

export default App;
```

## Label

`label` is the field label text; `labelPosition` puts it before (`before`) or after (`after`, the default) the input. To hide the label visually, turn on `invisibleLabel`: the accessible name is kept, and `title` falls back to the label text when not given explicitly.

:::note Prefer FieldLayout for labeled form fields
Writing the label on the input itself suits standalone placement; in a form, the label, alignment and "click label to focus the input" linkage are usually delegated to [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md), and the field control itself does not set `label`.
:::

```tsx preview
import { TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <TextInput label="Username" labelPosition="before" defaultValue="alice" />
      <TextInput label="Screen-reader-only label" invisibleLabel icon="user" />
    </div>
  );
}

export default App;
```

## Icons and indicators

`icon` renders on one side of the input (see [Icon](https://ooui-react.pages.dev/en/components/icon/index.md)), `indicator` on the other (see [Indicator](https://ooui-react.pages.dev/en/components/indicator/index.md)). When `indicator` is not given explicitly and `required` is true, it falls back to the `required` indicator.

```tsx preview
import { TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <TextInput icon="search" placeholder="With an icon" />
      <TextInput indicator="down" readOnly defaultValue="With an indicator (read-only)" />
      <TextInput required placeholder="Required; shows the required indicator automatically" />
    </div>
  );
}

export default App;
```

## Soft validation

`validate` is soft feedback: when the value fails, the input element gets `aria-invalid` and the root gets an invalid flag class, **but the value is not rewritten**. By default only native browser constraints (e.g. `required`) take part in submit validation. It fires on value change (debounced 250ms), on blur, and clears on focus.

`validate` accepts a regular expression (tested with `test`), a function (returning a boolean or `Promise<boolean>`), or the symbolic names `'non-empty'` (non-empty) and `'integer'` (digits only).

```tsx preview
import { TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <TextInput validate="non-empty" placeholder="Clear it and blur to see it flagged" />
      <TextInput validate="integer" placeholder="Digits only" />
      <TextInput validate={(v) => v.length >= 6} placeholder="At least 6 characters" />
    </div>
  );
}

export default App;
```

## Disabled and read-only

`disabled` outputs `oo-ui-widget-disabled` and `aria-disabled` (not the native `disabled`); the input can't be focused or typed into. `readOnly` keeps focus and text selection/copying, and only forbids edits.

```tsx preview
import { TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <TextInput disabled defaultValue="Disabled" />
      <TextInput readOnly defaultValue="Read-only; selectable and copyable" />
    </div>
  );
}

export default App;
```

## Attribute placement

The root is a `<div>` and the input element is an `<input>`. Placement rules (common to all input components):

- `...rest` from props (undeclared attributes like `id`, `className`, `data-*`) goes on the root div; attributes that must go on the native `<input>` (such as `role`, `aria-*`, `autoComplete`) must go through the `inputProps` channel.
- `inputRef` points to the inner `<input>` (the component `ref` points to the root div); use `inputRef` to focus the input.
- `tabIndex`, `title`, `dir` and `accessKey` are taken over by the component and go directly on the `<input>` (matching the original's placement), not via `rest`.

`onChange` / `onBlur` / `onFocus` in `inputProps` are **chained after** the component's own logic, so they don't interrupt the value flow or soft validation.

```tsx preview
import { useRef } from "react";
import { Button, TextInput } from "ooui-react";

function App() {
  const inputRef = useRef<HTMLInputElement>(null);

  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <TextInput
        inputRef={inputRef}
        inputProps={{ autoComplete: "off", "aria-label": "Custom label" }}
        placeholder="autoComplete goes through inputProps"
      />
      <Button onClick={() => inputRef.current?.focus()}>Focus</Button>
    </div>
  );
}

export default App;
```

## API

| Prop                       | Description                                                                                                       | Type                                                                                     | Default     |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------- |
| `value`                    | Input value (controlled; passing it enables controlled mode)                                                      | `string`                                                                                 | —           |
| `defaultValue`             | Uncontrolled initial value                                                                                        | `string`                                                                                 | —           |
| `onChange`                 | Value-change handler (value-first, includes the native event)                                                     | `ChangeHandler<string, HTMLInputElement>`                                                | —           |
| `type`                     | Input type, see the [Type](#type) whitelist; invalid values fall back to `text`                                   | `string`                                                                                 | `'text'`    |
| `placeholder`              | Input hint                                                                                                        | `string`                                                                                 | —           |
| `maxLength`                | Maximum length                                                                                                    | `number`                                                                                 | —           |
| `label` / `invisibleLabel` | Field label / label visually hidden (kept as accessible name)                                                     | `ReactNode` / `boolean`                                                                  | — / `false` |
| `labelPosition`            | Label position                                                                                                    | `'before' \| 'after'`                                                                    | `'after'`   |
| `icon`                     | Icon name                                                                                                         | `string`                                                                                 | —           |
| `indicator`                | Indicator (falls back to required when `required` and not given explicitly)                                       | `'up' \| 'down' \| 'clear' \| 'required'`                                                | —           |
| `required`                 | Required (native `required` attribute, part of browser validation; also outputs `aria-required`)                  | `boolean`                                                                                | `false`     |
| `validate`                 | Soft validation, see [Soft validation](#soft-validation)                                                          | `RegExp \| ((value: string) => boolean \| Promise<boolean>) \| 'non-empty' \| 'integer'` | —           |
| `readOnly`                 | Read-only                                                                                                         | `boolean`                                                                                | `false`     |
| `disabled`                 | Whether disabled                                                                                                  | `boolean`                                                                                | `false`     |
| `flags`                    | Extra flags on the root (the invalid flag from soft validation is layered on top)                                 | `string \| string[]`                                                                     | —           |
| `name`                     | Form field name (goes on `<input>`)                                                                               | `string`                                                                                 | —           |
| `accessKey`                | Access key (goes on `<input>`)                                                                                    | `string`                                                                                 | —           |
| `inputRef`                 | Ref to the inner `<input>`                                                                                        | `Ref<HTMLInputElement>`                                                                  | —           |
| `inputProps`               | Extra-props channel for the native `<input>`; `onChange`/`onBlur`/`onFocus` are chained after the component logic | `object`                                                                                 | —           |
| `indicatorProps`           | Extra props for the indicator element                                                                             | `object`                                                                                 | —           |
| `...rest`                  | Native `div` props (`className`, `id`, `data-*`, etc.) passed straight to the root                                | `HTMLAttributes<HTMLDivElement>`                                                         | —           |

When `required`
 is true, this library also outputs `aria-required`
 on the native `<input>`
 (the original only writes the native `required`
 attribute). This covers the components that inherit from TextInput (MultilineTextInput, NumberInput and ComboBoxInput alike); non-text forms (Dropdown, Checkbox, Radio, SelectFile) do not output it.
## See also

- How values flow between the component and your state: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md)
- The pass-through and `ref` rules shared by all components: [Common props](https://ooui-react.pages.dev/en/guide/basics.md)
- The multiline, number and search forms: [MultilineTextInput](https://ooui-react.pages.dev/en/components/multiline-text-input/index.md), [NumberInput](https://ooui-react.pages.dev/en/components/number-input/index.md), `SearchInput`



---
url: https://ooui-react.pages.dev/en/components/multiline-text-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# MultilineTextInput

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/MultilineTextInput) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MultilineTextInputWidget.html "OO.ui.MultilineTextInputWidget")

A multi-line text input; input capabilities match [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md).

## Basic usage

```tsx preview
import { useState } from "react";
import { MultilineTextInput } from "ooui-react";

function App() {
  const [text, setText] = useState("");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <MultilineTextInput value={text} onChange={setText} placeholder="Controlled multiline input" />
      <div>Current length: {text.length}</div>
      <MultilineTextInput defaultValue="Uncontrolled; the component remembers what you type" />
    </div>
  );
}

export default App;
```

## Rows and auto height

`rows` is the minimum number of rows (written to the `<textarea>`'s `rows` attribute). With `autosize` on, the height follows the content: it grows until `maxRows` and turns into internal scrolling beyond that; `maxRows` defaults to `max(2 × rows, 10)`.

Without `autosize`, the height stays at `rows` lines and overflowing content scrolls.

Beyond input, the auto-height re-measure has a size-observer fallback: font loading and container or width changes also trigger a re-measure (the original only re-measures on input, so the height can lag behind).
```tsx preview
import { MultilineTextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <MultilineTextInput autosize rows={2} placeholder="autosize: grows with the content" />
      <MultilineTextInput rows={3} defaultValue={"Line one\nLine two\nLine three\nLine four\nLine five"} />
    </div>
  );
}

export default App;
```

## Scrollbar offset

When a vertical scrollbar appears, the indicator and the label placed after the input shift by the scrollbar width to stay clear of it (always enabled for multiline input; nothing to configure). When the input's direction diverges from the page's (e.g. a `dir='rtl'`
 input on an LTR page), the offset is withdrawn entirely, avoiding the label-stretching distortion the original shows in that case.
## Line breaks and Enter

Enter always inserts a line break.

:::note Differences from OOUI
The original's `allowLinebreaks`
 option (suppressing line breaks and cleaning them into spaces) and its companion `enter`
 event (fired on Ctrl/Cmd+Enter) are not provided here — to restrict line breaks, clean the value in `onChange`
.
:::
## Capabilities shared with TextInput

The following behave exactly as in TextInput and are not repeated here:

- Label: `label` / `labelPosition` / `invisibleLabel`;
- Icon and indicator: `icon`, `indicator`; when `indicator` is not given explicitly and `required` is true, it falls back to the required indicator;
- Soft validation: `validate` (RegExp / function / `'non-empty'` / `'integer'`), flags without rewriting the value;
- State: `maxLength`, `readOnly` (focusable and copyable), `disabled`.

```tsx preview
import { MultilineTextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <MultilineTextInput label="Bio" labelPosition="before" placeholder="Up to 20 characters" maxLength={20} />
      <MultilineTextInput validate="non-empty" placeholder="Clear it and blur to see it flagged" />
    </div>
  );
}

export default App;
```

## Attribute placement

The component root is a non-focusable `<div>` and the input element is a `<textarea>`. The placement rules are the same as [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md):

- `...rest` from props goes on the root div; attributes that must go on the native `<textarea>` (such as `role`, `aria-*`) go through the `inputProps` channel, whose `onChange`/`onBlur`/`onFocus` are chained after the component's own logic.
- `inputRef` points to the inner `<textarea>` (the component `ref` points to the root div); use `inputRef` to focus the input.
- `tabIndex`, `title`, `dir`, `accessKey` and `name` are taken over by the component and written directly to the `<textarea>` (matching the original's placement), not via `rest`.

## API

| Prop                       | Description                                                                                                                                                            | Type                                                                                     | Default             |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------- |
| `value`                    | Input value (controlled; passing it enables controlled mode)                                                                                                           | `string`                                                                                 | —                   |
| `defaultValue`             | Uncontrolled initial value                                                                                                                                             | `string`                                                                                 | —                   |
| `onChange`                 | Value-change handler (value-first, includes the native event)                                                                                                          | `ChangeHandler<string, HTMLTextAreaElement>`                                             | —                   |
| `rows`                     | Minimum number of rows                                                                                                                                                 | `number`                                                                                 | —                   |
| `maxRows`                  | Height cap for autosize, in rows                                                                                                                                       | `number`                                                                                 | `max(2 × rows, 10)` |
| `autosize`                 | Whether the height follows the content                                                                                                                                 | `boolean`                                                                                | `false`             |
| `placeholder`              | Input hint                                                                                                                                                             | `string`                                                                                 | —                   |
| `maxLength`                | Maximum length                                                                                                                                                         | `number`                                                                                 | —                   |
| `label` / `invisibleLabel` | Field label / label visually hidden (kept as accessible name)                                                                                                          | `ReactNode` / `boolean`                                                                  | — / `false`         |
| `labelPosition`            | Label position                                                                                                                                                         | `'before' \| 'after'`                                                                    | `'after'`           |
| `icon`                     | Icon name                                                                                                                                                              | `string`                                                                                 | —                   |
| `indicator`                | Indicator (falls back to required when `required` and not given explicitly)                                                                                            | `'up' \| 'down' \| 'clear' \| 'required'`                                                | —                   |
| `required`                 | Required (native `required` attribute, part of browser validation)                                                                                                     | `boolean`                                                                                | `false`             |
| `validate`                 | Soft validation (RegExp / function / symbolic name), see [TextInput's soft validation](https://ooui-react.pages.dev/en/components/text-input/index.md#soft-validation) | `RegExp \| ((value: string) => boolean \| Promise<boolean>) \| 'non-empty' \| 'integer'` | —                   |
| `readOnly`                 | Read-only (keeps focus and selection/copying)                                                                                                                          | `boolean`                                                                                | `false`             |
| `disabled`                 | Whether disabled                                                                                                                                                       | `boolean`                                                                                | `false`             |
| `flags`                    | Extra flags on the root (the invalid flag is layered on top)                                                                                                           | `string \| string[]`                                                                     | —                   |
| `name`                     | Form field name (written to `<textarea>`)                                                                                                                              | `string`                                                                                 | —                   |
| `accessKey`                | Access key (written to `<textarea>`)                                                                                                                                   | `string`                                                                                 | —                   |
| `inputRef`                 | Ref to the inner `<textarea>`                                                                                                                                          | `Ref<HTMLTextAreaElement>`                                                               | —                   |
| `inputProps`               | Extra-props channel for the native `<textarea>`; `onChange`/`onBlur`/`onFocus` are chained after the component logic                                                   | `object`                                                                                 | —                   |
| `indicatorProps`           | Extra props for the indicator element                                                                                                                                  | `object`                                                                                 | —                   |
| `...rest`                  | Native `div` props (`className`, `id`, `data-*`, etc.) passed straight to the root                                                                                     | `HTMLAttributes<HTMLDivElement>`                                                         | —                   |

## See also

- The single-line form and full soft-validation details: [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md)
- How values flow between the component and your state: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md)
- The pass-through and `ref` rules shared by all components: [Common props](https://ooui-react.pages.dev/en/guide/basics.md)



---
url: https://ooui-react.pages.dev/en/components/number-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# NumberInput

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/NumberInput) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.NumberInputWidget.html "OO.ui.NumberInputWidget")

A number input; input capabilities match [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md).

## Basic usage

The value type is `number | ''` — clearing the input or typing non-numeric content means no value.

```tsx preview
import { useState } from "react";
import { NumberInput } from "ooui-react";

function App() {
  const [value, setValue] = useState<number | "">(5);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <NumberInput value={value} onChange={setValue} min={0} max={10} />
      <div>Current value: {value === "" ? "(empty)" : value}</div>
      <NumberInput defaultValue={1} />
    </div>
  );
}

export default App;
```

## Stepping

Stepping uses these channels; the everyday step is `buttonStep`:

- **Plus/minus buttons**: `showButtons` (on by default) renders a button on each side. They are purely decorative (`aria-hidden`, outside the tab order), and clicking them never steals focus from the input; they are disabled when `disabled` or `readOnly`.
- **Keyboard**: ↑/↓ steps by `buttonStep`; PgUp/PgDn steps by `pageStep` (10 × `buttonStep` by default).
- **Mouse wheel**: only while the input is focused (scroll up to increase, down to decrease), and page scrolling is prevented; hovering without focus never intercepts the wheel, so scrolling the page won't change the value by accident.

Stepping normalizes the value: the result is clamped into `[min, max]` and snapped to a multiple of `step`; when the current value is empty (`''`), stepping starts from 0. Normalization happens on stepping only — values typed out of range or off-step are kept as typed and flagged by soft validation.

## Range and step

- `min` / `max`: the valid range, also written as the `<input>`'s `min`/`max` attributes.
- `step`: the validity step — the value must be a multiple of it to count as valid; by default decimals are unrestricted (the attribute outputs `step="any"`).
- `buttonStep`: the actual step for buttons / arrow keys / wheel, defaulting to `step` (then 1).
- `pageStep`: the PgUp/PgDn step, defaulting to 10 × `buttonStep`.

## Soft validation

Validity is built in. When the value fails, the input element gets `aria-invalid` and the root gets an invalid flag class, **but the value is not rewritten**:

- Empty value: invalid when `required`, validated right on mount (empty + required is flagged red as soon as it loads);
- Non-finite numbers, values that are not a multiple of `step`, values outside `[min, max]`.

The timing matches TextInput's soft validation: on value change (debounced), on blur, cleared on focus; changing `min`/`max`/`step`/`required` re-validates immediately.

```tsx preview
import { NumberInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <NumberInput required placeholder="Required; empty is flagged red on load" />
      <NumberInput min={0} max={10} step={2} defaultValue={7} placeholder="step=2; 7 is not a multiple of 2" />
    </div>
  );
}

export default App;
```

## Label and icons

`label` / `labelPosition` / `invisibleLabel` work exactly as in TextInput; when `indicator` is not given explicitly and `required` is true, it falls back to the required indicator.

```tsx preview
import { NumberInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <NumberInput label="Quantity" labelPosition="before" defaultValue={1} />
      <NumberInput required placeholder="Required; shows the required indicator automatically" />
    </div>
  );
}

export default App;
```

## Attribute placement

The component root is a non-focusable `<div>` and the input element is an `<input type="number">` wrapped in an `oo-ui-numberInputWidget-field` container (with buttons on, the root also carries `oo-ui-numberInputWidget-buttoned`). The placement rules are the same as [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md):

- `...rest` from props goes on the root div; attributes that must go on the native `<input>` (such as `role`, `aria-*`, `autoComplete`) go through the `inputProps` channel, whose `onChange`/`onBlur`/`onFocus` are chained after the component's own logic.
- `inputRef` points to the inner `<input>` (the component `ref` points to the root div); use `inputRef` to focus the input.
- `tabIndex`, `title`, `dir`, `accessKey` and `name` are taken over by the component and written directly to the `<input>` (matching the original's placement), not via `rest`.

## API

| Prop                         | Description                                                                                                       | Type                                            | Default           |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ----------------- |
| `value`                      | Input value (controlled; passing it enables controlled mode); `''` means no value                                 | `number \| ''`                                  | —                 |
| `defaultValue`               | Uncontrolled initial value                                                                                        | `number \| ''`                                  | —                 |
| `onChange`                   | Value-change handler (value-first, includes the native event)                                                     | `ChangeHandler<number \| '', HTMLInputElement>` | —                 |
| `showButtons`                | Whether to show the stepping buttons on both sides                                                                | `boolean`                                       | `true`            |
| `min` / `max`                | Minimum / maximum (stepping clamp + soft-validation bounds)                                                       | `number`                                        | —                 |
| `step`                       | Validity step (the value must be a multiple); decimals unrestricted by default                                    | `number`                                        | —                 |
| `buttonStep`                 | Step for buttons / ↑↓ / wheel                                                                                     | `number`                                        | `step ?? 1`       |
| `pageStep`                   | Step for PgUp/PgDn                                                                                                | `number`                                        | `buttonStep × 10` |
| `allowInteger` / `isInteger` | Deprecated compatibility options: integers only (forces `step={1}`); a development warning fires when set         | `boolean`                                       | —                 |
| `placeholder`                | Input hint                                                                                                        | `string`                                        | —                 |
| `label` / `invisibleLabel`   | Field label / label visually hidden (kept as accessible name)                                                     | `ReactNode` / `boolean`                         | — / `false`       |
| `labelPosition`              | Label position                                                                                                    | `'before' \| 'after'`                           | `'after'`         |
| `icon`                       | Icon name                                                                                                         | `string`                                        | —                 |
| `indicator`                  | Indicator (falls back to required when `required` and not given explicitly)                                       | `'up' \| 'down' \| 'clear' \| 'required'`       | —                 |
| `required`                   | Required (native `required` attribute; empty is invalid, part of browser validation)                              | `boolean`                                       | `false`           |
| `readOnly`                   | Read-only (keeps focus; forbids edits and stepping)                                                               | `boolean`                                       | `false`           |
| `disabled`                   | Whether disabled                                                                                                  | `boolean`                                       | `false`           |
| `flags`                      | Extra flags on the root (the invalid flag is layered on top)                                                      | `string \| string[]`                            | —                 |
| `name`                       | Form field name (written to `<input>`)                                                                            | `string`                                        | —                 |
| `accessKey`                  | Access key (written to `<input>`)                                                                                 | `string`                                        | —                 |
| `inputRef`                   | Ref to the inner `<input>`                                                                                        | `Ref<HTMLInputElement>`                         | —                 |
| `inputProps`                 | Extra-props channel for the native `<input>`; `onChange`/`onBlur`/`onFocus` are chained after the component logic | `object`                                        | —                 |
| `...rest`                    | Native `div` props (`className`, `id`, `data-*`, etc.) passed straight to the root                                | `HTMLAttributes<HTMLDivElement>`                | —                 |

## Differences from OOUI

- Non-positive `step` / `buttonStep` / `pageStep` throws at construction time in the original; here it logs a one-time development warning and renders with the given values.{/* deviations: dev-numberinput-step */}
- `allowInteger` / `isInteger` are kept for compatibility: turning them on is equivalent to forcing `step={1}`, with a development warning suggesting migration (the original adopts them silently) — new code should use `step` directly.{/* deviations: dev-allow-integer */}

## See also

- The single-line foundation (type whitelist, `validate` soft validation, etc.): [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md)
- How values flow between the component and your state: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md)
- The pass-through and `ref` rules shared by all components: [Common props](https://ooui-react.pages.dev/en/guide/basics.md)



---
url: https://ooui-react.pages.dev/en/components/search-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# SearchInput

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/SearchInput) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.SearchInputWidget.html "OO.ui.SearchInputWidget")

A search input: the search form of [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md), with a clear indicator appearing when the value is non-empty and editable — click it to clear and refocus the input.

## Basic usage

```tsx preview
import { useState } from "react";
import { SearchInput } from "ooui-react";

function App() {
  const [query, setQuery] = useState("");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <SearchInput value={query} onChange={setQuery} placeholder="Search entries…" />
      <div>Query: {query || "(empty)"}</div>
      <SearchInput defaultValue="OOUI widgets" />
    </div>
  );
}

export default App;
```

When the field holds a value and is editable (not disabled, not read-only), a × clear indicator shows on the right; clearing the value removes it again and returns focus to the input.

## With labels and soft validation

`label`, `labelPosition`, `invisibleLabel`, `validate` and the rest follow TextInput's semantics.

```tsx preview
import { SearchInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <SearchInput label="Keyword" labelPosition="before" validate="non-empty" placeholder="Required example" />
    </div>
  );
}

export default App;
```

:::note Want an input with a persistent results list?
This component is just a search box with clear capability. To show dropdown results live as you type, use `SearchWidget` (a search box combined with a results list).
:::

## Attribute placement

Same as TextInput: `...rest` goes on the root `<div>`, props for the native `<input>` go through `inputProps`, and `inputRef` focuses the input. The clear indicator is taken over by the component, so `type` (always `search`), `indicator` and `indicatorProps` are **not exposed**.

## API

Only the differences from TextInput are listed; the rest are in [TextInput · API](https://ooui-react.pages.dev/en/components/text-input/index.md#api).

| Prop           | Description                         | Type                                      | Default    |
| -------------- | ----------------------------------- | ----------------------------------------- | ---------- |
| `value`        | Query text (controlled)             | `string`                                  | —          |
| `defaultValue` | Initial value for uncontrolled use  | `string`                                  | —          |
| `onChange`     | Value-change callback (value-first) | `ChangeHandler<string, HTMLInputElement>` | —          |
| `icon`         | Left icon name                      | `string`                                  | `'search'` |
| `inputRef`     | Ref to the inner `<input>`          | `Ref<HTMLInputElement>`                   | —          |

Unsupported props: `type` (always `search`), `indicator` / `indicatorProps` (the indicator slot is taken over by the clear logic).

## See also

- The base single-line input's full capabilities (types, soft validation, prop placement): [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md)
- Search with a results list: `SearchWidget`
- How values flow between the component and your state: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md)



---
url: https://ooui-react.pages.dev/en/components/search-widget/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# SearchWidget

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/SearchWidget) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.SearchWidget.html "OO.ui.SearchWidget")

A search widget: a query box with an always-visible results list.

## Basic usage

The component doesn't set a height on its own: query and results are absolutely positioned and the root element carries no height. It's recommended to give the root element a height (a fixed height, `height: 100%`, or `flex: 1` in a flex column all work), otherwise the results list overflows the widget box. The demo also adds `position: relative` to the root so those regions anchor to the widget itself (by default they anchor to the nearest positioned ancestor).

```tsx preview
import { useState } from "react";
import { SearchWidget } from "ooui-react";

const data = ["Apple", "Banana", "Orange", "Grape", "Melon"];

function App() {
  const [query, setQuery] = useState("");
  const [picked, setPicked] = useState("(nothing chosen)");

  // The caller filters and fills results from the query
  const results = data
    .filter((name) => name.toLowerCase().includes(query.toLowerCase()))
    .map((name) => ({ value: name, children: name }));

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 320 }}>
      <SearchWidget
        value={query}
        onQueryChange={setQuery}
        onChoose={(v) => setPicked(String(v))}
        results={results}
        placeholder="Search fruit…"
        style={{ height: 280, position: "relative" }}
      />
      <div>Chosen: {picked}</div>
    </div>
  );
}

export default App;
```

## Query and choosing

- `value` / `defaultValue` / `onQueryChange` are the query box's controlled/uncontrolled channels (there is no `onChange`; query changes go through `onQueryChange`).
- Each `results` item is standard [option data](https://ooui-react.pages.dev/en/guide/options.md) (with `value` and `children`).
- `onChoose` fires when a result is chosen (Enter on the highlighted result, or clicking one). The highlight clears whenever the results set or query changes.
- The component implements no searching; real use is mostly async: fire the request in `onQueryChange`, optionally empty `results` while loading and fill them in when ready — the highlight clears automatically on every results/query change, no manual reset needed.
- `inputProps` is a **two-layer channel**: SearchInput-level props are passed directly; props meant for the native `<input>` (`aria-*`, `autoComplete`, etc.) go through `inputProps.inputProps` (TextInput's input-element channel). `inputProps.inputRef` is merged — that input doubles as the focus owner for the results list's `aria-activedescendant`.

## Keyboard and focus

Focus always stays in the query box: ↑↓ move the highlight among results (wrapping at the ends), Enter chooses the current highlight. The clear indicator on the query box comes from [SearchInput](https://ooui-react.pages.dev/en/components/search-input/index.md) — it appears when there's a value and clears on click.

## API

| Prop            | Description                                                                                                                                                     | Type                              | Default |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
| `results`       | Result option set, filled by the caller from the query                                                                                                          | `SelectOptionProps[]`             | `[]`    |
| `value`         | Query text (controlled)                                                                                                                                         | `string`                          | —       |
| `defaultValue`  | Initial query for uncontrolled use                                                                                                                              | `string`                          | `''`    |
| `onQueryChange` | Query-change callback (refill `results` from it)                                                                                                                | `ChangeHandler<string>`           | —       |
| `onChoose`      | Result-chosen callback                                                                                                                                          | `ChangeHandler<string \| number>` | —       |
| `placeholder`   | Query box placeholder                                                                                                                                           | `string`                          | —       |
| `inputProps`    | Overrides for the query box (SearchInput); a two-layer channel, see [Query and choosing](#query-and-choosing); `value`/`defaultValue`/`onChange` are taken over | `object`                          | —       |
| `disabled`      | Whether disabled                                                                                                                                                | `boolean`                         | `false` |
| `...rest`       | Native `div` props passed straight to the root                                                                                                                  | `HTMLAttributes<HTMLDivElement>`  | —       |

## See also

- Lookup with candidates, shown as tags: [MenuTagMultiselect](https://ooui-react.pages.dev/en/components/menu-tag-multiselect/index.md)
- A free-input dropdown of candidates: [ComboBoxInput](https://ooui-react.pages.dev/en/components/combo-box-input/index.md)
- The query box itself: [SearchInput](https://ooui-react.pages.dev/en/components/search-input/index.md)



---
url: https://ooui-react.pages.dev/en/components/combo-box-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# ComboBoxInput

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ComboBoxInput) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ComboBoxInputWidget.html "OO.ui.ComboBoxInputWidget")

A combo box: a freely editable input with a dropdown candidate menu; the text doesn't have to be one of the candidates.

## Basic usage

```tsx preview
import { useState } from "react";
import { ComboBoxInput } from "ooui-react";

const options = [
  { value: "red", children: "Red" },
  { value: "green", children: "Green" },
  { value: "blue", children: "Blue" },
];

function App() {
  const [text, setText] = useState("");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 260 }}>
      <ComboBoxInput
        options={options}
        value={text}
        onChange={setText}
        placeholder="Type or pick from the dropdown"
      />
      <div>Current text: {text || "(empty)"}</div>
      <ComboBoxInput options={options} defaultValue="Green" label="Color" labelPosition="before" />
    </div>
  );
}

export default App;
```

## Labels, icons and soft validation

`label` / `labelPosition` / `invisibleLabel`, `icon` / `indicator`, `validate`, `required` and the rest follow [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md); `validate` is soft feedback (marks `aria-invalid`, never rewrites the value).

```tsx preview
import { ComboBoxInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 260 }}>
      <ComboBoxInput
        icon="search"
        validate={(v) => v.length >= 2}
        placeholder="At least two characters"
        options={[{ value: "ab", children: "AB" }, { value: "cd", children: "CD" }]}
      />
    </div>
  );
}

export default App;
```

## Keyboard and choosing

Typing only **opens the menu**
 and re-anchors the highlight to the option exactly matching the input (no match clears the highlight); the candidate list itself is not filtered by the input — to "filter as you type", narrow `options`
 yourself. Clicking the input also re-opens the menu. With `readOnly`
 the component is fully read-only: none of the open paths (arrow keys, the dropdown button, clicking the input) can expand the menu (the original would still expand a fully disabled menu on click; here read-only means no expansion).
Choosing (clicking an option, Enter, the dropdown button) writes the option text into the input and the value is always a string: **options with a numeric `value` never show as selected** (matching the original, which compares serialized text — `1` and `'1'` are not equal); use string values when you need the selected state.

| Key                | Behavior                                                                                                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ↑ / ↓              | Open the menu and move the highlight (starting from the first / last option when closed)                                                                                                                                                                                                    |
| Enter              | Choose the highlighted option (with no highlight, the option exactly matching the input) and close; while the menu is open the default is prevented, so Enter inside a [FormLayout](https://ooui-react.pages.dev/en/components/form-layout/index.md) won't submit the form as a side effect |
| Tab                | Taken only while the menu is open: with an unchosen highlight, it commits that option and keeps focus; otherwise it closes the menu and lets focus move on                                                                                                                                  |
| PageUp / PageDown  | Page by ±10 (only while the menu is open)                                                                                                                                                                                                                                                   |
| Home / End / ← / → | Not taken; the caret stays with the input                                                                                                                                                                                                                                                   |

The highlight does not wrap at the ends (unlike `SearchWidget`'s wrap-around); Escape or clicking outside closes the menu (handled in the capture phase, so nested in a [Dialog](https://ooui-react.pages.dev/en/components/dialog/index.md) it won't close the dialog by mistake). Focus stays on the input and the highlighted option is announced via `aria-activedescendant`; the common model is in [Selection and options](https://ooui-react.pages.dev/en/guide/options.md).

## Attribute placement

Same as [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md): `...rest` goes on the root `<div>`, props for the native `<input>` go through `inputProps`, `inputRef` focuses the input; `tabIndex`, `title`, `dir`, `accessKey` and `name` are taken over and go on the `<input>`.

## API

Only ComboBoxInput-specific props are listed; input props are in [TextInput · API](https://ooui-react.pages.dev/en/components/text-input/index.md#api).

| Prop                                                           | Description                                                                                                            | Type                                                                                 | Default                 |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------- |
| `options`                                                      | Candidate option set (**required**); see [Selection and options](https://ooui-react.pages.dev/en/guide/options.md)     | `DropdownOptionProps[]`                                                              | —                       |
| `value`                                                        | Input text (controlled)                                                                                                | `string`                                                                             | —                       |
| `defaultValue`                                                 | Initial value for uncontrolled use                                                                                     | `string`                                                                             | `''`                    |
| `onChange`                                                     | Value-change callback (typed and chosen items both fire)                                                               | `ChangeHandler<string>`                                                              | —                       |
| `placeholder` / `name` / `maxLength` / `required` / `readOnly` | Ordinary input props                                                                                                   | —                                                                                    | —                       |
| `label` / `labelPosition` / `invisibleLabel`                   | Field label / position / visually hidden                                                                               | —                                                                                    | — / `'after'` / `false` |
| `icon` / `indicator`                                           | Icon name / indicator                                                                                                  | `string` / `'up' \| 'down' \| 'clear' \| 'required'`                                 | —                       |
| `flags`                                                        | Extra root flags (invalid overlays it)                                                                                 | `string \| string[]`                                                                 | —                       |
| `validate`                                                     | Soft validation, see [Soft validation](https://ooui-react.pages.dev/en/components/text-input/index.md#soft-validation) | `RegExp \| ((v: string) => boolean \| Promise<boolean>) \| 'non-empty' \| 'integer'` | —                       |
| `inputRef`                                                     | Ref to the inner `<input>`                                                                                             | `Ref<HTMLInputElement>`                                                              | —                       |
| `inputProps`                                                   | Extra props for the native `<input>`; events chain after the component's logic                                         | `object`                                                                             | —                       |
| `disabled`                                                     | Whether disabled                                                                                                       | `boolean`                                                                            | `false`                 |

## See also

- The base single-line input: [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md)
- Pick only from candidates (no free entry): [Dropdown](https://ooui-react.pages.dev/en/components/dropdown/index.md)
- Option data and the keyboard focus model: [Selection and options](https://ooui-react.pages.dev/en/guide/options.md)



---
url: https://ooui-react.pages.dev/en/components/checkbox-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# CheckboxInput

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/CheckboxInput) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.CheckboxInputWidget.html "OO.ui.CheckboxInputWidget")

A single checkbox. It has no text label of its own — when you need one, wrap it in [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md).

## Basic usage

The checked state uses the `checked` / `defaultChecked` / `onChange` channels; the first argument of `onChange` is the new checked boolean.

```tsx preview
import { useState } from "react";
import { CheckboxInput } from "ooui-react";

function App() {
  const [checked, setChecked] = useState(false);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <CheckboxInput checked={checked} onChange={setChecked} />
        Checked: {String(checked)}
      </label>
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <CheckboxInput defaultChecked />
        Uncontrolled; initially checked
      </label>
    </div>
  );
}

export default App;
```

## Indeterminate state

`indeterminate` means "partially selected" — visually a dash rather than a check. It is independent of the checked state and is commonly used on a "select all" box to show that some, not all, children are selected.

```tsx preview
import { CheckboxInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <CheckboxInput indeterminate />
      <CheckboxInput checked indeterminate />
    </div>
  );
}

export default App;
```

The standard wiring of a "select all" box: its checked and indeterminate states are both **derived** from the children set (none → unchecked, all → checked, otherwise indeterminate), and clicking it sets all children to checked or unchecked:

```tsx preview
import { useState } from "react";
import { CheckboxInput } from "ooui-react";

const ITEMS = ["Apple", "Banana", "Orange"];

function App() {
  const [picked, setPicked] = useState<string[]>(["Apple"]);
  const allChecked = picked.length === ITEMS.length;

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <CheckboxInput
          checked={allChecked}
          indeterminate={picked.length > 0 && !allChecked}
          onChange={() => setPicked(allChecked ? [] : ITEMS)}
        />
        Select all
      </label>
      {ITEMS.map((item) => (
        <label key={item} style={{ display: "flex", alignItems: "center", gap: 8 }}>
          <CheckboxInput
            checked={picked.includes(item)}
            onChange={() =>
              setPicked((prev) =>
                prev.includes(item) ? prev.filter((x) => x !== item) : [...prev, item],
              )
            }
          />
          {item}
        </label>
      ))}
    </div>
  );
}

export default App;
```

## Form submission value

`value` is the **form submission value** (written to the native `<input>`'s `value` attribute, defaulting to an empty string). It **does not affect the checked state** — that is driven only by the `checked` channels. Combined with `name`, this `value` is submitted with the form when checked.

```tsx preview
import { CheckboxInput } from "ooui-react";

function App() {
  return (
    <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <CheckboxInput name="agree" value="yes" defaultChecked />
      I agree to the terms (submits as agree=yes)
    </label>
  );
}

export default App;
```

## Using it with FieldLayout

The field's text label is usually delegated to [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md). It automatically associates the label with this checkbox's native `<input>` (clicking the label toggles the check); to specify the association target manually, give the input element's id via `inputId`.

```tsx preview
import { CheckboxInput, FieldLayout } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 320 }}>
      <FieldLayout label="Enable notifications" align="inline">
        <CheckboxInput defaultChecked />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## Disabled

`disabled` outputs `aria-disabled` and disables the native `<input>`, so the checkbox can no longer be toggled. Inside a native `<fieldset>` such as `FieldsetLayout`, the group-level disable propagates to it.

```tsx preview
import { CheckboxInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <CheckboxInput disabled />
      <CheckboxInput disabled defaultChecked />
    </div>
  );
}

export default App;
```

## API

| Prop             | Description                                                                           | Type                                       | Default |
| ---------------- | ------------------------------------------------------------------------------------- | ------------------------------------------ | ------- |
| `checked`        | Checked state (controlled; passing it enables controlled mode)                        | `boolean`                                  | —       |
| `defaultChecked` | Uncontrolled initial checked state                                                    | `boolean`                                  | —       |
| `onChange`       | Checked-change handler (new state first, includes the native event)                   | `ChangeHandler<boolean, HTMLInputElement>` | —       |
| `value`          | Form submission value (written to `<input>`'s `value`, does not affect checked state) | `string \| number`                         | `''`    |
| `indeterminate`  | Half-selected state                                                                   | `boolean`                                  | `false` |
| `required`       | Required (native `required`)                                                          | `boolean`                                  | `false` |
| `name`           | Form field name (goes on `<input>`)                                                   | `string`                                   | —       |
| `inputId`        | The inner `<input>`'s id (pairs with a label's `htmlFor`)                             | `string`                                   | —       |
| `inputRef`       | Ref to the inner `<input>` (the component `ref` points to the outer `<span>`)         | `Ref<HTMLInputElement>`                    | —       |
| `disabled`       | Whether disabled                                                                      | `boolean`                                  | `false` |
| `accessKey`      | Access key (goes on `<input>`)                                                        | `string`                                   | —       |
| `...rest`        | Native `span` props (`className`, `id`, `data-*`, etc.) passed straight to the root   | `HTMLAttributes<HTMLSpanElement>`          | —       |

`title`, `dir` and `tabIndex` are taken over by the component and go on the inner `<input>`; `role` goes there too (semantics like `role="presentation"` must hit the real input to work).

## See also

- Where the checked channel sits among the three value channels: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md)
- Layout for a labeled field: [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md)
- The single-choice case: [RadioInput](https://ooui-react.pages.dev/en/components/radio-input/index.md) (same props as this component, without `indeterminate`)



---
url: https://ooui-react.pages.dev/en/components/radio-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# RadioInput

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/RadioInput) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.RadioInputWidget.html "OO.ui.RadioInputWidget")

A single radio button. It has no text label of its own — when you need one, wrap it in [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md).

## Basic usage

The checked state uses the `checked` / `defaultChecked` / `onChange` channels; the first argument of `onChange` is the new checked boolean. Note that a radio cannot be un-checked by clicking it again — clearing an exclusive group needs an extra mechanism (such as a "clear" button that resets the state).

```tsx preview
import { useState } from "react";
import { Button, RadioInput } from "ooui-react";

function App() {
  const [checked, setChecked] = useState(true);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, alignItems: "flex-start" }}>
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <RadioInput checked={checked} onChange={setChecked} />
        Checked: {String(checked)}
      </label>
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <RadioInput defaultChecked />
        Uncontrolled; initially checked
      </label>
      <Button onClick={() => setChecked(false)}>Clear</Button>
    </div>
  );
}

export default App;
```

## Same-name exclusivity and the form submission value

Give several `RadioInput`s the same `name` and the browser's native mechanism guarantees group exclusivity with at most one item submitted with the form. `value` is the **form submission value** (written to the native `<input>`'s `value` attribute, defaulting to an empty string). It **does not affect the checked state**.

```tsx preview
import { useState } from "react";
import { RadioInput } from "ooui-react";

function App() {
  const [size, setSize] = useState("medium");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, alignItems: "flex-start" }}>
      {["small", "medium", "large"].map((item) => (
        <label key={item} style={{ display: "flex", alignItems: "center", gap: 8 }}>
          <RadioInput
            name="size"
            value={item}
            checked={size === item}
            onChange={(next) => next && setSize(item)}
          />
          {item}
        </label>
      ))}
      <div>Current selection: {size}</div>
    </div>
  );
}

export default App;
```

## Using it with FieldLayout

The field's text label is usually delegated to [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md). It automatically associates the label with this radio's native `<input>` (clicking the label selects it); to specify the association target manually, give the input element's id via `inputId`.

```tsx preview
import { FieldLayout, RadioInput } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 320 }}>
      <FieldLayout label="Default option" align="inline">
        <RadioInput defaultChecked />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## Disabled

`disabled` outputs `aria-disabled` and disables the native `<input>`, so the radio can no longer be selected. Inside a native `<fieldset>` such as `FieldsetLayout`, the group-level disable propagates to it.

```tsx preview
import { RadioInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <RadioInput disabled />
      <RadioInput disabled defaultChecked />
    </div>
  );
}

export default App;
```

## API

| Prop             | Description                                                                           | Type                                       | Default |
| ---------------- | ------------------------------------------------------------------------------------- | ------------------------------------------ | ------- |
| `checked`        | Checked state (controlled; passing it enables controlled mode)                        | `boolean`                                  | —       |
| `defaultChecked` | Uncontrolled initial checked state                                                    | `boolean`                                  | —       |
| `onChange`       | Checked-change handler (new state first, includes the native event)                   | `ChangeHandler<boolean, HTMLInputElement>` | —       |
| `value`          | Form submission value (written to `<input>`'s `value`, does not affect checked state) | `string \| number`                         | `''`    |
| `name`           | Form field name (written to `<input>`; same name = same exclusive group)              | `string`                                   | —       |
| `inputId`        | The inner `<input>`'s id (pairs with a label's `htmlFor`)                             | `string`                                   | —       |
| `required`       | Required (native `required`)                                                          | `boolean`                                  | `false` |
| `disabled`       | Whether disabled                                                                      | `boolean`                                  | `false` |
| `accessKey`      | Access key (written to `<input>`)                                                     | `string`                                   | —       |
| `...rest`        | Native `span` props (`className`, `id`, `data-*`, etc.) passed straight to the root   | `HTMLAttributes<HTMLSpanElement>`          | —       |

`title`, `dir` and `tabIndex` are taken over by the component and written to the inner `<input>`; `role` is written there too (semantics like `role="presentation"` must hit the real input to work). The component `ref` points to the outer `<span>`.

## See also

- Where the checked channel sits among the value channels: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md)
- Layout for a labeled field: [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md)
- The radio group (exclusive items in one group, arrow keys select directly): [RadioSelect](https://ooui-react.pages.dev/en/components/radio-select/index.md)



---
url: https://ooui-react.pages.dev/en/components/select-file-input-widget/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# SelectFileInputWidget

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/SelectFileInputWidget) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.SelectFileInputWidget.html "OO.ui.SelectFileInputWidget")

A file-picker input, with drop-zone and button-only forms.

## Basic usage

The file set is an **array** driven by the `value` / `defaultValue` / `onChange` channels; when not multiple, only the first file is kept. The **clear indicator in the info field is the only way to clear** (click it or press Enter).

```tsx preview
import { useState } from "react";
import { SelectFileInputWidget } from "ooui-react";

function App() {
  const [files, setFiles] = useState<File[]>([]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <SelectFileInputWidget onChange={setFiles} />
      <SelectFileInputWidget defaultValue={[new File(["hello"], "hello.txt")]} />
      <div style={{ fontSize: 13 }}>
        {files.length ? `Selected: ${files.map((file) => file.name).join(", ")}` : "No file selected"}
      </div>
    </div>
  );
}

export default App;
```

## Multiple selection and type filtering

`multiple` enables multi-select; `accept` restricts types with MIME or `image/*` patterns — it is written to the `accept` attribute and filters both the picker results and dropped files (the picker is already restricted, so most filtering happens on the drop path; files without a type are let through).

```tsx preview
import { SelectFileInputWidget } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <SelectFileInputWidget multiple />
      <SelectFileInputWidget accept={["image/*"]} />
    </div>
  );
}

export default App;
```

## Drop-zone form

`showDropTarget` turns the whole component into a drop zone: when empty the whole block opens the picker on click, dragged-in files get accepted/rejected feedback, and dropping selects them. In single-select mode with an image file, a **thumbnail** is shown — loaded only for images within `thumbnailSizeLimit` (MB, default 20), falling back to an attachment icon when oversized or undecodable.

Dragging relies on the browser's `DataTransfer` constructor (Safari 14.1+); when unavailable, dragging turns off automatically and the select button keeps working. Pass `droppable={false}` to switch dragging off explicitly.

```tsx preview
import { useMemo } from "react";
import { SelectFileInputWidget } from "ooui-react";

const PNG_1PX =
  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=";

function App() {
  // A 1x1 PNG: with an initial image file, the single-select drop zone loads a thumbnail
  const imageFile = useMemo(() => {
    const bytes = Uint8Array.from(atob(PNG_1PX), (char) => char.charCodeAt(0));
    return new File([bytes], "logo.png", { type: "image/png" });
  }, []);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16, maxWidth: 420 }}>
      <SelectFileInputWidget showDropTarget />
      <SelectFileInputWidget showDropTarget defaultValue={[imageFile]} />
      {/* Limit set to 0: no thumbnail, falls back to the attachment icon */}
      <SelectFileInputWidget showDropTarget thumbnailSizeLimit={0} defaultValue={[imageFile]} />
    </div>
  );
}

export default App;
```

## Button-only form

`buttonOnly` renders just the select button, without the info field; use it when you display the file name yourself.

```tsx preview
import { useState } from "react";
import { SelectFileInputWidget } from "ooui-react";

function App() {
  const [name, setName] = useState("");

  return (
    <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
      <SelectFileInputWidget
        buttonOnly
        buttonLabel="Browse…"
        onChange={(files) => setName(files[0]?.name ?? "")}
      />
      <span>{name || "No file selected"}</span>
    </div>
  );
}

export default App;
```

## Controlled use and programmatic changes

Passing `value` enables controlled mode — the file set is fully caller-driven. The demo wires an external "Clear" button that resets the set to `[]`.

:::note Differences from OOUI
A `value`
 passed at construction is silently dropped by the original (a construction-order defect) and can only be applied afterwards with an imperative `setValue`
. Following the controlled convention, this implementation applies `value`
 / `defaultValue`
 directly and writes the set back to the inner `<input type="file">`
, so native form submission keeps working.
:::
```tsx preview
import { useState } from "react";
import { Button, SelectFileInputWidget } from "ooui-react";

function App() {
  const [files, setFiles] = useState<File[]>([]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 420 }}>
      <SelectFileInputWidget value={files} onChange={setFiles} />
      <div>
        <Button onClick={() => setFiles([])} disabled={files.length === 0}>
          Clear
        </Button>
      </div>
    </div>
  );
}

export default App;
```

## Focus and keyboard

- The **select button** is the `Tab` stop; the info field is out of the Tab order. The clear indicator is keyboard-reachable (focus it and press Enter to clear).
- The info field is a read-only `type="search"` input — typing in it never changes the file set; clearing always goes through the clear indicator.
- `required` and `name` are written to the inner file `<input>` and submit natively with [FormLayout](https://ooui-react.pages.dev/en/components/form-layout/index.md).

## API

| Prop                 | Description                                                                                                                      | Type                                                                                         | Default |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------- |
| `value`              | Current file set (controlled; passing it enables controlled mode; empty array = no selection), first file only when not multiple | `File[]`                                                                                     | —       |
| `defaultValue`       | Initial file set for uncontrolled use                                                                                            | `File[]`                                                                                     | `[]`    |
| `onChange`           | File-set change callback; not fired when the new set is equivalent to the old one (same name, size, type and last-modified)      | `(files: File[]) => void`                                                                    | —       |
| `accept`             | Accepted file types (MIME or `image/*` patterns), written to the `accept` attribute and filtering both picker results and drops  | `string[]`                                                                                   | —       |
| `multiple`           | Whether multiple files can be selected                                                                                           | `boolean`                                                                                    | `false` |
| `droppable`          | Whether dropping is allowed (forced off when the browser lacks `DataTransfer`)                                                   | `boolean`                                                                                    | `true`  |
| `showDropTarget`     | Drop-zone form: the whole block is droppable and clickable (requires `droppable`)                                                | `boolean`                                                                                    | `false` |
| `buttonOnly`         | Render only the select button (takes priority over `showDropTarget`)                                                             | `boolean`                                                                                    | `false` |
| `thumbnailSizeLimit` | Thumbnail size limit in MB (no thumbnail beyond it)                                                                              | `number`                                                                                     | `20`    |
| `placeholder`        | Info-field placeholder (defaults to the built-in message)                                                                        | `string`                                                                                     | —       |
| `icon`               | Info-field icon (none by default)                                                                                                | `string`                                                                                     | —       |
| `required`           | Required (native `required`, on the file `<input>`)                                                                              | `boolean`                                                                                    | `false` |
| `name`               | File field name (on the file `<input>`, submitted with the form)                                                                 | `string`                                                                                     | —       |
| `buttonLabel`        | Select-button text (defaults to the built-in message depending on `multiple`)                                                    | `ReactNode`                                                                                  | —       |
| `buttonProps`        | Select-button props override (`disabled` / `onClick` are taken over by the component)                                            | `Omit<ButtonProps, "children" \| "disabled" \| "onClick" \| "anchorContent" \| "anchorRef">` | —       |
| `inputRef`           | Ref to the inner file `<input>`                                                                                                  | `Ref<HTMLInputElement>`                                                                      | —       |
| `accessKey`          | Access key (written to the file `<input>`)                                                                                       | `string`                                                                                     | —       |
| `disabled`           | Whether disabled (button, info field and dragging all off)                                                                       | `boolean`                                                                                    | `false` |
| `...rest`            | Native `div` props (`className`, `id`, `data-*`, etc.) passed straight to the root                                               | `HTMLAttributes<HTMLDivElement>`                                                             | —       |

`title` is written to the file `<input>` and `tabIndex` to the select button; the component `ref` points to the root element (the button itself in the `buttonOnly` form).

## See also

- The value-channel convention: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md)
- Replacing built-in messages with a language pack: [Global configuration](https://ooui-react.pages.dev/en/guide/configuration.md#messages-and-i18n)
- The form submission container: [FormLayout](https://ooui-react.pages.dev/en/components/form-layout/index.md)



---
url: https://ooui-react.pages.dev/en/components/select/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Select

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Select) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.SelectWidget.html "OO.ui.SelectWidget")

A selection list: a clickable set of options — the inner list of floating components like [Dropdown](https://ooui-react.pages.dev/en/components/dropdown/index.md), and usable on its own. The option data format is described in [Selection and options](https://ooui-react.pages.dev/en/guide/options.md).

:::note How to interact with it standalone
Matching the original `SelectWidget`
, this component's root is **not focusable by default**
 (it is not in the Tab order), so it is best suited to mouse selection. For keyboard-reachable single or multiple selection, prefer components that handle focus for you — [Dropdown](https://ooui-react.pages.dev/en/components/dropdown/index.md)
, [RadioSelect](https://ooui-react.pages.dev/en/components/radio-select/index.md)
, `ButtonSelect`
 — all of which use `Select`
 as their inner list. As a menu's inner layer, keyboard navigation is handled by the outer trigger for you, so you don't have to manage it. 
:::
## Basic usage

```tsx preview
import { useState } from "react";
import { Select } from "ooui-react";

const options = [
  { value: "apple", children: "Apple" },
  { value: "orange", children: "Orange" },
  { value: "banana", children: "Banana", disabled: true },
  { value: "grape", children: "Grape" },
];

function App() {
  const [value, setValue] = useState<string | number>("apple");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 200 }}>
      <Select options={options} value={value} onChange={setValue} aria-label="Fruit" />
      <div>Current value: {String(value)}</div>
    </div>
  );
}

export default App;
```

## onChange and onChoose

The two "choose" callbacks have different roles:

- `onChange`: fires when the **selected value changes**; re-clicking the current item doesn't fire it.
- `onChoose`: fires on **every choice** (click / drag / Enter), including repeats. Floating components use it to "close on choose".

```tsx
<Select options={options} onChange={setValue} onChoose={() => setOpen(false)} />
```

## Command-menu form

When `clearOnChoose` is true, a choice only fires `onChoose` and doesn't change the selected value — a "selected" state never appears, which suits command menus that run an action and keep no selection.

```tsx preview
import { useState } from "react";
import { Select } from "ooui-react";

function App() {
  const [log, setLog] = useState<string[]>([]);

  return (
    <div style={{ display: "flex", gap: 16, alignItems: "flex-start" }}>
      <Select
        aria-label="Commands"
        clearOnChoose
        options={[
          { value: "copy", children: "Copy" },
          { value: "cut", children: "Cut" },
          { value: "paste", children: "Paste" },
        ]}
        onChoose={(v) => setLog((prev) => [...prev, `ran ${String(v)}`])}
      />
      <div style={{ fontSize: 14 }}>{log.length ? log.join(" → ") : "Click any command (no selection appears)"}</div>
    </div>
  );
}

export default App;
```

## Group headings

Items in the `options` array without a `value` render as group headings — not selectable and skipped by keyboard navigation.

```tsx preview
import { Select } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 200 }}>
      <Select
        aria-label="Grouped"
        defaultValue="cat"
        options={[
          { children: "Felines" },
          { value: "cat", children: "Cat" },
          { value: "lion", children: "Lion" },
          { children: "Canines" },
          { value: "dog", children: "Dog" },
        ]}
      />
    </div>
  );
}

export default App;
```

## Keyboard navigation switches

As a menu's inner layer, keyboard navigation is driven by the outer component. For the standalone case where the list has focus:

- `handleNavigationKeys`: whether Home / End / PageUp / PageDown are handled.
- `listWrapsAround`: whether arrow navigation wraps at the ends (default `true`).
- **Prefix jump**: with the list focused, typing characters cycles through options by text prefix (1.5 s buffer).
- **Hover highlight**: the hovered option becomes the highlighted one; the highlight clears on mouse-out (shared state with keyboard highlighting).

## API

| Prop                   | Description                                                                                                        | Type                                           | Default |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ------- |
| `options`              | The option set; see [Selection and options](https://ooui-react.pages.dev/en/guide/options.md) for the convention   | `SelectOptionProps[]`                          | —       |
| `value`                | Current selected value (controlled; passing it enables controlled mode)                                            | `string \| number`                             | —       |
| `defaultValue`         | Initial selected value for uncontrolled use                                                                        | `string \| number`                             | —       |
| `onChange`             | Selected-value change callback (value-first, fires only on change)                                                 | `ChangeHandler<string \| number>`              | —       |
| `onChoose`             | Choose callback (fires on every choice, incl. repeats)                                                             | `ChangeHandler<string \| number>`              | —       |
| `clearOnChoose`        | Command-menu form: a choice only fires `onChoose` and leaves the value unchanged                                   | `boolean`                                      | `false` |
| `outline`              | Render options as hierarchy-indented `OutlineOption`s                                                              | `boolean`                                      | `false` |
| `highlightedValue`     | Keyboard-highlighted value (controlled; pass it to manage from above — internally maintained when used standalone) | `string \| number`                             | —       |
| `onHighlightedChange`  | Highlight-change callback; write back through it when `highlightedValue` is controlled                             | `ChangeHandler<string \| number \| undefined>` | —       |
| `selectedValues`       | A set of selected values for multi-select display (used by tag inputs etc.)                                        | `(string \| number)[]`                         | —       |
| `handleNavigationKeys` | Whether Home/End/PageUp/PageDown are handled                                                                       | `boolean`                                      | `false` |
| `listWrapsAround`      | Whether keyboard navigation wraps at the ends                                                                      | `boolean`                                      | `true`  |
| `disabled`             | Whether disabled (also disables every option in the group)                                                         | `boolean`                                      | `false` |
| `...rest`              | Native `div` props (`className`, `id`, `aria-*`, etc.) passed straight to the root                                 | `HTMLAttributes<HTMLDivElement>`               | —       |

There is no `children` slot; every option is declared through `options`.

## See also

- Option data and the keyboard focus model: [Selection and options](https://ooui-react.pages.dev/en/guide/options.md)
- Floating components that use Select as their inner list: [Dropdown](https://ooui-react.pages.dev/en/components/dropdown/index.md)
- The division of labor between `onChange` and `onChoose`: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md#callback-signatures)



---
url: https://ooui-react.pages.dev/en/components/dropdown/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Dropdown

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Dropdown) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.DropdownWidget.html "OO.ui.DropdownWidget")

A dropdown select. The option data format is described in [Selection and options](https://ooui-react.pages.dev/en/guide/options.md).

## Basic usage

When `value` is not passed, the component remembers the selection itself, and `label` is the placeholder text shown until something is selected. `onChange` is value-first.

```tsx preview
import { useState } from "react";
import { Dropdown } from "ooui-react";

const options = [
  { value: "apple", children: "Apple" },
  { value: "orange", children: "Orange" },
  { value: "banana", children: "Banana" },
];

function App() {
  const [value, setValue] = useState<string | number>("apple");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 200 }}>
      <Dropdown options={options} value={value} onChange={setValue} label="Pick a fruit" />
      <div>Current value: {String(value)}</div>
      <Dropdown options={options} defaultValue="orange" label="Uncontrolled" />
    </div>
  );
}

export default App;
```

## Icon and label

`icon` renders at the front of the handle. `label` plays two roles: it is the handle's display text when nothing is selected, and it contributes to the combobox's accessible name.

```tsx preview
import { Dropdown } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 220 }}>
      <Dropdown
        icon="attachment"
        label="Attachment type"
        options={[
          { value: "image", children: "Image" },
          { value: "video", children: "Video" },
        ]}
      />
    </div>
  );
}

export default App;
```

## Groups and disabled items

Items without a `value` render as group headings; items with `disabled` cannot be selected. For menu-style components, `disabled` disables the **trigger** (the handle won't open, keyboard is off), while each item inside the menu is governed by its own `disabled` — see [Selection and options · Disabled](https://ooui-react.pages.dev/en/guide/options.md#disabled).

```tsx preview
import { Dropdown } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 220 }}>
      <Dropdown
        label="Grouped"
        options={[
          { children: "Common" },
          { value: "apple", children: "Apple" },
          { value: "banana", children: "Banana", disabled: true },
          { children: "Other" },
          { value: "durian", children: "Durian" },
        ]}
      />
      <Dropdown label="Fully disabled" disabled options={[{ value: "a", children: "A" }]} />
    </div>
  );
}

export default App;
```

## Keyboard and focus

- Tab focuses the handle, Enter / Space opens the menu; when open, ↑↓←→ move the highlight, Enter / Space choose and close, and Escape closes without changing the value.
- While closed but focused, navigation keys and prefix jump **change the selection directly without opening the menu** (screen-reader friendly, matching the original).
- Typing characters jumps by option text prefix (1.5 s buffer).
- Focus always stays on the handle; the highlighted item is linked via `aria-activedescendant`, and the menu itself is not in the Tab order.

:::note Differences from OOUI
With the menu open, **Space**
: the original never feeds Space to the menu — a keypress merely simulates a click that closes it; here Space shares the Enter branch and directly chooses the highlighted item (matching the ARIA convention of activating buttons with Space). While the type-ahead buffer is active, Space still counts as prefix search and does not choose.
:::
## API

| Prop           | Description                                                                                                  | Type                              | Default |
| -------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------- | ------- |
| `options`      | The option set; see [Selection and options](https://ooui-react.pages.dev/en/guide/options.md) for the format | `DropdownOptionProps[]`           | —       |
| `value`        | Current selected value (controlled; passing it enables controlled mode)                                      | `string \| number`                | —       |
| `defaultValue` | Initial selected value for uncontrolled use                                                                  | `string \| number`                | —       |
| `onChange`     | Selection-change callback (fires when the value changes)                                                     | `ChangeHandler<string \| number>` | —       |
| `label`        | Placeholder text when nothing is selected; also part of the accessible name                                  | `ReactNode`                       | —       |
| `icon`         | Icon name at the front of the handle                                                                         | `string`                          | —       |
| `disabled`     | Whether the trigger is disabled (won't open, keyboard off)                                                   | `boolean`                         | `false` |
| `tabIndex`     | Tab order; goes on the handle (the root is not focusable)                                                    | `number \| null`                  | `0`     |
| `...rest`      | Native `div` props (`className`, `id`, `data-*`, etc.) passed straight to the root                           | `HTMLAttributes<HTMLDivElement>`  | —       |

There is no `children` slot — the handle and menu are a fixed structure, and the display text comes from the selected option or `label`.

## See also

- Option data and the keyboard focus model: [Selection and options](https://ooui-react.pages.dev/en/guide/options.md)
- The inner list of the menu: [Select](https://ooui-react.pages.dev/en/components/select/index.md)
- How values flow between the component and your state: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md)



---
url: https://ooui-react.pages.dev/en/components/outline-select/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# OutlineSelect

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/OutlineSelect) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.OutlineSelectWidget.html "OO.ui.OutlineSelectWidget")

An outline select: `level` (0–2) expresses hierarchical indentation, suited to tables of contents and similar hierarchical lists.

## Basic usage

```tsx preview
import { useState } from "react";
import { OutlineSelect } from "ooui-react";

function App() {
  const [value, setValue] = useState<string | number>("intro");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 240 }}>
      <OutlineSelect
        aria-label="Document outline"
        value={value}
        onChange={setValue}
        options={[
          { value: "intro", children: "Introduction", level: 0 },
          { value: "background", children: "Background", level: 1 },
          { value: "prior", children: "Related work", level: 1 },
          { value: "method", children: "Method", level: 0 },
          { value: "dataset", children: "Dataset", level: 2 },
        ]}
      />
      <div>Current item: {String(value)}</div>
    </div>
  );
}

export default App;
```

## Levels and groups

- `level` is 0–2 (out-of-range is clamped); the theme only provides three indentation levels.
- Options without a `value` render as group headings, following the conventions in [Selection and options](https://ooui-react.pages.dev/en/guide/options.md).
- Options with icon slots support `icon` and `flags` (tinting the icon, see [Selection and options · Icons and flags](https://ooui-react.pages.dev/en/guide/options.md#icons-and-flags)).
- Keyboard: with the group focused, ↑↓←→ move the highlight and Enter chooses; Home/End/PageUp/PageDown are enabled via `handleNavigationKeys`, and `listWrapsAround` controls wrapping — exactly as in [Select](https://ooui-react.pages.dev/en/components/select/index.md).

```tsx preview
import { useState } from "react";
import { OutlineSelect } from "ooui-react";

function App() {
  const [value, setValue] = useState<string | number>("getting-started");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 240 }}>
      <OutlineSelect
        aria-label="Grouped outline"
        value={value}
        onChange={setValue}
        options={[
          { children: "Getting started" },
          { value: "getting-started", children: "Quick start", level: 1, icon: "book" },
          { value: "installation", children: "Installation", level: 1 },
          { children: "Advanced" },
          { value: "theming", children: "Theming", level: 1, icon: "palette", flags: "progressive" },
          { value: "i18n", children: "Internationalization", level: 1 },
        ]}
      />
      <div>Current: {String(value)}</div>
    </div>
  );
}

export default App;
```

## API

Inherits [Select](https://ooui-react.pages.dev/en/components/select/index.md) props (`value` / `defaultValue` / `onChange` / `disabled` / `handleNavigationKeys` / `listWrapsAround`, etc.); the differences are:

| Prop       | Description                                                                                                     | Type                         | Default |
| ---------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------- |
| `options`  | Outline option set (**required**); selectable items also support `level` (0–2 indentation) and `icon` / `flags` | `OutlineSelectOptionProps[]` | —       |
| `tabIndex` | Tab order, on the whole group (the outline list is focusable)                                                   | `number \| null`             | `0`     |

`outline` is fixed on by the component and cannot be overridden.

## See also

- The base selection list: [Select](https://ooui-react.pages.dev/en/components/select/index.md)
- Option data and the keyboard focus model: [Selection and options](https://ooui-react.pages.dev/en/guide/options.md)



---
url: https://ooui-react.pages.dev/en/components/tab-select/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# TabSelect

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/TabSelect) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.TabSelectWidget.html "OO.ui.TabSelectWidget")

A tab select: a set of mutually exclusive options shown as a row of tabs.

## Basic usage

```tsx preview
import { useState } from "react";
import { TabSelect } from "ooui-react";

const options = [
  { value: "general", children: "General" },
  { value: "advanced", children: "Advanced" },
  { value: "about", children: "About" },
];

function App() {
  const [tab, setTab] = useState<string | number>("general");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <TabSelect options={options} value={tab} onChange={setTab} aria-label="View" />
      <div>Current tab: {String(tab)}</div>
    </div>
  );
}

export default App;
```

## Framed and frameless

`framed` (on by default) gives the tab strip a bordered background; set it to `false` for a lighter frameless form.

```tsx preview
import { TabSelect } from "ooui-react";

const options = [
  { value: "a", children: "One" },
  { value: "b", children: "Two" },
  { value: "c", children: "Three", disabled: true },
];

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
      <TabSelect options={options} defaultValue="a" />
      <TabSelect options={options} defaultValue="a" framed={false} />
    </div>
  );
}

export default App;
```

## Keyboard

After a click, focus moves into the group automatically (slightly better than the original, which leaves focus where it was so the arrow keys stay dead), and ←→ (and ↑↓) then **cycle among non-disabled tabs and select directly**; Enter re-affirms the current tab. Pressing Tab also moves focus into the group. This is the direct-select family model; see [Selection and options · Keyboard and focus](https://ooui-react.pages.dev/en/guide/options.md#keyboard-and-focus).

## API

| Prop           | Description                                                                                | Type                              | Default |
| -------------- | ------------------------------------------------------------------------------------------ | --------------------------------- | ------- |
| `options`      | Tab set (**required**); each item has `value` and `children` (text), optionally `disabled` | `TabSelectOptionProps[]`          | —       |
| `value`        | Current selected value (controlled)                                                        | `string \| number`                | —       |
| `defaultValue` | Initial selected value for uncontrolled use                                                | `string \| number`                | —       |
| `onChange`     | Selected-value change callback (value-first)                                               | `ChangeHandler<string \| number>` | —       |
| `framed`       | Whether the strip has a border                                                             | `boolean`                         | `true`  |
| `disabled`     | Whether disabled (also disables every tab)                                                 | `boolean`                         | `false` |
| `tabIndex`     | Tab order (focus rests on the group)                                                       | `number \| null`                  | `0`     |
| `...rest`      | Native `div` props (`className`, `id`, `aria-*`, etc.) passed straight to the root         | `HTMLAttributes<HTMLDivElement>`  | —       |

## Differences from OOUI

- **`TabOption` does not support `href` links**: the original only used that from PHP; compose link tabs yourself if you need them. {/* deviations: dev-taboption-href */}
- **A lost mouseup no longer leaves a stale drag state**: in the original, dragging out of the window and releasing left the selecting state behind, so the next click on empty space submitted the stale option; this library resets on mousedown and cleans up on `pointercancel`. {/* deviations: dev-tabselect-drag-fix */}

## See also

- Button-style direct select: [ButtonSelect](https://ooui-react.pages.dev/en/components/button-select/index.md)
- Multiple panels with tabs: `BookletLayout`
- Option data and the keyboard focus model: [Selection and options](https://ooui-react.pages.dev/en/guide/options.md)



---
url: https://ooui-react.pages.dev/en/components/button-select/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# ButtonSelect

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ButtonSelect) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ButtonSelectWidget.html "OO.ui.ButtonSelectWidget")

A button select: a set of mutually exclusive options shown as a row of buttons. See [Selection and options](https://ooui-react.pages.dev/en/guide/options.md) for the option data format.

## Basic usage

```tsx preview
import { useState } from "react";
import { ButtonSelect } from "ooui-react";

const options = [
  { value: "left", icon: "alignLeft", children: "Align left" },
  { value: "center", icon: "alignCenter", children: "Center" },
  { value: "right", icon: "alignRight", children: "Align right" },
];

function App() {
  const [align, setAlign] = useState<string | number>("left");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <ButtonSelect options={options} value={align} onChange={setAlign} aria-label="Alignment" />
      <div>Current alignment: {String(align)}</div>
    </div>
  );
}

export default App;
```

## Unframed and disabled items

Options support `framed={false}`; items with `disabled` are not selectable, and a group-level `disabled` disables the whole group (see [Selection and options · Disabled](https://ooui-react.pages.dev/en/guide/options.md#disabled)).

```tsx preview
import { ButtonSelect } from "ooui-react";

function App() {
  return (
    <ButtonSelect
      defaultValue="a"
      options={[
        { value: "a", children: "Enabled" },
        { value: "b", children: "Unframed", framed: false },
        { value: "c", children: "Disabled", disabled: true },
        { value: "d", children: "Also enabled" },
      ]}
    />
  );
}

export default App;
```

## Keyboard

After a click, focus moves into the group automatically (slightly better than the original, which leaves focus where it was so the arrow keys stay dead), and ↑↓←→ then **cycle among non-disabled items and select directly**; Enter re-affirms the current item. Pressing Tab also moves focus into the group. This is the "direct-select family" keyboard model (shared by [TabSelect](https://ooui-react.pages.dev/en/components/tab-select/index.md) and [RadioSelect](https://ooui-react.pages.dev/en/components/radio-select/index.md)).

## API

| Prop           | Description                                                                                                                               | Type                              | Default |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
| `options`      | Option set (**required**); each item has `value` and `children` (text), optionally `icon` / `indicator` / `flags` / `framed` / `disabled` | `ButtonSelectOptionProps[]`       | —       |
| `value`        | Current selected value (controlled)                                                                                                       | `string \| number`                | —       |
| `defaultValue` | Initial selected value for uncontrolled use                                                                                               | `string \| number`                | —       |
| `onChange`     | Selected-value change callback (value-first)                                                                                              | `ChangeHandler<string \| number>` | —       |
| `disabled`     | Whether disabled (also disables every option in the group)                                                                                | `boolean`                         | `false` |
| `tabIndex`     | Tab order (focus rests on the group)                                                                                                      | `number \| null`                  | `0`     |
| `...rest`      | Native `div` props (`className`, `id`, `aria-*`, etc.) passed straight to the root                                                        | `HTMLAttributes<HTMLDivElement>`  | —       |

## Differences from OOUI

- **Initially selected framed options are inverted too**: the original inverts only after a user click while initially selected ones stay normal; this library applies the theme rule uniformly — active or disabled means inverted. {/* deviations: dev-buttonoption-invert */}

## See also

- Tab-style direct select: [TabSelect](https://ooui-react.pages.dev/en/components/tab-select/index.md)
- Radio group (native radio semantics): [RadioSelect](https://ooui-react.pages.dev/en/components/radio-select/index.md)
- Option data and the keyboard focus model: [Selection and options](https://ooui-react.pages.dev/en/guide/options.md)



---
url: https://ooui-react.pages.dev/en/components/button-menu-select/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# ButtonMenuSelectWidget

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ButtonMenuSelectWidget) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ButtonMenuSelectWidget.html "OO.ui.ButtonMenuSelectWidget")

A button-triggered command menu: choosing an item runs it and closes the menu. Unlike a [Dropdown](https://ooui-react.pages.dev/en/components/dropdown/index.md) that tracks a "current selection", it suits toolbar-style "click to run a command" cases.

## Basic usage

```tsx preview
import { useState } from "react";
import { ButtonMenuSelectWidget } from "ooui-react";

function App() {
  const [log, setLog] = useState("Nothing chosen");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, padding: 8 }}>
      <ButtonMenuSelectWidget
        icon="menu"
        indicator="down"
        options={[
          { value: "copy", children: "Copy" },
          { value: "cut", children: "Cut" },
          { value: "paste", children: "Paste" },
          { children: "Advanced" },
          { value: "selectall", children: "Select all" },
        ]}
        onChoose={(v) => setLog(`ran: ${String(v)}`)}
      >
        Actions
      </ButtonMenuSelectWidget>
      <div>{log}</div>
    </div>
  );
}

export default App;
```

## Controlled open state and keeping a selection

- `open` / `defaultOpen` / `onOpenChange` control the menu (the button, outside clicks, Escape and choosing all fire `onOpenChange`).
- `clearOnSelect` defaults to `true`: the menu is a pure command menu with no lingering selection; set it to `false` to keep the last chosen item.
- Options without a `value` render as group headings (the "Advanced" item above). See [Selection and options](https://ooui-react.pages.dev/en/guide/options.md) for the option format.

```tsx preview
import { useState } from "react";
import { ButtonMenuSelectWidget } from "ooui-react";

function App() {
  const [chosen, setChosen] = useState<string | number>("share");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 260 }}>
      <ButtonMenuSelectWidget
        icon="share"
        clearOnSelect={false}
        onChoose={(value) => setChosen(value)}
        options={[
          { value: "share", children: "Share link" },
          { value: "move", children: "Move page" },
          { value: "protect", children: "Protect page" },
        ]}
      >
        Share
      </ButtonMenuSelectWidget>
      <div>Last chosen: {String(chosen)} (kept selected in the menu)</div>
    </div>
  );
}

export default App;
```

## Keyboard

Focus is on the button: Enter / Space opens the menu; with it open, ↑↓ move the highlight, Enter / Space choose, and typed characters jump by prefix; Escape or an outside click closes it. Note that, unlike [Dropdown](https://ooui-react.pages.dev/en/components/dropdown/index.md), typing while the menu is closed and focused does not change the selection directly.

Two differences from OOUI:

- Opening with the keyboard also shows the button's pressed state — in the original, keyboard opening gets its pressed class wiped by the reset flow.
- While the type-ahead buffer is active, Space continues the search and never toggles the menu; with the menu open, Space shares the Enter branch and directly chooses the highlighted item (matching the ARIA convention of activating buttons with Space).{/* deviations: dev-bmsw-pressed dev-bmsw-gesture-guard dev-menu-space-select */}

## API

Inherits [Button](https://ooui-react.pages.dev/en/components/button/index.md) props (`icon` / `indicator` / `flags` / `framed` / `disabled`, etc.; `onClick` fires "before toggling the open state"), and adds:

| Prop            | Description                                                                                                   | Type                                  | Default |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------- |
| `options`       | Menu option set (**required**); see [Selection and options](https://ooui-react.pages.dev/en/guide/options.md) | `ButtonMenuSelectWidgetOptionProps[]` | —       |
| `open`          | Whether the menu is open (controlled)                                                                         | `boolean`                             | —       |
| `defaultOpen`   | Initial open state for uncontrolled use                                                                       | `boolean`                             | `false` |
| `onOpenChange`  | Menu open-state callback                                                                                      | `(open: boolean) => void`             | —       |
| `onChoose`      | Choose callback (fires on every choice, incl. repeats)                                                        | `ChangeHandler<string \| number>`     | —       |
| `clearOnSelect` | Whether to clear the menu's selection after choosing                                                          | `boolean`                             | `true`  |
| `menuSpacing`   | Gap between menu and button (px)                                                                              | `number`                              | `4`     |
| `menuProps`     | Menu prop overrides (`open`/`container`/`options`/`onChoose` etc. are taken over)                             | `object`                              | —       |

## See also

- A dropdown that records the current value: [Dropdown](https://ooui-react.pages.dev/en/components/dropdown/index.md)
- A general button that opens a popup: [PopupButton](https://ooui-react.pages.dev/en/components/popup-button/index.md)
- More command-menu forms: the toolbar's `MenuToolGroup`



---
url: https://ooui-react.pages.dev/en/components/checkbox-multiselect/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# CheckboxMultiselect

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/CheckboxMultiselect) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.CheckboxMultiselectWidget.html "OO.ui.CheckboxMultiselectWidget")

A checkbox group: several checkbox items in one group, multiple selections allowed.

## Basic usage

The selected value is an **array**, passed through `value` / `defaultValue` / `onChange`; `onChange` carries the full value array. With `name`, every option's checkbox shares it and the checked ones submit as multiple same-name fields.

```tsx preview
import { useState } from "react";
import { CheckboxMultiselect } from "ooui-react";

const options = [
  { value: "apple", children: "Apple" },
  { value: "banana", children: "Banana" },
  { value: "cherry", children: "Cherry" },
];

function App() {
  const [value, setValue] = useState<Array<string | number>>(["banana"]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <CheckboxMultiselect options={options} value={value} onChange={setValue} name="fruits" />
      <div>Current selection: {value.join(", ") || "(none)"}</div>
      <CheckboxMultiselect options={options} defaultValue={["apple", "cherry"]} />
    </div>
  );
}

export default App;
```

## Shift+click range selection

Click one item, then click another with `Shift` held: the range between the two clicks (both ends included) is set to the state the **second** item just flipped to; disabled items in the range keep their state. This mirrors bulk-checking in list tables.

```tsx preview
import { useState } from "react";
import { CheckboxMultiselect } from "ooui-react";

const options = [1, 2, 3, 4, 5].map((number) => ({
  value: number,
  children: `Item ${number}`,
}));

function App() {
  const [value, setValue] = useState<Array<string | number>>([]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <CheckboxMultiselect options={options} value={value} onChange={setValue} />
      <div style={{ fontSize: 13 }}>
        Current selection: {value.join(", ") || "(none)"}
      </div>
      <div style={{ color: "#54595d", fontSize: 13 }}>
        Click one item, then Shift+click another to see range selection
      </div>
    </div>
  );
}

export default App;
```

## Using it with FieldLayout

To give the whole group a field label, wrap it with [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md). Clicking the field label moves focus to the first enabled option's checkbox (it does not toggle anything — a group has no "one value for the whole group" semantics like a single checkbox does).

```tsx preview
import { CheckboxMultiselect, FieldLayout } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 320 }}>
      <FieldLayout label="Subscribed sections">
        <CheckboxMultiselect
          defaultValue={["news"]}
          options={[
            { value: "news", children: "News" },
            { value: "sports", children: "Sports" },
            { value: "tech", children: "Tech" },
          ]}
        />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## Disabled

- An option's own `disabled` skips that item (not checkable).
- Component-level `disabled` disables every option in the group, and the group state wins. See [Selection and options · Disabled](https://ooui-react.pages.dev/en/guide/options.md#disabled).

```tsx preview
import { CheckboxMultiselect } from "ooui-react";

function App() {
  return (
    <CheckboxMultiselect
      defaultValue={["a"]}
      options={[
        { value: "a", children: "Enabled" },
        { value: "b", children: "Disabled item", disabled: true },
        { value: "c", children: "Also enabled" },
      ]}
    />
  );
}

export default App;
```

## Keyboard and focus

- Every option's native `<input type="checkbox">` is in the Tab order; ↑↓←→ are an in-group shortcut — they move focus **cyclically between non-disabled items** (unlike `RadioSelect`, they only move focus and **do not select directly**), and Space toggles the current item.
- A Shift+click range starts from the item last clicked (or last toggled with Space).
- `onChange`'s second argument is the native `change` event that triggered this change.
- Option roots carry `role='checkbox'` and `aria-checked` (the original's option roots have no role and express selection only via a class), so screen readers can read each option's state directly. {/* deviations: dev-multioption-role */}

## API

| Prop           | Description                                                                                                                                                                                                                                                        | Type                                                    | Default |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | ------- |
| `options`      | The option set, rendered in display order; each item has `value` and `children` (the option text) and supports `disabled`, plus `inputRef` (ref to the inner checkbox), `checkboxProps` (passed to the inner checkbox, e.g. `inputId`) and a per-option `onChange` | `CheckboxMultiselectOptionProps[]`                      | —       |
| `value`        | Current selected values (controlled; passing it enables controlled mode)                                                                                                                                                                                           | `(string \| number)[]`                                  | —       |
| `defaultValue` | Initial selected values for uncontrolled use                                                                                                                                                                                                                       | `(string \| number)[]`                                  | `[]`    |
| `onChange`     | Selected-values change callback with the full value array and the native event                                                                                                                                                                                     | `ChangeHandler<(string \| number)[], HTMLInputElement>` | —       |
| `name`         | Form field name, passed to every option's `checkbox`                                                                                                                                                                                                               | `string`                                                | —       |
| `disabled`     | Whether disabled (also disables every option in the group)                                                                                                                                                                                                         | `boolean`                                               | `false` |
| `...rest`      | Native `div` props (`className`, `id`, `aria-*`, etc.) passed straight to the group container                                                                                                                                                                      | `HTMLAttributes<HTMLDivElement>`                        | —       |

## See also

- Option data and the keyboard focus model: [Selection and options](https://ooui-react.pages.dev/en/guide/options.md)
- A single checkbox: [CheckboxInput](https://ooui-react.pages.dev/en/components/checkbox-input/index.md)
- The checkbox group field that submits with a form: `CheckboxMultiselectInput`



---
url: https://ooui-react.pages.dev/en/components/radio-select/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# RadioSelect

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/RadioSelect) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.RadioSelectWidget.html "OO.ui.RadioSelectWidget")

A radio group: several radio items in one group, mutually exclusive with at most one selected.

## Basic usage

The selected value uses the `value` / `defaultValue` / `onChange` channels. Clearing the current selection never produces a new value — `onChange`'s argument is always the newly selected `value`.

```tsx preview
import { useState } from "react";
import { RadioSelect } from "ooui-react";

const options = [
  { value: "small", children: "Small" },
  { value: "medium", children: "Medium" },
  { value: "large", children: "Large" },
];

function App() {
  const [size, setSize] = useState<string | number>("medium");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <RadioSelect options={options} value={size} onChange={setSize} name="size" />
      <div>Current selection: {String(size)}</div>
      <RadioSelect options={options} defaultValue="large" />
    </div>
  );
}

export default App;
```

## With FieldLayout

To give the whole group a field label, wrap it with [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md); the label is associated with the group container, and clicking it focuses the group.

```tsx preview
import { RadioSelect, FieldLayout } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 320 }}>
      <FieldLayout label="Notification method">
        <RadioSelect
          name="notify"
          defaultValue="email"
          options={[
            { value: "email", children: "Email" },
            { value: "sms", children: "SMS" },
            { value: "none", children: "No notifications" },
          ]}
        />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## Disabled

- An option's own `disabled` skips that item (not selectable).
- Component-level `disabled` disables every option in the group, and the group state wins. See [Selection and options · Disabled](https://ooui-react.pages.dev/en/guide/options.md#disabled).

```tsx preview
import { RadioSelect } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
      <RadioSelect
        defaultValue="a"
        options={[
          { value: "a", children: "Enabled" },
          { value: "b", children: "Disabled item", disabled: true },
          { value: "c", children: "Also enabled" },
        ]}
      />
    </div>
  );
}

export default App;
```

## Keyboard and focus

- Focus rests on the **whole group** (individual items are not in the Tab order). ↑↓←→ move **cyclically between non-disabled items and select directly**; Enter re-affirms the current item.
- On first Tab focus to the group with nothing selected, the first non-disabled item is auto-selected (matching native radio-group behavior).
- `onChange`'s second argument is the native `change` event; changing selection via arrow keys does not fire a native `change` (matching the original), so the second argument may be absent.

## API

| Prop           | Description                                                                                   | Type                                                             | Default |
| -------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------- |
| `options`      | The option set; each item has `value` and `children` (the option text)                        | `RadioSelectOptionProps[]`                                       | —       |
| `value`        | Current selected value (controlled; passing it enables controlled mode)                       | `string \| number`                                               | —       |
| `defaultValue` | Initial selected value for uncontrolled use                                                   | `string \| number`                                               | —       |
| `onChange`     | Selected-value change callback (value-first, incl. native event)                              | `ChangeHandler<string \| number \| undefined, HTMLInputElement>` | —       |
| `name`         | Form field name, passed to each option's native `radio` (same name = mutually exclusive)      | `string`                                                         | —       |
| `disabled`     | Whether disabled (also disables every option in the group)                                    | `boolean`                                                        | `false` |
| `...rest`      | Native `div` props (`className`, `id`, `aria-*`, etc.) passed straight to the group container | `HTMLAttributes<HTMLDivElement>`                                 | —       |

## See also

- A single radio: [RadioInput](https://ooui-react.pages.dev/en/components/radio-input/index.md) (this component is built from it item by item; use it alone for custom layout)
- Option data and the keyboard focus model: [Selection and options](https://ooui-react.pages.dev/en/guide/options.md)
- The checkbox counterpart: [CheckboxMultiselect](https://ooui-react.pages.dev/en/components/checkbox-multiselect/index.md)



---
url: https://ooui-react.pages.dev/en/components/tag-multiselect/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# TagMultiselect

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/TagMultiselect) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.TagMultiselectWidget.html "OO.ui.TagMultiselectWidget")

A tag input: values are shown as removable chips. Free-entry form — for "type to filter + dropdown candidates" use [MenuTagMultiselect](https://ooui-react.pages.dev/en/components/menu-tag-multiselect/index.md).

## Basic usage

Type text in the input and press **Enter**
 to commit a tag; press **Backspace**
 (when the input is empty) at the end to remove the previous tag; **click a tag**
 to move it back into the input for editing. A tag's close button **only removes the tag**
 — it does not also trigger the select/edit flow (opening the menu in menu mode, or backfilling text in edit mode). In the original, clicks on the close button bubble into those flows; this is an intentional deviation.
Free entry requires `allowArbitrary`: matching the original, without it (and without `allowedValues`) any typed value lies outside the legal range, so Enter is rejected (no error — simply no tag). See the next section for the whitelist form.

```tsx preview
import { useState } from "react";
import { TagMultiselect } from "ooui-react";

function App() {
  const [tags, setTags] = useState<(string | number)[]>(["React", "TypeScript"]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 360 }}>
      <TagMultiselect
        value={tags}
        onChange={setTags}
        allowArbitrary
        placeholder="Press Enter to add a tag"
      />
      <div>Current tags: {tags.join(", ") || "(none)"}</div>
    </div>
  );
}

export default App;
```

## Keyboard editing

- **Enter** commits the typed text as a tag; **Backspace** (when the inline input is empty) removes the last tag and **backfills its text into the input** for editing — holding Ctrl / Cmd removes without backfilling.
- **← / →**: with the caret at either end of the input, navigation moves between tags; moving forward past the last tag hands focus back to the input (directions flip in RTL); **Escape** clears the uncommitted text in the input.

## Whitelist and limits

- `allowedValues` is the legal value range; tags outside it are invalid (unless `allowArbitrary`).
- `allowDuplicates` permits repeated values; `tagLimit` caps the tag count, disabling input once reached.
- `allowDisplayInvalidTags` keeps invalid values shown as tags (flagged invalid) rather than refusing to add them.

```tsx preview
import { useState } from "react";
import { TagMultiselect } from "ooui-react";

function App() {
  const [tags, setTags] = useState<(string | number)[]>([]);

  return (
    <div style={{ maxWidth: 360 }}>
      <TagMultiselect
        value={tags}
        onChange={setTags}
        allowedValues={["red", "green", "blue"]}
        allowDisplayInvalidTags
        tagLimit={2}
        placeholder="Only red / green / blue (invalid values kept and flagged), at most 2"
      />
    </div>
  );
}

export default App;
```

Typing something outside the range — say `purple` — and pressing Enter still creates a tag, flagged invalid (the `allowDisplayInvalidTags` effect; without it the value is refused outright); once `tagLimit` of 2 is reached the input is disabled. Note: the component's overall invalid flag (red border) is broader than `onInvalidTagsChange` — uncommitted text left in the input on blur also triggers it. If you see the red border without an `onInvalidTagsChange` callback, check for leftover text in the input first.

## Sanitizing external values: pickValidTags

The exported pure function `pickValidTags(values, { options?, allowedValues?, allowDuplicates? })`
 returns the **valid subset**
 of the given values — dropping values outside the legal range and duplicates (when `allowDuplicates`
 is off), using the same rules as the component (pass the component's own props to get a set complementary to `onInvalidTagsChange`
). Use it to sanitize tags before backfilling external data into `value`
, or before submitting. 
## Input position and reordering

`inputPosition`
 is `inline`
 (default, the input follows the last tag), `outline`
 (the input is below the tag area) or `none`
 (no input, display-only, paired with a controlled value). `allowReordering`
 (on by default) enables drag-to-reorder; when off, new tags insert according to the order in `allowedValues`
. The original allows replacing the inner input via `config.input`
 / `inputWidget`
; here the input is built in and cannot be replaced. 
```tsx preview
import { useState } from "react";
import { TagMultiselect } from "ooui-react";

function App() {
  const [tags, setTags] = useState<(string | number)[]>(["ooui", "react"]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16, maxWidth: 360 }}>
      <TagMultiselect
        value={tags}
        onChange={setTags}
        inputPosition="outline"
        placeholder="The input sits below the tag area"
      />
      <TagMultiselect defaultValue={["display", "only"]} inputPosition="none" />
    </div>
  );
}

export default App;
```

## API

| Prop                           | Description                                                           | Type                                            | Default    |
| ------------------------------ | --------------------------------------------------------------------- | ----------------------------------------------- | ---------- |
| `value`                        | Tag value set (controlled; passing it enables controlled mode)        | `(string \| number)[]`                          | —          |
| `defaultValue`                 | Initial value for uncontrolled use                                    | `(string \| number)[]`                          | —          |
| `onChange`                     | Add/remove callback (value-first, returns the scalar array)           | `ChangeHandler<(string \| number)[]>`           | —          |
| `allowedValues`                | Legal-value whitelist (the constraint without a menu)                 | `(string \| number)[]`                          | —          |
| `allowArbitrary`               | Allow arbitrary values (skips the range test)                         | `boolean`                                       | `false`    |
| `allowDuplicates`              | Allow repeated values                                                 | `boolean`                                       | `false`    |
| `allowReordering`              | Allow drag reordering                                                 | `boolean`                                       | `true`     |
| `allowEditTags`                | Allow clicking a tag to edit it in place                              | `boolean`                                       | `true`     |
| `allowDisplayInvalidTags`      | Keep invalid values shown as tags (flagged invalid)                   | `boolean`                                       | `false`    |
| `tagLimit`                     | Maximum tag count                                                     | `number`                                        | —          |
| `inputPosition`                | Input position                                                        | `'inline' \| 'outline' \| 'none'`               | `'inline'` |
| `onInvalidTagsChange`          | Invalid-tag set change callback (read-only, doesn't change the value) | `(invalidValues: (string \| number)[]) => void` | —          |
| `placeholder` / `name`         | Input placeholder / `name`                                            | `string`                                        | —          |
| `icon` / `indicator` / `flags` | Icon / indicator / flags                                              | —                                               | —          |
| `disabled`                     | Whether disabled                                                      | `boolean`                                       | `false`    |
| `...rest`                      | Native `div` props passed straight to the root                        | `HTMLAttributes<HTMLDivElement>`                | —          |

:::note Differences from OOUI
The original allows `tag.data`
 to be any object; this library always keeps a tag's identity as the scalar `value`
, so the controlled array is serializable and diffable. To carry an object with a tag, use the `data`
 field on [MenuTagMultiselect](https://ooui-react.pages.dev/en/components/menu-tag-multiselect/index.md)
 options and look it up by `value`
 in your own `options`
. 
:::
## See also

- Tag input with a candidate menu: [MenuTagMultiselect](https://ooui-react.pages.dev/en/components/menu-tag-multiselect/index.md)
- The `label` / `labelText` / `data` option convention: [Selection and options](https://ooui-react.pages.dev/en/guide/options.md#options-of-tag-inputs)



---
url: https://ooui-react.pages.dev/en/components/menu-tag-multiselect/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# MenuTagMultiselect

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/MenuTagMultiselect) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MenuTagMultiselectWidget.html "OO.ui.MenuTagMultiselectWidget")

A tag input with a candidate menu. Props match [TagMultiselect](https://ooui-react.pages.dev/en/components/tag-multiselect/index.md), plus the required `options`.

## Basic usage

Typing filters the candidates, ↑↓ moves the highlight and Enter chooses the highlighted item (with no highlight, the typed text is committed); without `allowArbitrary`, typed text outside the candidate value range is rejected (no error — simply no tag). A candidate's own `disabled` marks it as disabled — it cannot be added as a tag. See the next section for free entry.

```tsx preview
import { useState } from "react";
import { MenuTagMultiselect } from "ooui-react";

const options = [
  { value: "bold", label: "Bold", icon: "bold" },
  { value: "italic", label: "Italic", icon: "italic" },
  { value: "link", label: "Link", icon: "link" },
  { value: "image", label: "Image", icon: "image" },
];

function App() {
  const [tags, setTags] = useState<(string | number)[]>(["bold"]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 360 }}>
      <MenuTagMultiselect
        options={options}
        value={tags}
        onChange={setTags}
        placeholder="Type to filter, or pick from the menu"
      />
      <div>Selected: {tags.join(", ") || "(none)"}</div>
    </div>
  );
}

export default App;
```

## Toggle semantics and tag editing

Menu candidates are **toggle-style**
: pressing Enter / clicking an already-chosen candidate again **removes**
 that tag — the same candidate is both the add and the remove entry, and menu items with a corresponding tag show as selected (tags added by typing are marked selected as well). 
Clicking a tag behaves differently depending on `allowArbitrary`: without it, clicking a tag locates it in the menu (opens the menu and highlights the matching candidate), and [TagMultiselect](https://ooui-react.pages.dev/en/components/tag-multiselect/index.md)'s `allowEditTags` backfill-to-edit doesn't take effect; with `allowArbitrary`, clicking a tag moves its text back into the input for editing.

:::note Differences from OOUI
With `inputPosition='none'`
 (no input), clicking a tag also opens the menu and highlights the clicked candidate — the original has no path at all to open the menu in that form; keyboard navigation is not yet available once opened. 
:::
## Value range and arbitrary values

Without `allowArbitrary`, the legal range for tags is the union of `allowedValues` and each option's `value` — usually only `options` is given, i.e. you can only add candidate values. With `allowArbitrary`, you can also type free text outside the candidates as a tag. `clearInputOnChoose` (on by default) controls whether the input's filter text is cleared after choosing a menu item.

```tsx preview
import { useState } from "react";
import { MenuTagMultiselect } from "ooui-react";

function App() {
  const [tags, setTags] = useState<(string | number)[]>([]);

  return (
    <div style={{ maxWidth: 360 }}>
      <MenuTagMultiselect
        allowArbitrary
        options={[
          { value: "cat", label: "Cat" },
          { value: "dog", label: "Dog" },
        ]}
        value={tags}
        onChange={setTags}
        placeholder="Pick from candidates, or type freely and press Enter"
      />
    </div>
  );
}

export default App;
```

## Rich-content tags

An option's `label` accepts a `ReactNode`; when it is rich content (not a plain string), the plain text needed for prefix filtering and backfill must be provided explicitly via `labelText`, or that option won't participate in prefix filtering (see [Selection and options · Options of tag inputs](https://ooui-react.pages.dev/en/guide/options.md#options-of-tag-inputs)). Tags with `fixed: true` are fixed and can't be removed.

```tsx preview
import { useState } from "react";
import { MenuTagMultiselect } from "ooui-react";

function App() {
  const [tags, setTags] = useState<(string | number)[]>(["template"]);

  return (
    <div style={{ maxWidth: 320 }}>
      <MenuTagMultiselect
        value={tags}
        onChange={setTags}
        placeholder={'Type "re" to filter by prefix'}
        options={[
          {
            value: "template",
            label: (
              <>
                <b>Template</b> (regular page)
              </>
            ),
            labelText: "Template",
            fixed: true,
          },
          {
            value: "redirect",
            label: (
              <>
                <b>Redirect</b> (points to another page)
              </>
            ),
            labelText: "Redirect",
          },
        ]}
      />
    </div>
  );
}

export default App;
```

The "Template" tag comes from the `fixed: true` candidate and shows the fixed marker (no close button); typing "re" filters to the "Redirect" candidate via `labelText` and backfills the plain text.

## API

On top of all [TagMultiselect](https://ooui-react.pages.dev/en/components/tag-multiselect/index.md) props:

| Prop                 | Description                                                                                                                                         | Type                              | Default |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
| `options`            | Candidate menu option set (**required**); fields in [Selection and options](https://ooui-react.pages.dev/en/guide/options.md#options-of-tag-inputs) | `MenuTagMultiselectOptionProps[]` | —       |
| `clearInputOnChoose` | Whether to clear the filter text after choosing a menu item                                                                                         | `boolean`                         | `true`  |

## See also

- Free entry without a candidate menu: [TagMultiselect](https://ooui-react.pages.dev/en/components/tag-multiselect/index.md)
- Option data and the keyboard focus model: [Selection and options](https://ooui-react.pages.dev/en/guide/options.md)



---
url: https://ooui-react.pages.dev/en/components/button-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# ButtonInput

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ButtonInput) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ButtonInputWidget.html "OO.ui.ButtonInputWidget")

A form button: renders a real `<button>` / `<input>` element whose `type` / `name` / `value` / `formNoValidate` take part in native form submission. Use [Button](https://ooui-react.pages.dev/en/components/button/index.md) when you have no submission needs.

## Basic usage

Drop it into a [FormLayout](https://ooui-react.pages.dev/en/components/form-layout/index.md) to trigger native submission; a `type="submit"` button carries its own `name` / `value` — whichever is clicked is the one submitted.

```tsx preview
import { useState } from "react";
import { ButtonInput, FormLayout, HiddenInputWidget } from "ooui-react";

function App() {
  const [submitted, setSubmitted] = useState("");

  return (
    <FormLayout
      onSubmit={(event) => {
        event.preventDefault();
        const pairs: string[] = [];
        new FormData(event.currentTarget).forEach((value, key) => {
          pairs.push(`${key}=${value}`);
        });
        setSubmitted(pairs.join(" & "));
      }}
    >
      <HiddenInputWidget name="source" value="demo" />
      <ButtonInput type="submit" flags={["primary", "progressive"]}>
        Save
      </ButtonInput>
      <ButtonInput type="submit" name="action" value="draft" formNoValidate>
        Save draft (skip validation)
      </ButtonInput>
      {submitted && <div>Submitted: {submitted}</div>}
    </FormLayout>
  );
}

export default App;
```

## The input form

`useInputTag` renders an `<input>` instead of a `<button>`: the label text doubles as the submitted value; icons, indicators and the `value` prop are not supported (the label must be plain text).

```tsx preview
import { ButtonInput } from "ooui-react";

function App() {
  return (
    <ButtonInput type="submit" useInputTag flags={["primary", "progressive"]}>
      Save
    </ButtonInput>
  );
}

export default App;
```

## API

| Prop                        | Description                                                                                                 | Type                                                 | Default    |
| --------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------- |
| `children`                  | Button text                                                                                                 | `ReactNode`                                          | —          |
| `type`                      | Native `type` attribute                                                                                     | `'button' \| 'submit' \| 'reset'`                    | `'button'` |
| `name` / `value`            | Submitted field name and value (ignored with `useInputTag`; the `<input>`'s value is the label)             | `string`                                             | —          |
| `formNoValidate`            | Skip form validation on submit                                                                              | `boolean`                                            | `false`    |
| `useInputTag`               | Render as `<input>` instead of `<button>`                                                                   | `boolean`                                            | `false`    |
| `flags`                     | Extra flags (color and form)                                                                                | `ButtonFlag \| ButtonFlag[]`                         | `[]`       |
| `framed`                    | Whether framed                                                                                              | `boolean`                                            | `true`     |
| `active`                    | Whether in the active state                                                                                 | `boolean`                                            | `false`    |
| `icon` / `indicator`        | Icon / indicator (unsupported with `useInputTag`)                                                           | `string` / `'clear' \| 'up' \| 'down' \| 'required'` | —          |
| `invisibleLabel`            | Hide the label visually but keep it as the accessible name                                                  | `boolean`                                            | `false`    |
| `onClick`                   | Click handler (Enter/Space on the keyboard fire it too)                                                     | `(ev) => void`                                       | —          |
| `onMouseDown` / `onMouseUp` | Mouse-down / -up handlers; down enters and up resets the pressed state (not entered while disabled)         | `(ev) => void`                                       | —          |
| `onKeyDown` / `onKeyUp`     | Key-down / -up handlers; Enter / Space enter and reset the pressed state, other keys only forward the event | `(ev) => void`                                       | —          |
| `accessKey`                 | Access key (goes on the real `button` / `input`)                                                            | `string`                                             | —          |
| `disabled`                  | Whether disabled                                                                                            | `boolean`                                            | `false`    |
| `...rest`                   | Native `span` props passed straight to the root                                                             | `HTMLAttributes<HTMLSpanElement>`                    | —          |

The pressed-state class (`oo-ui-buttonElement-pressed`) shows while pressed via mouse or keyboard, matching the original.

## See also

- The button without submission semantics: [Button](https://ooui-react.pages.dev/en/components/button/index.md)
- The form container: [FormLayout](https://ooui-react.pages.dev/en/components/form-layout/index.md)
- Select fields that submit natively: [DropdownInput](https://ooui-react.pages.dev/en/components/dropdown-input/index.md)



---
url: https://ooui-react.pages.dev/en/components/dropdown-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# DropdownInput

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/DropdownInput) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.DropdownInputWidget.html "OO.ui.DropdownInputWidget")

A dropdown select field: a Dropdown handles display and interaction while an embedded hidden `<select>` carries the form submission (`name` goes on it).

## Basic usage

The value is passed through the `value` / `defaultValue` / `onChange` props. A value not among the selectable options falls back to the first selectable one, so the component always holds a valid value.

```tsx preview
import { useState } from "react";
import { ButtonInput, DropdownInput, FormLayout } from "ooui-react";

function App() {
  const [size, setSize] = useState<string | number>("m");
  const [submitted, setSubmitted] = useState("");

  return (
    <FormLayout
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(new FormData(event.currentTarget).get("size")?.toString() ?? "");
      }}
    >
      <DropdownInput
        name="size"
        value={size}
        onChange={setSize}
        options={[
          { value: "s", children: "Small" },
          { value: "m", children: "Medium" },
          { value: "l", children: "Large" },
        ]}
      />
      <ButtonInput type="submit">Submit</ButtonInput>
      <div>Current: {String(size)}; submitted: {submitted}</div>
    </FormLayout>
  );
}

export default App;
```

When the passed value isn't among the options it falls back to the first selectable one — in the example below the initial `xl` is invalid, so the select shows "Small" and submits `s` as usual:

```tsx preview
import { useState } from "react";
import { ButtonInput, DropdownInput, FormLayout } from "ooui-react";

function App() {
  const [submitted, setSubmitted] = useState("");

  return (
    <FormLayout
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(new FormData(event.currentTarget).get("size")?.toString() ?? "");
      }}
    >
      <DropdownInput
        name="size"
        defaultValue="xl"
        options={[
          { value: "s", children: "Small" },
          { value: "m", children: "Medium" },
          { value: "l", children: "Large" },
        ]}
      />
      <ButtonInput type="submit">Submit</ButtonInput>
      <div>Submitted: {submitted || "(not submitted)"}</div>
    </FormLayout>
  );
}

export default App;
```

## Grouped options

Options without `value` are group headings, mapped to `<optgroup>` elements in the hidden `<select>` (`disabled` disables the whole group).

```tsx preview
import { DropdownInput } from "ooui-react";

function App() {
  return (
    <DropdownInput
      defaultValue="apple"
      options={[
        { children: "Fruit" },
        { value: "apple", children: "Apple" },
        { value: "banana", children: "Banana" },
        { children: "Vegetables" },
        { value: "carrot", children: "Carrot" },
      ]}
    />
  );
}

export default App;
```

:::note
In the mobile form ([OOUIProvider](https://ooui-react.pages.dev/en/guide/configuration.md#mobile-mode)'s `isMobile`), the theme CSS hides the Dropdown and switches interaction to the native `<select>`, matching the original's branch.
:::

## API

| Prop           | Description                                                                                                                                                                                     | Type                                                 | Default |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------- |
| `options`      | The option set: items with `value` are selectable (`children` is the display text, `disabled` disables), items without `value` are group headings                                               | `DropdownInputOptionProps[]`                         | —       |
| `value`        | Current value (controlled; passing it enables controlled mode)                                                                                                                                  | `string \| number`                                   | —       |
| `defaultValue` | Initial value for uncontrolled use                                                                                                                                                              | `string \| number`                                   | —       |
| `onChange`     | Value change callback (the second argument is the native change event: carried on the mobile native `<select>` path; choosing from the desktop menu has no native event and passes `undefined`) | `ChangeHandler<string \| number, HTMLSelectElement>` | —       |
| `name`         | Form field name (goes on the hidden `<select>`)                                                                                                                                                 | `string`                                             | —       |
| `required`     | Required (native `required`, carried by the hidden `<select>`)                                                                                                                                  | `boolean`                                            | `false` |
| `disabled`     | Whether disabled                                                                                                                                                                                | `boolean`                                            | `false` |
| `tabIndex`     | Forwarded to the inner Dropdown's handle                                                                                                                                                        | `number`                                             | —       |
| `...rest`      | Native `div` props passed straight to the root                                                                                                                                                  | `HTMLAttributes<HTMLDivElement>`                     | —       |

## See also

- The interactive dropdown itself: [Dropdown](https://ooui-react.pages.dev/en/components/dropdown/index.md)
- The form container: [FormLayout](https://ooui-react.pages.dev/en/components/form-layout/index.md)
- The radio group field: [RadioSelectInput](https://ooui-react.pages.dev/en/components/radio-select-input/index.md)



---
url: https://ooui-react.pages.dev/en/components/checkbox-multiselect-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# CheckboxMultiselectInput

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/CheckboxMultiselectInput) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.CheckboxMultiselectInputWidget.html "OO.ui.CheckboxMultiselectInputWidget")

A checkbox group field: the form variant of [CheckboxMultiselect](https://ooui-react.pages.dev/en/components/checkbox-multiselect/index.md) — display and interaction unchanged, with each option's checkbox carrying `name` and its own `value`, so the checked ones submit natively as multiple same-name fields.

## Basic usage

The value channels match [CheckboxMultiselect](https://ooui-react.pages.dev/en/components/checkbox-multiselect/index.md): array-valued `value` / `defaultValue` / `onChange`.

```tsx preview
import { useState } from "react";
import { ButtonInput, CheckboxMultiselectInput, FormLayout } from "ooui-react";

const FRUITS = [
  { value: "apple", children: "Apple" },
  { value: "banana", children: "Banana" },
  { value: "cherry", children: "Cherry" },
];

function App() {
  const [fruits, setFruits] = useState<Array<string | number>>(["apple"]);
  const [submitted, setSubmitted] = useState("");

  return (
    <FormLayout
      onSubmit={(event) => {
        event.preventDefault();
        const values: string[] = [];
        new FormData(event.currentTarget).forEach((value, key) => {
          if (key === "fruits") {
            values.push(String(value));
          }
        });
        setSubmitted(values.join(", ") || "(none checked)");
      }}
    >
      <CheckboxMultiselectInput
        name="fruits"
        value={fruits}
        onChange={setFruits}
        options={FRUITS}
      />
      <ButtonInput type="submit">Submit</ButtonInput>
      <div>Submitted: {submitted}</div>
    </FormLayout>
  );
}

export default App;
```

:::note Performance
The mapped option set is rebuilt only when the `options` reference changes: pass a stable reference (a module constant or `useMemo`) in hot paths instead of an inline array literal.
:::

## API

Inherits all props of [CheckboxMultiselect](https://ooui-react.pages.dev/en/components/checkbox-multiselect/index.md) (`options` / `value` / `defaultValue` / `onChange` / `name` / `disabled`, etc.); no new fields.

:::note
The options' checkbox `value` is taken over by this component (written with the option's own `value` for submission), so a value passed via `options[].checkboxProps.value` is overridden.
:::

## See also

- The interactive checkbox group (Shift+click range selection, etc.): [CheckboxMultiselect](https://ooui-react.pages.dev/en/components/checkbox-multiselect/index.md)
- The radio group field: [RadioSelectInput](https://ooui-react.pages.dev/en/components/radio-select-input/index.md)
- The form container: [FormLayout](https://ooui-react.pages.dev/en/components/form-layout/index.md)



---
url: https://ooui-react.pages.dev/en/components/radio-select-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# RadioSelectInput

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/RadioSelectInput) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.RadioSelectInputWidget.html "OO.ui.RadioSelectInputWidget")

A radio group field: a [RadioSelect](https://ooui-react.pages.dev/en/components/radio-select/index.md) handles display and keyboard interaction while an embedded hidden `<input>` carries the form submission.

## Basic usage

Compared with [RadioSelect](https://ooui-react.pages.dev/en/components/radio-select/index.md): `name` is not written on each `radio` (exclusivity is guaranteed by the controlled state), and the component **always has a selection** — a value not among the selectable options falls back to the first selectable one, matching the "always one selected" semantics of HTML radio forms.

```tsx preview
import { useState } from "react";
import { ButtonInput, FormLayout, RadioSelectInput } from "ooui-react";

function App() {
  const [notify, setNotify] = useState<string | number>("email");
  const [submitted, setSubmitted] = useState("");

  return (
    <FormLayout
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(new FormData(event.currentTarget).get("notify")?.toString() ?? "");
      }}
    >
      <RadioSelectInput
        name="notify"
        value={notify}
        onChange={setNotify}
        options={[
          { value: "email", children: "Email" },
          { value: "sms", children: "SMS" },
          { value: "none", children: "No notifications" },
        ]}
      />
      <ButtonInput type="submit">Submit</ButtonInput>
      <div>Current: {String(notify)}; submitted: {submitted}</div>
    </FormLayout>
  );
}

export default App;
```

Invalid-value fallback: in the example below the initial `fax` is not among the options, so it falls back to the first selectable one ("Email") and submits `email` as usual:

```tsx preview
import { useState } from "react";
import { ButtonInput, FormLayout, RadioSelectInput } from "ooui-react";

function App() {
  const [submitted, setSubmitted] = useState("");

  return (
    <FormLayout
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(new FormData(event.currentTarget).get("notify")?.toString() ?? "");
      }}
    >
      <RadioSelectInput
        name="notify"
        defaultValue="fax"
        options={[
          { value: "email", children: "Email" },
          { value: "sms", children: "Text message" },
          { value: "none", children: "Don't notify" },
        ]}
      />
      <ButtonInput type="submit">Submit</ButtonInput>
      <div>Submitted: {submitted || "(not submitted)"}</div>
    </FormLayout>
  );
}

export default App;
```

## API

| Prop           | Description                                                                                                                                                                                                        | Type                                                | Default |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | ------- |
| `options`      | The option set; each item has `value` and `children` (the option text), `disabled` supported                                                                                                                       | `RadioSelectInputOptionProps[]`                     | —       |
| `value`        | Current value (controlled; passing it enables controlled mode)                                                                                                                                                     | `string \| number`                                  | —       |
| `defaultValue` | Initial value for uncontrolled use                                                                                                                                                                                 | `string \| number`                                  | —       |
| `onChange`     | Value change callback (the second argument is the radio's native change event, carried on click reselection; keyboard reselection and the focus auto-select update silently, matching the original, with no event) | `ChangeHandler<string \| number, HTMLInputElement>` | —       |
| `name`         | Form field name (written to the hidden `input` only)                                                                                                                                                               | `string`                                            | —       |
| `disabled`     | Whether disabled (the hidden `input` is disabled too, dropping out of submission)                                                                                                                                  | `boolean`                                           | `false` |
| `tabIndex`     | Forwarded to the inner RadioSelect's root                                                                                                                                                                          | `number`                                            | —       |
| `...rest`      | Native `div` props passed straight to the root                                                                                                                                                                     | `HTMLAttributes<HTMLDivElement>`                    | —       |

The original forwards only `data`
 and `label`
 when building options, silently dropping `options[].disabled`
; this implementation honors `disabled`
 as declared, matching [CheckboxMultiselectInput](https://ooui-react.pages.dev/en/components/checkbox-multiselect-input/index.md)
 and [DropdownInput](https://ooui-react.pages.dev/en/components/dropdown-input/index.md)
.
## See also

- The interactive radio group: [RadioSelect](https://ooui-react.pages.dev/en/components/radio-select/index.md)
- The dropdown field form: [DropdownInput](https://ooui-react.pages.dev/en/components/dropdown-input/index.md)
- The checkbox group field: [CheckboxMultiselectInput](https://ooui-react.pages.dev/en/components/checkbox-multiselect-input/index.md)



---
url: https://ooui-react.pages.dev/en/components/hidden-input-widget/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# HiddenInputWidget

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/HiddenInputWidget) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.HiddenInputWidget.html "OO.ui.HiddenInputWidget")

A hidden input: never shown, only carries a fixed value with the `<form>` on submit.

## Basic usage

`value` is a controlled value (updated with the props) and `name` is the submitted field name. The demo below intercepts the submission and prints the fields — note that the disabled hidden field is left out.

```tsx preview
import { useState } from "react";
import { ButtonInput, FieldLayout, FormLayout, HiddenInputWidget } from "ooui-react";

function App() {
  const [submitted, setSubmitted] = useState("");

  return (
    <div style={{ maxWidth: 420 }}>
      <FormLayout
        onSubmit={(event) => {
          event.preventDefault();
          const pairs: string[] = [];
          new FormData(event.currentTarget).forEach((value, key) => {
            pairs.push(`${key}=${value}`);
          });
          setSubmitted(pairs.join(" & "));
        }}
      >
        <HiddenInputWidget name="pageId" value="4711" />
        <HiddenInputWidget name="traceId" value="keep-me" />
        {/* A disabled hidden field is not submitted with the form */}
        <HiddenInputWidget name="draft" value="ignored" disabled />
        <FieldLayout label=" ">
          <ButtonInput type="submit">Submit</ButtonInput>
        </FieldLayout>
        {submitted && <div>Submitted: {submitted}</div>}
      </FormLayout>
    </div>
  );
}

export default App;
```

## Disabled

Unlike the original: the original's "disable" only toggles style classes and the hidden field is **still**
 submitted with the form; this implementation writes `disabled`
 to the native attribute, so a disabled field drops out of submission (as in the demo above). Pass `disabled`
 only when there is a submission scenario to block.
## API

| Prop       | Description                                                                            | Type                                    | Default |
| ---------- | -------------------------------------------------------------------------------------- | --------------------------------------- | ------- |
| `value`    | The hidden input's value (controlled, updated with the props)                          | `string`                                | `''`    |
| `name`     | The field name on submission                                                           | `string`                                | —       |
| `disabled` | Whether disabled (drops out of form submission)                                        | `boolean`                               | `false` |
| `...rest`  | Native `<input>` props (`id`, `className`, `data-*`, etc.) passed straight to the root | `InputHTMLAttributes<HTMLInputElement>` | —       |

This component has no wrapper element: the component `ref` and props all go on the `<input type="hidden">` itself.

## See also

- The form container: [FormLayout](https://ooui-react.pages.dev/en/components/form-layout/index.md)
- The value-channel convention: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md)



---
url: https://ooui-react.pages.dev/en/components/layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Layout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/Layout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Layout.html "OO.ui.Layout")

The layout base class: the common root of the other layout components. Used alone it only provides the `oo-ui-layout` root class and the `hidden` three-state control.

## The hidden three states

`hidden` has three states: `true` hides fully (`hidden` attribute + `aria-hidden`); `'until-found'` hides visually but stays reachable by the browser's in-page search (Ctrl+F) — when matched, the browser reveals the element itself and fires the `beforematch` event, which you can listen for on the element for custom reactions ([IndexLayout](https://ooui-react.pages.dev/en/components/index-layout/index.md)'s `openMatchedPanels` is exactly this); omitting it leaves the element visible.

```tsx preview
import { useState } from "react";
import { Button, Layout } from "ooui-react";

function App() {
  const [hidden, setHidden] = useState<boolean | "until-found">(false);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <Layout hidden={hidden}>
        <p>
          {hidden === "until-found"
            ? "Reachable by search: find this text with the browser's Ctrl+F and it is revealed"
            : "Currently visible"}
        </p>
      </Layout>
      <div style={{ display: "flex", gap: 8 }}>
        <Button onClick={() => setHidden(true)}>hidden</Button>
        <Button onClick={() => setHidden("until-found")}>until-found</Button>
        <Button onClick={() => setHidden(false)}>Unhide</Button>
      </div>
    </div>
  );
}

export default App;
```

:::note
React 18 writes any truthy `hidden` as the boolean attribute, so the component rewrites the attribute after commit to make `'until-found'` take effect; once React 19 types support it natively this workaround can go.
:::

## API

| Prop      | Description                                                                                                                                                                                         | Type                             | Default |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------- |
| `hidden`  | Whether hidden: `true` hides fully; `'until-found'` hides visually but stays reachable by in-page search                                                                                            | `boolean \| 'until-found'`       | —       |
| `...rest` | Native `div` props (`className`, `id`, `data-*`, etc.) passed straight to the root; to listen for `beforematch`, attach a native listener via a ref (React 18's types do not include the event yet) | `HTMLAttributes<HTMLDivElement>` | —       |

## See also

- The form switches built on it: [PanelLayout](https://ooui-react.pages.dev/en/components/panel-layout/index.md)
- The full application of `until-found`: [IndexLayout](https://ooui-react.pages.dev/en/components/index-layout/index.md)'s `openMatchedPanels`



---
url: https://ooui-react.pages.dev/en/components/panel-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# PanelLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/PanelLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.PanelLayout.html "OO.ui.PanelLayout")

A panel: a content container with a set of presentation switches (padding, scrolling, expansion, border), also the base of layout components such as [StackLayout](https://ooui-react.pages.dev/en/components/stack-layout/index.md).

## Basic usage

```tsx preview
import { PanelLayout } from "ooui-react";

function App() {
  return (
    <div style={{ position: "relative", height: 120 }}>
      <PanelLayout padded scrollable framed>
        <p>A padded, framed panel; a scrollbar appears when content overflows.</p>
        <p>Second paragraph.</p>
        <p>Third paragraph.</p>
        <p>Fourth paragraph.</p>
        <p>Fifth paragraph.</p>
      </PanelLayout>
    </div>
  );
}

export default App;
```

In the `expanded` form (on by default) the panel fills its parent via absolute positioning, so the parent must be positioned and sized — the outer `div` above (its `position: relative` and `height`) exists for exactly that; with an unpositioned or unsized parent, the panel expands against a further positioned ancestor (or the viewport) and looks like it "vanished". `expanded={false}` is the static form, shrinking to fit the content:

```tsx preview
import { PanelLayout } from "ooui-react";

function App() {
  return (
    <PanelLayout padded framed expanded={false}>
      Static form: does not fill the parent, shrinks to fit the content, no positioned or sized container needed.
    </PanelLayout>
  );
}

export default App;
```

Layouts built on this component, such as [StackLayout](https://ooui-react.pages.dev/en/components/stack-layout/index.md), inherit the same premise.

## API

| Prop         | Description                                                                                                    | Type                             | Default |
| ------------ | -------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------- |
| `padded`     | Whether to leave padding                                                                                       | `boolean`                        | `false` |
| `scrollable` | Whether scrollable                                                                                             | `boolean`                        | `false` |
| `expanded`   | Whether to fill the parent element                                                                             | `boolean`                        | `true`  |
| `framed`     | Whether framed                                                                                                 | `boolean`                        | `false` |
| `hidden`     | Whether hidden (three-state semantics in [Layout](https://ooui-react.pages.dev/en/components/layout/index.md)) | `boolean \| 'until-found'`       | —       |
| `...rest`    | Native `div` props (`className`, `id`, `data-*`, etc.) passed straight to the root                             | `HTMLAttributes<HTMLDivElement>` | —       |

## See also

- The `hidden` three-state semantics of the base class: [Layout](https://ooui-react.pages.dev/en/components/layout/index.md)
- The paged container built on it: [StackLayout](https://ooui-react.pages.dev/en/components/stack-layout/index.md)



---
url: https://ooui-react.pages.dev/en/components/page-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# PageLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/PageLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.PageLayout.html "OO.ui.PageLayout")

A page panel: an item of [StackLayout](https://ooui-react.pages.dev/en/components/stack-layout/index.md)'s `options` array. You rarely render it directly — put it into StackLayout's `options` instead.

## Standalone use

Standalone, the active state is declared via `active`; without `active` it derives from `hidden` (not hidden = active) and outputs the `oo-ui-pageLayout-active` class. `label` / `value` are fields carried along with the page-set object — the component takes them but never writes them as DOM attributes.

```tsx preview
import { StackLayout } from "ooui-react";

function App() {
  return (
    <StackLayout
      value="a"
      options={[
        { value: "a", label: "First page", padded: true, children: "First page content" },
        { value: "b", label: "Second page", padded: true, children: "Second page content" },
      ]}
    />
  );
}

export default App;
```

Rendered without a StackLayout, the active state is declared via `active` / `hidden` (panels default to `expanded`, filling a positioned parent; pass `expanded={false}` to place them statically):

```tsx preview
import { PageLayout } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <PageLayout active padded expanded={false}>
        Active page: declared with active, the root emits the oo-ui-pageLayout-active class
      </PageLayout>
      <PageLayout padded expanded={false} hidden>
        Hidden page: hidden derives to inactive
      </PageLayout>
    </div>
  );
}

export default App;
```

## API

Inherits all [PanelLayout](https://ooui-react.pages.dev/en/components/panel-layout/index.md) props, plus:

| Prop              | Description                                                                                                                                                                                     | Type                             | Default               |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | --------------------- |
| `active`          | Whether this is the active page; without it, derived from `hidden` (not hidden = active) — in continuous mode all pages are visible and the derivation no longer applies, so pass it explicitly | `boolean`                        | derived from `hidden` |
| `scrollable`      | Whether scrollable (pages scroll by default)                                                                                                                                                    | `boolean`                        | `true`                |
| `label` / `value` | Carried with the page-set object, taken by the component but never written as DOM attributes                                                                                                    | `ReactNode` / `string \| number` | —                     |

## See also

- The paged container: [StackLayout](https://ooui-react.pages.dev/en/components/stack-layout/index.md)



---
url: https://ooui-react.pages.dev/en/components/menu-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# MenuLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/MenuLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MenuLayout.html "OO.ui.MenuLayout")

A menu layout: a `menu` area and a content area (`children`), with the menu placed by `menuPosition`. When the menu is collapsed its subtree is not rendered, avoiding invisible focus traps.

## Basic usage

```tsx preview
import { useState } from "react";
import { MenuLayout, OutlineSelect } from "ooui-react";

function App() {
  const [section, setSection] = useState("intro");

  return (
    <div style={{ height: 200 }}>
      <MenuLayout
        menuPosition="before"
        expanded={false}
        menu={
          <OutlineSelect
            value={section}
            onChange={(value) => setSection(String(value))}
            options={[
              { value: "intro", children: "Intro" },
              { value: "usage", children: "Usage" },
            ]}
          />
        }
      >
        <div style={{ padding: 12 }}>
          {section === "intro" ? "This is the Intro content." : "This is the Usage content."}
        </div>
      </MenuLayout>
    </div>
  );
}

export default App;
```

## Menu position and collapsing

`menuPosition` takes `before` (left, default) / `after` (right) / `top` / `bottom`; `showMenu={false}` collapses the menu. `expanded` decides whether the layout fills the parent (`true`, default) or shrinks to content (`static`).

```tsx preview
import { useState } from "react";
import { MenuLayout } from "ooui-react";

const positions = ["before", "after", "top", "bottom"] as const;

function App() {
  const [position, setPosition] = useState<(typeof positions)[number]>("before");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <div style={{ display: "flex", gap: 8 }}>
        {positions.map((item) => (
          <button key={item} onClick={() => setPosition(item)}>
            {item}
          </button>
        ))}
      </div>
      <div style={{ height: 160 }}>
        <MenuLayout
          menuPosition={position}
          expanded={false}
          menu={<div style={{ padding: 12 }}>Menu area</div>}
        >
          <div style={{ padding: 12 }}>Content area</div>
        </MenuLayout>
      </div>
    </div>
  );
}

export default App;
```

:::note
The `expanded` (default) form fills the parent with absolute positioning — the parent must position and size itself; `expanded={false}` is the static form that shrinks to content (the demos above use it). Menu width and placement details come from the theme CSS. For finished components with full menu interaction, see [BookletLayout](https://ooui-react.pages.dev/en/components/booklet-layout/index.md) and [IndexLayout](https://ooui-react.pages.dev/en/components/index-layout/index.md).
:::

## API

Inherits all [Layout](https://ooui-react.pages.dev/en/components/layout/index.md) props (including the `hidden` three states), plus:

| Prop           | Description                                                           | Type                                       | Default    |
| -------------- | --------------------------------------------------------------------- | ------------------------------------------ | ---------- |
| `menu`         | The menu area content                                                 | `ReactNode`                                | —          |
| `menuPosition` | Menu position (invalid values fall back to `before`)                  | `'before' \| 'after' \| 'top' \| 'bottom'` | `'before'` |
| `showMenu`     | Whether to show the menu (the subtree is not rendered when collapsed) | `boolean`                                  | `true`     |
| `expanded`     | Whether to fill the parent (`false` is the static form)               | `boolean`                                  | `true`     |

## See also

- Finished components built from it: [BookletLayout](https://ooui-react.pages.dev/en/components/booklet-layout/index.md), [IndexLayout](https://ooui-react.pages.dev/en/components/index-layout/index.md)
- The `hidden` three-state semantics: [Layout](https://ooui-react.pages.dev/en/components/layout/index.md)



---
url: https://ooui-react.pages.dev/en/components/stack-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# StackLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/StackLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.StackLayout.html "OO.ui.StackLayout")

A stack layout: renders a set of [pages](https://ooui-react.pages.dev/en/components/page-layout/index.md) from `options`, showing only the active page at a time; with `continuous`, all pages are visible and the container scrolls. Also the inner page stack of [BookletLayout](https://ooui-react.pages.dev/en/components/booklet-layout/index.md).

## Basic usage

The active page is controlled by `value` / `defaultValue` / `onChange`; an option is a [PageLayout](https://ooui-react.pages.dev/en/components/page-layout/index.md) prop set plus `value` (which doubles as the match key and the list key).

```tsx preview
import { useState } from "react";
import { Button, StackLayout } from "ooui-react";

const options = [
  { value: "a", label: "First page", padded: true, children: "First page content" },
  { value: "b", label: "Second page", padded: true, children: "Second page content" },
];

function App() {
  const [page, setPage] = useState<string | number>("a");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <div style={{ display: "flex", gap: 8 }}>
        <Button onClick={() => setPage("a")}>First page</Button>
        <Button onClick={() => setPage("b")}>Second page</Button>
      </div>
      <div style={{ position: "relative", height: 120 }}>
        <StackLayout value={page} onChange={setPage} options={options} framed />
      </div>
    </div>
  );
}

export default App;
```

:::note Form requirement
In the `expanded` form (on by default) the layout fills its parent via absolute positioning, so the parent must be positioned and sized (the demo wrapper above exists for exactly that); the whole-container scrolling of `continuous` depends on the same requirement. The `expanded={false}` static form works only for [MenuLayout](https://ooui-react.pages.dev/en/components/menu-layout/index.md)'s own flow content — this component's pages are absolutely positioned panels with no content height in static mode, so don't use it here.
:::

When the active value is missing or stale (e.g. its page was removed), a page is auto-selected: the next surviving page, or the new last page when the last one was removed; when no value was ever given or the value is not among the options, the first usable page is taken.

## Continuous mode

`continuous` makes all pages visible with the container scrolling as one; `onPageFocus` fires when focus enters a page (without changing the active value), which you can use for scroll-linked page selection.

```tsx preview
import { useState } from "react";
import { StackLayout } from "ooui-react";

function App() {
  const [focused, setFocused] = useState("");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <div style={{ height: 140 }}>
        <StackLayout
          continuous
          framed
          onPageFocus={(value) => setFocused(String(value))}
          options={[
            { value: "a", label: "First page", padded: true, children: "First page content" },
            { value: "b", label: "Second page", padded: true, children: "Second page content" },
            { value: "c", label: "Third page", padded: true, children: "Third page content" },
          ]}
        />
      </div>
      <div>Last focused page: {focused || "(click a page to try)"}</div>
    </div>
  );
}

export default App;
```

## API

Inherits all [PanelLayout](https://ooui-react.pages.dev/en/components/panel-layout/index.md) props, plus:

| Prop           | Description                                                                                                                      | Type                                                                   | Default      |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------ |
| `options`      | The page set: [PageLayout](https://ooui-react.pages.dev/en/components/page-layout/index.md) props plus `value`                   | `(PageLayoutProps & { value: string \| number })[]`                    | —            |
| `value`        | Current active page (controlled; passing it enables controlled mode)                                                             | `string \| number`                                                     | —            |
| `defaultValue` | Initial active page for uncontrolled use                                                                                         | `string \| number`                                                     | —            |
| `onChange`     | Active-page change callback                                                                                                      | `ChangeHandler<string \| number>`                                      | —            |
| `onPageFocus`  | Fires when focus enters a page (with the page value; for focus linkage, does not change the active value)                        | `(value: string \| number, event: FocusEvent<HTMLDivElement>) => void` | —            |
| `continuous`   | Whether all pages show (`true` ignores `value`)                                                                                  | `boolean`                                                              | `false`      |
| `scrollable`   | Whether scrollable (defaults follow `continuous`: the container scrolls in continuous mode, pages scroll individually otherwise) | `boolean`                                                              | `continuous` |

## See also

- The fields of a single page: [PageLayout](https://ooui-react.pages.dev/en/components/page-layout/index.md)
- The wrapper with an outline menu: [BookletLayout](https://ooui-react.pages.dev/en/components/booklet-layout/index.md)
- The controlled-value convention: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md)



---
url: https://ooui-react.pages.dev/en/components/booklet-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# BookletLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/BookletLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.BookletLayout.html "OO.ui.BookletLayout")

A booklet layout: with `outlined`, an [outline select](https://ooui-react.pages.dev/en/components/outline-select/index.md) on the left and a [page stack](https://ooui-react.pages.dev/en/components/stack-layout/index.md) on the right; without it, a plain stacked panel. Suits settings pages and multi-section content.

## Basic usage

An `options` item is `{ value, label, children }` plus the [PageLayout](https://ooui-react.pages.dev/en/components/page-layout/index.md) panel fields; the active page is controlled through `value` / `defaultValue` / `onChange`.

```tsx preview
import { useState } from "react";
import { BookletLayout } from "ooui-react";

function App() {
  const [page, setPage] = useState<string | number>("intro");

  return (
    <div style={{ position: "relative", height: 180 }}>
      <BookletLayout
        outlined
        value={page}
        onChange={setPage}
        options={[
          { value: "intro", label: "Intro", padded: true, children: "This is the Intro page." },
          { value: "usage", label: "Usage", padded: true, children: "This is the Usage page." },
          { value: "faq", label: "FAQ", padded: true, children: "This is the FAQ page." },
        ]}
      />
    </div>
  );
}

export default App;
```

:::note Form premise
In the `expanded` form (on by default) the layout fills its parent via absolute positioning, so the parent must be positioned and sized (the demo wrapper above exists for exactly that). The `expanded={false}` static form works only for [MenuLayout](https://ooui-react.pages.dev/en/components/menu-layout/index.md)'s own flow content — the panels in the page stack are absolutely positioned panels with no content height in static mode, so don't use it here. The `editable` outline's select widget and controls are absolutely positioned in the theme CSS, likewise usable only in the expanded form.
:::

## Editable outline

`editable`
 shows move-up/move-down/remove controls at the bottom of the outline: each option declares its own `movable`
 / `removable`
 ability, the operations are handed back via `onMoveOption`
 / `onRemoveOption`
 for the caller to update `options`
, and `outlineControlsExtra`
 adds extra buttons beside them (such as "Add"). 
```tsx preview
import { useState } from "react";
import { BookletLayout, Button } from "ooui-react";

function App() {
  const [pages, setPages] = useState([
    { value: "a", label: "Section 1", movable: true, removable: true, padded: true, children: "Section 1 content" },
    { value: "b", label: "Section 2", movable: true, removable: true, padded: true, children: "Section 2 content" },
    { value: "c", label: "Section 3", movable: true, removable: true, padded: true, children: "Section 3 content" },
  ]);

  const move = (value: string | number, direction: -1 | 1) => {
    setPages((prev) => {
      const index = prev.findIndex((item) => item.value === value);
      const target = index + direction;
      if (target < 0 || target >= prev.length) {
        return prev;
      }
      const next = [...prev];
      [next[index], next[target]] = [next[target], next[index]];
      return next;
    });
  };

  return (
    <div style={{ position: "relative", height: 220 }}>
      <BookletLayout
        outlined
        editable
        defaultValue="a"
        options={pages}
        onMoveOption={move}
        onRemoveOption={(value) =>
          setPages((prev) => prev.filter((item) => item.value !== value))
        }
        outlineControlsExtra={
          <Button
            framed={false}
            icon="add"
            title="Add a section"
            onClick={() =>
              setPages((prev) => [
                ...prev,
                {
                  value: `page-${prev.length + 1}`,
                  label: `New section ${prev.length + 1}`,
                  movable: true,
                  removable: true,
                  padded: true,
                  children: "New section content",
                },
              ])
            }
          />
        }
      />
    </div>
  );
}

export default App;
```

## Continuous mode and auto-focus

`continuous` makes all pages visible and smooth-scrolls to the target page when switching; in continuous mode, focus entering a page (via Tab or clicking a focusable element inside it) conversely selects that page as the active one. `autoFocus` (default `true`) focuses the first focusable element inside the page after every switch (the first frame does not grab focus; skipped when focus is already inside the page, and suppressed in the mobile form). Both can be turned off.

When the active page is removed, a page is auto-selected: the next surviving page, or the new last page when the last one was removed — the outline and the page stack stay in sync.

## API

Inherits all [MenuLayout](https://ooui-react.pages.dev/en/components/menu-layout/index.md) props (except `menu` / `children`), plus:

| Prop                   | Description                                                                                                                                      | Type                                                    | Default |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | ------- |
| `options`              | The page set: `value`, `label`, `movable`, `removable` plus [PageLayout](https://ooui-react.pages.dev/en/components/page-layout/index.md) fields | array                                                   | —       |
| `value`                | Current active page (controlled; passing it enables controlled mode)                                                                             | `string \| number`                                      | —       |
| `defaultValue`         | Initial active page for uncontrolled use                                                                                                         | `string \| number`                                      | —       |
| `onChange`             | Active-page change callback                                                                                                                      | `ChangeHandler<string \| number>`                       | —       |
| `outlined`             | Whether to show the outline (`false` is the plain stacked mode)                                                                                  | `boolean`                                               | `false` |
| `continuous`           | Whether all pages show continuously, scrolling to the target on switch                                                                           | `boolean`                                               | `false` |
| `autoFocus`            | Focus the page's first focusable element after switching (not on the first frame)                                                                | `boolean`                                               | `true`  |
| `editable`             | Whether to show the outline controls (requires `outlined`)                                                                                       | `boolean`                                               | `false` |
| `onMoveOption`         | Move-up/down click handler in editable mode; `direction` is `-1` (up) or `1` (down)                                                              | `(value: string \| number, direction: -1 \| 1) => void` | —       |
| `onRemoveOption`       | Remove click handler in editable mode                                                                                                            | `(value: string \| number) => void`                     | —       |
| `outlineControlsExtra` | Extra button area left of the outline controls in editable mode                                                                                  | `ReactNode`                                             | —       |

## See also

- The page stack on the right: [StackLayout](https://ooui-react.pages.dev/en/components/stack-layout/index.md)
- The outline select on the left: [OutlineSelect](https://ooui-react.pages.dev/en/components/outline-select/index.md)
- The top-tabs variant: [IndexLayout](https://ooui-react.pages.dev/en/components/index-layout/index.md)



---
url: https://ooui-react.pages.dev/en/components/index-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# IndexLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/IndexLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.IndexLayout.html "OO.ui.IndexLayout")

An index layout: a [tab select](https://ooui-react.pages.dev/en/components/tab-select/index.md) on top and a stack of [tab panels](https://ooui-react.pages.dev/en/components/tab-panel-layout/index.md) below. Suits settings pages — "top tabs + chunked content"; for the side-outline variant see [BookletLayout](https://ooui-react.pages.dev/en/components/booklet-layout/index.md).

## Basic usage

An `options` item is `{ value, label, children }` plus the [TabPanelLayout](https://ooui-react.pages.dev/en/components/tab-panel-layout/index.md) panel fields (with `disabled` to disable a tab); the active tab is controlled through `value` / `defaultValue` / `onChange`. Tabs and panels are wired with `aria-controls` / `aria-labelledby` automatically.

```tsx preview
import { useState } from "react";
import { IndexLayout } from "ooui-react";

function App() {
  const [tab, setTab] = useState<string | number>("general");

  return (
    <div style={{ position: "relative", height: 180 }}>
      <IndexLayout
        framed
        value={tab}
        onChange={setTab}
        options={[
          { value: "general", label: "General", padded: true, children: "General settings" },
          { value: "appearance", label: "Appearance", padded: true, children: "Appearance settings" },
          { value: "advanced", label: "Advanced", padded: true, disabled: true, children: "Advanced settings" },
        ]}
      />
    </div>
  );
}

export default App;
```

:::note Form premise
In the `expanded` form (on by default) the layout fills its parent via absolute positioning, so the parent must be positioned and sized (the demo wrapper above exists for exactly that). The `expanded={false}` static form works only for [MenuLayout](https://ooui-react.pages.dev/en/components/menu-layout/index.md)'s own flow content — the panel stacks of this component and BookletLayout are absolutely positioned panels with no content height in static mode, so don't use it here.
:::

## Browser-search linkage

`openMatchedPanels` (default `true`) hides inactive panels with `hidden="until-found"`: when the browser's in-page search (Ctrl+F) matches content inside a hidden panel, the corresponding tab is activated automatically. **Under `continuous` all panels show at once and `openMatchedPanels` is disabled** — panels are no longer hidden with until-found and the browser-search linkage stops. `autoFocus` (default `true`) focuses the panel's first focusable element after a switch (suppressed in the mobile form).

When the active tab is removed, the first selectable (non-disabled) tab is auto-selected.

Under `continuous`, all panels are visible at once, stacked vertically (useful for printing and full-text reading):

```tsx preview
import { useState } from "react";
import { IndexLayout } from "ooui-react";

function App() {
  const [tab, setTab] = useState<string | number>("intro");

  return (
    <div style={{ position: "relative", height: 220 }}>
      <IndexLayout
        framed
        continuous
        value={tab}
        onChange={setTab}
        options={[
          { value: "intro", label: "Intro", padded: true, children: "Introduction content…" },
          { value: "usage", label: "Usage", padded: true, children: "Usage content…" },
          { value: "faq", label: "FAQ", padded: true, children: "Frequently asked questions…" },
        ]}
      />
    </div>
  );
}

export default App;
```

## API

Inherits all [MenuLayout](https://ooui-react.pages.dev/en/components/menu-layout/index.md) props (except `menu` / `menuPosition` / `children`), plus:

| Prop                | Description                                                                                                                                                                                                                  | Type                              | Default |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
| `options`           | The tab set: `value`, `label`, `disabled` plus [TabPanelLayout](https://ooui-react.pages.dev/en/components/tab-panel-layout/index.md) fields (a disabled tab's panel stays fully `hidden` regardless of `openMatchedPanels`) | `IndexLayoutTabProps[]`           | —       |
| `value`             | Current active tab (controlled; passing it enables controlled mode)                                                                                                                                                          | `string \| number`                | —       |
| `defaultValue`      | Initial active tab for uncontrolled use                                                                                                                                                                                      | `string \| number`                | —       |
| `onChange`          | Active-tab change callback                                                                                                                                                                                                   | `ChangeHandler<string \| number>` | —       |
| `framed`            | Whether the tabs are framed                                                                                                                                                                                                  | `boolean`                         | `true`  |
| `continuous`        | Whether all panels show                                                                                                                                                                                                      | `boolean`                         | `false` |
| `autoFocus`         | Focus the panel's first focusable element after switching                                                                                                                                                                    | `boolean`                         | `true`  |
| `openMatchedPanels` | Hide inactive panels with `hidden="until-found"` and switch tabs when the browser search matches (disabled under `continuous`)                                                                                               | `boolean`                         | `true`  |

## See also

- The fields of a single tab panel: [TabPanelLayout](https://ooui-react.pages.dev/en/components/tab-panel-layout/index.md)
- The side-outline variant: [BookletLayout](https://ooui-react.pages.dev/en/components/booklet-layout/index.md)
- The `hidden="until-found"` three states: [Layout](https://ooui-react.pages.dev/en/components/layout/index.md)



---
url: https://ooui-react.pages.dev/en/components/tab-panel-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# TabPanelLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/TabPanelLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.TabPanelLayout.html "OO.ui.TabPanelLayout")

A tab panel: an item of [IndexLayout](https://ooui-react.pages.dev/en/components/index-layout/index.md)'s `options` array, with `role="tabpanel"` on the root. You rarely render it directly.

## Standalone use

`active` declares the active state (outputs the `oo-ui-tabPanelLayout-active` class). `label` / `value` / `disabled` are fields carried along with the tab-set object — the component consumes them, so they are never written as DOM attributes. The panel defaults to `expanded` (fills its parent via absolute positioning), so when placed on its own it needs a positioned, sized parent.

```tsx preview
import { IndexLayout } from "ooui-react";

function App() {
  return (
    <div style={{ position: "relative", height: 180 }}>
      <IndexLayout
        defaultValue="general"
        options={[
          { value: "general", label: "General", padded: true, children: "General settings" },
          { value: "advanced", label: "Advanced", padded: true, children: "Advanced settings" },
        ]}
      />
    </div>
  );
}

export default App;
```

Rendered without an IndexLayout, the active state is declared via `active` (the root emits the `oo-ui-tabPanelLayout-active` class; panels default to `expanded`, filling a positioned parent — pass `expanded={false}` to place them statically):

```tsx preview
import { TabPanelLayout } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <TabPanelLayout active padded expanded={false}>
        General panel: declared with active, the root emits the oo-ui-tabPanelLayout-active class
      </TabPanelLayout>
      <TabPanelLayout padded expanded={false} hidden>
        Advanced panel: fully hidden while hidden
      </TabPanelLayout>
    </div>
  );
}

export default App;
```

## API

Inherits all [PanelLayout](https://ooui-react.pages.dev/en/components/panel-layout/index.md) props, plus:

| Prop                           | Description                                                | Type                                         | Default |
| ------------------------------ | ---------------------------------------------------------- | -------------------------------------------- | ------- |
| `active`                       | Whether this is the active panel                           | `boolean`                                    | `false` |
| `scrollable`                   | Whether scrollable (panels scroll by default)              | `boolean`                                    | `true`  |
| `label` / `value` / `disabled` | Carried with the tab-set object, consumed by the component | `ReactNode` / `string \| number` / `boolean` | —       |

## See also

- The tab container (with the tabpanel association): [IndexLayout](https://ooui-react.pages.dev/en/components/index-layout/index.md)



---
url: https://ooui-react.pages.dev/en/components/field-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# FieldLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/FieldLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.FieldLayout.html "OO.ui.FieldLayout")

Field layout: a container that places a field control together with its label — the basic unit inside a [FormLayout](https://ooui-react.pages.dev/en/components/form-layout/index.md).

## Basic usage

The label/control association is done automatically: an input control placed inside `FieldLayout` claims an `id`, and the label's `htmlFor` points at it, so clicking the label focuses the control and screen readers read the label. The field control itself does **not** need to set `label`.

```tsx preview
import { TextInput, FieldLayout } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 360 }}>
      <FieldLayout label="Username">
        <TextInput placeholder="Clicking the label on the left focuses here" />
      </FieldLayout>
      <FieldLayout label="Email">
        <TextInput type="email" placeholder="you@example.com" />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## Alignment

`align`
 decides how the label and control are laid out: `left`
 (default, label on the left), `right`
 (label on the right), `top`
 (label above), and `inline`
 (label and control on the same line, commonly for checkboxes and radios). Passing `inline`
 is not auto-downgraded (the original falls back to `top`
 when the field root element isn't a `span`
); make sure the field root element is inline before passing it. 
```tsx preview
import { CheckboxInput, FieldLayout, TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 360 }}>
      <FieldLayout label="Label on the left" align="left">
        <TextInput />
      </FieldLayout>
      <FieldLayout label="Label on top" align="top">
        <TextInput />
      </FieldLayout>
      <FieldLayout label="Inline (checkbox)" align="inline">
        <CheckboxInput defaultChecked />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## Label and tooltip

- `label` is the label content (`ReactNode`).
- `invisibleLabel` hides the label visually but keeps the accessible name; then `title` falls back to the label text when not given explicitly.
- `title` goes on the **label element** (matching the original `$titled = $label`), not on the layout root.
- When the field control registers its own `accessKey`, the label tooltip gets the key appended (the chord text can be localized via [OOUIProvider](https://ooui-react.pages.dev/en/guide/configuration.md)).

```tsx preview
import { FieldLayout, TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 360 }}>
      <FieldLayout label="With tooltip" title="This value is kept">
        <TextInput defaultValue="Hover the label to see the tooltip" />
      </FieldLayout>
      <FieldLayout label="Hidden label" invisibleLabel>
        <TextInput placeholder="No visible label, still read by screen readers" />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## Disabled

`FieldLayout`'s `disabled` only adds the `oo-ui-fieldLayout-disabled` style class to the layout root, giving the field area a disabled look — it **does not disable the control in `children` for you**. To actually disable it, set `disabled` on the control itself; to disable a whole group, use `FieldsetLayout`, which relies on a native `<fieldset disabled>`.

```tsx preview
import { FieldLayout, TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 360 }}>
      <FieldLayout label="Field name" disabled>
        <TextInput disabled defaultValue="The control must be disabled on its own" />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## API

| Prop             | Description                                                                        | Type                                     | Default  |
| ---------------- | ---------------------------------------------------------------------------------- | ---------------------------------------- | -------- |
| `children`       | The field control                                                                  | `ReactNode`                              | —        |
| `label`          | Label content                                                                      | `ReactNode`                              | —        |
| `invisibleLabel` | Label visually hidden (kept as accessible name)                                    | `boolean`                                | `false`  |
| `align`          | Label alignment                                                                    | `'left' \| 'right' \| 'top' \| 'inline'` | `'left'` |
| `title`          | Tooltip text for the label (goes on the label element)                             | `string`                                 | —        |
| `disabled`       | Adds a disabled style class to the layout (not passed to the control)              | `boolean`                                | `false`  |
| `...rest`        | Native `div` props (`className`, `id`, `data-*`, etc.) passed straight to the root | `HTMLAttributes<HTMLDivElement>`         | —        |

## See also

- The form container that wraps several `FieldLayout`s: [FormLayout](https://ooui-react.pages.dev/en/components/form-layout/index.md)
- Props and placement of the controls: [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md), [CheckboxInput](https://ooui-react.pages.dev/en/components/checkbox-input/index.md)
- The `disabled`, `title` and `accessKey` semantics shared by all components: [Common props](https://ooui-react.pages.dev/en/guide/basics.md)



---
url: https://ooui-react.pages.dev/en/components/fieldset-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# FieldsetLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/FieldsetLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.FieldsetLayout.html "OO.ui.FieldsetLayout")

A field set: a native `<fieldset>` with a `<legend>` header (title, icon and help entry), with the field items inside the group container. The root is a native `fieldset`, so its `disabled` natively disables every input control inside the group.

## Basic usage

```tsx preview
import { FieldLayout, FieldsetLayout, TextInput } from "ooui-react";

function App() {
  return (
    <FieldsetLayout label="Account details" icon="userAvatar">
      <FieldLayout label="Username">
        <TextInput />
      </FieldLayout>
      <FieldLayout label="Email">
        <TextInput type="email" />
      </FieldLayout>
    </FieldsetLayout>
  );
}

export default App;
```

## Help text

How `help` is presented depends on `helpInline`: `helpInline={false}` (default) renders an ⓘ icon in the header that opens a popup on click; `helpInline={true}` shows the help as inline text after the header.

```tsx preview
import { CheckboxInput, FieldLayout, FieldsetLayout } from "ooui-react";

function App() {
  return (
    <FieldsetLayout
      label="Notification preferences"
      help="Security notices are still sent when these are off."
    >
      <FieldLayout label="Product updates" align="inline">
        <CheckboxInput defaultChecked />
      </FieldLayout>
      <FieldLayout label="Community events" align="inline">
        <CheckboxInput />
      </FieldLayout>
    </FieldsetLayout>
  );
}

export default App;
```

Here the default ⓘ popup and the inline text with `helpInline={true}` appear side by side:

```tsx preview
import { FieldLayout, FieldsetLayout, TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16, maxWidth: 420 }}>
      <FieldsetLayout label="Popup help" help="Click the ⓘ icon in the header to pop up this explanation.">
        <FieldLayout label="Username">
          <TextInput />
        </FieldLayout>
      </FieldsetLayout>
      <FieldsetLayout
        label="Inline help"
        helpInline
        help="This explanation shows right after the heading, for things one sentence can cover."
      >
        <FieldLayout label="Email">
          <TextInput type="email" />
        </FieldLayout>
      </FieldsetLayout>
    </div>
  );
}

export default App;
```

## Group-level disable

`disabled` goes on the native `<fieldset>`, so every input control inside the group is disabled by the browser's own mechanism — no per-item passing needed.

```tsx preview
import { CheckboxInput, FieldLayout, FieldsetLayout, TextInput } from "ooui-react";

function App() {
  return (
    <FieldsetLayout label="Read-only group" disabled>
      <FieldLayout label="Name">
        <TextInput defaultValue="Not editable" />
      </FieldLayout>
      <FieldLayout label="Enabled" align="inline">
        <CheckboxInput checked />
      </FieldLayout>
    </FieldsetLayout>
  );
}

export default App;
```

## API

| Prop             | Description                                                     | Type                                  | Default |
| ---------------- | --------------------------------------------------------------- | ------------------------------------- | ------- |
| `label`          | The group title (legend header)                                 | `ReactNode`                           | —       |
| `icon`           | Header icon                                                     | `string`                              | —       |
| `help`           | Help text                                                       | `ReactNode`                           | —       |
| `helpInline`     | Whether help is inline (`false` renders the ⓘ popup)            | `boolean`                             | `false` |
| `invisibleLabel` | Hide the title visually but keep it as the accessible name      | `boolean`                             | `false` |
| `disabled`       | Group-level disable (propagated natively to every input inside) | `boolean`                             | `false` |
| `...rest`        | Native `fieldset` props passed straight to the root             | `HTMLAttributes<HTMLFieldSetElement>` | —       |

## See also

- Label and help for a single field: [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md)
- The form container: [FormLayout](https://ooui-react.pages.dev/en/components/form-layout/index.md)



---
url: https://ooui-react.pages.dev/en/components/form-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# FormLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/FormLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.FormLayout.html "OO.ui.FormLayout")

Form container: it renders a `<form>` wrapping several [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md)s. It does no data management itself — input controls with a `name` (`TextInput`, `CheckboxInput`, `ButtonInput`, etc.) submit natively with the `<form>`. When you don't need native submission semantics, just place the controls in your own container; you don't have to add this layer.

## Basic usage

Call `event.preventDefault()` inside `onSubmit` following React convention to stop the real navigation (the original blocks the default submit when the event listener returns `false`). The submit action is triggered by a `ButtonInput` with `type="submit"`.

```tsx preview
import { useState } from "react";
import {
  ButtonInput,
  CheckboxInput,
  FieldLayout,
  FormLayout,
  TextInput,
} from "ooui-react";

function App() {
  const [submitted, setSubmitted] = useState(false);

  return (
    <FormLayout
      method="post"
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(true);
      }}
    >
      <FieldLayout label="Username">
        <TextInput name="username" placeholder="Required" required />
      </FieldLayout>
      <FieldLayout label="I agree to the terms" align="inline">
        <CheckboxInput name="agree" value="yes" required />
      </FieldLayout>
      <FieldLayout label=" " invisibleLabel>
        <ButtonInput type="submit" flags={["primary", "progressive"]}>
          Submit
        </ButtonInput>
      </FieldLayout>
      {submitted && <div style={{ marginTop: 8 }}>Submitted (page navigation prevented)</div>}
    </FormLayout>
  );
}

export default App;
```

## Submission attributes

`method`, `action` and `enctype` pass straight through to the native `<form>`'s attributes of the same names:

| Attribute | Description                                                                       |
| --------- | --------------------------------------------------------------------------------- |
| `method`  | Submission method, native `method` (defaults to GET)                              |
| `action`  | Submission URL, native `action`                                                   |
| `enctype` | Encoding type, native `enctype` (defaults to `application/x-www-form-urlencoded`) |

:::warning Security note
This component does not sanitize `action`
 (it skips the original's `OO.ui.isSafeUrl`
 check). `<form action="javascript:...">`
 runs a script on submit, and neither the browser nor React blocks it at runtime. An `action`
 of **untrusted origin (e.g. concatenated from user input) must have its protocol validated by you or the backend first**
, otherwise this is an XSS; when you want component-level sanitizing, use the exported `sanitizeUrl`
. 
:::
## Controls that submit with the form

Native submission only carries the values of **real form controls**: the input family (`TextInput`, `MultilineTextInput`, `NumberInput`, `ComboBoxInput`, `SearchInput`), the check family (`CheckboxInput`, `RadioInput`), and `SelectFileInputWidget` / `HiddenInputWidget` render real controls — with a `name`, they submit with the form.

The display forms of the select family (`Select`, `Dropdown`, `RadioSelect`, `CheckboxMultiselect`, `TagMultiselect`, `TabSelect`, etc.) render no real form control; placed in a `FormLayout` they **silently drop their values on submit** — to submit a selection, switch to the matching form-field forms [DropdownInput](https://ooui-react.pages.dev/en/components/dropdown-input/index.md), [RadioSelectInput](https://ooui-react.pages.dev/en/components/radio-select-input/index.md) and [CheckboxMultiselectInput](https://ooui-react.pages.dev/en/components/checkbox-multiselect-input/index.md), or carry arbitrary custom values with [HiddenInputWidget](https://ooui-react.pages.dev/en/components/hidden-input-widget/index.md).

## API

| Prop       | Description                                                                                 | Type                                | Default |
| ---------- | ------------------------------------------------------------------------------------------- | ----------------------------------- | ------- |
| `children` | The field set (usually several `FieldLayout`s)                                              | `ReactNode`                         | —       |
| `method`   | Submission method (native `method`)                                                         | `string`                            | —       |
| `action`   | Submission URL (native `action`, not sanitized)                                             | `string`                            | —       |
| `enctype`  | Encoding type (native `enctype`)                                                            | `string`                            | —       |
| `onSubmit` | Submit handler; call `event.preventDefault()` inside it to stop the default navigation      | `FormEventHandler<HTMLFormElement>` | —       |
| `...rest`  | Native `form` props (`className`, `id`, `name`, `aria-*`, etc.) passed straight to the root | `HTMLAttributes<HTMLFormElement>`   | —       |

## See also

- Layout for fields and labels: [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md)
- Input controls that submit with the form: [TextInput](https://ooui-react.pages.dev/en/components/text-input/index.md), [CheckboxInput](https://ooui-react.pages.dev/en/components/checkbox-input/index.md)
- Bundle output and SSR limits: see [Usage](https://ooui-react.pages.dev/en/guide/usage.md)



---
url: https://ooui-react.pages.dev/en/components/action-field-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# ActionFieldLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/ActionFieldLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ActionFieldLayout.html "OO.ui.ActionFieldLayout")

A field layout with an action button: built on [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md) with an extra `button` slot beside the field control (usually a [Button](https://ooui-react.pages.dev/en/components/button/index.md) or a [ButtonInput](https://ooui-react.pages.dev/en/components/button-input/index.md)).

## Basic usage

```tsx preview
import { useState } from "react";
import { ActionFieldLayout, Button, TextInput } from "ooui-react";

function App() {
  const [tags, setTags] = useState<string[]>(["ooui"]);

  return (
    <div style={{ maxWidth: 420 }}>
      <ActionFieldLayout
        label="Add tag"
        button={
          <Button
            flags={["primary", "progressive"]}
            onClick={() => setTags((prev) => [...prev, prev.length.toString()])}
          >
            Add
          </Button>
        }
      >
        <TextInput placeholder="Type and add" />
      </ActionFieldLayout>
      <div style={{ marginTop: 8 }}>Added: {tags.join(", ")}</div>
    </div>
  );
}

export default App;
```

## Inline controls

When the field control is a span-rooted inline control (such as `CheckboxInput`
 or `ButtonInput`
), pass `fieldInline`
 so the input wrapper renders as a `span`
. Passing it wrongly has no visual consequence (the theme CSS normalizes both wrappers' layout); it only keeps the DOM shape aligned with the original. 
## API

Inherits all [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md) props (`label` / `align` / `title`, etc.), plus:

| Prop          | Description                                                                                            | Type        | Default |
| ------------- | ------------------------------------------------------------------------------------------------------ | ----------- | ------- |
| `button`      | The button control beside the field                                                                    | `ReactNode` | —       |
| `fieldInline` | Whether the field control is a span-rooted inline control (decides the input wrapper: `span` vs `div`) | `boolean`   | `false` |

## See also

- Field arrangement and label wiring: [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md)
- The finished read-only field with a copy button: [CopyTextLayout](https://ooui-react.pages.dev/en/components/copy-text-layout/index.md)



---
url: https://ooui-react.pages.dev/en/components/copy-text-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# CopyTextLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/CopyTextLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.CopyTextLayout.html "OO.ui.CopyTextLayout")

A copy-text layout: a read-only field with a copy button; the text is selected automatically when the field gains focus or the button is clicked. Suits read-only content the user needs to copy — links, embed codes and the like.

## Basic usage

`copyText` is the text to copy (the field's initial value); `onCopyResult` fires when the copy attempt ends, with whether it succeeded.

```tsx preview
import { useState } from "react";
import { CopyTextLayout } from "ooui-react";

function App() {
  const [result, setResult] = useState("");

  return (
    <div style={{ maxWidth: 460 }}>
      <CopyTextLayout
        label="Invite link"
        copyText="https://example.com/invite/9f3k"
        onCopyResult={(copied) => setResult(copied ? "Copied" : "Copy failed")}
      />
      <div style={{ marginTop: 8 }}>{result}</div>
    </div>
  );
}

export default App;
```

## Dynamic text

`copyText` serves only as the field's **initial value**, and what gets copied is the field's current value. For share links that change with the user's choices, pass the controlled value via `textInputProps={{ value }}` (it wins over `copyText`) — updating `copyText` alone won't refresh the field.

```tsx preview
import { useState } from "react";
import { Button, CopyTextLayout } from "ooui-react";

function App() {
  const [id, setId] = useState("9f3k");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 460 }}>
      <CopyTextLayout label="Invite link" textInputProps={{ value: `https://example.com/invite/${id}` }} />
      <Button onClick={() => setId(Math.random().toString(36).slice(2, 6))}>New link</Button>
    </div>
  );
}

export default App;
```

## Multiline

`multiline` switches the field to the multi-line form and moves the copy button below, aligned right.

```tsx preview
import { CopyTextLayout } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 460 }}>
      <CopyTextLayout
        label="Embed code"
        multiline
        copyText={"<script src=\"https://example.com/widget.js\"></script>"}
        textInputProps={{ rows: 3 }}
      />
    </div>
  );
}

export default App;
```

:::note Differences from OOUI
Copying prefers `navigator.clipboard`
, falling back to `document.execCommand('copy')`
 when unavailable or permission-denied (the original uses only the latter, a deprecated API that fails silently). 
:::
## API

Inherits all [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md) props (`label` / `align` / `title`, etc.), plus:

| Prop             | Description                                                                                                                                     | Type                           | Default |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------- |
| `copyText`       | The text to copy (the field's initial value; `textInputProps.value` wins when given)                                                            | `string`                       | —       |
| `multiline`      | Whether multi-line (uses MultilineTextInput, button moves below-right)                                                                          | `boolean`                      | `false` |
| `textInputProps` | Field props override: `value` is the controlled value, `readOnly` defaults to `true`, the rest pass through (`inputRef` is taken by the layout) | `CopyTextLayoutTextInputProps` | —       |
| `buttonProps`    | Copy-button props override (`children` is the button text, `icon` defaults to `'copy'`)                                                         | `Partial<ButtonProps>`         | —       |
| `onCopyResult`   | Copy-finished callback with whether it succeeded                                                                                                | `(copied: boolean) => void`    | —       |

## See also

- Field arrangement and label wiring: [FieldLayout](https://ooui-react.pages.dev/en/components/field-layout/index.md)
- A plain action button beside an input field: [ActionFieldLayout](https://ooui-react.pages.dev/en/components/action-field-layout/index.md)



---
url: https://ooui-react.pages.dev/en/components/horizontal-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# HorizontalLayout

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/HorizontalLayout) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.HorizontalLayout.html "OO.ui.HorizontalLayout")

A horizontal container: it only outputs the `oo-ui-horizontalLayout` root class and leaves the arrangement to the theme CSS; write your own styles (or a plain `div`) when you need exact spacing control.

## Basic usage

```tsx preview
import { Button, HorizontalLayout, TextInput } from "ooui-react";

function App() {
  return (
    <HorizontalLayout>
      <TextInput placeholder="Search…" />
      <Button flags="primary">Search</Button>
    </HorizontalLayout>
  );
}

export default App;
```

## API

Inherits every prop of [Layout](https://ooui-react.pages.dev/en/components/layout/index.md) (including the `hidden` three states).

## See also

- The `hidden` three-state semantics of the base class: [Layout](https://ooui-react.pages.dev/en/components/layout/index.md)



---
url: https://ooui-react.pages.dev/en/components/dialog/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Dialog

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/dialogs) | [Original components](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Dialog.html "OO.ui.Dialog") · [OO.ui.MessageDialog](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MessageDialog.html "OO.ui.MessageDialog")

The dialog component, with variants such as `MessageDialog` and `ProcessDialog`.

Imperative `confirm` / `alert` / `prompt` that don't depend on the React tree are covered in [Imperative dialogs](https://ooui-react.pages.dev/en/components/imperative-dialogs/index.md).

## MessageDialog

A message (`children`) plus an OK / Cancel pair at the bottom. You control `open` and close it in `onOk` / `onCancel`. `cancelLabel={null}` hides the cancel button (so you can roll your own controlled `alert`). The action area switches to a vertical layout automatically when the buttons don't fit horizontally.

```tsx preview
import { useState } from "react";
import { Button, MessageDialog } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button flags="destructive" onClick={() => setOpen(true)}>
        Delete
      </Button>
      <MessageDialog
        open={open}
        title="Delete page"
        size="small"
        okLabel="Delete"
        cancelLabel="Keep"
        onOk={() => setOpen(false)}
        onCancel={() => setOpen(false)}
      >
        Deletion cannot be undone. Continue?
      </MessageDialog>
    </>
  );
}

export default App;
```

`MessageDialog` focuses the OK button once ready; Ctrl / Cmd + Enter is equivalent to clicking OK.

With `cancelLabel={null}` hiding the cancel button you get the single-button form — rolling your own controlled `alert` (remember to wire ESC in `onEscape`):

```tsx preview
import { useState } from "react";
import { Button, MessageDialog } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Show result</Button>
      <MessageDialog
        open={open}
        title="All done"
        okLabel="Got it"
        cancelLabel={null}
        onOk={() => setOpen(false)}
        onEscape={() => setOpen(false)}
      >
        The page has been moved to the recycle bin.
      </MessageDialog>
    </>
  );
}

export default App;
```

**ESC fires only `onEscape`** (`escapable` on by default): with only `onOk` / `onCancel` wired, pressing ESC won't close the dialog — wire the close in `onEscape` yourself (the imperative `confirm` internally maps `onEscape` to "cancel").

When you need three or more actions (e.g. "OK / Cancel / Remind me later"), pass `foot` to replace the default action area entirely: you own the action layout and the close wiring; the OK button is then no longer focused automatically — focus it yourself in `onReady`.

## The Dialog base class

Use `Dialog` when you need full control over the content: `children` is the body and `foot` is the bottom action area (`head` is mainly for subclasses that carry a layout class; a bare base dialog's body starts at the top and doesn't make room for `head` automatically). It presumes no buttons — you wire the close timing and callbacks yourself; when there are bottom actions, use `bodyFitFoot` so the body yields height to `foot`.

:::warning Differences from OOUI
A bare `Dialog`
 has no built-in title slot: render the title yourself and associate it with the dialog via `aria-labelledby`
 — omitting it yields an unnamed `role="dialog"`
 (the original base class establishes this association automatically). 
:::
```tsx preview
import { useState } from "react";
import { Button, Dialog, FieldLayout, TextInput } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);
  const [name, setName] = useState("");

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open custom dialog</Button>
      <Dialog
        open={open}
        size="medium"
        bodyFitFoot
        onEscape={() => setOpen(false)}
        foot={
          <div style={{ display: "flex", gap: 8 }}>
            <Button onClick={() => setOpen(false)}>Cancel</Button>
            <Button flags="primary" onClick={() => setOpen(false)}>
              Done
            </Button>
          </div>
        }
      >
        <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
          <strong>Rename entry</strong>
          <FieldLayout label="New name">
            <TextInput value={name} onChange={setName} />
          </FieldLayout>
        </div>
      </Dialog>
    </>
  );
}

export default App;
```

## Sizes

`size` is `small` / `medium` / `large` / `larger` / `full` (`Dialog` defaults to `medium`, `MessageDialog` to `small`). Non-`full` dialogs grow with their content and center vertically; when the chosen width doesn't fit the viewport, they become fullscreen automatically. `full` is always fullscreen.

## Multiple dialogs and background isolation

Opening several dialogs at once **requires no queueing**: each dialog carries its own manager container, stacking follows DOM order (later ones on top), and which one closes is decided by its own `open` state — stacking a confirm above a process dialog is legitimate.

While a dialog is open, sibling nodes off the path to the topmost dialog get `aria-hidden="true"`
 and `inert`
, keeping screen readers and pointer / focus inside the dialog; this is undone on close. **Do not declare React's `inert` prop on background nodes you render yourself**
 (supported as a prop since React 19): isolation removal strips the DOM attribute directly, which desynchronizes React's DOM. Floating layers opened inside a dialog (`Popup`
, toolbar panels) portal into the owning dialog's container at the same level, so stacking stays correct. 
## API

### MessageDialog

Inherits `Dialog`'s `open` / `size` / `escapable` / `onEscape` / `onReady`, and adds:

| Prop                      | Description                                                                                                                                 | Type                  | Default            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------ |
| `children`                | The body message                                                                                                                            | `ReactNode`           | —                  |
| `title`                   | Title                                                                                                                                       | `ReactNode`           | —                  |
| `okLabel` / `cancelLabel` | OK / Cancel button text (`cancelLabel={null}` hides Cancel)                                                                                 | `ReactNode`           | localized defaults |
| `foot`                    | Custom bottom action area, replacing the default OK / Cancel buttons entirely (the OK button is no longer focused automatically when given) | `ReactNode`           | —                  |
| `onOk` / `onCancel`       | Fired on OK (or Ctrl/Cmd+Enter) / Cancel                                                                                                    | `() => void`          | —                  |
| `size`                    | Dialog size                                                                                                                                 | `DialogProps["size"]` | `'small'`          |

### Dialog

| Prop               | Description                                                     | Type                                                   | Default    |
| ------------------ | --------------------------------------------------------------- | ------------------------------------------------------ | ---------- |
| `open`             | Whether open (controlled, required)                             | `boolean`                                              | —          |
| `size`             | Dialog size                                                     | `'small' \| 'medium' \| 'large' \| 'larger' \| 'full'` | `'medium'` |
| `children`         | Body-area content                                               | `ReactNode`                                            | —          |
| `head` / `foot`    | Head / bottom action area                                       | `ReactNode`                                            | —          |
| `overlay`          | Overlay content covering the whole dialog (e.g. an error panel) | `ReactNode`                                            | —          |
| `contentClassName` | Extra class for the `children` content container                | `string`                                               | —          |
| `escapable`        | Whether ESC can trigger close                                   | `boolean`                                              | `true`     |
| `onEscape`         | Fired on ESC (the caller is responsible for closing)            | `() => void`                                           | —          |
| `onPrimaryAction`  | Fired on Ctrl / Cmd + Enter                                     | `() => void`                                           | —          |
| `onReady`          | Fired after the opening animation ends (to focus, etc.)         | `() => void`                                           | —          |
| `...rest`          | Native `div` props passed straight to the dialog root           | `HTMLAttributes<HTMLDivElement>`                       | —          |

`ProcessDialog` (multi-step flow, error panel and custom action buttons) extends `Dialog`; see its component page.

## See also

- Function-style calls without the React tree: [Imperative dialogs](https://ooui-react.pages.dev/en/components/imperative-dialogs/index.md)
- Why dialogs must be controlled and the callback division of labor: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md#dialogs-must-be-controlled)
- The multi-step dialog: [ProcessDialog](https://ooui-react.pages.dev/en/components/process-dialog/index.md)
- Global config (language, direction, popup container): [OOUIProvider](https://ooui-react.pages.dev/en/guide/configuration.md)



---
url: https://ooui-react.pages.dev/en/components/imperative-dialogs/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Imperative dialogs

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/dialogs) | [Original API](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.html "OO.ui.confirm / alert / prompt")

`confirm` / `alert` / `prompt` are three standalone functions — import and `await` them from any event callback: no hook, no component to mount, no React tree required. For fully custom dialogs use the [Dialog](https://ooui-react.pages.dev/en/components/dialog/index.md) component.

## Basic usage

`confirm` returns a `Promise<boolean>` (OK → `true`, Cancel / ESC → `false`); `alert` returns a `Promise<void>`; `prompt` returns a `Promise<string | null>` (Cancel / ESC → `null`).

```tsx preview
import { useState } from "react";
import { Button, alert, confirm, prompt } from "ooui-react";

function App() {
  const [log, setLog] = useState("No action yet");
  const note = (s: string) => setLog(s);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
        <Button onClick={() => alert("Your changes have been saved.", { title: "Done" })}>
          alert
        </Button>
        <Button
          onClick={() =>
            confirm("Delete this record?", { title: "Confirm delete" }).then((ok) =>
              note(ok ? "Confirmed" : "Cancelled"),
            )
          }
        >
          confirm
        </Button>
        <Button
          onClick={() =>
            prompt("Enter your name:", { textInput: { defaultValue: "" } }).then((v) =>
              note(v === null ? "Cancelled" : `Hello, ${v}`),
            )
          }
        >
          prompt
        </Button>
      </div>
      <div>{log}</div>
    </div>
  );
}

export default App;
```

## Config inheritance

A dialog called inside an `OOUIProvider`
 subtree inherits that Provider's language, direction and popup container settings; unwrapped, it renders with defaults. For overriding message text, see [OOUIProvider · Imperative dialogs](https://ooui-react.pages.dev/en/guide/configuration.md#imperative-dialogs)
. 
## Runtime semantics

- **The Promise resolves after the close animation finishes** (plus a \~50ms margin), not at the instant of the button click — code right after `await confirm(...)` that reads the DOM or navigates waits for the animation first.
- The dialog renders inside the app's React tree and inherits all context of its subtree; **with nested `OOUIProvider`s, the outermost host renders all imperative dialogs**.
- Repeated calls **stack multiple dialogs**, each independently interactive; the original shares one single-window manager, where a second call while a window is open is rejected and its Promise never settles. {/* deviations: dev-imperative-no-queue */}
- In `prompt`, pressing Enter in the input equals clicking OK (except during IME composition; `textInput.onKeyDown` can veto with `preventDefault`); the input is focused automatically once ready (`textInput.inputRef` is taken internally and passing it has no effect; `textInput.value` is only the initial value). {/* deviations: dev-prompt-textinput-value */}

## API

| Function                     | Returns                   | Notes                                               |
| ---------------------------- | ------------------------- | --------------------------------------------------- |
| `confirm(message, options?)` | `Promise<boolean>`        | OK `true`, Cancel / ESC `false`                     |
| `alert(message, options?)`   | `Promise<void>`           | OK button only, resolves on close                   |
| `prompt(message, options?)`  | `Promise<string \| null>` | OK resolves the input, Cancel / ESC resolves `null` |

`options` (`ConfirmAlertOptions` / `AlertOptions` / `PromptOptions`):

| Prop          | Description                                                            | Type                  |
| ------------- | ---------------------------------------------------------------------- | --------------------- |
| `title`       | Dialog title                                                           | `ReactNode`           |
| `okLabel`     | OK button text                                                         | `ReactNode`           |
| `cancelLabel` | Cancel button text (`confirm` / `prompt` only)                         | `ReactNode`           |
| `size`        | Dialog size                                                            | `DialogProps["size"]` |
| `textInput`   | Input props (`prompt` only); `value` is used only as the initial value | `TextInputProps`      |

## See also

- The dialog components themselves (controlled `open`, action areas, multi-dialog isolation): [Dialog](https://ooui-react.pages.dev/en/components/dialog/index.md)
- How imperative dialogs inherit provider config: [OOUIProvider](https://ooui-react.pages.dev/en/guide/configuration.md#imperative-dialogs)
- The multi-step dialog: [ProcessDialog](https://ooui-react.pages.dev/en/components/process-dialog/index.md)



---
url: https://ooui-react.pages.dev/en/components/process-dialog/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# ProcessDialog

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/dialogs/ProcessDialog) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ProcessDialog.html "OO.ui.ProcessDialog")

A multi-step process dialog with an action area and an error panel, extending the [Dialog](https://ooui-react.pages.dev/en/components/dialog/index.md) base class.

## Basic usage

Actions are declared in the `actions` array: **each special-action class takes only the first visible action** — the first visible action with the `safe` flag sits on the left of the header (cancel/close style), the first visible one with `primary` sits on the right (continue/save style), and all the remaining actions (including second and further `safe` / `primary` ones) line up in the footer action area; actions with `close` / `back` flags render as icon-only buttons.

`onAction` receives the action's `action` name; while the returned `Promise` is running, the header shows pending stripes, and the flow ends when it settles.

```tsx preview
import { useState } from "react";
import { Button, ProcessDialog } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);
  const [savedAt, setSavedAt] = useState("");

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open process dialog</Button>
      <ProcessDialog
        open={open}
        title="Edit entry"
        onEscape={() => setOpen(false)}
        actions={[
          { action: "cancel", label: "Cancel", flags: "safe" },
          { action: "save", label: "Save", flags: ["primary", "progressive"] },
        ]}
        onAction={(action) => {
          if (action === "cancel") {
            setOpen(false);
            return;
          }
          // Returning a Promise: pending stripes show in the header while it runs
          return new Promise<void>((resolve) => {
            setTimeout(() => {
              setSavedAt(new Date().toLocaleTimeString());
              setOpen(false);
              resolve();
            }, 1200);
          });
        }}
      >
        <div style={{ padding: 12 }}>
          Put your form or content here. {savedAt && `Last saved at ${savedAt}`}
        </div>
      </ProcessDialog>
    </>
  );
}

export default App;
```

## Multi-step flows

The remaining actions line up in the bottom action area; actions with the `close` / `back` flag render as icon-only buttons:

```tsx preview
import { useState } from "react";
import { Button, ProcessDialog } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);
  const [log, setLog] = useState<string[]>([]);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open multi-action dialog</Button>
      <ProcessDialog
        open={open}
        title="Edit entry"
        onEscape={() => setOpen(false)}
        actions={[
          { action: "cancel", label: "Cancel", flags: "safe" },
          { action: "save", label: "Save", flags: ["primary", "progressive"] },
          { action: "preview", label: "Preview" },
          { action: "discard", label: "Discard changes", flags: "destructive" },
          { action: "back", label: "Go back", flags: "back" },
        ]}
        onAction={(action) => {
          if (action === "cancel" || action === "save") {
            setOpen(false);
            return;
          }
          setLog((prev) => [`clicked ${action}`, ...prev].slice(0, 3));
        }}
      >
        <div style={{ padding: 12 }}>safe / primary sit in the header; the rest and the icon buttons sit at the bottom.</div>
      </ProcessDialog>
      <div>Recent clicks: {log.join(", ") || "(none)"}</div>
    </>
  );
}

export default App;
```

Once `mode` is passed, only actions whose `modes` include the current mode stay visible (actions without `modes` are hidden too); without `mode`, all actions are visible. Switch it with state and you have a wizard.

```tsx preview
import { useState } from "react";
import { Button, ProcessDialog } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);
  const [mode, setMode] = useState("edit");

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open wizard dialog</Button>
      <ProcessDialog
        open={open}
        mode={mode}
        title={mode === "edit" ? "Edit" : "Preview"}
        onEscape={() => setOpen(false)}
        actions={[
          { action: "back", label: "Back", flags: "back", modes: ["preview"] },
          { action: "cancel", label: "Cancel", flags: "safe", modes: ["edit"] },
          {
            action: "next",
            label: "Next",
            flags: ["primary", "progressive"],
            modes: ["edit"],
          },
          { action: "save", label: "Save", flags: ["primary", "progressive"], modes: ["preview"] },
        ]}
        onAction={(action) => {
          if (action === "next") {
            setMode("preview");
          } else if (action === "back") {
            setMode("edit");
          } else if (action === "cancel") {
            setOpen(false);
          }
        }}
      >
        <div style={{ padding: 12 }}>
          {mode === "edit" ? "Step 1: fill in the content" : "Step 2: review and save"}
        </div>
      </ProcessDialog>
    </>
  );
}

export default App;
```

## Error panel

When the `onAction` Promise rejects with an error object (or an array of them), a panel covering the whole dialog opens (other reject values — a plain `Error` or string — are normalized to a recoverable error carrying only the `message`):

- The error object is `{ message, recoverable?, warning? }` (type `ProcessDialogErrorProps`); `recoverable` defaults to `true` and the panel shows a **Retry** button (re-runs the most recently executed action).
- Errors with `warning: true` render as warning messages and the button reads Continue.
- With `recoverable: false`, the triggered action is disabled (until the dialog closes) and the panel can only be left via Dismiss.
- The error panel collapses automatically before each action runs.

```tsx preview
import { useState } from "react";
import { Button, ProcessDialog } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);
  const [failNext, setFailNext] = useState(true);

  return (
    <>
      <Button
        onClick={() => {
          setFailNext(true);
          setOpen(true);
        }}
      >
        Open (first save fails)
      </Button>
      <ProcessDialog
        open={open}
        title="Upload attachment"
        onEscape={() => setOpen(false)}
        actions={[
          { action: "cancel", label: "Cancel", flags: "safe" },
          { action: "save", label: "Save", flags: ["primary", "progressive"] },
        ]}
        onAction={(action) => {
          if (action === "cancel") {
            setOpen(false);
            return;
          }
          return new Promise<void>((resolve, reject) => {
            setTimeout(() => {
              if (failNext) {
                setFailNext(false);
                reject([{ message: "Saving failed: network timeout, please retry", recoverable: true }]);
              } else {
                setOpen(false);
                resolve();
              }
            }, 800);
          });
        }}
      >
        <div style={{ padding: 12 }}>
          Click "Save" to trigger a failure; one Retry in the panel succeeds.
        </div>
      </ProcessDialog>
    </>
  );
}

export default App;
```

## Keyboard

- `Ctrl` / `Cmd` + `Enter` runs the primary action.
- `ESC` triggers `onEscape`; the caller handles closing.

## API

Inherits `open` / `size` / `escapable` / `onReady` and the rest from [Dialog](https://ooui-react.pages.dev/en/components/dialog/index.md); `title` / `head` / `foot` / `bodyFitFoot` are taken over by this component, and `onPrimaryAction` is taken over to run the primary action.

| Prop        | Description                                                                                                                                  | Type                                        | Default |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------- |
| `open`      | Whether the dialog is open (controlled, required)                                                                                            | `boolean`                                   | —       |
| `title`     | Dialog title (auto-associated via `aria-labelledby`)                                                                                         | `ReactNode`                                 | —       |
| `actions`   | The action set                                                                                                                               | `ProcessDialogActionProps[]`                | `[]`    |
| `mode`      | Current mode; when passed, only actions whose `modes` include it are visible                                                                 | `string`                                    | —       |
| `onAction`  | Action handler; pending stripes show in the header while the returned `Promise` runs, and rejecting with error objects opens the error panel | `(action: string) => Promise<void> \| void` | —       |
| `onEscape`  | Triggered on `ESC` (the caller closes the dialog)                                                                                            | `() => void`                                | —       |
| `escapable` | Whether `ESC` may trigger closing                                                                                                            | `boolean`                                   | `true`  |
| `children`  | Body content                                                                                                                                 | `ReactNode`                                 | —       |
| `...rest`   | Remaining `Dialog` props (`size`, `onReady`, etc.) and native `div` props                                                                    | —                                           | —       |

Items of the `actions` array (`ProcessDialogActionProps`):

| Prop       | Description                                                               | Type                         | Default |
| ---------- | ------------------------------------------------------------------------- | ---------------------------- | ------- |
| `action`   | The action name (passed to `onAction`)                                    | `string`                     | —       |
| `label`    | Button text (replaced by an icon when `flags` include `close` / `back`)   | `ReactNode`                  | —       |
| `flags`    | Button flags; `safe` / `primary` also decide the special header positions | `ButtonFlag \| ButtonFlag[]` | —       |
| `modes`    | Visible modes; once declared, the action shows only when `mode` matches   | `string[]`                   | —       |
| `disabled` | Whether disabled                                                          | `boolean`                    | `false` |
| `pending`  | Whether this action's button is pending (striped overlay)                 | `boolean`                    | `false` |
| `title`    | Button tooltip                                                            | `string`                     | —       |

The error object (`ProcessDialogErrorProps`):

| Prop          | Description                                                                                           | Type        | Default |
| ------------- | ----------------------------------------------------------------------------------------------------- | ----------- | ------- |
| `message`     | The error message                                                                                     | `ReactNode` | —       |
| `recoverable` | Whether recoverable; `false` disables the triggered action and the panel can only be left via Dismiss | `boolean`   | `true`  |
| `warning`     | Warning error (renders as a warning message, button reads Continue)                                   | `boolean`   | `false` |

## Differences from OOUI

- **Action orchestration collapses into one async `onAction` callback**: the original chains steps via `getActionProcess` returning an `OO.ui.Process`; here you chain the steps inside the callback, and throwing (rejecting) ends the flow into the error panel. {/* deviations: dev-onaction */}
- **`ActionWidget` / `ActionSet` / `OO.ui.Error` are not provided as standalone classes**: their abilities are provided through the `actions` array (the `action` / `flags` / `modes` / `pending` fields) and the error object rendered by the error panel. {/* deviations: dev-actionset-inline */}
- **The "special action" flags are fixed to `safe` / `primary`**: the original lets subclasses extend `ActionSet.static.specialFlags`; there is no class inheritance here — declare `safe` or `primary` via `flags` and the action is placed in the header. {/* deviations: dev-special-flags */}
- **Passing `mode` filters by `modes` from the first frame** (the original shows all actions until the first `setMode`). {/* deviations: dev-processdialog-mode */}

## See also

- The Dialog base class and MessageDialog: [Dialog](https://ooui-react.pages.dev/en/components/dialog/index.md)
- Messages rendered inside the error panel: [Message](https://ooui-react.pages.dev/en/components/message/index.md)
- Why dialogs are controlled-only: [Controlled and uncontrolled](https://ooui-react.pages.dev/en/guide/controlled.md#dialogs-must-be-controlled)



---
url: https://ooui-react.pages.dev/en/components/toolbar/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# Toolbar

> [Source](https://github.com/BearBin1215/ooui-react/tree/main/src/toolbars) | [Original component](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Toolbar.html "OO.ui.Toolbar")

A toolbar: a horizontal bar arranging several tool groups, with tools held inside the groups:

- `BarToolGroup`: tools tiled horizontally as icon buttons (the most common).
- `ListToolGroup` / `MenuToolGroup`: tools gathered into a dropdown panel opened from a handle.
- `LabelToolGroup`: a static text label inside the toolbar, non-interactive, with optional icon and indicator.

## Basic usage

```tsx preview
import { useState } from "react";
import { Toolbar, BarToolGroup } from "ooui-react";

function App() {
  const [marks, setMarks] = useState<string[]>([]);
  const toggle = (name: string) =>
    setMarks((prev) =>
      prev.includes(name) ? prev.filter((x) => x !== name) : [...prev, name],
    );

  return (
    <Toolbar>
      <BarToolGroup
        tools={[
          {
            name: "bold",
            icon: "bold",
            label: "Bold",
            title: "Bold",
            active: marks.includes("bold"),
            onSelect: () => toggle("bold"),
          },
          {
            name: "italic",
            icon: "italic",
            label: "Italic",
            title: "Italic",
            active: marks.includes("italic"),
            onSelect: () => toggle("italic"),
          },
          {
            name: "link",
            icon: "link",
            label: "Insert link",
            title: "Insert link",
            onSelect: () => setMarks((p) => [...p, "link"]),
          },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

## Group alignment and the actions area

A tool group sits on the left (`before`, default) or the right (`after`) according to its own `align`:

```tsx preview
import { Toolbar, BarToolGroup } from "ooui-react";

function App() {
  return (
    <Toolbar>
      <BarToolGroup
        tools={[
          { name: "undo", icon: "undo", label: "Undo", onSelect: () => {} },
          { name: "redo", icon: "redo", label: "Redo", onSelect: () => {} },
        ]}
      />
      <BarToolGroup
        align="after"
        tools={[
          { name: "settings", icon: "settings", label: "Settings", onSelect: () => {} },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

`actions` renders in its own area at the far right and takes any ReactNode (native buttons, switches and other non-tool content). A native button's height baseline differs from the tool slots (frameless button 32px vs tool 42px, top-aligned) — the original renders identically, so treat it as a standalone control:

```tsx preview
import { Toolbar, BarToolGroup, Button } from "ooui-react";

function App() {
  return (
    <Toolbar
      actions={
        <Button icon="check" flags={["primary", "progressive"]}>
          Done
        </Button>
      }
    >
      <BarToolGroup
        tools={[
          { name: "undo", icon: "undo", label: "Undo", onSelect: () => {} },
          { name: "redo", icon: "redo", label: "Redo", onSelect: () => {} },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

## Icon text forms and accelerators in Bar groups

A Bar group's tool shows the icon only by default; `displayBothIconAndLabel` makes a single tool show its text (icon + text with an icon; a text-only button without an icon — without it an icon-less tool uses the original's raw icon-slot form). `accelerator` is the keyboard-shortcut hint — a Bar group appends it to the link's tooltip (List / Menu groups render it as a visible accel slot inside the panel).

```tsx preview
import { useState } from "react";
import { BarToolGroup, Toolbar } from "ooui-react";

function App() {
  const [marks, setMarks] = useState<string[]>([]);
  const toggle = (name: string) =>
    setMarks((prev) =>
      prev.includes(name) ? prev.filter((x) => x !== name) : [...prev, name],
    );

  return (
    <Toolbar>
      <BarToolGroup
        tools={[
          {
            name: "bold",
            icon: "bold",
            label: "Bold",
            title: "Bold",
            accelerator: "Ctrl+B",
            displayBothIconAndLabel: true,
            active: marks.includes("bold"),
            onSelect: () => toggle("bold"),
          },
          {
            name: "italic",
            icon: "italic",
            label: "Italic",
            title: "Italic",
            accelerator: "Ctrl+I",
            onSelect: () => toggle("italic"),
          },
          { name: "clear", label: "Clear formatting", title: "Clear formatting", displayBothIconAndLabel: true, onSelect: () => {} },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

The tool slots demonstrate the forms in order: `bold` icon + text, `italic` icon only (default), `clear` text only (no icon, also via `displayBothIconAndLabel`). Hover the first two to see the accelerator hint in the tooltip.

## Popup tools

A tool with a `popup` config becomes a popup tool: clicking it opens/closes a floating layer, and the tool shows an active state while the layer is open. The layer content comes from `popup.popupContent`, and its visibility can be controlled with `open` / `defaultOpen` / `onOpenChange`. `onSelect` still fires on every selection (independent of the toggling; adding `popup` doesn't disable it); the layer is fixed below the tool (above on a bottom toolbar), with `autoFlip` off by default and available to enable; `container` / `autoClose` / `position` are taken over by the tool and can't be overridden.

:::warning Differences from OOUI
Do not put popup tools inside `ListToolGroup`
 / `MenuToolGroup`
: selecting the tool collapses the group panel and the popup anchor is invalidated with it — the original hides the layer, while here it still renders but ends up misplaced at the viewport's top-left corner. Put popup tools in a Bar group. 
:::
```tsx preview
import { Toolbar, BarToolGroup } from "ooui-react";

function App() {
  return (
    <Toolbar>
      <BarToolGroup
        tools={[
          {
            name: "color",
            icon: "palette",
            label: "Color",
            popup: {
              popupContent: (
                <div style={{ padding: 12 }}>Put a color-picker panel here</div>
              ),
            },
          },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

## List and Menu tool groups

Both consist of a handle plus a dropdown panel (the handle's icon/label/indicator are configurable; the indicator defaults to flipping with `position`: pointing up on a bottom toolbar), and the panel can show a `header` at the top.

**ListToolGroup** holds tools as a vertical text list with a collapse system: tools named in `allowCollapse` start collapsed (visible only once the panel is expanded), and a More / Fewer toggle appears at the bottom of the panel automatically (choosing it keeps the panel open; its text and icon switch with the state); `forceExpand` declares it the other way — the listed tools are always visible and everything else is collapsible. The name list is intersected with the actual `tools`; invalid names produce no toggle. The expanded state is managed via `expanded` (controlled) / `defaultExpanded` (initial value for uncontrolled use, collapsed by default).

**MenuToolGroup**
 holds tools as a horizontal text list, and the handle label is composed from the **active tool**
's (`active: true`
) visible text joined with ", ", falling back to `label`
 when none is active — a fit for exclusive menus that display the current choice, such as paragraph format or alignment. 
Shared convention of the two groups: the panel opens and closes through the common `open`
 / `defaultOpen`
 / `onOpenChange`
 controlled props (handle toggle, choosing a tool, outside click and Escape all fire it); `onToolSelect`
 receives the tool definition whenever any tool is chosen, for unified dispatch; the panel closes automatically after a tool is chosen. A group-level `disabled`
 disables every tool; **when all tools are disabled the group disables itself**
, and a group with empty `tools`
 hides entirely — permission-driven scenarios that clear `tools`
 dynamically need no extra handling. Escape closes the panel in the capture phase, so a toolbar nested in a Dialog won't close the dialog by mistake. 
```tsx preview
import { useState } from "react";
import { ListToolGroup, Toolbar } from "ooui-react";

function App() {
  const [active, setActive] = useState("p");

  return (
    <Toolbar>
      <ListToolGroup
        label="Paragraph"
        allowCollapse={["pre", "blockquote"]}
        tools={[
          { name: "p", label: "Text", active: active === "p", onSelect: () => setActive("p") },
          { name: "h", label: "Heading", active: active === "h", onSelect: () => setActive("h") },
          { name: "pre", label: "Preformatted", onSelect: () => {} },
          { name: "blockquote", label: "Block quote", onSelect: () => {} },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

The example below packs three pieces into one toolbar: a **Menu group** (its handle text is composed from the active tool — switch the alignment and the handle follows; it falls back to `label` when nothing is active), a **Label group** (a static text segment, usable as a visual divider) and a **nested tool group** (a Bar group's tool slot renders a whole List group via `group`, forming a "nested dropdown").

```tsx preview
import { useState } from "react";
import {
  BarToolGroup,
  LabelToolGroup,
  ListToolGroup,
  MenuToolGroup,
  Toolbar,
} from "ooui-react";

function App() {
  const [align, setAlign] = useState("left");

  return (
    <Toolbar>
      <MenuToolGroup
        label="Alignment"
        tools={[
          {
            name: "left",
            icon: "alignLeft",
            label: "Align left",
            active: align === "left",
            onSelect: () => setAlign("left"),
          },
          {
            name: "center",
            icon: "alignCenter",
            label: "Center",
            active: align === "center",
            onSelect: () => setAlign("center"),
          },
          {
            name: "right",
            icon: "alignRight",
            label: "Align right",
            active: align === "right",
            onSelect: () => setAlign("right"),
          },
        ]}
      />
      <LabelToolGroup icon="article" label="Insert" />
      <BarToolGroup
        tools={[
          {
            name: "insert",
            group: (
              <ListToolGroup
                label="Insert"
                icon="add"
                tools={[
                  { name: "link", icon: "link", label: "Link", onSelect: () => {} },
                  { name: "image", icon: "image", label: "Image", onSelect: () => {} },
                  {
                    name: "gallery",
                    icon: "imageGallery",
                    label: "Gallery",
                    onSelect: () => {},
                  },
                ]}
              />
            ),
          },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

## Narrow mode and position

When the toolbar isn't wide enough to tile all its content, it enters **narrow mode**: the theme CSS tightens the overall spacing; tools and handles can customize their narrow form via `narrowConfig` (hide labels, swap icons or text, restored on leaving narrow mode). `position` is `top` (default) or `bottom`, deciding whether popup panels open downward or upward.

The example below squeezes the toolbar into narrow mode with a fixed-width container: `bold` and the List handle each hide their text in narrow mode via `narrowConfig`; the toolbar also sits at the bottom (`position="bottom"`) — open the List panel to see it expand upward with the handle indicator pointing up.

```tsx preview
import { useState } from "react";
import { BarToolGroup, ListToolGroup, Toolbar } from "ooui-react";

function App() {
  const [active, setActive] = useState("p");

  return (
    <div style={{ maxWidth: 230 }}>
      <Toolbar position="bottom">
        <BarToolGroup
          tools={[
            {
              name: "bold",
              icon: "bold",
              label: "Bold",
              title: "Bold",
              displayBothIconAndLabel: true,
              narrowConfig: { displayBothIconAndLabel: false },
            },
            { name: "italic", icon: "italic", label: "Italic", title: "Italic" },
            { name: "link", icon: "link", label: "Link", title: "Link" },
            { name: "clear", icon: "clear", label: "Clear", title: "Clear" },
          ]}
        />
        <ListToolGroup
          align="after"
          label="More"
          icon="menu"
          narrowConfig={{ invisibleLabel: true }}
          tools={[
            {
              name: "p",
              label: "Text",
              active: active === "p",
              onSelect: () => setActive("p"),
            },
            {
              name: "h",
              label: "Heading",
              active: active === "h",
              onSelect: () => setActive("h"),
            },
          ]}
        />
      </Toolbar>
    </div>
  );
}

export default App;
```

## API

| Prop       | Description                                                                        | Type                             | Default |
| ---------- | ---------------------------------------------------------------------------------- | -------------------------------- | ------- |
| `children` | Tool groups (`BarToolGroup`, `ListToolGroup`, `MenuToolGroup`, etc.)               | `ReactNode`                      | —       |
| `position` | Toolbar position; affects popup direction and class names                          | `'top' \| 'bottom'`              | `'top'` |
| `actions`  | Content of the separate actions area on the right                                  | `ReactNode`                      | —       |
| `...rest`  | Native `div` props (`className`, `id`, `data-*`, etc.) passed straight to the root | `HTMLAttributes<HTMLDivElement>` | —       |

Common fields of a tool (an element of the `tools` array):

- `name` (symbol name, required): contributes the `oo-ui-tool-name-{name}` class (a path form `'a/b/c'` takes its first two segments) — usable as a style or test hook.
- `label` (visible text) and `icon`: Bar groups show the icon only by default; the text shows via `displayBothIconAndLabel: true` (icon + text with an icon, a text-only button without one — without it an icon-less tool uses the original's raw icon-slot form); List / Menu groups always show the label. `title` is always a tooltip (Bar groups append `title` and `accelerator` to the link's title; List / Menu groups render only the accelerator slot and don't append it). {/* deviations: dev-tool-accelerator */}
- `active` (controlled active state), `onSelect` (fires on click or keyboard Enter / Space), `disabled`.
- `narrowConfig`: in narrow mode the **defined** fields replace the tool's icon / label form, restored on leaving narrow mode.
- `popup`: popup tool (see the previous section).
- `group`: a nested tool group — the tool slot renders a whole tool group instead of a tool link (for "nested dropdowns"); the handle and selection state are owned by the nested group, and `title` / `icon` / `active` / `onSelect` don't apply to this tool, only `disabled` carries over as the slot's disabled state; when both `popup` and `group` are given, `group` wins. {/* deviations: dev-toolgroup-tool-element */}

The full reference is in the tool-group components and the `ToolProps` type.

## Differences from OOUI

- **Tools are no longer registered through a `ToolFactory`**: tools are handed to the group as a declarative `tools` array, with the active state owned by the caller. {/* deviations: dev-tool-factory */}
- **The toolbar and tool groups have no event surface**: the equivalent of listening to `Toolbar.active` in the original is re-rendering the `tools` array with `active` declared; popup layers and panels likewise use controlled props and callbacks. {/* deviations: dev-toolbar-events */}
- **A popup tool's `onSelect` still fires**: in the original it is occupied by the popup toggle and the caller never hears about selections; here selection is independent of toggling, and visibility changes are reported via `popup.onOpenChange`. {/* deviations: dev-popup-tool-onselect */}
- **A popup tool's `autoFlip` defaults to off and can be enabled explicitly.** {/* deviations: dev-popup-tool-autoflip */}
- **Visible text and tooltip are split from one `title` key into `label` + `title`**: `label` is the visible text, `title` is always the tooltip; when migrating, pass the old `narrowConfig.title` value as `label`. {/* deviations: dev-tool-label-title */}
- **In narrow mode the handle's tooltip always falls back to the effective `label`.** {/* deviations: dev-popuptoolgroup-title */}
- **A panel that fills the container width is still height-clamped to the visible area with internal scrolling** (tools stay reachable). {/* deviations: dev-panel-maxheight */}
- **The narrow-mode measurement baseline is remeasured when tool groups are added or removed**, so dynamic tool sets keep correct narrow detection. {/* deviations: dev-narrow-threshold-reset */}
- **On a bottom toolbar (`position="bottom"`) the More / Fewer arrow directions are inverted compared to the original**; functionality is unaffected. {/* deviations: dev-listtoolgroup-icons */}

## See also

- The flat icon-button tool group: `BarToolGroup`
- Tool groups gathered into a dropdown: `ListToolGroup`, `MenuToolGroup`
- The static label tool group: `LabelToolGroup`
- Common pass-through and `ref` rules: [Common props](https://ooui-react.pages.dev/en/guide/basics.md)



---
url: https://ooui-react.pages.dev/en/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/en/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/en/llms-full.txt.

# ooui-react

> OOUI for React

[Get Started](/en/guide/usage) | [Components](/en/components/)

## Features

- /feature-icons/code-xml.svg **Structure parity**: Outputs the same DOM structure, class names and attributes as OOUI. Styles are loaded by the consumer from OOUI, making it a natural fit for MediaWiki sites.
- /feature-icons/keyboard.svg **Behavior parity**: Keyboard, focus, a11y and edge cases are checked one by one against OOUI, so interaction semantics match.
- /feature-icons/react.svg **Declarative API**: OOUI's imperative setters and events are turned into controlled props such as value and onChange, matching React conventions.
- /feature-icons/typescript.svg **Type support**: Written entirely in TypeScript, with complete type definitions.
- /feature-icons/preact.svg **Preact compatible**: Runs on the Preact compatibility layer to keep bundles small.
- /feature-icons/package.svg **Tree Shaking**: Import only what you use.
:::note About this translation
The English documentation is translated and proofread with AI assistance from the Chinese source, so some wording may lag the original or read imperfectly; please [report any inaccuracies on GitHub](https://github.com/BearBin1215/ooui-react/issues).
:::

## Try it live

```tsx file="<root>/demos/en/advanced-search.tsx"
import { useState } from "react";
import { Button, Dropdown, TextInput } from "ooui-react";
import "./advanced-search.css";

const SEARCH_CODES = {
  none: "None",
  intitle: "Page title contains",
  incategory: "Pages in these categories",
  hastemplate: "Pages with these templates",
  linksto: "Pages linking to",
  insource: "Source text contains",
};

const OPTIONS = Object.entries(SEARCH_CODES).map(([value, label]) => ({
  value,
  children: label,
}));

function AdvancedSearchDemo() {
  const [rows, setRows] = useState([{ code: "none", value: "" }]);
  const addRow = () => setRows((prev) => [...prev, { code: "none", value: "" }]);
  const setRow = (index: number, patch: { code?: string; value?: string }) =>
    setRows((prev) => prev.map((row, i) => (i === index ? { ...row, ...patch } : row)));

  return (
    <div className="advsearch">
      <div className="advsearch-header">Advanced search</div>
      {rows.map(({ code, value }, index) => {
        const pending = index === rows.length - 1;
        return (
          <div
            key={index}
            className={`advsearch-line${pending ? " advsearch-line-pending" : ""}`}
          >
            <Dropdown
              className="advsearch-code"
              value={code}
              onChange={(next) => setRow(index, { code: String(next) })}
              onFocus={pending ? addRow : undefined}
              options={OPTIONS}
            />
            <TextInput
              className="advsearch-value"
              value={value}
              onChange={(next) => setRow(index, { value: next })}
              onFocus={pending ? addRow : undefined}
            />
            <Button
              className="advsearch-remove"
              icon="subtract"
              tabIndex={-1}
              disabled={pending}
              onClick={() => setRows((prev) => prev.filter((_, i) => i !== index))}
            />
          </div>
        );
      })}
    </div>
  );
}

export default AdvancedSearchDemo;

```
```css file="<root>/demos/en/advanced-search.css"
.advsearch {
  max-width: 50em;
  box-sizing: border-box;
  padding: 0.5em 0.75em;
  border: 1px solid #c8ccd1;
  background-color: #f8f9fa;
}
.advsearch-header {
  font-size: 1.2em;
  font-weight: 600;
}
.advsearch .advsearch-line {
  display: flex;
  gap: 8px;
  margin-top: 0.4em;
}
.advsearch .advsearch-line-pending {
  opacity: 0.4;
  transition: opacity ease-out 0.3s;
}
.advsearch .advsearch-line-pending:hover {
  opacity: 1;
}
.advsearch .advsearch-line-pending .advsearch-remove {
  opacity: 0;
}
.advsearch .advsearch-code {
  flex: 0 0 19em;
}
.advsearch .advsearch-value {
  flex: 1 1 40em;
  max-width: none;
}

```

Focus the trailing empty row to append another line, and the minus button at the end of a row removes it.

## Installation


```sh [npm]
npm install ooui-react
```

```sh [yarn]
yarn add ooui-react
```

```sh [pnpm]
pnpm add ooui-react
```

```sh [bun]
bun add ooui-react
```

```sh [deno]
deno add npm:ooui-react
```

React ≥ 18 is required; SSR is not supported yet. For loading styles, MediaWiki integration and Preact compatibility, see the [Usage guide](https://ooui-react.pages.dev/en/guide/usage.md).

## Why this library?

Back in 2023, while writing [my own Moegirlpedia gadget](https://github.com/BearBin1215/MoegirlPedia), I found that managing state with jQuery alone got painful in more complex scenarios, so I wanted to bring in a modern framework. At the time:

- MediaWiki was on 1.31, which shipped neither Vue nor Codex.
- Bundling Vue myself started at 60 KB, and writing a little more would push the bundle past what could be uploaded to the site without timing out.
- Most mature component libraries ship their own stylesheets, which also makes for large bundles.
- I lack the art skills to design the styles myself ~~(important!)~~.

So I went with [Preact](https://preactjs.com/) plus a self-built OOUI component library: a small framework, no stylesheet, rendering only DOM.

As AI-assisted programming took off, this project grew into a proper component library. Moegirlpedia has since upgraded MediaWiki and supports Vue + Codex, but I still think this library earns its place.