# Progress Sparkline

## Content

The Progress Sparkline displays progress directly inside a cell. You can use it to show completion status, readiness, quota progress, or other ratio-based values without adding a separate chart.
A progress value is treated as a ratio from `0` to `1`. For example, `0.37` represents `37%`.
![SpreadJS worksheet demonstrating Progress Sparklines that visualize ratio-based completion status directly inside cells without requiring separate charts.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.e672e1.png?width=600)

## Configure a Progress Sparkline

The **ProgressSparkline Setting** dialog provides the following options:

| Setting | Description |
| ------- | ----------- |
| **Value** | Specifies the progress value, cell reference, or supported range expression that resolves to a numeric ratio. <br>Use a ratio from `0` to `1`, such as `0.75` for `75%`. |
| **Mode** | Specifies the visual style of the Progress Sparkline. |
| **Bar Color** | Sets the color of the completed portion. |
| **Band Color** | Sets the color of the remaining portion or track. |
| **Show Value** | Shows or hides the percentage text. |

>type=note
> By default, Designer uses mode `0`, `Accent 1` as the bar color, `Accent 1 80` as the band color, and shows the percentage text.

### Progress Modes

The `mode` argument specifies the visual style of the Progress Sparkline.

| Mode | Name | Description | Example |
| ---- | ---- | ----------- | ------- |
| `0` | Bar Continuous | Horizontal rounded progress bar. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 0 as a continuous horizontal bar with a rounded progress track.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.0f2e0a.png?width=250) |
| `1` | Bar Striped | Horizontal progress bar with diagonal stripes on the completed portion. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 1 as a horizontal bar with diagonal stripes across the completed portion.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.1a01a0.png?width=250) |
| `2` | Bar Segmented | Discrete block segments. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 2 as discrete rectangular segments representing completed and remaining progress.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.348cda.png?width=250) |
| `3` | Ring | Circular progress ring. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 3 as a circular ring that indicates the current completion ratio.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.e7ba9a.png?width=150) |
| `4` | Arc | Semi-circular gauge arc. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 4 as a semicircular gauge arc for displaying ratio-based progress.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.9a9c6d.png?width=150) |
| `5` | Bar Hatched | Filled bar with a hatched remaining track. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 5 as a filled bar with a hatched remaining track.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.699782.png?width=250) |
| `6` | Bar Bubble | Filled and outlined circles for discrete progress steps. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 6 with filled and outlined circles representing discrete progress steps.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.b192d5.png?width=250) |
| `7` | Bar Dotted Track | Filled bar with a dotted remaining track. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 7 as a filled bar followed by a dotted remaining track.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.a03dc5.png?width=250) |
| `8` | Bar Checkbox | Checked and unchecked squares for progress steps. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 8 with checked and unchecked squares representing completed and remaining steps.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.a38b9a.png?width=250) |
| `9` | Ring Gap | Circular ring with a fixed gap. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 9 as a circular progress ring containing a fixed visual gap.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.07b5f6.png?width=100) |
| `10` | Ring Thick | Thick circular progress ring. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 10 as a thick circular ring for prominently displaying completion status.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.0287c5.png?width=100) |
| `11` | Ring Ticks | Circular ring with tick marks. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 11 as a circular progress ring divided by visible tick marks.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.948c40.png?width=100) |
| `12` | Ring Dash | Circular ring with dashed progress segments. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 12 as a circular ring composed of dashed progress segments.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.e53079.png?width=100) |
| `13` | Ring Dots | Circular ring with dotted progress segments. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 13 as a circular ring composed of dotted progress segments.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.12b2ac.png?width=100) |
| `14` | Ring Knob | Circular ring with an endpoint dot indicator. | ![SpreadJS worksheet cell rendering Progress Sparkline mode 14 as a circular ring with a dot marking the progress endpoint.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.7c3671.png?width=100) |

## Example

The following example creates Progress Sparklines with different styles and color settings.

```javascript
var sheet = spread.getActiveSheet();

sheet.setColumnWidth(0, 180);
sheet.setColumnWidth(1, 80);
sheet.setColumnWidth(2, 200);

sheet.getRange(0, 0, 4, 3).vAlign(GC.Spread.Sheets.VerticalAlign.center);

for (var r = 0; r < 4; r++) {
    sheet.setRowHeight(r, 80);
}

// Theme color, literal value, and visible percentage text.
sheet.setValue(0, 0, "Project Delivery");
sheet.setFormula(0, 2, '=PROGRESSSPARKLINE(0.37,1,"Accent 1","Accent 1 80")');

// CSS color, literal value, and hidden percentage text.
sheet.setValue(1, 0, "Release Readiness");
sheet.setFormula(1, 2, '=PROGRESSSPARKLINE(0.37,4,"#8e44ad","#e8d5f5",FALSE)');

// Theme color, cell reference, and visible percentage text.
sheet.setValue(2, 0, "Sales Quota");
sheet.setValue(2, 1, 0.73);
sheet.setFormula(2, 2, '=PROGRESSSPARKLINE(B3,14,"Accent 2","Accent 2 80")');
```

![SpreadJS worksheet showing striped, arc, and ring-knob Progress Sparklines for project delivery, release readiness, and sales quota, using literal values and a cell reference.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260709.433f2c.png?width=600)

## Notes

* Progress values are interpreted as ratios. Use `0.75` for `75%`.
* Blank or empty values are displayed as `0`.
* Values less than `0` are displayed as `0`.
* Values greater than `1` are displayed as `1`.
* If the value or mode is invalid, the formula returns `#VALUE!`.
* The Progress Sparkline is formula-driven and is displayed inside the cell that contains the formula.