Slicers and Timelines
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
Add the following to your existing Sheets setup, with drawing support and the Table or PivotTable source configured. Load the locale and register these plugins before creating the workbook.
pnpm add @univerjs-pro/sheets-slicer @univerjs-pro/sheets-slicer-uinpm install @univerjs-pro/sheets-slicer @univerjs-pro/sheets-slicer-uiyarn add @univerjs-pro/sheets-slicer @univerjs-pro/sheets-slicer-uibun add @univerjs-pro/sheets-slicer @univerjs-pro/sheets-slicer-uiimport { 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)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.
pnpm add @univerjs/preset-sheets-core @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancednpm install @univerjs/preset-sheets-core @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedyarn add @univerjs/preset-sheets-core @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedbun add @univerjs/preset-sheets-core @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedimport { 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, 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().
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.
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:
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.
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.
How is this guide?