English for Radix UI Developers

Radix UI conversations use precise terms for how unstyled, accessible components are assembled — primitive, composition, asChild — and a developer used to fully-styled component libraries can mix these up with generic “component” language in a way that makes design system discussions vague.

Key Vocabulary

Primitive — an unstyled, accessible building-block component, such as Dialog or Dropdown Menu, that handles behavior and ARIA semantics but leaves all visual styling to the consumer. “We’re using the Radix dialog primitive and layering our own design system’s styles on top, instead of writing focus-trapping logic ourselves.”

Composition — the pattern of building a complex component out of several smaller sub-components, like Dialog.Trigger, Dialog.Content, and Dialog.Close, each responsible for one part of the behavior. “This isn’t one big Dialog component — it’s a composition of Trigger, Content, and Close pieces, so we can rearrange the markup without losing accessibility behavior.”

asChild prop — a Radix pattern that lets a primitive merge its behavior and props onto a custom child element instead of rendering its own wrapper DOM node, avoiding unwanted nested elements. “Use asChild here so the trigger renders as our existing Button component directly, instead of wrapping it in an extra <button> from Radix.”

Controlled vs. uncontrolled state — whether a primitive’s open/closed or selected state is managed externally via props like open and onOpenChange, or internally by the component itself when no such props are passed. “Switch this to a controlled dropdown since we need to close it programmatically from outside when another action happens — the uncontrolled version can’t be driven externally.”

Portal — a Radix pattern for rendering a component’s content, like a dialog overlay or tooltip, into a different part of the DOM tree, typically to avoid clipping from parent elements with overflow: hidden. “Render the tooltip content through a portal — otherwise it gets clipped by the scrollable container it’s nested inside.”

Common Phrases

• “Are we using the Radix primitive here, or did we build the accessibility behavior from scratch?”
• “Should this be controlled so we can close it externally, or is uncontrolled fine for this use case?”
• “Can we use asChild instead of letting Radix render its own wrapper element?”
• “Is this content going through a portal, or is it getting clipped by an ancestor’s overflow?”
• “Is this really a composition of separate parts, or did we collapse it into one opaque component?”

Example Sentences

Explaining a design system decision: “We built our design system’s dialog on top of the Radix dialog primitive so we get correct focus trapping and ARIA attributes for free, and only need to own the visual styling.”

Debugging a nested-button warning: “That hydration warning is because Radix’s trigger renders its own button by default — using asChild here lets it merge onto our existing button component instead of nesting two.”

Reviewing a controlled-state bug: “This dropdown isn’t closing when the user submits the form because it’s uncontrolled — we need to lift the open state up and drive it with open and onOpenChange.”

Professional Tips

• Say primitive rather than “component” when specifically discussing Radix’s unstyled building blocks — it signals the accessibility behavior is handled, and only visuals remain to be added.
• Describe complex UI as a composition of named sub-parts in documentation and reviews — it clarifies which piece owns which behavior, rather than treating the whole thing as one black box.
• Recommend asChild explicitly when a nested-element or duplicate-semantics bug shows up — naming the pattern speeds up the fix for anyone familiar with Radix.
• Clarify controlled vs. uncontrolled early when a component needs to be driven by external logic — retrofitting control after building uncontrolled often means a larger rewrite than starting controlled would have.

Practice Exercise

1. Explain what a Radix primitive provides and what it deliberately leaves to the consumer.
2. Describe what problem the asChild prop solves.
3. Write a sentence explaining when you’d choose a controlled component over an uncontrolled one.