Portal

Preview

Installation

npm install @native-ui-org/primitives

pnpm add @native-ui-org/primitives

yarn add @native-ui-org/primitives

bun add @native-ui-org/primitives

Overview

Portal moves component rendering to a different part of the DOM tree on web, while maintaining normal rendering on mobile.

Setup & Usage Guide

Portal is primarily a web utility for escaping z-index and overflow constraints.

1. Install and Import

Install from npm:

npm install @native-ui-org/primitives

Then import from the package:

import { Portal } from "@native-ui-org/primitives";

2. Basic Usage

Render content at document root (web only):

    <Portal>
  <View style={styles.overlay}>
    <Text>This renders at document.body on web</Text>
  </View>
    </Portal>

3. Custom Container

Specify a custom DOM container:

  const modalRoot = document.getElementById('modal-root');
  
    <Portal container={modalRoot}>
  <View style={styles.modal}>
    <Text>Modal content</Text>
  </View>
    </Portal>

4. Building a Modal

Combine Portal with other components:

function Modal({ open, children }) {
  if (!open) return null;
  
  return (
    <Portal>
      <View style={styles.overlay}>
        <View style={styles.modalContent}>
        {children}
        </View>
      </View>
        </Portal>
  );
}

API Reference

Portal

Renders children outside the normal React tree.

Platform notes:

• On web: Creates a React portal to the specified container
• On mobile: Renders children normally (Portal is transparent)

Platform Behavior

Accessibility

Portal is transparent to accessibility. All ARIA props and roles are maintained on the rendered children.

Best practices:

• Add proper focus management for modals
• Include aria-modal="true" on modal content
• Manage focus trap for keyboard navigation
• Restore focus when portal content unmounts

Version History

Summary: Portal is essential for overlays, modals, and tooltips on web. Use it to escape z-index stacking contexts and overflow constraints. On mobile, it's a transparent wrapper with no special behavior.