Provide proper docs regarding usage of portaled components

[kotAPI]

Explain Rad UI's philosophy and also how devs can bring in their own styling if they choose not to use the Theme component

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• [New Feature] Standardize Portal behaviors across components #603

Related Issues

• Preserve Dark Mode details when using React Portals #468
• Tooltips do not portal gracefully inside Theme Component #1657
• [New Feature] Theme utility component  #762
• Set up JS/TS Linting as a pre-commit hook #472
• Make Snyk raise PRs only on security-fixes branch #478

👤 Suggested Assignees

• kotAPI
• GoldGroove06

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Create comprehensive documentation explaining Rad UI's styling philosophy and guide developers on bringing their own styling when not using the Theme component, with specific attention to portaled components and theming considerations.

Observations

Rad UI is a React component library that follows a "headless-first" philosophy—components are unstyled by default with optional pre-built styling. The library uses a multi-layered styling approach combining SCSS component themes, CSS tokens, Tailwind CSS integration, and data attribute-based theming. Portaled components (AlertDialog, Dialog, Tooltip, DropdownMenu, ContextMenu) use Floating UI and render outside the normal DOM hierarchy. The Theme component applies styling through data attributes rather than Context or CSS variables. A #rad-ui-theme-container pattern exists in primitive portal components to help ensure portaled content receives theme attributes, but this pattern is currently undocumented.

Assumptions

Assumption 1: Documentation structure and location

Options Considered:

• Create a single combined guide covering philosophy, custom styling, and portals
• Create separate guides for styling philosophy and portaled components

Chosen Option: Create separate guides for styling philosophy and portaled components

Rationale: Styling philosophy and custom styling patterns are distinct concerns from portal-specific theming behavior. Developers seeking general styling guidance shouldn't need to wade through portal-specific details, and developers working with portals need targeted guidance about their unique challenges. This separation improves discoverability and maintains focused documentation.

Assumption 2: Depth of #rad-ui-theme-container documentation

Options Considered:

• Document it as a primary recommended pattern with code examples
• Mention it as an advanced technique with minimal detail
• Don't document it and let the default Theme wrapping approach suffice

Chosen Option: Document it as a primary recommended pattern with code examples

Rationale: This pattern solves a real problem that developers will encounter when using portaled components with custom styling. Radix UI documents a similar pattern of wrapping portal content with Theme components, showing this is a known need. Making this discoverable prevents developers from debugging styling issues with portaled components.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Create Core Styling Philosophy and Customization Guide

Create comprehensive documentation explaining Rad UI's "opinionated where bugs live, flexible where taste lives" philosophy and guide developers through various custom styling approaches.

Task 1: Create styling philosophy guide structure

Establish the main styling guide page that articulates Rad UI's design principles and customization philosophy.

• Create docs/app/docs/guides/styling/page.mdx to house the main styling guide
• Document the "unstyled by default" philosophy, explaining why Rad UI stays neutral about visual design while being strict about accessibility and behavior
• Explain the "escape hatch" approach where developers can use optional default styles or progressively adopt their own design system
• Position Rad UI as complementary to design systems rather than prescriptive about visual language
• Include navigation updates in docs/app/docs/docsNavigationSections.tsx to add the new "Styling" guide under the Guides section

Task 2: Document styling approaches without Theme component

Provide concrete guidance on the multiple ways developers can style components when building their own design system.

• Create examples showing Tailwind CSS customization using utility classes applied via className prop
• Demonstrate CSS Modules approach with scoped stylesheets imported alongside components
• Show vanilla CSS/SCSS usage with custom stylesheets targeting component data attributes
• Document CSS variable customization by overriding the existing --rad-ui-* tokens in global stylesheets
• Explain how component data attributes (e.g., data-button-variant, data-state) serve as styling hooks
• Include code examples in docs/app/docs/guides/styling/examples/ directory showing each approach

Task 3: Document Theme component behavior and optional usage

Clarify what the Theme component does and when developers should or shouldn't use it.

• Explain that Theme applies styling through data attributes (data-rad-ui-theme, data-rad-ui-accent-color, etc.) on a container div
• Document that Theme is optional—components work without it when developers provide their own styling
• Explain the relationship between Theme data attributes and the compiled SCSS stylesheets in dist/themes/default.css
• Clarify that developers using custom styling can skip Theme entirely or use it selectively for only certain component trees
• Show how to import the compiled theme CSS (dist/themes/default.css) for default styling support

🤖 Prompt for AI agents

Create comprehensive styling documentation explaining Rad UI's philosophy and
custom styling approaches.

Create the main styling guide at `docs/app/docs/guides/styling/page.mdx`:
- Document the "unstyled by default" philosophy
- Explain the "escape hatch" approach with optional default styles
- Position Rad UI as complementary to design systems
- Show multiple styling approaches: Tailwind CSS with className prop, CSS
Modules, vanilla CSS/SCSS targeting data attributes, CSS variable overrides
- Explain component data attributes as styling hooks (data-button-variant,
data-state, etc.)
- Document Theme component behavior: applies styling via data attributes on
container div
- Clarify Theme is optional when using custom styling
- Explain relationship between Theme data attributes and compiled SCSS in
dist/themes/default.css
- Show how to import compiled theme CSS for default styling

Create code examples in `docs/app/docs/guides/styling/examples/` showing each
styling approach

Update `docs/app/docs/docsNavigationSections.tsx` to add "Styling" guide under
Guides section

Phase 2: Create Portaled Components Guide with Theming Considerations

Document portal behavior, styling challenges, and solutions specific to components that render outside the normal DOM hierarchy.

Task 1: Create portaled components overview

Establish foundational understanding of what portaled components are and why they exist.

• Create docs/app/docs/guides/portaled-components/page.mdx for the portaled components guide
• Explain what React portals are and why they're used for dialogs, tooltips, and similar UI elements that need to break out of their container
• List which Rad UI components use portals: AlertDialog, Dialog, Tooltip, DropdownMenu, ContextMenu
• Document that portaled components don't inherit CSS properties from their parent React component because they render in a different DOM location
• Add navigation entry in docs/app/docs/docsNavigationSections.tsx under Guides section

Task 2: Document portal theming challenges and the #rad-ui-theme-container pattern

Provide clear guidance on ensuring portaled components receive theme styling.

• Explain that Theme component data attributes don't reach portaled content since it renders outside the Theme wrapper's DOM subtree
• Document the #rad-ui-theme-container pattern used in SelectPrimitivePortal, MenuPrimitivePortal, and DialogPrimitivePortal
• Show how to create a <div id="rad-ui-theme-container"> element and wrap it with the Theme component to ensure portals render inside a themed container
• Provide code examples showing the setup pattern where Theme wraps the theme container div
• Explain the fallback chain: custom container prop → #rad-ui-theme-container → document.body
• Document that this pattern is necessary when using Theme component with custom portaled components

Task 3: Document custom styling approaches for portaled components

Guide developers using their own styling on how to style portaled components without Theme.

• Explain that when not using Theme, developers need to ensure their global CSS reaches portaled elements
• Show how to use CSS selectors targeting portal container elements (e.g., [data-floating-ui-portal] or body-level selectors)
• Document approaches for injecting custom CSS variables or classes at the portal rendering location
• Provide example of wrapping portal content with custom context or styling providers when needed
• Show how component data attributes remain available on portaled content for custom styling hooks

🤖 Prompt for AI agents

Create comprehensive portaled components documentation explaining portal
behavior and theming.

Create the portaled components guide at
`docs/app/docs/guides/portaled-components/page.mdx`:
- Explain what React portals are and why they're used for dialogs, tooltips,
etc.
- List portaled Rad UI components: AlertDialog, Dialog, Tooltip, DropdownMenu,
ContextMenu
- Document that portaled components don't inherit CSS from parent React
components due to different DOM location
- Explain theming challenge: Theme data attributes don't reach portaled content
outside wrapper's DOM subtree
- Document #rad-ui-theme-container pattern with code examples showing setup
- Show creating div with id="rad-ui-theme-container" wrapped by Theme component
- Explain fallback chain: custom container prop → #rad-ui-theme-container →
document.body
- Document custom styling approaches without Theme: global CSS reaching portaled
elements, CSS selectors targeting portal containers, injecting CSS
variables/classes at portal location
- Show wrapping portal content with custom providers
- Explain component data attributes remain available on portaled content

Update `docs/app/docs/docsNavigationSections.tsx` to add navigation entry under
Guides section

Phase 3: Update Component Documentation

Add portal-specific guidance to relevant component documentation pages with links to the comprehensive guides.

Task 1: Add portal behavior sections to component docs

Update individual component documentation to mention portal usage and link to detailed guides.

• Add "Portal Behavior" sections to docs/app/docs/components/dialog/page.mdx, docs/app/docs/components/alert-dialog/page.mdx, docs/app/docs/components/tooltip/page.mdx
• Briefly mention that these components use portals to render outside normal DOM hierarchy
• Include a note about theming considerations with a link to the Portaled Components guide
• Show that Portal fragments accept optional container prop for custom rendering location
• Link to the Styling guide for developers implementing custom designs

Task 2: Enhance introduction documentation

Update the getting started documentation to reference the new comprehensive guides.

• Update docs/app/docs/first-steps/introduction/page.mdx to add links to the new Styling guide in the "Styling Freedom" section
• Add a brief mention of portaled components with a link to the guide for developers who will work with dialogs, tooltips, etc.
• Ensure the philosophy section maintains its concise nature while pointing to detailed guides for implementation details

🤖 Prompt for AI agents

Update existing documentation to reference new styling and portaled components
guides.

Add "Portal Behavior" sections to component documentation:
- Update `docs/app/docs/components/dialog/page.mdx`
- Update `docs/app/docs/components/alert-dialog/page.mdx`
- Update `docs/app/docs/components/tooltip/page.mdx`

In each, briefly mention portal usage, add theming considerations note linking
to Portaled Components guide, show Portal fragments accept optional container
prop, link to Styling guide

Update `docs/app/docs/first-steps/introduction/page.mdx`:
- Add links to Styling guide in "Styling Freedom" section
- Add brief mention of portaled components with link to guide
- Keep philosophy section concise while pointing to detailed guides

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create comprehensive styling documentation explaining Rad UI's philosophy and
custom styling approaches.

Create the main styling guide at `docs/app/docs/guides/styling/page.mdx`:
- Document the "unstyled by default" philosophy
- Explain the "escape hatch" approach with optional default styles
- Position Rad UI as complementary to design systems
- Show multiple styling approaches: Tailwind CSS with className prop, CSS
Modules, vanilla CSS/SCSS targeting data attributes, CSS variable overrides
- Explain component data attributes as styling hooks (data-button-variant,
data-state, etc.)
- Document Theme component behavior: applies styling via data attributes on
container div
- Clarify Theme is optional when using custom styling
- Explain relationship between Theme data attributes and compiled SCSS in
dist/themes/default.css
- Show how to import compiled theme CSS for default styling

Create code examples in `docs/app/docs/guides/styling/examples/` showing each
styling approach

Update `docs/app/docs/docsNavigationSections.tsx` to add "Styling" guide under
Guides section
===============================================================================

Task: 2

Create comprehensive portaled components documentation explaining portal
behavior and theming.

Create the portaled components guide at
`docs/app/docs/guides/portaled-components/page.mdx`:
- Explain what React portals are and why they're used for dialogs, tooltips,
etc.
- List portaled Rad UI components: AlertDialog, Dialog, Tooltip, DropdownMenu,
ContextMenu
- Document that portaled components don't inherit CSS from parent React
components due to different DOM location
- Explain theming challenge: Theme data attributes don't reach portaled content
outside wrapper's DOM subtree
- Document #rad-ui-theme-container pattern with code examples showing setup
- Show creating div with id="rad-ui-theme-container" wrapped by Theme component
- Explain fallback chain: custom container prop → #rad-ui-theme-container →
document.body
- Document custom styling approaches without Theme: global CSS reaching portaled
elements, CSS selectors targeting portal containers, injecting CSS
variables/classes at portal location
- Show wrapping portal content with custom providers
- Explain component data attributes remain available on portaled content

Update `docs/app/docs/docsNavigationSections.tsx` to add navigation entry under
Guides section
===============================================================================

Task: 3

Update existing documentation to reference new styling and portaled components
guides.

Add "Portal Behavior" sections to component documentation:
- Update `docs/app/docs/components/dialog/page.mdx`
- Update `docs/app/docs/components/alert-dialog/page.mdx`
- Update `docs/app/docs/components/tooltip/page.mdx`

In each, briefly mention portal usage, add theming considerations note linking
to Portaled Components guide, show Portal fragments accept optional container
prop, link to Styling guide

Update `docs/app/docs/first-steps/introduction/page.mdx`:
- Add links to Styling guide in "Styling Freedom" section
- Add brief mention of portaled components with link to guide
- Keep philosophy section concise while pointing to detailed guides

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!