Skip to content

Getting started

This guide walks through adding var-ui to a React app and rendering a component with the design system providers.

1. Install packages

Add @var-ui/react, @var-ui/core, and optionally @var-ui/icons to your app.

2. Wrap your app

Mount DesignSystemProvider, IconProvider, and LayerProvider at the root of your application.

Direction and locale

Pass direction and a real locale on DesignSystemProvider:

<DesignSystemProvider applyToDocument direction="rtl" locale="he-IL">
  {children}
</DesignSystemProvider>

applyToDocument syncs html dir (and lang when locale is set) after hydration / on mount. It always writes dir for the resolved direction — including default ltr. If SSR set <html dir="rtl"> and the client provider omits direction/locale, mount will rewrite dir to ltr. SSR apps that care about first paint should set <html dir> (and lang if needed) themselves and pass matching direction/locale to the provider.

React Aria overlays (Popover, Menu, start / end placement) take direction from locale, not from dir. I18nProvider only accepts locale.

  • Prefer a real RTL locale (he-IL, ar-EG) so dates, numbers, and overlays agree.
  • direction="rtl" with no locale wraps I18nProvider with ar so placement still flips. That workaround does not set html lang="ar".
  • direction="ltr" (explicit) with no locale wraps I18nProvider with en-US so a nested LTR island does not inherit a parent RTL locale for overlay placement.
  • locale="en-US" plus direction="rtl" keeps English formatting; overlays may not flip.
  • If you omit direction but pass locale, dir is derived from RAC isRTL(locale).
  • useDirection() returns { direction, isRtl } and defaults to ltr when no provider is mounted.
  • Directional icons opt in: <Icon name="chevronRight" data-mirror={isRtl || undefined} />.

Do not set dir on the whole docs site to try this — use a DirectionProvider island (see Hidden).

Portals and stacking

Wrap the application in an isolating root so portaled dialogs and popovers stack above page z-index:

<body>
  <div class="root">{children}</div>
</body>
.root {
  isolation: isolate;
}

When DesignSystemProvider uses applyToDocument, put isolation: isolate on html or body instead of an extra wrapper.

Themed portals

Token CSS variables cascade from the theme class. If an overlay portals to document.body and the theme class is on a subtree, pass portalContainer pointing at the themed node (or use applyToDocument).

iOS 26+ Safari backdrops

Dialog and drawer backdrops use position: absolute under @supports (-webkit-touch-callout: none). Add body { position: relative; } so a scrolled page still covers the visual viewport.

Overlay data-* attributes, positioner CSS variables, and onOpenChange details are documented in Overlay lifecycle.

3. Use a component

Import components from @var-ui/react and compose them with TypeStyles-powered layout primitives.

Detailed install commands and copy-paste snippets will be added in a follow-up pass.