#  Worksheet Background Image

## Content

SpreadJS supports setting background images for worksheets, which can help you enhance visual aesthetics, aid in data visualization (such as overlaying maps or guidelines), and unify the template style, balancing professionalism and user experience. It is suitable for scenarios such as reports and dashboards.

## Using Code

The [`backgroundImage`](/spreadjs/api/v19/classes/GC.Spread.Sheets.Worksheet#backgroundimage) method of the Worksheet class sets a worksheet background image. Pass an image source string as the first argument. You can also pass an options object to control whether the image repeats and whether it is drawn below or above worksheet content.
The image source can be one of the following:

* **Image URL**
    * A path pointing to an image located somewhere on the web.
    * Example: `"https://example.com/path/to/image.jpg"`
    * If using the external path, ensure that the server is configured with appropriate CORS headers to allow your application to access the resource.
* **Base64 Encoded Image Data**
    * The image is encoded in Base64 format, which can be directly embedded into HTML or CSS as a Data URL.
    * Example: `"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."`
* **Relative Path Image**
    * If the API and image resources are on the same server, you can use a relative path to reference the image.
    * Example: `"/images/background.png"`

```auto
let workbook = new GC.Spread.Sheets.Workbook("ss");
let worksheet = workbook.getActiveSheet();
worksheet.backgroundImage("https://cdn.mescius.io/umb/media/pujnxfci/mescuis-logo-horiz.svg", {
    layout: "repeat",
    paintOrder: "over-content"
});
```

![SpreadJS worksheet displaying a repeated background image above cell content after the backgroundImage method sets layout to repeat and paintOrder to over-content.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260728.b50bd8.png?width=600)

## Background Image Size

The background image is always rendered using its original size and will not be stretched or scaled. This means that regardless of the actual size of the worksheet, the background image will maintain its original width and height and will not automatically resize to fit the worksheet.
For example, if you have a background image that is 500x300 pixels, even if the worksheet is larger than this size, the background image will not be stretched or shrunk.

```auto
let workbook = new GC.Spread.Sheets.Workbook("ss");
let worksheet = workbook.getActiveSheet();
worksheet.backgroundImage("https://cdn.mescius.io/umb/media/pujnxfci/mescuis-logo-horiz.svg");
```

![SpreadJS worksheet rendering a background image at its original dimensions without stretching, demonstrating the default output of the backgroundImage method.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260728.5481b7.png?width=600)

## Background Image Repeat

Use the `layout` option to control whether the image is repeated.

* `"repeat"` \- Repeats the image horizontally and vertically until it fills the worksheet area\. This is the default behavior\.
* `"none"` \- Draws the image once at the upper\-left corner of the worksheet\.

```auto
let workbook = new GC.Spread.Sheets.Workbook("ss");
let worksheet = workbook.getActiveSheet();
worksheet.backgroundImage("https://cdn.mescius.io/umb/media/pujnxfci/mescuis-logo-horiz.svg", {
    layout: "repeat"
});
```

![SpreadJS worksheet filled with repeated background image tiles after the backgroundImage method applies the repeat layout option across the worksheet area.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260728.a17cd2.png?width=600)
The background image will be repeated in both the x-axis (horizontal direction) and y-axis (vertical direction) according to the actual size of the worksheet until it fills the entire worksheet area.
For example, if your worksheet is 1900x900 pixels and your background image is 500x300 pixels, the background image will repeat 4 times horizontally and 3 times vertically. Any portion of the image that exceeds the worksheet dimensions will be automatically clipped, thus filling the worksheet background.
![SpreadJS worksheet background image comparison showing the repeat layout filling the worksheet and the none layout drawing one image in the upper-left corner.](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/image.fbed33.png?width=600)

## Background Image Clip

To ensure that the background image does not exceed the actual display area of the worksheet if the background image extends beyond the display area of the worksheet in either the x-axis or y-axis, the excess portion will be automatically clipped. This means that the background image will only be displayed within the actual dimensions of the worksheet, and any part that extends beyond this range will not be shown.
For example, if your worksheet is 1900x900 pixels and your background image is 2000x1200 pixels, then the 100 pixels exceeding horizontally and the 300 pixels exceeding vertically will not be displayed. Only the portion that matches the worksheet's dimensions will be visible.
![SpreadJS worksheet clipping portions of an oversized background image outside the worksheet display area while preserving the image’s original dimensions.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260728.6d08ad.png?width=600)

## Freeze Panes and Scrolling

* Scrolling without freeze panes:

![SpreadJS worksheet scrolling without freeze panes showing how a background image remains rendered within the worksheet area.](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/bg1.ba1c8a.gif?width=600)

* Scrolling with freeze panes:

![SpreadJS worksheet scrolling with freeze panes showing background image behavior across frozen and scrollable worksheet regions.](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/bg3.2399ca.gif?width=600)

* Right to Left

![SpreadJS right-to-left worksheet showing background image rendering behavior while developers configure worksheet direction and scrolling.](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/bg2.884060.gif?width=600)

## Background Image Paint Order

By default, a worksheet background image is drawn below worksheet content.
To draw the background image above worksheet content, set `paintOrder` to `"over-content"`. This is useful for watermark-style images in reports, such as confidential marks or company branding.

```javascript
worksheet.backgroundImage("./image/background.png", {
    paintOrder: "over-content"
});
```

When the background image is drawn over content, worksheet content such as text, numbers, formula results, borders, cell styles, and merged cells remains editable and selectable.
![SpreadJS animation compares the original worksheet with normal and over-content paintOrder settings, showing the repeated background image first behind and then above the table and chart.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/paintOrder-20260728.e76551.gif?width=600)

## Print, PDF Export, and Excel Export

Worksheet background images behave differently depending on the output format.

* When `paintOrder` is `"normal"`, the worksheet background image is not included when printing or exporting to PDF.
* When `paintOrder` is `"over-content"`, the worksheet background image is included when printing and exporting to PDF, and is rendered above worksheet content.
* When exporting to Excel, the `paintOrder` setting is ignored because Excel does not support drawing worksheet background images above content. The background image is exported as a regular worksheet background image.
* The background image layout setting is preserved when exporting to Excel.

## Use a Background Image as a Watermark in ReportSheet

You can use a worksheet background image with `paintOrder` set to `"over-content"` to display a watermark-style image above ReportSheet content.

```javascript
const spread = new GC.Spread.Sheets.Workbook('ss', { sheetCount: 1 });
const reportSheet = spread.addSheetTab(0, 'report1', GC.Spread.Sheets.SheetType.reportSheet);
const templateSheet = reportSheet.getTemplate();

templateSheet.backgroundImage('./image/background.jpg', {
    paintOrder: 'over-content'
});

reportSheet.renderMode('Preview');
```

![SpreadJS ReportSheet Preview showing a watermark-style background image drawn over generated report content with paintOrder over-content.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260715.8ce743.png?width=600)
This approach is useful when a report needs a watermark, such as "Confidential", to appear above generated report content.

## Setting the Worksheet Background Image in the Designer

In the Designer, use the **Page Layout** tab to set or delete a worksheet background image. The **Background** group also provides options to control whether the image is repeated and whether it is drawn over worksheet content.

* **Repeat** \- Repeats the background image across the worksheet\.
* **Over Content** \- Draws the background image above worksheet content\.
* **Delete Background** \- Removes the worksheet background image\.

![SpreadJS Designer Page Layout tab showing Background commands for setting repeat, over-content, and delete background image options.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260715.9fb557.png?width=800)

>type=note
> By default, the background image operation button in the Designer is associated with commands for setting the background image on a per-worksheet basis. If users wish to revert to the functionality of applying background images to the entire workbook, they can execute the following script during the initialization of the Designer.

```javascript
//Before V19 SP2
var config = GC.Spread.Sheets.Designer.DefaultConfig;
var pageLayout = config.ribbon.filter((item)=>{ return item.id === 'pageLayout'})[0];
var pageSetup = pageLayout.buttonGroups.filter((item)=>{return item.thumbnailClass==='ribbon-thumbnail-page-setup'})[0]
var pageSetupCmdGroup = pageSetup.commandGroup.children[0].children;
pageSetup.commandGroup.children[0].children = pageSetupCmdGroup.map(function(ele){
    if(ele === 'worksheetBackground'){
        return GC.Spread.Sheets.Designer.CommandNames.Background;
    }else if(ele === 'deleteWorksheetBackground'){
        return GC.Spread.Sheets.Designer.CommandNames.DeleteBackground;
    }
    return ele;
});
designer.setConfig(config);

//After V19 SP2, the background node changed.
var config = GC.Spread.Sheets.Designer.DefaultConfig;
var pageLayout = config.ribbon.filter((item)=>{ return item.id === 'pageLayout'})[0];
var background = pageLayout.buttonGroups[2];
background.commandGroup.children[0].commands = background.commandGroup.children[0].commands.map(function(ele){
    if(ele === 'worksheetBackground'){
        return GC.Spread.Sheets.Designer.CommandNames.Background;
    }else if(ele === 'deleteWorksheetBackground'){
        return GC.Spread.Sheets.Designer.CommandNames.DeleteBackground;
    }
    return ele;
});
background.commandGroup.children.splice(1,1);

designer.setConfig(config);
```