Chapter 2: Getting Started

Core Idea

Installing Base UI is a single package add; the only mandatory app-shell setup is a root stacking-context style for portaled popups, plus an iOS 26+ Safari backdrop fix — everything else is assembling Root/Trigger/Portal/Positioner/Popup parts and styling them yourself.

Key Concepts

Install: pnpm add @base-ui/react (or npm i / yarn add / bun add) — one package, tree-shakable, so unused components don't ship.
Portal stacking context: Dialog, Popover, and other popup components portal their content. Wrap the app root in a div.root with isolation: isolate so portaled content reliably renders above page content regardless of any z-index elsewhere.
iOS 26+ Safari fix: Safari on iOS 26+ can show content beneath the UI chrome, so fixed-position backdrops (e.g. dialog overlays) must use position: absolute instead of position: fixed; add body { position: relative; } globally so the absolute positioning covers the full visual viewport even after scroll.
Styling is bring-your-own: the official demo pattern is Root → Trigger → Portal → Positioner → Popup (+ Arrow, Title, Description for a Popover), styled with Tailwind classes off data-* attributes or CSS Modules targeting the same attributes — see ch005 (Styling).
shadcn/ui path: if you want pre-styled, higher-level components instead of styling primitives yourself, shadcn/ui is built on Base UI and is the recommended starting point.
LLM-friendly docs: every docs page has a "View as Markdown" link; an llms.txt index is linked from the Handbook nav section for feeding the full doc set to an AI assistant.

Code Examples

/* layout.tsx — required app-shell wrapper for portaled popups */
<body>
  <div className="root">{children}</div>
</body>

/* styles.css — stacking context + iOS 26 Safari backdrop fix */
.root { isolation: isolate; }
body { position: relative; }

/* Minimal Popover assembly (Tailwind) */
import { Popover } from '@base-ui/react/popover';

<Popover.Root>
  <Popover.Trigger className="...">Notifications</Popover.Trigger>
  <Popover.Portal>
    <Popover.Positioner sideOffset={8}>
      <Popover.Popup className="...">
        <Popover.Arrow className="..." />
        <Popover.Title className="...">Notifications</Popover.Title>
        <Popover.Description className="...">You are all caught up. Good job!</Popover.Description>
      </Popover.Popup>
    </Popover.Positioner>
  </Popover.Portal>
</Popover.Root>

What it demonstrates: the canonical part-assembly shape shared by every overlay/positioned component in Base UI — Root (state) → Trigger (opener) → Portal (DOM escape) → Positioner (placement) → Popup (visual surface), optionally with Arrow/Title/Description.

Key Takeaways

Add the .root { isolation: isolate } + body { position: relative } styles once, globally, before building any popup component — skipping this causes stacking/backdrop bugs that are easy to misdiagnose later.
There is no default visual output for any component — plan CSS Modules, Tailwind, or CSS-in-JS from the start; see ch005 for the data-*-attribute styling contract every component shares.
Prefer shadcn/ui over hand-styling every primitive if the project wants a fast, opinionated starting point — it's built directly on this library.

Connects To

ch005 (Styling): the data-* attribute convention referenced by every class name in the demo above.
ch006 (Animation): data-starting-style/data-ending-style used in the Popover demo's transition classes.
ch033 (Popover): full API for the component assembled here.