Platemap

Build interactive laboratory plate layouts with independently editable layers, well selection, annotations, and CSV/JSON workflows. These examples use the published @nitro-bio/platemap 2.0.3 package, compatible with React 18.2 and newer versions below React 20.

View source

This package is available under GPL-3.0-or-later. For commercial licensing options, contact platemap@nitro.bio.

Installation

pnpm add @nitro-bio/platemap@^2.0.3

Import the public stylesheet once in your application entry point or root layout:

import "@nitro-bio/platemap/dist/nitro-platemap.css";

Quick start

usePlateReducer provides the shared state and actions for both Plate and PlateControls.

"use client";

import { Plate, PlateControls, usePlateReducer } from "@nitro-bio/platemap";

export function PlateEditor() {
  const reducer = usePlateReducer({
    initialPlateSize: 96,
    initialLayers: [
      {
        id: "00000000-0000-4000-8000-000000000096",
        name: "Layer 1",
        annotations: [],
      },
    ],
  });
  return (
    <>
      <Plate {...reducer} />
      <PlateControls {...reducer} />
    </>
  );
}

For server-rendered applications, provide stable initial layer IDs so the server and browser render the same attributes.

Select wells, create or rename layers, and switch between the editable flat view and the read-only layers overview. PlateControls also provides file import and export.

Interactive 96-well plate

Plate sizes

Supported sizes are 24, 48, 96, 384, and 1536. Set initialPlateSize when initializing state, or call plateActions.setPlateSize to change it later.

Layers and annotations

Version 2 stores annotations in plateState.layers. The active layer is identified by activeLayerId; selected and excluded wells remain global across layers.

Use plateActions.setLayerAnnotations(layerId, annotations) to update a layer. An annotation includes an id, label, wells, and semantic annotationStyle:

import { GREEN_STYLE, type WellAnnotation } from "@nitro-bio/platemap";

const annotations: WellAnnotation[] = [
  {
    id: "00000000-0000-4000-8000-000000000001",
    label: "Control",
    wells: [0, 1, 2],
    annotationStyle: GREEN_STYLE,
  },
];

Well indices are zero-based. Use excelCellToIndex and indexToExcelCell to convert between indices and labels such as A1. Preset colors and canonical custom #RRGGBB colors are supported.

Import and export

The durable JSON format uses schemaVersion: 1 and stores plateSize, excludedWells, and layers. Selection, active IDs, and view mode are transient. Use parsePlateDocument, plateStateToDocument, and plateDocumentToJSON for validated document workflows.

Tidy CSV import requires Well and Annotation columns. Annotation Key and Color are optional, and extra columns can carry flat primitive metadata. The older plate-shaped CSV matrix remains an export format; it is not accepted by the layer importer.

Upgrading from version 1

Replace flat wellAnnotations state with layer annotations and use the shared reducer props shown above. The component stylesheet owns visual classes; customize the semantic --platemap-* variables rather than constructing Tailwind classes inside annotation styles.

parsePlateState can migrate validated legacy flat state. The package README describes the current state and layer controls.