Bubble Display

Interactive Three.js bubble display with configurable content - perfect for creating engaging portfolio sections, feature showcases, or interactive content displays.

Features

• 🫧 Liquid-like bubbles with smooth physics simulation
• 📱 Interactive content - click to expand bubbles and show detailed information
• 🎨 Fully customizable - colors, sizes, content, and positioning
• 📝 Optional titles - bubbles can have text labels or be plain spheres
• 🖼️ Rich content - support for images, descriptions, and custom styling
• ⚡ Physics-based - bubbles push each other around naturally
• 🎯 TypeScript - full type safety and excellent developer experience

Installation

npm install @lukeyreyno/bubble-display three

Note: three is a peer dependency, so you need to install it separately.

Quick Start

import { BubbleDisplay, BubbleConfig } from '@lukeyreyno/bubble-display';

// Define your bubble content
const bubbles: BubbleConfig[] = [
  {
    content: {
      title: "My Project",
      description: "An awesome project I built with React and TypeScript",
      color: "#4A90E2",
      images: [
        { url: "/project-screenshot.jpg", alt: "Project Screenshot" }
      ]
    },
    position: { x: 0, y: 0, z: 0 },
    initialRadius: 1,
    expandedRadius: 2.5
  },
  {
    content: {
      title: "Another Project", 
      description: "A different project with cool features",
      color: "#50C878"
    },
    position: { x: 3, y: 1, z: 0 }
  }
];

// Get your container element
const container = document.getElementById('bubble-container');

// Create the display
const display = new BubbleDisplay(container, bubbles);

Configuration

BubbleConfig

| Property | Type | Required | Description | |----------|------|----------|-------------| | content | BubbleContent | ✅ | The content and styling for the bubble | | position | {x, y, z} | ❌ | Initial 3D position (random if not provided) | | initialRadius | number | ❌ | Starting size (default: 1) | | expandedRadius | number | ❌ | Size when expanded (default: 2.5) |

BubbleContent

| Property | Type | Required | Description | |----------|------|----------|-------------| | title | string | ❌ | Text shown on bubble surface | | description | string | ✅ | Detailed content shown when expanded | | color | string | ❌ | Bubble color (hex, rgb, etc.) | | textColor | string | ❌ | Title text color (default: white) | | images | BubbleContentImage[] | ❌ | Images to show in expanded view |

BubbleContentImage

| Property | Type | Required | Description | |----------|------|----------|-------------| | url | string | ✅ | Image URL | | alt | string | ✅ | Alt text for accessibility | | width | number | ❌ | Image width | | height | number | ❌ | Image height |

API Reference

BubbleDisplay

class BubbleDisplay {
  constructor(
    container: HTMLElement, 
    bubbles?: BubbleConfig[],
    bounds?: { min: {x, y, z}, max: {x, y, z} }
  )
  
  addBubble(config: BubbleConfig): Bubble
  addBubbles(configs: BubbleConfig[]): Bubble[]
  getCamera(): THREE.Camera
  getScene(): THREE.Scene  
  getRenderer(): THREE.WebGLRenderer
  dispose(): void
}

Examples

Simple Usage

const display = new BubbleDisplay(container, [
  {
    content: {
      title: "Hello World",
      description: "My first bubble!",
      color: "#ff6b6b"
    }
  }
]);

Without Titles (Plain Spheres)

const display = new BubbleDisplay(container, [
  {
    content: {
      description: "This bubble has no title text",
      color: "#4ecdc4"
    }
  }
]);

With Custom Bounds

const display = new BubbleDisplay(
  container, 
  bubbles,
  {
    min: { x: -5, y: -5, z: -5 },
    max: { x: 5, y: 5, z: 5 }
  }
);

Dynamic Content

const display = new BubbleDisplay(container);

// Add bubbles dynamically
display.addBubble({
  content: {
    title: "Dynamic Bubble",
    description: "Added after initialization"
  }
});

Development

# Install dependencies
npm install

# Run demo
npm run dev

# Build library
npm run build:lib

# Type check
npm run type-check

Browser Support

• Modern browsers with WebGL support
• Chrome 51+
• Firefox 51+
• Safari 12+
• Edge 79+

License

MIT

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.