Getting Started with SmarterElements

SmarterElements is a powerful system for embedding interactive UI components into web applications. Elements can be mounted directly into the DOM or displayed in modals with full isolation and automatic resizing.

Installation

npm install @smarterservices/smarter-elements

Quick Start

React Integration

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

function App() {
  const elements = useSmarterElements();
  
  const openElement = async () => {
    const element = elements.create('blockkit/renderer', {
      config: {
        blocksJson: JSON.stringify([
          {
            type: "heading",
            level: 1,
            text: "Hello SmarterElements!"
          }
        ])
      }
    });
    
    await element.openModal({
      width: '600px',
      height: '400px'
    });
  };
  
  return (
    <div>
      <button onClick={openElement}>
        Open Element
      </button>
    </div>
  );
}

JavaScript Integration

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

// Initialize the elements system
const elements = new SmarterElements({
  baseUrl: '/elements' // Your elements endpoint
});

// Create and display an element
const element = elements.create('blockkit/renderer', {
  config: {
    blocksJson: JSON.stringify([
      {
        type: "heading", 
        level: 1,
        text: "Hello SmarterElements!"
      }
    ])
  },
  onReady: () => {
    console.log('Element loaded successfully');
  },
  onError: (error) => {
    console.error('Element failed to load:', error);
  }
});

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

// Or open in a modal
element.openModal({
  width: '80%',
  maxWidth: '900px'
});

Authentication

Production embeds are authenticated with short-lived STS tokens minted by your backend — your long-lived API credential never reaches the browser. Your server exchanges its credential for a token scoped to a single element + end user, and hands the signed assertion to the SDK:

// Your backend returns { elementToken, stsToken, expiresIn, absoluteExpiresAt }
const auth = await fetch('/api/embeds/token').then((r) => r.json());

const element = elements.create('proctoring/sessionviewer', {
  config: { sessionSid: 'ES123456' },
  elementToken: auth.elementToken,                // RS256-signed element assertion
  stsToken: auth.stsToken,                        // opaque runtime credential
  tokenExpiresIn: auth.expiresIn,
  tokenAbsoluteExpiresAt: new Date(auth.absoluteExpiresAt).getTime(),
  onTokenRefresh: async () => {                   // silent rotation before expiry
    const next = await fetch('/api/embeds/token/refresh', { method: 'POST' }).then((r) => r.json());
    return {
      elementToken: next.elementToken,
      stsToken: next.stsToken,
      expiresIn: next.expiresIn,
      absoluteExpiresAt: new Date(next.absoluteExpiresAt).getTime(),
    };
  },
});

element.mount('#proctoring');

See Authentication & Tokens for how to mint and refresh tokens and the full security model.

Core Concepts

Elements

Elements are self-contained UI components that run in isolated contexts. Each element has:

Type: A unique identifier (e.g., blockkit/renderer)
Configuration: Parameters passed to the element
Events: Messages the element can send/receive
Lifecycle: Methods for mounting, destroying, etc.

Element Lifecycle

Create - Initialize element with configuration
Mount - Attach to DOM or open in modal
Ready - Element is loaded and interactive
Events - Ongoing communication with element
Destroy - Clean up resources

Configuration

Elements accept configuration through the config parameter:

const element = elements.create('element-type', {
  config: {
    // Element-specific parameters
    param1: 'value1',
    param2: 'value2'
  }
});

Display Options

DOM Mounting

Mount elements directly into existing DOM elements:

const element = elements.create('element-type', { config });
element.mount('#container'); // Mount to element with ID 'container'
element.mount('.my-class');  // Mount to first element with class
element.mount(domElement);   // Mount to DOM element reference

Display elements in overlay modals with automatic sizing:

const element = elements.create('element-type', { config });

await element.openModal({
  width: '80%',           // Modal width
  height: '600px',        // Modal height (optional, auto-sizes by default)
  maxWidth: '1000px',     // Maximum width constraint
  maxHeight: '90vh',      // Maximum height constraint
  dismissOnDocumentClick: false, // Close on backdrop click
  escapeClose: true,      // Close on Escape key
  zIndex: 1000           // Modal z-index
});

Event Handling

Elements can send events to the parent application:

const element = elements.create('element-type', {
  config: { /* ... */ },
  onEvent: (eventType, data) => {
    switch (eventType) {
      case 'user-action':
        console.log('User performed action:', data);
        break;
      case 'data-changed':
        console.log('Data updated:', data);
        break;
    }
  }
});

Error Handling

Handle element errors gracefully:

const element = elements.create('element-type', {
  config: { /* ... */ },
  onError: (error) => {
    console.error('Element error:', error);
    // Handle error (show message, retry, etc.)
  }
});

Advanced Features

Auto-Resizing

Elements automatically resize based on their content. The modal system includes:

Content-driven sizing - Height adjusts to content
Smooth transitions - Animated resize changes
Performance optimization - Debounced resize updates
Constraint handling - Respects min/max limits

Element Communication

Send messages to elements after they’re mounted:

// Send data to element
element.postMessage({
  type: 'update-config',
  data: { newParam: 'newValue' }
});

// Listen for responses
element.on('config-updated', (data) => {
  console.log('Element updated:', data);
});

Multiple Elements

Manage multiple elements simultaneously:

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

// Create multiple elements
const element1 = elements.create('type1', { config: {} });
const element2 = elements.create('type2', { config: {} });

// Mount to different containers
element1.mount('#container1');
element2.mount('#container2');

// Get all active elements
const allElements = elements.getElements();

// Clean up all elements
elements.destroyAll();

Best Practices

Performance

Lazy loading - Only create elements when needed
Proper cleanup - Always destroy elements when done
Event management - Remove event listeners appropriately

Error Handling

Graceful degradation - Handle element load failures
User feedback - Show loading states and error messages
Retry logic - Implement retry for transient failures

Accessibility

Keyboard navigation - Elements support keyboard interaction
Screen readers - Proper ARIA labels and roles
Focus management - Modal focus trapping and restoration

Next Steps

Browse the Element Reference for available elements
Check out Examples for common use cases
Read the API Reference for detailed method documentation

Need help? Check our troubleshooting guide or contact support.

​Getting Started with SmarterElements

​Installation

​Quick Start

​React Integration

​JavaScript Integration

​Authentication

​Core Concepts

​Elements

​Element Lifecycle

​Configuration

​Display Options

​DOM Mounting

​Modal Display

​Event Handling

​Error Handling

​Advanced Features

​Auto-Resizing

​Element Communication

​Multiple Elements

​Best Practices

​Performance

​Error Handling

​Accessibility

​Next Steps

Getting Started with SmarterElements

Installation

Quick Start

React Integration

JavaScript Integration

Authentication

Core Concepts

Elements

Element Lifecycle

Configuration

Display Options

DOM Mounting

Modal Display

Event Handling

Error Handling

Advanced Features

Auto-Resizing

Element Communication

Multiple Elements

Best Practices

Performance

Error Handling

Accessibility

Next Steps