> ## Documentation Index
> Fetch the complete documentation index at: https://developers.smarterservices.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SmarterElements

> Embeddable UI components with component isolation and modal support

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

## What are SmarterElements?

SmarterElements are embeddable UI components that provide:

* **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 isolated 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

```bash theme={null}
npm install @smarterservices/smarter-elements
```

### CDN (Browser)

```html theme={null}
<script src="https://unpkg.com/@smarterservices/smarter-elements@latest/dist/browser.js"></script>
```

### React Integration

```jsx theme={null}
import { useSmarterElements } from '@smarterservices/smarter-elements';
```

## Quick Start

### Vanilla JavaScript

```javascript theme={null}
// 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

```jsx theme={null}
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

```javascript theme={null}
import { debounce, throttle } from '@smarterservices/smarter-elements';

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

window.addEventListener('resize', debouncedResize);
```