# @open-pioneer/react-utils

> Contains common react utilities used by the open pioneer trails project

Latest version **4.10.0** (published 2026-11-19) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @open-pioneer/react-utils
pnpm add @open-pioneer/react-utils
yarn add @open-pioneer/react-utils
bun add @open-pioneer/react-utils
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 4.10.0 |
| Published | 2026-11-19 |
| First published | 2023-11-20 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 5 |
| Unpacked size | 128 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 4 |
| Maintainers | mbeckem_conterra, jessebluemr, antoniave_conterra, open_pioneer |
| Keywords | open-pioneer-trails |

## Links

- npm: https://www.npmjs.com/package/@open-pioneer/react-utils
- Repository: https://github.com/open-pioneer/trails-core-packages
- Homepage: https://github.com/open-pioneer
- npm.io page: https://npm.io/package/@open-pioneer/react-utils

## Dependencies (5)

- [react](https://npm.io/package/react.md) ^19.3.1
- [@chakra-ui/react](https://npm.io/package/@chakra-ui/react.md) ^3.38.0
- [@open-pioneer/core](https://npm.io/package/@open-pioneer/core.md) 4.10.0
- [@open-pioneer/reactivity](https://npm.io/package/@open-pioneer/reactivity.md) 4.10.0
- [@conterra/reactivity-core](https://npm.io/package/@conterra/reactivity-core.md) ^0.8.9

## Recent versions

- 4.10.0 (latest) — 2026-11-19
- 4.10.0-dev.20261119090001 (dev) — 2026-11-19
- 4.7.1-dev-test-snapshot-123.20260821142246 (dev-test-snapshot-123) — 2026-08-21
- 4.7.1-dev-test-snapshot.20260821120534 (dev-test-snapshot) — 2026-08-21
- 4.9.0 — 2026-10-30
- 4.9.0-dev.20261029090037 — 2026-10-29
- 4.9.0-dev.20261002130116 — 2026-10-02
- 4.9.0-dev.20260930055642 — 2026-09-30
- 4.8.0 — 2026-09-17
- 4.8.0-dev.20260910101405 — 2026-09-10
- 4.7.0 — 2026-07-28
- 4.7.0-dev.20260727091735 — 2026-07-27
- 4.7.0-dev.20260713101438 — 2026-07-13
- 4.7.0-dev-test-snapshot.20260707113553 — 2026-07-07
- 4.7.0-dev-test-snapshot.20260707113111 — 2026-07-07
- … 85 more at https://npm.io/package/@open-pioneer/react-utils/versions

## README

# @open-pioneer/react-utils

This package provides React utilities that help a developer create applications.

## Usage

### Titled sections

Use the `<TitledSection>` and `<SectionHeading>` components instead of raw `hX` HTML tags (such as `<h1>` or `<h2>`).
This way, the appropriate heading level is determined automatically.

Example:

```jsx
import { TitledSection, SectionHeading } from "@open-pioneer/react-utils";

function SomeComponent(props) {
    return (
        {/* Renders as h1 if this is the topmost section.
            Title strings are automatically wrapped into `SectionHeading`. */}
        <TitledSection title="Root Title">
            ... Some content ...
            {/* Custom react component as title. Renders as the next level (h2). */}
            <TitledSection title={<SectionHeading size="4xl">Sub Title</SectionHeading>}>
                ... More content ...
            </TitledSection>
        </TitledSection>
    );
}
```

To override the automatic heading level, use the `ConfigureTitledSection` component.
This can be used for example to override the initial heading level or to force a certain level when the React tree differs from the DOM tree.

Example:

```jsx
<ConfigureTitledSection level={2}>
    <TheRestOfYourApplication />
</ConfigureTitledSection>
```

In the preceding example the topmost heading(s) in `TheRestOfYourApplication` start at level 2, and nested headings use increasing levels as usual.
For more details, see the API documentation.

### FormattedMessage

This package provides a few helper components to render formatted messages in a React tree:

```tsx
import { FormattedMessage } from "@open-pioneer/react-utils";

<FormattedMessage intl={intl} id="message.id" />
<FormattedRichMessage intl={intl} id="message.id" />
```

`intl` can be either a plain `PackageIntl` object, or a signal (`ReadonlyReactive<PackageIntl>`), or a reactive getter (e.g. `() => currentIntl.value`).

`FormattedMessage` and `FormattedRichMessage` support `values`, too:

```tsx
// greeting: "Hello {name}"
<FormattedMessage intl={intl} id="greeting" values={{ name: "World" }} /> // -> Hello World
```

When used from a plain react component, these components only offer minor additional utility.
Compared to direct calls of `intl.formatMessage`, they add a layer of caching (`useMemo`).
However, because they support reactive props for `intl`, they make it easy to compose reactive strings from non-react code.

### Roving menu

The roving menu is a render-less component that can be used to implement an accessible menu with keyboard navigation.
It implements focus management and supports navigation using the arrow keys and home/end buttons.

To create a roving menu, use the `useRovingMenu` hook in combination with the `RovingMenuRoot`.
You must apply the `menuProps` to some container element (a `div`, a list, etc.) and the `menuState` to the `<RovingMenuRoot />`, which acts as a context provider.

For example:

```tsx
import { useRovingMenu, RovingMenuRoot } from "@open-pioneer/react-utils";

function HorizontalMenu() {
    const { menuProps, menuState } = useRovingMenu({
        orientation: "horizontal"
    });

    return (
        <HStack {...menuProps} justify="center" gap={5} padding={2}>
            <RovingMenuRoot menuState={menuState}>
                <MenuItem value="1" />
                <MenuItem value="2" />
                <MenuItem value="3" />
                <MenuItem value="4" />
            </RovingMenuRoot>
        </HStack>
    );
}
```

To implement a menu item, use the `useRovingMenuItem` hook.
You must provide a unique value for the item (unique within the menu).
You must also make certain to apply the resulting `itemProps` to the menu item component (which can be any focusable DOM element).
These props implement keyboard navigation and focus handling.

For example:

```tsx
function MenuItem(props: { value: string }) {
    const { value } = props;
    const { itemProps } = useRovingMenuItem({
        value
    });

    return (
        <Button {...itemProps} onClick={() => console.log(`Button ${value} triggered.`)}>
            {value}
        </Button>
    );
}
```

#### Disabled menu items

Use the `disabled` prop of `useRovingMenuItem` to indicate that your menu item is currently disabled.
Disabled items will lose focus and will be skipped during keyboard navigation.
The `itemProps` of a disabled item carry `aria-disabled="true"`, so the DOM element is marked as disabled for assistive technology as well.

To mark your items as disabled for your users, prefer `aria-disabled` over HTML's `disabled` attribute.
The `disabled` attribute completely disables focus and any browser events, which makes moving the focus to a neighboring item difficult to implement.

#### Unmounting / hiding menu items

`display: none` in combination with a `disabled: true` in `useRovingMenuItem` works well.
As an alternative, you can also completely unmount your component from a parent of your menu item.

Note that returning `null` or `undefined` from your component will interfere with focus handling.
You should always render your menu item's dom node, for as long as your item exists.

#### Nested menus

Roving menu supports limited nesting (2 levels deep).

For the outer menu, use the normal `useRovingMenu()` hook with a certain orientation.
For the child menu, use the `useNestedRovingMenu()` hook with the _opposite_ orientation.

The child menu will act as an item in its parent menu, so it requires a `value` as well.

Example for the child menu:

```tsx
function NestedMenu() {
    const { menuProps, menuState } = useNestedRovingMenu({
        orientation: "horizontal",
        value: "some-value"
    });

    return (
        <HStack {...menuProps} justify="center" gap={5} padding={2}>
            <RovingMenuRoot menuState={menuState}>{/* nested items ... */}</RovingMenuRoot>
        </HStack>
    );
}
```

### Hooks

#### useCommonComponentProps()

A helper hook that automatically computes `containerProps`: common properties to set on the topmost container element of a public component.

For the time being, these properties are `className` (combined component class and optional additional class names) and `data-testid` (for tests).

Example:

```tsx
import { CommonComponentProps, useCommonComponentProps } from "@open-pioneer/react-utils";
// ...

// Inherit from CommonComponentProps
export interface InitialExtentProps extends CommonComponentProps {
    // props ...
}

export const InitialExtent: FC<InitialExtentProps> = (props: InitialExtentProps) => {
    // Use the hook to compute container props (classNames, data-testid, maybe more in the future)
    const { containerProps } = useCommonComponentProps("initial-extent", props);

    // Pass containerProps directly to the container
    return <Box {...containerProps}>{/* ... */}</Box>;
};
```

#### useEvent()

The `useEvent` can be used to obtain a stable event handler function with changing implementation.
This is useful to avoid re-triggering `useEffect`-hooks when only the event handler changed.

Example:

```jsx
import { useEvent } from "@open-pioneer/react-utils";

function SomeReactComponent(props) {
    // NOTE: logMessage() must not be called during rendering!
    const logMessage = useEvent((message: string) => {
        console.log(message, props.someProperty);
    });
    const someService = ...; // injected

    // Changes of prop.someProperty will not cause the effect to re-fire, because the function identity
    // of `logMessage` remains stable.
    useEffect(() => {
        const handle = someService.registerHandler(logMessage);
        return () => handle.destroy();
    }, [someService, logMessage]);
}
```

> Warning: the function returned by `useEvent` must **not** be called during rendering.  
> It can only be used in an effect or in a event handler callback.

For more details, see the API docs of `useEvent` or <https://github.com/reactjs/rfcs/blob/useevent/text/0000-useevent.md>.

## License

Apache-2.0 (see `LICENSE` file)

---
_Source: https://npm.io/package/@open-pioneer/react-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
