UI root
A React component in Beamline's Layout category, in the free sample.
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).
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, sheet, popover, menus, select, tooltip, hover card, toast) reads usePortalContainer() from here.
Dependencies
@radix-ui/react-direction
Import
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 · Connect your agent
More in Layout
- 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: Holds media, video and embeds at a fixed width-to-height ratio while the layout resizes.
- 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: 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: 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: One region that opens and closes in place from its trigger, its height animating to the content.
- 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: A dense card that grows in place when asked: the frame resizes and the clamped preview opens into the full text.
- 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: 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: A hairline between groups, horizontal or vertical; hidden from screen readers unless it carries meaning.