# UI root

A React component in [Beamline](https://beamline.io/)'s [Layout](https://beamline.io/components/layout) category, in the free sample. Live demo: https://beamline.io/components/ui-root

Makes a region of any app a Beamline root: theme, brand and direction for everything inside, and a matching layer at page level where its menus, dialogs and tooltips open.

## Use it for

- Using Beamline inside an app that has its own styles: wrap only the screens or widgets that use the system, so nothing outside the root is affected.
- A region with a different theme, brand or direction from the rest of the page (a dark trading panel in a light app).

## Not for

- An app built entirely on the system: put class="pui dark" on <html> instead (no wrapper, overlays open in the page).
- Right-to-left text alone inside an existing root ([direction](https://beamline.io/components/direction)).

## Anatomy

- root (div.pui with the theme class, data-theme, data-accent, dir, and --pui-brand when set)
- portal layer (div.pui appended to <body>, mirroring theme, accent, brand and dir; every overlay inside the root renders into it)

## Variants

- **theme**: dark, light
- **dir**: ltr, rtl
- **accent**: blue, violet, green, amber, orange, rose, neutral

## States

- server and first client render: managed portal pending
- attached: stable portal destination
- appearance changed: same controls and portal node
- inherit=false resets numeric foundation parameters on both root and stable portal
- per-host CSS timing overrides are resolved independently of sibling regions

## Keyboard

- None of its own; sets the direction Radix parts use for ←/→ inside rtl.

## Motion

None. Changing theme switches tokens in one frame.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `"dark" \| "light"` | `"dark"` | Theme for everything inside, overlays included. |
| `brand` | `string` | — | Any CSS colour; becomes --pui-brand. Accent, focus ring, series 1 and glows derive from it (Prism keeps its spectrum for charts and takes the brand for its main action, focus ring and glows). |
| `accent` | `"blue" \| "violet" \| "green" \| "amber" \| "orange" \| "rose" \| "neutral"` | — | A preset brand when no brand colour is given. Unset, the look's own brand applies (Prism: white light in dark, ink-black in light; Pop: tomato; the others: blue). |
| `dir` | `"ltr" \| "rtl"` | `"ltr"` | Reading direction for the region and its overlays. |
| `look` | `"soft" \| "blueprint" \| "glass" \| "metal" \| "glow" \| "pop" \| "mono" \| "ink"` | `"soft"` | The look inside, overlays included: type, icon weight, corners, page colours and paint (DESIGN-LANGUAGE.md "Looks"). Independent of theme. |
| `motionScale` | `number` | — | Animation speed: multiplies every duration and spring in CSS and JS (1 = foundation default). Reduced and none motion still win. |
| `radiusScale` | `number` | — | Roundness: scales the style's corner radii (0 = square); a style's pinned corners stay. |
| `typeScale` | `number` | — | Type size: multiplies every step of the type scale and every type role. |
| `typeRatio` | `number` | — | Type contrast: how far headings sit from 14px body (<1 flatter, >1 more dramatic). |
| `spaceScale` | `number` | — | Spacing: scales spacing tokens and Tailwind padding, margin and gap utilities; control heights, icon sizes and row density stay. |
| `preset` | `PresetRef` | — | A built-in look or a custom preset { id, visualContract: 1, base } whose stylesheet the app imports. |
| `density` | `"compact" \| "default" \| "comfortable"` | — | Row density for tables, grids and order books in this scope and its overlays. |
| `motion` | `"auto" \| "reduced" \| "none"` | — | Motion mode; auto follows the OS. |
| `className` | `string` | — | Lands on the root element. |
| `children` (required) | `ReactNode` | — |  |

## Built from

- Every overlay ([dialog](https://beamline.io/components/dialog), [sheet](https://beamline.io/components/sheet), [popover](https://beamline.io/components/popover), menus, [select](https://beamline.io/components/select), [tooltip](https://beamline.io/components/tooltip), hover [card](https://beamline.io/components/card), [toast](https://beamline.io/components/toast)) reads usePortalContainer() from here.

## Dependencies

`@radix-ui/react-direction`

## Import

```tsx
import { UIRoot } from "@/components/ui-root/ui-root";
```

## Get it

UI root is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. UI root is in the free sample, which costs nothing. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Layout

- [Accordion](https://beamline.io/components/accordion): Topics that open in place, one at a time or several: FAQs and settings sections; each header is a button and the panel's height follows its content.
- [Aspect ratio](https://beamline.io/components/aspect-ratio): Holds media, video and embeds at a fixed width-to-height ratio while the layout resizes.
- [Bezel](https://beamline.io/components/bezel): A double-bezel frame: an outer shell with a hairline, a small gap, and an inset panel with its own edge, so a preview, chart or media reads as set into…
- [Card](https://beamline.io/components/card): A record or a small group of related content and actions: optional media, avatar, title, status, action, meta, free content and a Details toggle; plain…
- [Carousel](https://beamline.io/components/carousel): A row of slides that snap into place: swipe on touch, drag or the arrows with a mouse, ← → when focused, or the dots; optional autoplay that pauses and…
- [Collapsible](https://beamline.io/components/collapsible): One region that opens and closes in place from its trigger, its height animating to the content.
- [Direction](https://beamline.io/components/direction): Sets left-to-right or right-to-left for everything inside: text and logical spacing flip, and Radix parts read the direction for keys and placement.
- [Expandable card](https://beamline.io/components/expandable-card): A dense card that grows in place when asked: the frame resizes and the clamped preview opens into the full text.
- [Resizable panels](https://beamline.io/components/resizable-panels): Panes that trade space across draggable dividers; each divider is a focusable separator with arrow keys, limits, folding for collapsible panes and…
- [Scroll area](https://beamline.io/components/scroll-area): A native scroll region with thin overlay thumbs and edge fades that show only where more content waits; thumbs can be dragged or clicked.
- [Separator](https://beamline.io/components/separator): A hairline between groups, horizontal or vertical; hidden from screen readers unless it carries meaning.