# Storage Map

## Specs

| Label                     | Value                         |
| ------------------------- | ----------------------------- |
| **Version**               | 4.0.0 (updated on 2025-06-23) |
| **Developer**             | Labii Inc.                    |
| **Type**                  | Section                       |
| **Support Configuration** | Yes                           |

## Overview

The Storage Map widget renders an interactive 2D grid view of a storage unit, enabling laboratory professionals to visualize occupied and vacant positions at a glance. By linking directly to a Storage table, the widget reads the configured row count, column count, and header orientation to generate an accurate spatial map of stored samples, reagents, and other inventory items. Users can assign records to individual cells, rearrange items, and download the map or list for reporting — making it an essential tool for freezer management, well-plate tracking, and agricultural field-plot layouts.

{% hint style="warning" %}
Only the Storage table can be used with this widget.
{% endhint %}

## Use Cases

* **Freezer and Refrigerator Management**: Visualize which shelves, boxes, or positions are occupied in a multi-compartment storage unit.
* **Well-Plate Tracking**: Map sample positions in 96- or 384-well plates using transposed numeric column headers.
* **Field Trial Layout**: Display agricultural research plots and their assigned treatments in an organized grid during ARM studies.
* **Inventory Organization**: Quickly identify empty positions and efficiently assign incoming samples to available locations.
* **Compliance and Audit**: Generate a downloadable map or list view of stored items to support regulatory documentation and chain-of-custody records.

## Interface

### Read-only View

The read-only view displays the fully rendered storage map as a 2D grid. Column headers are labeled with letters (e.g., A, B, C) and row headers with numbers (e.g., 1, 2, 3) by default. Each cell is identified by a coordinate (e.g., A1, B2). Cells that contain assigned records appear as clickable links showing the record name and, optionally, the created date and owner. Empty cells are shown as blank positions.

<figure><img src="/files/hJ8dnfXo0xIXk1YCrGpb" alt="Read-only view of the Storage Map widget showing a 2D grid with assigned records"><figcaption><p>The read-only view renders the storage grid with occupied cells displayed as clickable record links</p></figcaption></figure>

### Edit View

The edit view is the same interactive grid used in read-only mode, but with additional action buttons enabled — including **Assign**, **Arrange**, **Randomize**, **List view**, and **Download**. Clicking an empty cell reveals the **Assign** action to place records into that position.

## Configuration

### Initial Setup

{% stepper %}
{% step %}
Add the **Storage Map** widget to a section of a Storage record by clicking **Add Section** and selecting **Storage Map**
{% endstep %}

{% step %}
Click the **Configure** (gear) icon in the section header to open the configuration panel
{% endstep %}

{% step %}
Map the required column configuration fields to the appropriate columns of your Storage table
{% endstep %}

{% step %}
Adjust display settings to control how cell content is rendered, then click **Save**
{% endstep %}
{% endstepper %}

### Column Configuration

These settings link the widget to the structural columns of the Storage table that define the grid dimensions and orientation.

* **Column (Number of rows)**: Choose the column (Number of rows) of the storage table.
* **Column (Number of columns)**: Choose the column (Number of columns) of the storage table.
* **Column (Should transpose header)**: Choose the column (Should transpose header) of the storage table. When the referenced column value is `true`, numeric labels are used for columns and letter labels for rows — the standard orientation for well-plates such as the 96-well plate.

{% hint style="info" %}
All three column configuration fields are required for the widget to render the grid correctly.
{% endhint %}

### Display Configuration

These settings control the visual appearance and content of each cell in the map.

* **Should display name**: If you would like to include the record name in the map, please check this box.
* **Should display date**: If you would like to display the created date of the record, please check this box.
* **Should display owner**: If you would like to display the owner of the record, please check this box.
* **Should reverse vertical display order**: If you would like to display the vertical order in reverse, please check this box.
* **Font size**: The font size of the text in the cell.
* **Min width**: The minimum width of the cell, in pixels.
* **Max width**: The maximum width of the cell, in pixels.
* **Should truncate**: If you would like to truncate the text in the cell, please check this box.

{% hint style="success" %}
Enable **Should truncate** together with **Max width** to keep cells uniform in size when record names vary in length.
{% endhint %}

## Additional Functions

### Assign

Any existing records (samples and reagents) can be assigned to a storage position directly from the map.

{% stepper %}
{% step %}
From the Storage Map, click an empty cell or well
{% endstep %}

{% step %}
Click the **Assign to \[coordinate]** button that appears
{% endstep %}

{% step %}
Select one or more records from the pop-up window
{% endstep %}

{% step %}
Click **Submit** to confirm the assignment
{% endstep %}
{% endstepper %}

<figure><img src="/files/RXShgelLvC75nqyAgik5" alt="Assign dialog for adding records to a storage map cell"><figcaption><p>Clicking an empty cell reveals the Assign button and a record selection pop-up</p></figcaption></figure>

### Arrange

Labii supports arranging items within the Storage Map widget to redistribute all assigned records in a structured order.

* **Arrange from Left to Right**: Redistributes all items row by row, from left to right.
* **Arrange from Top to Bottom**: Redistributes all items column by column, from top to bottom.

### Randomization

In the **Agricultural Research Manager (ARM)** application, randomization of plots based on treatments is a critical step in designing field trials. The Storage Map widget supports randomized redistribution to ensure unbiased treatment assignments across plots.

* **Randomize by Rows**: Randomly redistributes items within each row independently, maintaining row structure while shuffling column assignments.
* **Randomize by Columns**: Randomly redistributes items within each column independently, keeping column structure intact while shuffling row assignments.
* **Randomize All**: Completely randomizes all items across the entire map with no spatial constraints — ideal when full randomization is required.

### List View

Click the **List view** button to switch from the grid layout to a flat list of all items stored in the storage unit, making it easier to scan or search for specific records.

### Download

Click the **Download** button to export the storage contents. You can download either:

* **As a map** — exports the grid layout with coordinates
* **As a list** — exports a flat list of all stored records

## Best Practices

### Data Organization

* Define consistent column names for number of rows, number of columns, and transpose header across all Storage records to simplify configuration reuse.
* Use the **Should truncate** and **Max width** settings to maintain a clean, uniform grid layout when record names are long.

### Performance Optimization

* For large storage units (e.g., 96-well plates or 384-well plates), enable **Should truncate** and set a reasonable **Max width** to prevent the grid from overflowing the page.
* Limit displayed fields to only what is necessary for the workflow — enabling all three display options (name, date, owner) on dense grids can reduce readability.

## Related Widgets

### Complementary Widgets

* [**Storage**](/widgets/column-widgets/advanced/storage.md): Column widget that lets a record capture and display its own storage coordinates with a visual map picker. Use together with Storage Map for end-to-end storage tracking.
* [**Storage Coordinates**](/widgets/column-widgets/advanced/storage-coordinates.md): Column widget that stores the specific coordinate value (e.g., A1) of a record within a storage unit.

### Integration Scenarios

* Combine **Storage Map** + **Storage** column widget for a complete inventory workflow: the Storage Map shows the overall layout, while the Storage column widget on each sample record shows its exact position.
* Use **Storage Map** alongside the **Section Display** dashboard widget to embed a live storage view directly on a laboratory dashboard.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.labii.com/widgets/section-widgets/productivity/storage/storage-map.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.