cloupe.js.cloupe File Reader

JavaScript library for reading 10x Genomics Loupe files in the browser

Get Started

Live Demo

GitHub

🌐

Browser-first

Uses File API for random access without loading the entire file into memory.

⚡

Lazy Loading

Reads only the data you need, efficiently handling large files.

📊

Full Format Support

Supports Barcodes, Features, Projections, Cell tracks, Clusterings, and Expression matrix.

🔷

TypeScript

Includes complete type definitions for better development experience.

🔧

Web Worker Support

Offload heavy operations to background threads to prevent UI blocking.

📦

Lightweight

Minimal dependencies with fflate-based compression.

Quick Start

bash

npm install cloupe.js

typescript

import { CloupeReader } from "cloupe.js";

// Open a .cloupe file
const reader = await CloupeReader.open(file);

// Get summary information
const summary = await reader.getSummary();
console.log(`Cells: ${summary.barcodeCount}, Genes: ${summary.featureCount}`);

// Read UMAP/t-SNE coordinates
const projection = await reader.getDefaultProjection();

// Search for genes
const results = await reader.features.search("CD3");

// Clean up
reader.close();

What is a .cloupe file?

A .cloupe file is a single-cell genomics data format used by 10x Genomics' Loupe Browser. Generated by the Cell Ranger pipeline, it contains:

Barcodes: Unique identifiers for each cell
Features: Gene/protein information (ID, name, type)
Projections: Dimensionality reduction coordinates (UMAP, t-SNE, PCA)
Cell Tracks: Cluster assignments and custom annotations
Expression Matrix: Sparse expression matrix in CSC format

Why cloupe.js?

Previously, reading .cloupe files required the Loupe Browser desktop application or Python/R libraries. cloupe.js enables reading .cloupe files directly in the browser, making it possible to:

Build web-based single-cell analysis tools
Explore data client-side without a server
Create interactive visualization and analysis applications