Skip to main content
SmarterElements is a JavaScript library for embedding isolated UI components into web applications. Components run in secure iframes with automatic resizing, modal support, and seamless parent-child communication.

​
What are SmarterElements?

SmarterElements are iframe-based UI components that provide:
  • Iframe Isolation: Components run in isolated contexts for security
  • Automatic Resizing: Content-driven sizing with smooth transitions
  • Modal System: Overlay display with backdrop blur and focus management
  • Event Communication: Bidirectional messaging between parent and element
  • Size Constraints: Flexible width/height limits with CSS unit support

​
Key Features

  • Secure Isolation: Each element runs in its own iframe sandbox
  • Modal & DOM Mounting: Display elements inline or as overlay modals
  • Auto-Resizing: Elements automatically adjust to content size
  • React Integration: Dedicated hooks and components for React apps
  • CDN Ready: Direct script inclusion without build tools
  • Utility Functions: Built-in debounce and throttle for performance
  • TypeScript Support: Full type definitions included

​
Architecture

​
Element Types

  • BlockKit Renderer: Dynamic UI rendering from JSON configurations
  • Custom Elements: Application-specific components
  • Modal Elements: Overlay components with backdrop and focus management

​
Integration Patterns

  • DOM Mounting: Embed elements directly into existing containers
  • Modal Display: Show elements as overlay modals with auto-sizing
  • React Components: Use dedicated React hooks and components
  • Vanilla JavaScript: Direct API usage without frameworks

​
Installation

​
NPM Package

npm install @smarterservices/smarter-elements

​
CDN (Browser)

<script src="https://unpkg.com/@smarterservices/smarter-elements@latest/dist/browser.js"></script>

​
React Integration

import { useSmarterElements } from '@smarterservices/smarter-elements';

​
Quick Start

​
Vanilla JavaScript

// Initialize SmarterElements
const elements = new SmarterElements({
  baseUrl: '/elements'
});

// Create and mount an element
const element = elements.create('blockkit/renderer', {
  config: {
    blocksJson: JSON.stringify([
      { type: "heading", level: 1, text: "Hello World" }
    ])
  }
});

// Mount to DOM
element.mount('#container');

// Or open as modal
await element.openModal({
  width: '600px',
  maxWidth: '90vw'
});

​
React Hook

import { useSmarterElements } from '@smarterservices/smarter-elements';

function MyComponent() {
  const elements = useSmarterElements();
  
  const openElement = async () => {
    const element = elements.create('blockkit/renderer', {
      config: { /* ... */ }
    });
    
    await element.openModal({ width: '80%' });
  };
  
  return <button onClick={openElement}>Open Element</button>;
}

​
Utility Functions

import { debounce, throttle } from '@smarterservices/smarter-elements';

// Debounce resize events for performance
const debouncedResize = debounce(() => {
  element.recalculateSize();
}, 300);

window.addEventListener('resize', debouncedResize);