UXF Core-React

Components

Hide

Conditionally hide some jsx content.

import { Hide } from "@uxf/core-react/components/hide";

<Hide when={SOME_CONDITION}>...some content</Hide>;

Show

Conditionally show some jsx content.

import { Show } from "@uxf/core-react/components/show";

<Show when={SOME_CONDITION}>...some content</Show>;

ViewportHeightPolyfill

Polyfill for custom css variable --viewport-height to mimic functionality of browser's dynamic viewport height.

Add component to react app root (eg. _app.tsx).

import { ViewportHeightPolyfill } from "@uxf/core-react/components/viewport-height-polyfill";

<ViewportHeightPolyfill />;

Add css variable declaration with fallback to app global styles (eg. base.css) if already not there.

:root {
    --viewport-height: 100vh;

    @supports (height: 100dvh) {
        --viewport-height: 100dvh;
    }
}

Hooks

useBodyScrollLock

Lock scrolling on body element. Useful for modals, popovers, etc.

import { useBodyScrollLock } from "@uxf/core-react/hooks/use-body-scroll-lock";
import { useState } from "react";

const innerRef = useRef<HTMLDivElement>(null);
const [isOpen, setIsOpen] = useState<boolean>();

const clearAllOnclose = false;

useBodyScrollLock<HTMLDivElement>(innerRef, isOpen, {
    allowTouchMove: undefined, // https://github.com/willmcpo/body-scroll-lock#allowtouchmove
    clearAllOnClose: false, // optionally call clearAllBodyScrollLocks method on unmount
    reserveScrollBarGap: undefined, // https://github.com/willmcpo/body-scroll-lock#reservescrollbargap
});

<div ref={innerRef}>Element which activates scroll lock on its parent elements.</div>;

isMounted

Check if component is mounted.

import { useIsMounted } from "@uxf/core-react/hooks/use-is-mounted";

const isMounted = useIsMounted();

useIsomorphicLayoutEffect

Returns useEffect on client and useLayoutEffect on server.

import { useIsomorphicLayoutEffect } from "@uxf/core-react/hooks/use-isomorphic-layout-effect";

useIsomorphicLayoutEffect(
    () => {
        /* code */
    },
    [/* deps */],
);

useKey

Trigger callback on given key.

import { useKey } from "@uxf/core-react/hooks/use-key";
import { useRef } from "react";

const targetRef = useRef<HTMLDivElement>(null);
const disabled = false; // eg. for passing disabled state

useKey<HTMLDivElement>("Enter", () => console.log("callback"), {
    disabled,
    targetRef, // if not provided, then `document` will be used
    type: "keydown",
});

<div ref={targetRef} tabIndex={0}>
    Element with callback triggerable by enter key.
</div>;

useMinWindowWidth

Deprecated — Use useMediaQuery instead.

Returns boolean if window width is equal or greater than given value.

import { useMinWindowWidth } from "@uxf/core-react/hooks/use-min-window-width";

const isDesktop = useMinWindowWidth(1200);
const isDesktopWithDebounce = useMinWindowWidth(1200, 200); // will be updated every 200 ms

const example = isDesktop ? "desktop" : "tablet";
const debouncedExample = isDesktopWithDebounce ? "debouncedDesktop" : "debouncedTablet";

usePagination

Returns array of pagination items.

import { usePagination } from "@uxf/core-react/hooks/use-pagination";

const paginationItems = usePagination({ page: 1, count: 10 });

useRafState

Updates state only in the callback of requestAnimationFrame.

import { useRafState } from "@uxf/core-react/hooks/use-raf-state";

const [state, setState] = useRafState<boolean>(false);

useOnMount

Calls the callback on component mount.

import { useOnUnmount } from "@uxf/core-react/hooks/use-on-unmount";

const exampleCallback = () => {};

useOnUnmount(exampleCallback());

useOnUpdate

Calls the callback only on component update, except initial mount.

import { useOnUpdate } from "@uxf/core-react/hooks/use-on-update";

useOnUpdate(
    () => {
        /* code */
    },
    [/* deps */],
);

useWindowScroll

Returns x and y scroll coordinates of window on scroll.

import { useWindowScroll } from "@uxf/core-react/hooks/use-window-scroll";

const windowScroll = useWindowScroll();

const example = windowScroll && windowScroll.y > 100 ? "scroled" : "on top";

useWindowSize

Returns window width and height.

import { useWindowSize } from "@uxf/core-react/hooks/use-window-size";

const windowSize = useWindowSize();

const example = windowSize && windowSize.width > 1200 ? "desktop" : "tablet";

useFocusTrap

Locks focus inside given element.

import { useFocusTrap } from "@uxf/core-react/hooks/use-focus-trap";
import { useState } from "react";

const [active, setActive] = useState<boolean>();

const focusTrapRef = useFocusTrap(active);

<div ref={focusTrapRef}>Element which trap focus inside if `active` is truthy.</div>;

useFocusReturn

Returns focus to last active element.

import { useFocusReturn } from "@uxf/core-react/hooks/use-focus-return";
import { useState } from "react";

const [active, setActive] = useState<boolean>();

// Returns focus to last active element, e.g. in Modal or Popover
useFocusReturn(active);

useAnchorProps

Returns props for anchor element.

import { useAnchorProps } from "@uxf/core-react/clickable/use-anchor-props";
import { AnchorHTMLAttributes } from "react";

// extends <a /> by `analyticsCallback`, `disabled`, `loading`, `submit` props
const anchorProps = useAnchorProps<AnchorHTMLAttributes<HTMLAnchorElement>>({
    analyticsCallback: () => console.log("analytics"),
    disabled: false,
    href: "https://www.google.com/",
    loading: false,
    onClick: () => console.log("success"),
    type: "submit", // simulate <button type="submit" /> function
});

<a {...anchorProps}>Click me</a>;

// example with generics
import { UseAnchorProps, useAnchorProps } from "@uxf/core-react/clickable/use-anchor-props";
import { AnchorHTMLAttributes } from "react";

interface Props extends UseAnchorProps, AnchorHTMLAttributes<HTMLAnchorElement> {
    customProp?: boolean;
}

const anchorProps = useAnchorProps<Props>({
    customProp: true,
    loading: false,
    href: "https://www.google.com/",
});

<a {...anchorProps}>Click me</a>;

useButtonProps

Returns props for button element.

import { useButtonProps } from "@uxf/core-react/clickable/use-button-props";
import { ButtonHTMLAttributes } from "react";

// extends <button /> by `analyticsCallback` and `loading` props
const buttonProps = useButtonProps<ButtonHTMLAttributes<HTMLButtonElement>>({
    analyticsCallback: () => console.log("analytics"),
    disabled: false,
    loading: false,
    onClick: () => console.log("success"),
    type: "submit",
});

<button {...buttonProps}>Click me</button>;

// example with generics
import { UseButtonProps, useButtonProps } from "@uxf/core-react/clickable/use-button-props";
import { ButtonHTMLAttributes } from "react";

interface Props extends UseButtonProps, ButtonHTMLAttributes<HTMLButtonElement> {
    customProp?: boolean;
}

const buttonProps = useButtonProps<Props>({
    customProp: true,
    loading: false,
    type: "submit",
});

<button {...buttonProps}>Click me</button>;

useClickableProps

Returns props for clickable element.

import { useClickableProps } from "@uxf/core-react/clickable/use-clickable-props";
import { HTMLAttributes } from "react";

// extends any HTML element by `analyticsCallback`, `disabled`, `loading`, `submit` props
const clickableProps = useClickableProps<HTMLAttributes<HTMLDivElement>>({
    analyticsCallback: () => console.log("analytics"),
    disabled: false,
    loading: false,
    onClick: () => console.log("success"),
    type: "submit", // simulate <button type="submit" /> function
});

<div {...clickableProps}>Click me</div>;

// example with generics
import { UseClickableProps, useClickableProps } from "@uxf/core-react/clickable/use-clickable-props";
import { HTMLAttributes } from "react";

interface Props extends UseClickableProps, HTMLAttributes<HTMLDivElement> {
    customProp?: boolean;
}

const buttonProps = useClickableProps<Props>({
    customProp: true,
    hidden: false,
    loading: false,
});

<button {...buttonProps}>Click me</button>;

useMouseDragToScroll

Allow to scroll element by dragging mouse.

import { useMouseDragToScroll } from "@uxf/core-react/hooks/use-mouse-drag-to-scroll";

const targetRef = useRef<HTMLDivElement>(null);

const style = useMouseDragToScroll(scrollRef);

<div style={style}>Drag to scroll</div>;

useInputFocus

Manage focus states of input element.

import { useInputFocus } from "@uxf/core-react/hooks/use-input-focus";

const focusRef = useRef<HTMLInputElement>(null); // or HTMLTextAreaElement
const { onBlur, onFocus } = props;

const input = useInputFocus(focusRef, onBlur, onFocus);

<div>Input is {input.focused}</div>
<button onClick={input.focus}>Focus input</button>
<input onBlur={input.onBlur} onFocus={input.onFocus} ref={focusRef} />

useLatest

Allways returns latest value of given variable.

import { useLatest } from "@uxf/core-react/hooks/use-latest";

const latestState = useLatest(someUnstableWhatever);

useEffect(() => {
    latestState.current(); // use newest state of 'someUnstableWhatever' without affecting this effetct update
}, [latestState]);

usePrevious

Returns previous value of given variable.

import { usePrevious } from "@uxf/core-react/hooks/use-previous";

const previousState = usePrevious(someUnstableWhatever);

useEffect(() => {
    previousState.current(); // use state of 'someUnstableWhatever' from previous render without affecting this effetct update
}, [previousState]);

useToggle

Returns boolean state and methods to toggle it.

import { useToggle } from "@uxf/core-react/hooks/use-toggle";

const [isVisible, toggleIsVisible, setVisible, setInvisible] = useToggle(false);

<button onClick={toggleIsVisible}>Toggle visibility</button>;

useIncrement

Returns number state and methods to increment, decrement and reset.

import { useIncrement } from "@uxf/core-react/hooks/use-increment";

const [count, increment, decrement, reset] = useIncrement(5, 1);

<button onClick={increment}>Toggle visibility</button>;

useDebounce

Returns the latest value after given delay.

import { useDebounce } from "@uxf/core-react/hooks/use-debounce";

const debouncedValue = useDebounce<string>("some value", 300);

String helpers

import { nl2br } from "@uxf/core-react/string/nl2br";

<div>{nl2br("Hello\nWorld")}</div>;

useMediaQuery

Returns whether the given media query is currently matched. Optionally accepts a callback that is called on every change.

Uses window.matchMedia with a change event listener (via AbortController) for efficient updates.

import { useMediaQuery } from "@uxf/core-react/hooks/use-media-query";
import type { UseMediaQueryCallback } from "@uxf/core-react/hooks/use-media-query";
import { twScreens } from "@generated/tw-tokens/tw-screens";

// Basic usage – reactive boolean (SSR-safe, initializes as false)
const isDesktop = useMediaQuery(`(min-width: ${twScreens.sm})`);

// With optional callback – fired on every match change
const callback: UseMediaQueryCallback = (isMatching, mediaQueryString) => {
    console.log(isMatching, mediaQueryString);
};

const isDesktopWithCallback = useMediaQuery(`(min-width: ${twScreens.sm})`, callback);

// Client-only usage – initializes immediately from window.matchMedia (no SSR hydration)
// Pass isSSR=false only when the component is guaranteed to render client-side only
const isDesktopClientOnly = useMediaQuery(`(min-width: ${twScreens.sm})`, undefined, false);

Parameters:

mediaQueryString – CSS media query string
callback (optional) – called with (isMatching, mediaQueryString) on every match change
isSSR (optional, default: true) – when true, initial state is false to avoid SSR/hydration mismatch; when false, initial state is read directly from window.matchMedia (use only in client-only components)

Drag and Drop

Moved to its own package. The sortable hooks and a facade over @dnd-kit now live in @uxf/dnd, so that @dnd-kit is a dependency only of the projects that actually render drag and drop — it used to be a peer of this package, and therefore of everything that depends on it.

See the @uxf/dnd README, and the migration note for the import rewrites.

Global Context

createGlobalContext is a thin wrapper around React.createContext that caches the resulting Context object on globalThis, keyed by a unique name. Use it instead of createContext for any Context exported from a library package.

Why it exists

Under Turbopack a single "use client" module can be evaluated more than once — typically once per "use client" boundary that imports it. Each evaluation calls createContext(...) separately, producing distinct Context identities in the same JS realm. The Provider ends up writing into one identity and useContext reads from another, so consumers silently fall back to the default value. Caching the Context on globalThis collapses all evaluations to a single identity.

Webpack does not exhibit this because its chunking layer deduplicates by module ID; Turbopack does not (yet) guarantee that for client-boundary modules.

Usage

import { createGlobalContext } from "@uxf/core-react/global-context";
import { useContext } from "react";

const themeContext = createGlobalContext<"light" | "dark">("ui/theme", "light");

export const ThemeProvider = themeContext.Provider;

export function useTheme() {
    return useContext(themeContext);
}

Naming convention

The name argument must be unique across the monorepo. Use "<package>/<context>", for example:

"core-react/translations"
"localize/locale"
"ui/color-scheme"

The same name on subsequent calls returns the original Context — the defaultValue argument is honored only on the first call.

When to use it

Use createGlobalContext for any Context that is:

exported from a library package (@uxf/*), or
consumed from more than one "use client" boundary.

For Contexts that are private to a single app file and never imported elsewhere, plain React.createContext is fine.

Translations

Provides a translation system that can be used in both single-language and multi-language projects.

Single-language projects

For single-language projects, use the TranslationsProvider context and createDefaultT function to provide translations for the packages you use:

import { TranslationsProvider } from "@uxf/core-react/translations";
import { createDefaultT } from "@uxf/core-react/translations/create-default-t";

// Import translations for packages you use
import uiTranslations from "@uxf/ui/translations/cs.json";
import formTranslations from "@uxf/form/translations/cs.json";

// Create a translation function for your language
const t = createDefaultT({
    ...uiTranslations,
    ...formTranslations,
});

// Provide the translation function to your app
function App() {
    return <TranslationsProvider value={t}>{/* Your app content */}</TranslationsProvider>;
}

Multi-language projects

For multi-language projects, use the TranslationsProvider context with a translation function from your preferred translation library (e.g., next-translate):

import { TranslationsProvider } from "@uxf/core-react/translations";
import useTranslation from "next-translate/useTranslation"; // Or any other translation library

function App() {
    // Get the translation function from your translation library
    const { t } = useTranslation();

    return <TranslationsProvider value={t}>{/* Your app content */}</TranslationsProvider>;
}

Using translations in components

To use translations in your components, use the useUxfTranslation hook:

import { useUxfTranslation } from "@uxf/core-react/translations";

function MyComponent() {
    const t = useUxfTranslation();

    return <div>{t("form:validation.required")}</div>;
}