🔍 Bitcoin Inscription Viewer

A React/TypeScript library for displaying Bitcoin Ordinals inscriptions with responsive design and comprehensive content support.

🔧 Compatibility: React 18 & React 19 | TypeScript 5+ | Modern Browsers

🚀 Quick Start

npm install bitcoin-inscription-viewer

import { InscriptionGallery } from 'bitcoin-inscription-viewer';

function MyApp() {
  const inscriptionIds = [
    '6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0',
    'e317a2a5d68bd1004ae15a06175a319272a10389ff125c98820389edef8b0a94i0'
  ];

  return (
    <InscriptionGallery
      inscriptionIds={inscriptionIds}
      columns={3}
      cardSize={200}
      enableModal={true}
    />
  );
}

✨ Features

• 🎨 Responsive Design - Works perfectly in any container size
• 🖼️ Content Support - Images, videos, audio, 3D models, JSON, text, HTML
• 💰 Wallet Integration - Built-in LaserEyes wallet support
• ⚡ Performance - Lazy loading, caching, and optimization features
• 🔧 Flexible - Customizable layouts, themes, and behaviors
• 📱 Mobile-First - Optimized for all screen sizes
• 🛡️ Type Safe - Full TypeScript support

📖 Documentation

Visit our comprehensive documentation:

• 🎮 Live React Demo - Interactive React demo with all features
• 📚 Complete Documentation - Full integration guides and examples
• ⚡ Integration Guide - Quick setup and patterns
• 💰 LaserEyes Integration - Wallet integration guide
• 🎮 Legacy Examples - Static HTML demos

⚠️ Important: Implementation Status (Updated Dec 2024)

For Production Use: Please refer to our Working Features Only page for accurate implementation details.

Some of our examples show "aspirational" features that aren't fully implemented yet. We've now:

• ✅ Fixed all runtime errors - No more toUpperCase() crashes or unsafe operations
• ✅ Added comprehensive error handling - ErrorBoundary components throughout
• ✅ Created working-only examples - Working Features Only for production reference
• ✅ Added implementation status - Full status breakdown explains what works vs. what's planned
• ✅ Enhanced safety - All string operations, array access, and user inputs properly validated

Quick Reference:

• 📋 Implementation Status - What works vs. what's planned
• ✅ Working Features Only - Production examples
• 🧪 All Test Pages - Full test suite

🔧 Core Components

InscriptionGallery

Display multiple inscriptions in a responsive grid:

<InscriptionGallery
  inscriptionIds={['inscription1', 'inscription2']}
  columns={3}
  cardSize={200}
  enableModal={true}
  showIndex={true}
/>

LaserEyesInscriptionGallery

Auto-fetch inscriptions from connected LaserEyes wallet:

import { LaserEyesProvider } from '@omnisat/lasereyes';

<LaserEyesProvider>
  <LaserEyesInscriptionGallery
    columns={3}
    cardSize={250}
    enableModal={true}
  />
</LaserEyesProvider>

InscriptionRenderer

Display individual inscriptions with full controls:

<InscriptionRenderer
  inscriptionId="6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0"
  size={400}
  showHeader={true}
  showControls={true}
/>

🎯 Use Cases

• Wallet Applications - Display user inscription collections
• NFT Marketplaces - Showcase inscriptions for sale
• Portfolio Trackers - Monitor inscription values
• Explorer Tools - Browse and analyze inscriptions
• Collection Galleries - Curate inscription displays

⚡ Advanced Features

• Enhanced Caching - LRU cache with TTL support
• Batch Fetching - Efficient concurrent loading
• Virtual Scrolling - Handle thousands of inscriptions
• Performance Monitoring - Real-time metrics
• Service Worker - Offline support and intelligent caching
• Custom Fetchers - Pluggable data sources

🛠️ Installation & Setup

NPM

npm install bitcoin-inscription-viewer

Yarn

yarn add bitcoin-inscription-viewer

Import Styles

import 'bitcoin-inscription-viewer/dist/style.css';

🌐 API Support

Works with any Bitcoin Ordinals API:

• Recursive endpoints (recommended) - No Bitcoin node required
• Standard endpoints - Fallback support
• Custom servers - Configure your own endpoints

🚀 Service Worker Caching

The library includes an optional service worker for intelligent caching and offline support. The service worker provides:

• Smart Caching - Automatic caching of inscription content and metadata
• Offline Support - View previously loaded inscriptions without internet
• Performance - Dramatically faster load times for cached content
• Bandwidth Savings - Reduce API calls and data usage

In-Memory Caching

The library includes built-in in-memory caching for improved performance:

import { useInscriptionCache } from 'bitcoin-inscription-viewer';

function App() {
  const { 
    cachedData,
    cacheSize,
    clearCache,
    getCachedData,
    setCachedData
  } = useInscriptionCache();

  return (
    <div>
      <div>Cache Size: {Object.keys(cachedData).length} entries</div>
      <button onClick={clearCache}>Clear Cache</button>
      {/* Your inscription components */}
    </div>
  );
}

Caching Features

• Automatic Caching - Content is automatically cached after first load
• LRU Eviction - Least recently used items are removed when cache is full
• Memory Efficient - Configurable cache size limits
• Manual Control - Programmatic cache management
• Performance Monitoring - Cache hit/miss statistics

The caching system improves load times for frequently viewed inscriptions and reduces API requests.

🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub: https://github.com/switch-900/InscriptionViewer
• NPM: https://www.npmjs.com/package/bitcoin-inscription-viewer
• Documentation: https://switch-900.github.io/InscriptionViewer

Built with ❤️ for the Bitcoin ecosystem