> For the complete documentation index, see [llms.txt](https://docs.rowsncolumns.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rowsncolumns.app/configuration/features/gradient-fills.md).

# Gradient cell fills

Set a gradient on any cell's `uf` (user-entered format) and the canvas renderer paints it directly. Supports both **linear** (with a rotation angle) and **path / radial** (with axis-of-radial insets), each with two or more color stops.

Mirrors OOXML's `<gradientFill>` element. XLSX round-trip is full; the canvas paint uses native `CanvasGradient` (`createLinearGradient` / `createRadialGradient`).

## Authoring

```ts
const cellData: CellData = {
  ue: { sv: "Header" },
  fv: "Header",
  uf: {
    gradient: {
      type: "linear",
      degree: 90,              // 0 = left→right, 90 = top→bottom, 180 = right→left, 270 = bottom→top
      stops: [
        { position: 0, color: "#fde68a" },
        { position: 1, color: "#dc2626" },
      ],
    },
  },
};
```

`position` is on `[0, 1]`. At least two stops are required; three+ stops give multi-stop ramps.

## Path / radial gradients

Use `type: "path"` with four optional inset values describing where the inner stop's "core" rectangle sits relative to the cell:

```ts
uf: {
  gradient: {
    type: "path",
    left: 0.5,
    right: 0.5,
    top: 0.5,
    bottom: 0.5,
    stops: [
      { position: 0, color: "#ffffff" },   // center
      { position: 1, color: "#7c3aed" },   // edges
    ],
  },
}
```

The example above produces a radial gradient centered in the cell. Shift the center off-axis by adjusting `left` / `right` / `top` / `bottom` (each 0..1 — the inset of the inner stop's core from that edge).

## Three-stop ramps

```ts
uf: {
  gradient: {
    type: "linear",
    degree: 45,
    stops: [
      { position: 0,   color: "#fef08a" },   // yellow at one end
      { position: 0.5, color: "#22c55e" },   // green in the middle
      { position: 1,   color: "#1e40af" },   // blue at the other end
    ],
  },
}
```

## Precedence over solid + pattern fills

When `gradient` is present on a cell's format, it takes precedence over `backgroundColor` and `fillPattern`. Excel's UI treats fills as mutually exclusive on a single cell, so the renderer matches that: pattern + solid are ignored.

The `cellXfsRegistry` deduplication hash includes the gradient stops, so two cells with the same gradient share a `sid` reference (same compression behavior as for regular fills).

## XLSX round-trip

Parser reads `<gradientFill>` from `xl/styles.xml` and hydrates the `gradient` field on `CellFormat`. Exporter emits the same element with `<stop position><color rgb="..."/></stop>` children. Both linear and path/radial round-trip. The OOXML attributes map 1:1 onto the type's fields:

| OOXML                                   | Field                             |
| --------------------------------------- | --------------------------------- |
| `type="linear"` + `degree`              | `type: "linear"`, `degree`        |
| `type="path"` + `left/right/top/bottom` | `type: "path"`, four inset fields |
| `<stop position><color rgb=…/></stop>`  | `stops` array                     |

## Canvas rendering

The renderer constructs a `CanvasGradient` for each cell:

* **Linear**: the gradient axis projects through the cell's centroid at the given angle; start/end points are where that axis exits the bounding box.
* **Path / radial**: a `createRadialGradient` anchored at the inset midpoint with radius = distance to the farthest corner.

`setLineDash` and stroke styles are preserved — gradient cells still get cell borders, conditional-format icons, etc.

## Storybook example

See the `compatShowcaseSheet` in the storybook (Sheet 1, row 12) for a side-by-side gallery: `linear 0°`, `linear 90°`, `linear 45° (3 stops)`, `path (radial)`, `linear 180°`, and a `linear vert 3-stop` example. The pattern-fill row (row 11) is positioned right above so you can compare the two paint paths.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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.rowsncolumns.app/configuration/features/gradient-fills.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.