@dimetrix/react-iframe

React Iframe

A fully configurable React component that renders React components inside an isolated iframe with complete style isolation and full React functionality.

✨ Features

• 🎯 Full React Support - All React features work normally (hooks, state, effects, context)
• 🎨 Style Isolation - CSS is scoped to the iframe, preventing style conflicts with parent page
• 🔧 Complete iframe API - All standard HTML iframe attributes and events are supported
• 📏 Auto Height - Automatically adjust iframe height to match content (no scrollbars)
• 💪 TypeScript - Full type safety with proper iframe prop types
• 🎭 Flexible API - Accept components as children or via component prop
• ♿ Accessibility - All ARIA attributes supported
• ⚡ Performance - Optimized with React best practices (memo, useMemo, useCallback)

📦 Installation

npm install @dimetrix/react-iframe

Peer Dependencies:

• react ^17.0.0 || ^18.0.0 || ^19.0.0
• react-dom ^17.0.0 || ^18.0.0 || ^19.0.0

🚀 Quick Start

Basic Usage

import { ReactIframe } from '@dimetrix/react-iframe';
import MyComponent from './MyComponent';

function App() {
  return (
    <ReactIframe
      component={MyComponent}
      width="100%"
      height="400px"
      sandbox="allow-scripts allow-same-origin"
    />
  );
}

Using Children

import { ReactIframe } from '@dimetrix/react-iframe';

function App() {
  return (
    <ReactIframe width="100%">
      <MyComponent />
    </ReactIframe>
  );
}

Note: autoHeight is enabled by default, so no height prop is needed.

📖 Documentation

Props

The ReactIframe component extends all standard HTML iframe attributes and adds the following props:

Prop	Type	Default	Description
component	ComponentType<Record<string, unknown>>	-	React component to render inside the iframe (alternative to children)
children	ReactNode	-	React component(s) to render inside the iframe (alternative to component)
componentProps	Record<string, unknown>	{}	Props to pass to the component rendered inside the iframe
autoHeight	boolean	true	Automatically adjust iframe height to match content height (enabled by default)
minHeight	number	0	Minimum height in pixels when autoHeight is enabled
maxHeight	number	undefined	Maximum height in pixels when autoHeight is enabled
...iframeProps	React.IframeHTMLAttributes	-	All standard HTML iframe attributes

Note: Either component or children must be provided, but not both.

Standard Iframe Attributes

All standard HTML iframe attributes are supported and passed through:

Common Attributes:

• sandbox - Security sandbox attributes (e.g., "allow-scripts allow-same-origin")
• allow - Feature policy (e.g., "camera; microphone; geolocation")
• allowFullScreen - Allow fullscreen mode
• referrerPolicy - Referrer policy ("no-referrer", "strict-origin-when-cross-origin", etc.)
• loading - Lazy loading ("lazy" or "eager")
• name - Frame name
• width, height - Dimensions (ignored when autoHeight is true)
• title - Accessibility title
• className, style - Styling

Event Handlers:

• onLoad - Fired when iframe loads
• onError - Fired on iframe error
• onFocus, onBlur - Focus events
• All other standard React event handlers

Data & ARIA Attributes:

• All data-* attributes
• All aria-* attributes

💡 Usage Examples

Example 1: Basic Component Rendering

import { ReactIframe } from '@dimetrix/react-iframe';
import Counter from './Counter';

function App() {
  return (
    <ReactIframe
      component={Counter}
      width="100%"
      height="300px"
      sandbox="allow-scripts allow-same-origin"
      title="Counter Component"
    />
  );
}

Example 2: Passing Props to Component

import { ReactIframe } from '@dimetrix/react-iframe';
import UserProfile from './UserProfile';

function App() {
  return (
    <ReactIframe
      component={UserProfile}
      componentProps={{
        userId: 123,
        showEmail: true,
        theme: 'dark'
      }}
      width="100%"
      height="500px"
    />
  );
}

Example 3: Auto Height (Responsive)

import { ReactIframe } from '@dimetrix/react-iframe';
import DynamicContent from './DynamicContent';

function App() {
  return (
    <ReactIframe
      component={DynamicContent}
      width="100%"
      minHeight={200}
      maxHeight={1000}
      // autoHeight is enabled by default
      sandbox="allow-scripts allow-same-origin"
    />
  );
}

The autoHeight prop automatically adjusts the iframe height to match its content, preventing vertical scrollbars. This is especially useful for dynamic content that changes size.

Example 4: Advanced Configuration

import { ReactIframe } from '@dimetrix/react-iframe';
import MyComponent from './MyComponent';

function App() {
  const handleLoad = (event: React.SyntheticEvent<HTMLIFrameElement>) => {
    console.log('Iframe loaded successfully', event);
  };

  const handleError = (event: React.SyntheticEvent<HTMLIFrameElement>) => {
    console.error('Iframe error', event);
  };

  return (
    <ReactIframe
      component={MyComponent}
      width="600px"
      height="400px"
      sandbox="allow-scripts allow-same-origin allow-forms"
      allow="camera; microphone; geolocation"
      referrerPolicy="no-referrer"
      loading="lazy"
      title="My Isolated Component"
      className="my-iframe-class"
      style={{ border: '2px solid #ccc', borderRadius: '8px' }}
      onLoad={handleLoad}
      onError={handleError}
      data-testid="my-component-iframe"
      aria-label="Isolated React component"
    />
  );
}

Example 5: Using Children with Render Props

import { ReactIframe } from '@dimetrix/react-iframe';

function App() {
  return (
    <ReactIframe
      width="100%"
      height="400px"
      componentProps={{ initialCount: 10 }}
    >
      {(props) => <Counter initialCount={props.initialCount} />}
    </ReactIframe>
  );
}

🔍 How It Works

• Iframe Creation: The component creates an iframe element with your specified attributes
• Document Setup: Sets up the iframe's document structure with basic HTML and styles
• React Rendering: Uses the parent window's ReactDOM to render your component into the iframe
• Style Isolation: All styles are scoped to the iframe, preventing conflicts with the parent page
• Auto Height (if enabled): Uses ResizeObserver and MutationObserver to detect content size changes and adjust the iframe height accordingly

🎯 Common Use Cases

Widget Embedding

Embed React components as isolated widgets in third-party websites without style conflicts.

Component Sandboxing

Test or preview components in isolation without affecting the parent application.

Style Isolation

Render components with their own CSS that won't interfere with the parent page styles.

Dynamic Content

Display content that changes size dynamically with automatic height adjustment.

🛠️ TypeScript

Full TypeScript support is included. Import types as needed:

import { ReactIframe, ReactIframeProps } from '@dimetrix/react-iframe';

// Use the type for props
const props: ReactIframeProps = {
  component: MyComponent,
  width: '100%',
  height: '400px',
  autoHeight: true,
};

🌐 Browser Support

Works in all modern browsers that support:

• React 17, 18, or 19
• HTML5 iframes
• ES6+ JavaScript
• ResizeObserver (for auto-height feature, with fallback for older browsers)

📚 Examples

See the example/ directory for a complete demo application showcasing:

• Counter Component - Demonstrates React state management inside an iframe
• Form Component - Shows user interaction and form handling
• Styled Box Component - Illustrates CSS isolation

To run the example:

cd example
npm install
npm run dev

⚠️ Important Notes

Sandbox Restrictions

When using the sandbox attribute, ensure you include allow-same-origin if you need to access the iframe's content:

// ✅ Good - allows script execution and same-origin access
sandbox="allow-scripts allow-same-origin"

// ❌ May not work - too restrictive
sandbox="allow-scripts"

Auto Height Limitations

• Auto-height requires access to the iframe's content, so ensure sandbox includes allow-same-origin if used
• The feature uses ResizeObserver with a fallback to polling for older browsers
• Performance is optimized with requestAnimationFrame throttling

Component Props

• Props passed via componentProps are passed directly to your component
• The component receives these props as normal React props
• Changes to componentProps will trigger re-renders inside the iframe

🐛 Troubleshooting

Iframe content not accessible

If you see warnings about not being able to access iframe content:

• Check your sandbox attribute - ensure allow-same-origin is included
• Verify CORS settings if loading from a different origin
• Check browser console for specific error messages

Auto-height not working

• Ensure autoHeight={true} is set
• Verify sandbox includes allow-same-origin
• Check that content is actually changing size
• Try setting explicit minHeight to see if the feature is working

Styles not applying

Styles inside the iframe are isolated. If you need to share styles:

• Inject styles programmatically into the iframe document
• Use CSS variables that can be passed through
• Include styles within your component

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

📄 Changelog

1.0.0

• Initial release
• Full iframe prop propagation
• Auto-height feature
• TypeScript support
• React 17/18/19 compatibility

Made with ❤️ for the React community