@rvanbaalen/portals

A reusable system for rendering content above the normal DOM flow. This library helps create and manage portal containers for UI elements like dropdowns, tooltips, modals, etc. that need to appear above other content regardless of stacking context.

Install the package via npm:

npm install @rvanbaalen/portals

Basic Example

import portalManager from '@rvanbaalen/portals';

// Create a dropdown element
const dropdown = document.createElement('div');
dropdown.className = 'dropdown';
dropdown.textContent = 'Dropdown Content';

// Add it to a portal
portalManager.addToPortal(dropdown);

// Position it relative to a button
const button = document.getElementById('dropdown-button');
portalManager.positionElement(dropdown, button, {
  placement: 'bottom-left',
  margin: 8
});

// Remove when no longer needed
portalManager.removeFromPortal(dropdown);

API Reference

PortalManager

The core class that manages portals in the DOM.

Constructor

constructor()

Creates a new PortalManager instance and initializes the main portal.

Properties

signals

manager.signals.portalCreated // Signal for when a portal is created
manager.signals.elementAdded // Signal for when an element is added to a portal
manager.signals.elementRemoved // Signal for when an element is removed from a portal

Signals that can be subscribed to for various portal events.

portals

manager.portals // Object containing references to all portal containers

Object containing references to all portal containers, indexed by their ID.

Methods

_createPortal

_createPortal(id, zIndex = 9999)

Internal method. Creates a new portal container.

Parameters:

• id (string): Unique identifier for the portal
• zIndex (number, optional): Z-index for the portal (higher appears above lower). Default: 9999

Returns: The portal container element (HTMLElement)

getPortal

getPortal(id = 'main', zIndex = 9999)

Gets a portal by ID (creates if it doesn't exist).

Parameters:

• id (string, optional): Portal identifier. Default: 'main'
• zIndex (number, optional): Z-index for new portal if created. Default: 9999

Returns: The portal container (HTMLElement)

addToPortal

addToPortal(element, portalId = 'main')

Adds an element to a portal.

Parameters:

• element (HTMLElement): Element to add to the portal
• portalId (string, optional): Portal identifier. Default: 'main'

Returns: The added element (HTMLElement)

removeFromPortal

removeFromPortal(element)

Removes an element from a portal.

Parameters:

• element (HTMLElement): Element to remove

Returns: True if the element was found and removed, false otherwise (boolean)

positionElement

positionElement(element, referenceElement, options = {})

Positions an element in a portal relative to another element.

Parameters:

• element (HTMLElement): Element to position
• referenceElement (HTMLElement): Reference element for positioning
• options (Object, optional): Positioning options
  • placement (string, optional): Placement relative to reference. Default: 'bottom'
    • Possible values: 'top', 'bottom', 'left', 'right', 'top-left', 'top-right', 'bottom-left', 'bottom-right'
  • portalId (string, optional): Portal identifier. Default: 'main'
  • margin (number, optional): Margin from reference element in pixels. Default: 5

Returns: The positioned element (HTMLElement)

destroy

destroy()

Cleans up all portals.

Returns: void

Event System

The PortalManager exposes signals that you can subscribe to:

// Listen for new portals being created
portalManager.signals.portalCreated.add((id, portal) => {
  console.log(`Portal created: ${id}`);
});

// Listen for elements being added to portals
portalManager.signals.elementAdded.add((element, portalId) => {
  console.log(`Element added to portal: ${portalId}`);
});

// Listen for elements being removed from portals
portalManager.signals.elementRemoved.add((element, portalId) => {
  console.log(`Element removed from portal: ${portalId}`);
});

Advanced Examples

Dropdown Example

import portalManager from '@rvanbaalen/portals';

// Create a simple dropdown component
function createDropdown() {
  const dropdown = document.createElement('div');
  dropdown.className = 'dropdown-content';
  dropdown.style.cssText = `
    background-color: white;
    border: 1px solid #ccc;
    border-radius: 4px;
    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
    padding: 10px;
    width: 200px;
  `;
  
  // Add some dropdown items
  const items = ['Profile', 'Settings', 'Help', 'Logout'];
  items.forEach(item => {
    const itemElement = document.createElement('div');
    itemElement.textContent = item;
    itemElement.style.cssText = `
      padding: 8px 10px;
      cursor: pointer;
    `;
    itemElement.addEventListener('click', () => {
      console.log(`Clicked: ${item}`);
      portalManager.removeFromPortal(dropdown);
    });
    itemElement.addEventListener('mouseover', () => {
      itemElement.style.backgroundColor = '#f5f5f5';
    });
    itemElement.addEventListener('mouseout', () => {
      itemElement.style.backgroundColor = 'transparent';
    });
    dropdown.appendChild(itemElement);
  });
  
  return dropdown;
}

// Usage
document.addEventListener('DOMContentLoaded', () => {
  // Create a dropdown toggle button
  const button = document.createElement('button');
  button.textContent = 'Open Dropdown';
  button.style.cssText = `
    padding: 10px 15px;
    background-color: #4285f4;
    color: white;
    border: none;
    border-radius: 4px;
    cursor: pointer;
    margin: 20px;
  `;
  document.body.appendChild(button);
  
  // Handle button click
  let isOpen = false;
  let dropdown = null;
  
  button.addEventListener('click', () => {
    if (!isOpen) {
      // Create and show dropdown
      dropdown = createDropdown();
      portalManager.positionElement(dropdown, button, {
        placement: 'bottom-left',
        margin: 5
      });
      isOpen = true;
    } else {
      // Hide dropdown
      portalManager.removeFromPortal(dropdown);
      isOpen = false;
    }
  });
  
  // Add a click listener to close dropdown when clicking outside
  document.addEventListener('click', (event) => {
    if (isOpen && event.target !== button && !dropdown.contains(event.target)) {
      portalManager.removeFromPortal(dropdown);
      isOpen = false;
    }
  });
});

Tooltip Example

import portalManager from '@rvanbaalen/portals';

// Create a reusable tooltip factory
function createTooltipSystem() {
  // Create a dedicated portal for tooltips
  const tooltipPortal = portalManager.getPortal('tooltips', 10000);
  
  // Keep track of active tooltip
  let activeTooltip = null;
  
  // Create a tooltip element
  function createTooltip(text) {
    const tooltip = document.createElement('div');
    tooltip.className = 'tooltip';
    tooltip.textContent = text;
    tooltip.style.cssText = `
      background-color: rgba(0, 0, 0, 0.8);
      color: white;
      padding: 5px 10px;
      border-radius: 4px;
      font-size: 14px;
      max-width: 200px;
      pointer-events: none;
    `;
    return tooltip;
  }
  
  // Show tooltip
  function showTooltip(element, text, placement = 'top') {
    // Remove any existing tooltip
    hideTooltip();
    
    // Create new tooltip
    activeTooltip = createTooltip(text);
    
    // Position relative to target element
    portalManager.positionElement(activeTooltip, element, {
      placement,
      portalId: 'tooltips',
      margin: 8
    });
  }
  
  // Hide tooltip
  function hideTooltip() {
    if (activeTooltip) {
      portalManager.removeFromPortal(activeTooltip);
      activeTooltip = null;
    }
  }
  
  // Apply tooltip behavior to an element
  function applyTooltip(element, text, placement = 'top') {
    element.addEventListener('mouseenter', () => showTooltip(element, text, placement));
    element.addEventListener('mouseleave', hideTooltip);
    element.addEventListener('focus', () => showTooltip(element, text, placement));
    element.addEventListener('blur', hideTooltip);
  }
  
  return {
    applyTooltip,
    showTooltip,
    hideTooltip
  };
}

// Usage
document.addEventListener('DOMContentLoaded', () => {
  const tooltipSystem = createTooltipSystem();
  
  // Create some example elements
  const container = document.createElement('div');
  container.style.cssText = `
    display: flex;
    gap: 20px;
    margin: 100px;
  `;
  document.body.appendChild(container);
  
  // Create buttons with different tooltip placements
  const placements = [
    { label: 'Top Tooltip', placement: 'top', text: 'This tooltip appears above the button' },
    { label: 'Right Tooltip', placement: 'right', text: 'This tooltip appears to the right of the button' },
    { label: 'Bottom Tooltip', placement: 'bottom', text: 'This tooltip appears below the button' },
    { label: 'Left Tooltip', placement: 'left', text: 'This tooltip appears to the left of the button' }
  ];
  
  placements.forEach(({ label, placement, text }) => {
    const button = document.createElement('button');
    button.textContent = label;
    button.style.cssText = `
      padding: 10px 15px;
      background-color: #4285f4;
      color: white;
      border: none;
      border-radius: 4px;
      cursor: pointer;
    `;
    container.appendChild(button);
    
    // Apply tooltip
    tooltipSystem.applyTooltip(button, text, placement);
  });
});

To modify or extend this library:

1. Clone the repository:

   git clone https://github.com/rvanbaalen/portals.git
   cd portals
   

2. Install dependencies:

   npm install
   

3. Make your changes to the source code in index.js

4. Test your changes in your project by using npm link:

   # In the portals directory
   npm link
   
   # In your project directory
   npm link @rvanbaalen/portals
   

Contributions are welcome! If you have any suggestions, improvements, or bug fixes, please open an issue or submit a pull request.

Distributed under the MIT License. See the LICENSE file for more information.

---