# FCandlestickChartBuilder

- Human documentation: [https://docs.univer.ai/reference/facade/candlestick-chart-builder](https://docs.univer.ai/reference/facade/candlestick-chart-builder)

- Agent Markdown: [https://docs.univer.ai/reference/facade/candlestick-chart-builder.md](https://docs.univer.ai/reference/facade/candlestick-chart-builder.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/candlestick-chart-builder.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/candlestick-chart-builder.mdx)

---

Fluent semantic builder for one HLC or OHLC Candlestick series.

Each source row represents one trading interval. Map one category field and four
distinct numeric fields in Open, High, Low, Close order, or three in High, Low, Close order. A row with any missing or
non-finite required price renders as a gap. Three roles mean HLC; four mean OHLC.
Missing prices never change roles, and HLC never fabricates Open.

Sheet Header belongs to the source. Doc/Slide use `setSource()` for raw rows and
`setDataSource()` to update an inserted chart; explicit Lite Header belongs to the
host resource context. Both project titles into dataset dimensions. ChartContext
only selects dataset indexes and does not store Header. An inline resource containing
a title row uses host context `{ orient: 'row', header: { band: { startOffset: 0, endOffset: 0 } } }`.
The following Doc/Slide examples pass body rows directly, with no title band.

## Inheritance

Extends [`FAxisChartBuilder`](https://docs.univer.ai/reference/facade/axis-chart-builder.md). Its inherited members are available on this object.

## Example

Sheet HLC with an explicit title band

```ts
const chartInfo = fWorksheet
  .newChart(univerAPI.Enum.ChartTypeString.Candlestick)
  .setSource({
    range: 'A1:D6',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
    header: { band: { startOffset: 0, endOffset: 0 } },
  })
  .setCategoryField(0)
  .setCandlestickFields({ highIndex: 1, lowIndex: 2, closeIndex: 3 })
  .setHighLowLineStyle({ border: { color: '#333333', width: 1 } })
  .setCloseMarkerStyle({ point: { shape: univerAPI.Enum.ChartLinePointShape.Dash, size: 8 } })
  .build()
// clearHighLowLineStyle()/clearCloseMarkerStyle() restore the default appearance.
```

Sheet

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const chartInfo = fWorksheet
  .newChart(univerAPI.Enum.ChartTypeString.Candlestick)
  .setSource({
    range: 'A1:E8',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
    header: { band: { startOffset: 0, endOffset: 0 } },
  })
  .setCategoryField(0)
  .setCandlestickFields({ openIndex: 1, highIndex: 2, lowIndex: 3, closeIndex: 4 })
  .setRisingStyle({ color: '#0DA471', hollow: true })
  .setFallingStyle({ color: '#F05252' })
  .setDojiStyle({ color: '#8C8C8C', border: { width: 2 } })
  .setCandleWidth(18)
  .build()
await fWorksheet.insertChart(chartInfo)
```

Doc

```ts
const fDocument = univerAPI.getActiveDocument()
const chartInfo = fDocument
  .newChart(univerAPI.Enum.ChartTypeString.Candlestick)
  .setSource([
    ['Mon', 112, 96, 108],
    ['Tue', 116, 102, 105],
  ])
  .setCategoryField(0)
  .setCandlestickFields({ highIndex: 1, lowIndex: 2, closeIndex: 3 })
  .setHighLowLineStyle({ border: { color: '#333333', width: 1 } })
  .setCloseMarkerStyle({ point: { shape: univerAPI.Enum.ChartLinePointShape.Dot, size: 8 } })
  .build()
await fDocument.insertChart(chartInfo)
```

Slide

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const chartInfo = fSlide
  .newChart(univerAPI.Enum.ChartTypeString.Candlestick)
  .setSource([
    ['Mon', 100, 112, 96, 108],
    ['Tue', 108, 116, 102, 105],
  ])
  .setCategoryField(0)
  .setCandlestickFields({ openIndex: 1, highIndex: 2, lowIndex: 3, closeIndex: 4 })
  .setRisingStyle({ color: '#0DA471', hollow: true })
  .setFallingStyle({ color: '#F05252' })
  .setDojiStyle({ color: '#8C8C8C', border: { width: 2 } })
  .setCandleWidth(18)
  .build()
await fSlide.insertChart(chartInfo)
```

Board

```ts
const fBoard = univerAPI.getActiveBoard()
const chartInfo = fBoard
  .newChart(univerAPI.Enum.ChartTypeString.Candlestick)
  .setSource([
    ['Mon', 100, 112, 96, 108],
    ['Tue', 108, 116, 102, 105],
  ])
  .setCategoryField(0)
  .setCandlestickFields({ openIndex: 1, highIndex: 2, lowIndex: 3, closeIndex: 4 })
  .setRisingStyle({ color: '#0DA471', hollow: true })
  .setFallingStyle({ color: '#F05252' })
  .setDojiStyle({ color: '#8C8C8C', border: { width: 2 } })
  .setCandleWidth(18)
  .build()
await fBoard.insertChart(chartInfo)
```

## Setup

Register [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) or a preset that includes it. In plugin mode, import `@univerjs-pro/engine-chart/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/guides/sheets/getting-started/facade.md).

## `@univerjs-pro/engine-chart`

### `FCandlestickChartBuilder.clearCandlestickFields`

Clears the atomic Candlestick mapping while preserving the category field.

```typescript
clearCandlestickFields(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearCandlestickFields()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.clearCloseMarkerStyle`

Clears authored Close marker appearance.

```typescript
clearCloseMarkerStyle(): this
```

**Examples**

builder.clearCloseMarkerStyle();

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.clearDojiStyle`

Clears explicit Doji style overrides so runtime defaults apply.

```typescript
clearDojiStyle(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearDojiStyle()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.clearFallingStyle`

Clears explicit Falling style overrides so runtime defaults apply.

```typescript
clearFallingStyle(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearFallingStyle()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.clearHighLowLineStyle`

Clears authored high-low appearance.

```typescript
clearHighLowLineStyle(): this
```

**Examples**

builder.clearHighLowLineStyle();

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.clearRisingStyle`

Clears explicit Rising style overrides so runtime defaults apply.

```typescript
clearRisingStyle(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearRisingStyle()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.resetCandleWidth`

Removes the fixed candle width so the renderer chooses it automatically.

```typescript
resetCandleWidth(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetCandleWidth()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.setCandlestickFields`

Replaces High, Low, Close, and optionally Open source fields atomically.

Category remains configured through `setCategoryField()`. Every supplied index must be a
unique non-negative integer. Read the pending or persisted value with
`builder.build().config.mapping?.candlestick`.

```typescript
setCandlestickFields(fields: IChartCandlestickMappingSpec): this
```

**Parameters**

* `fields` — Required. HLC indexes; omit Open for HLC or supply a real Open index for OHLC.

**Returns**

This builder for chaining.

**Examples**

```ts
builder
  .setCategoryField(0)
  .setCandlestickFields({ openIndex: 1, highIndex: 2, lowIndex: 3, closeIndex: 4 })
const mapping = builder.build().config.mapping?.candlestick
```

**Types:** [`IChartCandlestickMappingSpec`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/types.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.setCandleWidth`

Sets a fixed candle width value without Facade range validation.

```typescript
setCandleWidth(width: number): this
```

**Parameters**

* `width` — Required. Fixed candle width in pixels.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setCandleWidth(18)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.setCloseMarkerStyle`

Sets Close marker appearance.

```typescript
setCloseMarkerStyle(style: NonNullable<IChartCandlestickSpec['closeMarker']>): this
```

**Parameters**

* `style` — Required.

**Examples**

builder.setCloseMarkerStyle(\{ point: \{ size: 8 } });

**Types:** [`NonNullable`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IChartCandlestickSpec`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/types.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.setDojiStyle`

Sets semantic Doji body and wick style overrides.

```typescript
setDojiStyle(style: IChartCandlestickStateStyleSpec): this
```

**Parameters**

* `style` — Required. Doji body and wick style values, passed through without Facade range validation.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setDojiStyle({ color: '#8C8C8C', border: { width: 2 } })
```

**Types:** [`IChartCandlestickStateStyleSpec`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/types.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.setFallingStyle`

Sets semantic Falling candle body and wick style overrides.

```typescript
setFallingStyle(style: IChartCandlestickStateStyleSpec): this
```

**Parameters**

* `style` — Required. Falling body and wick style values, passed through without Facade range validation.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setFallingStyle({ color: '#F05252' })
```

**Types:** [`IChartCandlestickStateStyleSpec`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/types.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.setHighLowLineStyle`

Sets high-low line appearance.

```typescript
setHighLowLineStyle(style: NonNullable<IChartCandlestickSpec['highLowLine']>): this
```

**Parameters**

* `style` — Required.

**Examples**

builder.setHighLowLineStyle(\{ visible: false });

**Types:** [`NonNullable`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IChartCandlestickSpec`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/types.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)

### `FCandlestickChartBuilder.setRisingStyle`

Sets semantic Rising candle body and wick style overrides.

```typescript
setRisingStyle(style: IChartCandlestickStateStyleSpec): this
```

**Parameters**

* `style` — Required. Rising body and wick style values, passed through without Facade range validation.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setRisingStyle({ color: '#0DA471', hollow: true })
```

**Types:** [`IChartCandlestickStateStyleSpec`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/types.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-candlestick-chart-builder.d.ts)