AR Product Image Viewer

Display product images in AR - just select a product and view its image in your environment! No 3D models needed.

Features

• 🖼️ Image-Based AR - Just pass an image URL, no 3D models required
• 🛒 E-commerce Ready - Perfect for product pages
• 🐘 PHP Compatible - Works with PHP backends (Laravel, WordPress, WooCommerce, etc.)
• 📱 WebXR Native - Built from scratch using WebXR API (no AR.js)
• ⚡ Easy Integration - Simple API for React and vanilla JS
• 📦 TypeScript Support - Full TypeScript definitions included
• 🎯 Hit Testing - Automatically places images in your real environment

Installation

npm install ar-product-image-viewer

or

yarn add ar-product-image-viewer

Requirements

• HTTPS connection (required for WebXR)
• Modern browser with WebXR support (Chrome on Android, Safari on iOS 12+)
• Just an image URL - no 3D models needed!

PHP Integration

Yes, it fully supports PHP! This is a frontend JavaScript package, so it works with any backend including PHP. See PHP-INTEGRATION.md for detailed examples.

Quick PHP Example

<?php
$product = getProductFromDatabase($id);
?>

<div id="ar-container"></div>

<script type="module">
import { createARImageViewer } from './dist/index.esm.js';

const viewer = createARImageViewer(
    document.getElementById('ar-container'),
    {
        imageUrl: '<?php echo htmlspecialchars($product['image_url']); ?>',
        width: 1.5
    }
);
</script>

Works with:

• ✅ Laravel
• ✅ WordPress/WooCommerce
• ✅ Magento
• ✅ PrestaShop
• ✅ Any PHP framework

Usage

React Component

import React from 'react';
import { ARProductImageViewer } from 'ar-product-image-viewer';

function ProductPage({ product }) {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ARProductImageViewer
        imageUrl={product.imageUrl}
        width={1}
        showPreview={true}
        onImageLoad={() => console.log('Image loaded!')}
        onARSessionStart={() => console.log('AR started!')}
      />
    </div>
  );
}

E-commerce Example

import React, { useState } from 'react';
import { ARProductImageViewer } from 'ar-product-image-viewer';

function EcommerceApp() {
  const [selectedProduct, setSelectedProduct] = useState(null);

  const products = [
    { id: 1, name: 'Product 1', imageUrl: 'https://example.com/product1.jpg' },
    { id: 2, name: 'Product 2', imageUrl: 'https://example.com/product2.jpg' },
  ];

  return (
    <div>
      {/* Product List */}
      <div style={{ display: 'flex', gap: '20px', padding: '20px' }}>
        {products.map(product => (
          <div
            key={product.id}
            onClick={() => setSelectedProduct(product)}
            style={{ cursor: 'pointer', border: '1px solid #ccc', padding: '10px' }}
          >
            <img src={product.imageUrl} alt={product.name} style={{ width: '200px' }} />
            <p>{product.name}</p>
          </div>
        ))}
      </div>

      {/* AR Viewer */}
      {selectedProduct && (
        <div style={{ width: '100vw', height: '100vh', position: 'fixed', top: 0, left: 0 }}>
          <ARProductImageViewer
            imageUrl={selectedProduct.imageUrl}
            width={1.5}
            showPreview={true}
            onARSessionStart={() => console.log('Viewing', selectedProduct.name, 'in AR')}
          />
        </div>
      )}
    </div>
  );
}

TypeScript React Example

import React from 'react';
import { ARProductImageViewer, ARImageOptions } from 'ar-product-image-viewer';

interface Product {
  id: number;
  name: string;
  imageUrl: string;
}

const ProductARViewer: React.FC<{ product: Product }> = ({ product }) => {
  const options: ARImageOptions = {
    imageUrl: product.imageUrl,
    width: 1.5,
    height: undefined, // Auto-calculate from aspect ratio
    position: [0, 0, -1],
    onImageLoad: () => {
      console.log('Product image loaded:', product.name);
    },
    onARSessionStart: () => {
      console.log('Viewing', product.name, 'in AR');
    },
    onARSessionEnd: () => {
      console.log('AR session ended');
    },
  };

  return (
    <div style={{ width: '100%', height: '600px' }}>
      <ARProductImageViewer {...options} showPreview={true} />
    </div>
  );
};

Vanilla JavaScript

import { createARImageViewer, isARSupported } from 'ar-product-image-viewer';

// Check if AR is supported
if (isARSupported()) {
  console.log('AR is supported!');
}

// Create viewer - just pass an image URL
const container = document.getElementById('ar-container');
const viewer = createARImageViewer(container, {
  imageUrl: 'https://example.com/product.jpg',
  width: 1.5,
  onImageLoad: () => {
    console.log('Image loaded!');
  },
});

// Start AR session
viewer.startAR().then(() => {
  console.log('AR session started');
}).catch((error) => {
  console.error('Failed to start AR:', error);
});

// End AR session
viewer.endAR();

Vanilla TypeScript

import { createARImageViewer, isARSupported, ARImageOptions } from 'ar-product-image-viewer';

const container = document.getElementById('ar-container') as HTMLElement;

if (!container) {
  throw new Error('Container element not found');
}

const options: ARImageOptions = {
  imageUrl: 'https://example.com/product.jpg',
  width: 1.5,
  position: [0, 0, -1],
  onImageLoad: () => {
    console.log('Image loaded successfully');
  },
  onImageError: (error) => {
    console.error('Image loading error:', error);
  },
  onARSessionStart: () => {
    console.log('AR session started');
  },
  onARSessionEnd: () => {
    console.log('AR session ended');
  },
};

const viewer = createARImageViewer(container, options);

// Check AR support
if (isARSupported()) {
  const startARButton = document.createElement('button');
  startARButton.textContent = 'View in AR';
  startARButton.onclick = async () => {
    try {
      await viewer.startAR();
    } catch (error) {
      alert('AR is not available. Please use a compatible device.');
    }
  };
  document.body.appendChild(startARButton);
}

API Reference

ARProductImageViewer (React Component)

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | imageUrl | string \| Blob \| File | required | URL to the product image OR Blob/File object | | width | number | 1 | Width of the image plane in AR (meters) | | height | number | undefined | Height (auto-calculated from aspect ratio if not provided) | | position | [number, number, number] | [0, 0, -1] | Initial position in AR space | | onARSessionStart | () => void | - | Callback when AR session starts | | onARSessionEnd | () => void | - | Callback when AR session ends | | onImageLoad | () => void | - | Callback when image loads | | onImageError | (error: Error) => void | - | Callback when image fails to load | | className | string | - | CSS class name for container | | style | React.CSSProperties | - | Inline styles for container | | showARButton | boolean | true | Show AR button | | arButtonText | string | 'View in AR' | AR button text | | arButtonClassName | string | - | CSS class for AR button | | showPreview | boolean | true | Show preview image before AR |

Vanilla JavaScript API

createARImageViewer(container: HTMLElement, options: ARImageOptions): ARImageViewerInstance

Creates a new AR image viewer instance. Just pass an image URL!

isARSupported(): boolean

Checks if AR is supported in the current browser.

checkARSessionSupport(): Promise<boolean>

Asynchronously checks if AR session is supported.

ARImageViewerInstance Methods

• startAR(): Promise<void> - Start AR session
• endAR(): void - End AR session
• isARSupported(): boolean - Check if AR is supported
• isARActive(): boolean - Check if AR session is active
• updateImage(imageUrl: string | Blob | File): void - Update the image (URL or Blob/File)
• destroy(): void - Destroy the viewer and clean up resources

Supported Image Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• WebP (.webp)
• Any format supported by browsers

Image Sources

The package supports both:

1. Image URLs (String)

const viewer = createARImageViewer(container, {
  imageUrl: 'https://example.com/product.jpg'  // String URL
});

2. Image Blobs/Files

// From file input
const file = document.getElementById('file-input').files[0];
const viewer = createARImageViewer(container, {
  imageUrl: file  // File object (extends Blob)
});

// From canvas
canvas.toBlob((blob) => {
  const viewer = createARImageViewer(container, {
    imageUrl: blob  // Blob object
  });
});

// From fetch
const response = await fetch('image.jpg');
const blob = await response.blob();
const viewer = createARImageViewer(container, {
  imageUrl: blob  // Blob object
});

Browser Support

• Chrome/Edge (Android) - Full WebXR support
• Safari (iOS 12+) - AR Quick Look support
• Firefox Reality - Full WebXR support

How It Works

1. Select a Product - User clicks on a product (e.g., from e-commerce site)
2. Pass Image URL - Just pass the product's image URL to the component
3. View in AR - Click "View in AR" button
4. Place in Environment - Image appears in your real environment using hit testing

No 3D models needed - just images!

Development

# Install dependencies
npm install

# Build the package
npm run build

# Type check
npm run type-check

# Development mode with watch
npm run dev

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.