🔍 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

1npm install bitcoin-inscription-viewer

1import { InscriptionGallery } from 'bitcoin-inscription-viewer';
2
3function MyApp() {
4  const inscriptionIds = [
5    '6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0',
6    'e317a2a5d68bd1004ae15a06175a319272a10389ff125c98820389edef8b0a94i0'
7  ];
8
9  return (
10    <InscriptionGallery
11      inscriptionIds={inscriptionIds}
12      columns={3}
13      cardSize={200}
14      enableModal={true}
15    />
16  );
17}

✨ 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:

1<InscriptionGallery
2  inscriptionIds={['inscription1', 'inscription2']}
3  columns={3}
4  cardSize={200}
5  enableModal={true}
6  showIndex={true}
7/>

LaserEyesInscriptionGallery

Auto-fetch inscriptions from connected LaserEyes wallet:

1import { LaserEyesProvider } from '@omnisat/lasereyes';
2
3<LaserEyesProvider>
4  <LaserEyesInscriptionGallery
5    columns={3}
6    cardSize={250}
7    enableModal={true}
8  />
9</LaserEyesProvider>

InscriptionRenderer

Display individual inscriptions with full controls:

1<InscriptionRenderer
2  inscriptionId="6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0"
3  size={400}
4  showHeader={true}
5  showControls={true}
6/>

🎯 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

1npm install bitcoin-inscription-viewer

Yarn

1yarn add bitcoin-inscription-viewer

Import Styles

1import '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:

1import { useInscriptionCache } from 'bitcoin-inscription-viewer';
2
3function App() {
4  const { 
5    cachedData,
6    cacheSize,
7    clearCache,
8    getCachedData,
9    setCachedData
10  } = useInscriptionCache();
11
12  return (
13    <div>
14      <div>Cache Size: {Object.keys(cachedData).length} entries</div>
15      <button onClick={clearCache}>Clear Cache</button>
16      {/* Your inscription components */}
17    </div>
18  );
19}

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