# Slicers and Timelines

- Human documentation: [https://docs.univer.ai/guides/sheets/features/slicer](https://docs.univer.ai/guides/sheets/features/slicer)

- Agent Markdown: [https://docs.univer.ai/guides/sheets/features/slicer.md](https://docs.univer.ai/guides/sheets/features/slicer.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.3.0`

- Source: [sheets/features/slicer.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/slicer.mdx)

---

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/en-US",
      "style": "@univerjs/preset-sheets-advanced/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/sheets-slicer",
      "facade": "@univerjs-pro/sheets-slicer/facade"
    },
    {
      "client": "@univerjs-pro/sheets-slicer-ui",
      "locale": "@univerjs-pro/sheets-slicer-ui/locale/en-US",
      "style": "@univerjs-pro/sheets-slicer-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

Slicers filter Tables, PivotTables, and PivotCharts by source members. Timelines filter supported original Pivot date fields; Table columns, text fields, calculated fields, and derived grouping fields cannot be Timeline sources.

## Integration

#### Plugin mode

Add the following to your existing [Sheets setup](https://docs.univer.ai/guides/sheets/getting-started/installation.md), with [drawing support](https://docs.univer.ai/guides/sheets/features/images.md) and the [Table](https://docs.univer.ai/guides/sheets/features/table.md) or [PivotTable](https://docs.univer.ai/guides/sheets/features/pivot-table.md) source configured. Load the locale and register these plugins before creating the workbook.

```package-install
npm install @univerjs-pro/sheets-slicer @univerjs-pro/sheets-slicer-ui
```

```ts
import { UniverSheetsSlicerPlugin } from '@univerjs-pro/sheets-slicer'
import { UniverSheetsSlicerUIPlugin } from '@univerjs-pro/sheets-slicer-ui'
import SheetsSlicerUILocale from '@univerjs-pro/sheets-slicer-ui/locale/en-US'
import { LocaleType } from '@univerjs/core'
import '@univerjs-pro/sheets-slicer/facade'
import '@univerjs-pro/sheets-slicer-ui/lib/index.css'

univerAPI.loadLocales(LocaleType.EN_US, SheetsSlicerUILocale)
univer.registerPlugin(UniverSheetsSlicerPlugin)
univer.registerPlugin(UniverSheetsSlicerUIPlugin)
```

#### Preset mode

The advanced preset includes slicer and timeline model/UI plugins and their Facade APIs. Combine it with the core and drawing presets, and merge the locale packages. If you already use the advanced preset, add `slicer` to that registration instead of registering it again. Configure the client license as described in [using a license](https://docs.univer.ai/server/license.md).

```package-install
npm install @univerjs/preset-sheets-core @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

```ts
import { LocaleType, mergeLocales } from '@univerjs/core'
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'
import AdvancedLocale from '@univerjs/preset-sheets-advanced/locales/en-US'
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import CoreLocale from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'
import DrawingLocale from '@univerjs/preset-sheets-drawing/locales/en-US'
import { createUniver } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css'
import '@univerjs/preset-sheets-advanced/lib/index.css'

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(CoreLocale, DrawingLocale, AdvancedLocale),
  },
  presets: [
    UniverSheetsCorePreset({ container: 'app' }),
    UniverSheetsDrawingPreset(),
    UniverSheetsAdvancedPreset({ slicer: { maxMemberWindowSize: 200 } }),
  ],
})
```

When using a [Worker](https://docs.univer.ai/guides/sheets/getting-started/worker.md), set `useWorker: true` on the advanced preset and register `UniverSheetsAdvancedWorkerPreset()` in the Worker; it also includes the slicer calculation plugin.

## Create a slicer

This example uses a PivotTable at I1 on the active sheet with a source field named `Region`. Obtain its stable original field ID with `getSourceFieldsInfo()`; display names and report field IDs cannot be passed to `newSlicer()`.

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook?.getActiveSheet()
if (!fWorkbook || !fWorksheet) throw new Error('No active worksheet')

const pivotTable = fWorkbook.getPivotTableByCell(
  fWorkbook.getId(),
  fWorksheet.getSheetId(),
  0,
  8,
)
const regionField = pivotTable?.getSourceFieldsInfo().find((field) => field.name === 'Region')
if (!pivotTable || !regionField) throw new Error('Region source field not found')

const slicer = await fWorksheet.insertSlicer(
  pivotTable.newSlicer(regionField.id)
    .setCaption(regionField.name)
    .setPosition('N2')
    .build(),
)
```

`pivotTable.newSlicer()` binds the builder to its source. `build()` only prepares the configuration; `insertSlicer()` creates the control. The host and source sheets may differ, but must be in the same workbook. For a Table source, use `fWorksheet.newSlicer(columnId).setTableReference({ subUnitId, tableId })`, where `columnId` is the stable Table column ID.

## Create a timeline

Continuing with the same PivotTable, this example requires an original date field named `Date`. `newTimeline()` validates the source and rejects unsupported fields. Timeline range APIs use Excel serial values in the workbook’s date system, not JavaScript `Date` objects.

```ts
const dateField = pivotTable.getSourceFieldsInfo().find((field) => field.name === 'Date')
if (!dateField) throw new Error('Date source field not found')

const timeline = await fWorksheet.insertTimeline(
  pivotTable.newTimeline(dateField.id)
    .setCaption(dateField.name)
    .setLevel(univerAPI.Enum.TimelineLevel.Month)
    .setPosition('N18')
    .build(),
)
```

## Find controls and observe changes

Use `getSlicer(viewId)` / `getSlicers()` and `getTimeline(viewId)` / `getTimelines()` on the host worksheet. `viewId` is the business ID returned by the control’s `getId()`, not its drawing ID.

Listen to `SlicerAdded`, `SlicerChanged`, `SlicerRemoved`, `TimelineAdded`, `TimelineChanged`, and `TimelineRemoved` through `univerAPI.addEvent()`. Events describe committed local changes, not remote saving or completed rendering. Dispose the returned subscription when it is no longer needed.

API reference:

- [FSheetSlicer](https://docs.univer.ai/reference/facade/sheet-slicer.md)
- [FSheetSlicerBuilder](https://docs.univer.ai/reference/facade/sheet-slicer-builder.md)
- [FSheetTimeline](https://docs.univer.ai/reference/facade/sheet-timeline.md)
- [FSheetTimelineBuilder](https://docs.univer.ai/reference/facade/sheet-timeline-builder.md)
- [FEventName](https://docs.univer.ai/reference/facade/events.md#univerjs-prosheets-slicer)

## Member queries and shared filters

Use typed source values with `setSelection()`: the number `1`, string `'1'`, and a blank are different members. Do not pass display labels or visible item indexes. The filter is shared by every view of the same cache and its connected reports. For a Table source, it replaces that column’s filter while preserving other columns. Call `clearFilter()` to clear it.

```ts
import { FilterSelectionMode, RecordValueType } from '@univerjs/core'

const accepted = await slicer.setSelection({
  mode: FilterSelectionMode.Include,
  values: [{ type: RecordValueType.String, value: 'EMEA' }],
})
```

`getItems({ start, count })` reads a window, not the whole source; reading does not change the selection. The default request is 100 items, capped by `maxMemberWindowSize` (default 200, a positive integer). Preserve selections outside the visible window. `setConnections()` replaces Pivot report connections; use `getConnectionCandidates()` to discover compatible reports. Editing requires the relevant worksheet permissions. See [FSheetSlicer](https://docs.univer.ai/reference/facade/sheet-slicer.md).