# Image Rich Data

## Content

Image Rich Data is a cell value type that stores images as structured data.
Unlike picture shapes or background images, image rich data is stored directly as the cell’s value. Because it is treated as data rather than a visual object, it participates in worksheet operations such as sorting, filtering, formulas, search, and PivotTables.
Image rich data is designed for scenarios where images are part of the dataset and must behave consistently with other cell values.

## Data Structure

Image Rich Data is a concrete implementation of the `IRichData` interface. To store an image in a cell, the value must include a type discriminator and a value payload.
The structure is:

```typescript
{
    richDataType: "Image",
    value: {
        src: string,
        imageBase64Data?: string,
        altText?: string,
        drawType?: number,
        width?: number,
        height?: number,
        clipX?: number,
        clipY?: number,
        clipWidth?: number,
        clipHeight?: number,
        vAlign?: number,
        hAlign?: number
    }
}
```

* `richDataType` must be set to `"Image"`.
* `value` contains the image source and optional layout or clipping settings.

The `altText` property is used as the primary comparison key in sorting, filtering, searching, and logical comparison operations.

### Example

You can create Image Rich Data by assigning an object that conforms to the `IImageRichData` structure using `sheet.setValue`.

```javascript
var sheet = spread.getActiveSheet();
sheet.setValue(0, 0, {
    richDataType: "Image",   // Identifies the value as Image Rich Data
    value: {
        src: "https://example.com/product.png",  // Image URL
        altText: "Laptop Pro",                   // Used for sorting, filtering, and search, and logical comparison operations
        drawType: 0,                             // Keep aspect ratio and fit within the cell
        vAlign: 1,                               // Vertically center the image
        hAlign: 1                                // Horizontally center the image
    }
});
```

![example1.gif](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/example1-20260414.f05a37.gif?width=600)
You can also use custom sizing and clipping options:

```auto
sheet.setValue(1, 0, {
    richDataType: "Image",
    value: {
        src: "https://example.com/product.png",
        altText: "Laptop Pro (Cropped)",
        drawType: 3,      // Enable custom size mode
        width: 80,        // Custom width (pixels)
        height: 60,       // Custom height (pixels)
        clipX: 20,        // Start X position of the clipped region
        clipY: 20,        // Start Y position of the clipped region
        clipWidth: 100,   // Width of the clipped region
        clipHeight: 100   // Height of the clipped region
    }
});
```

![example2.gif](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/example2-20260414.1797c7.gif?width=600)
For complete property definitions and enum values, see the [`IRichData`](/spreadjs/api/interfaces/GC.Spread.Sheets.IRichData) and [`IImageRichData`](/spreadjs/api/interfaces/GC.Spread.Sheets.IImageRichData) API reference.

## Behavioral Semantics

### Type Participation

Image Rich Data:

* Is treated as a first-class cell value type
* Can be stored in ranges and tables
* Can be referenced in formulas
* Can appear in PivotTable data sources

It is not treated as a Shape object.

### Sorting Semantics

Sorting behavior follows these rules:

1. Image Rich Data is ordered consistently with Excel when compared against primitive types.
2. When comparing two Image Rich Data values, ordering is primarily determined by the `altText` property.

![sort.gif](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/sort-20260403.e10666.gif?width=600)

>type=note
> **Notes:**
>
> * If two values have identical `altText`, sorting behavior may differ from Microsoft Excel.
> * Because Excel does not provide publicly documented comparison rules for cell images, full behavioral equivalence cannot be guaranteed.

### Filtering Semantics

Filtering operations evaluate Image Rich Data using the `altText` property.
![filter.gif](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/filter-20260403.98d0c2.gif?width=600)

### Search Semantics

Search operations evaluate Image Rich Data using the `altText` property.
![search.gif](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/search-20260403.3fc627.gif?width=600)

### Formula Semantics

Image Rich Data can be used in:

* [Lookup and reference functions](/spreadjs/docs/formulareference/FormulaFunctions/lookup-reference-functions) (such as `VLOOKUP`, `XLOOKUP`, `INDEX`, `MATCH`)
* [Dynamic array functions](/spreadjs/docs/features/formulas/dynamic-array-formulas) (such as `SORT`, `UNIQUE`, `FILTER`)
* Logical comparison operators (`=`, `<>`)
* Counting functions such as `COUNT` and `COUNTA`
* Criteria parameters in functions such as `SUMIF` and `SUMIFS`

Most mathematical and statistical functions do not support Image Rich Data.
Unsupported operations may return `#VALUE!` or produce results that differ from Excel.

## Example Scenarios

**Example 1: Using Image Rich Data in a PivotTable**
If a column contains Image Rich Data values with different `altText` values, the column can be used as a PivotTable field.
When creating a PivotTable from this range:

* The images appear as field items.
* Grouping and filtering are based on `altText`.
* Sorting follows the same semantics described in the Sorting section.

No additional configuration is required.
![pt.gif](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/pt-20260407.fdf3cf.gif?width=800)
**Example 2: Using Image Rich Data in Conditional Formatting**
Image Rich Data can be used in conditional formatting rules that rely on logical comparison.
For example:

```auto
=B7="Laptop Pro"
```

If cell `B7` contains Image Rich Data whose `altText` is `"Laptop Pro"`, the condition evaluates to `TRUE`.
Conditional formatting rules evaluate Image Rich Data using the `altText` property.
![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260407.897ba2.png?width=600)
**Example 3: Lookup with Image Rich Data**
Image Rich Data can participate in lookup operations.

```auto
=XLOOKUP("Laptop Pro", A:A, B:B)
```

If column A contains Image Rich Data with matching `altText`, the corresponding value in column B is returned.
![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260407.d2cf50.png?width=600)

## Inserting Images in the Designer

You can insert images into cells using the SpreadJS Designer.
For detailed instructions about inserting and converting pictures in the Designer, see [Insert Pictures in the Designer](/spreadjs/docs/spreadjs-designer-component/spdesignerwork/insert-pictures-in-designer).

## Import and Export Behavior

### Excel Import (.xlsx)

* Excel cell images are imported as Image Rich Data.
* They are no longer mapped to `SparklineEx`.

Import/export behavior for `SparklineEx` in `.sjs` and `.ssjson` formats is unchanged.

### Excel Export

* SVG images may cause errors when exporting to Excel.
* No automatic validation or format conversion is performed at the API layer.
* In the Designer, SVG images inserted using *Place in Cell* are converted to PNG before storage.

## Clipboard Limitations

Cells containing images copied from Excel Desktop cannot be pasted into SpreadJS.
Excel places HTML clipboard data with `<img src="file:///...">` references to local files.
Browsers cannot access local file paths, so SpreadJS cannot retrieve the image data.
This behavior is consistent with Excel Online.

## Platform Limitations

Image Rich Data is not supported in:

* Data Manager
* TableSheet
* GanttSheet

If a table containing Image Rich Data is converted using [Convert to Data Table](/spreadjs/docs/features/tablegen/convert-fromto-data-table#convert-table-to-data-table), the image values are discarded.

## Related Features

Image Rich Data differs from:

* [IMAGE() Function](/spreadjs/docs/formulareference/FormulaFunctions/sparkline-functions/IMAGE) (formula-generated image values)
* [Cell background images](/spreadjs/docs/features/cells/backimage) (visual only)
* [Picture Shape](/spreadjs/docs/features/UnderstandingShapes/picture-shape) (Place over Cells)

>type=note
> Picture Shapes and Image Rich Data can be converted between each other in the Designer.
> For details, see [Insert Pictures in Designer](/spreadjs/docs/spreadjs-designer-component/spdesignerwork/insert-pictures-in-designer#convert-between-placement-modes).

## Alt Text Behavior

Image Rich Data contains its own `altText` property used to describe the image content.

* This alt text is consistent with Excel behavior.
* It can be displayed in the Formula Bar.
* It can be edited in the Alt Text panel.

This property is independent from the cell alternative text set using `CellRange.altText()`.

* The `altText` in Image Rich Data describes the image value itself.
* The cell-level alternative text in SpreadJS is a separate property and does not affect the image value.