Web SDK

Filter

The Filter feature allows users to filter data in spreadsheets to quickly find and analyze specific information. It supports various filtering conditions and operations, helping users process data more efficiently.

Plugin Mode

Installation

Shell
pnpm add @univerjs/sheets-filter @univerjs/sheets-filter-ui

Usage

TypeScript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverSheetsFilterPlugin } from '@univerjs/sheets-filter'import { UniverSheetsFilterUIPlugin } from '@univerjs/sheets-filter-ui'import SheetsFilterUIEnUS from '@univerjs/sheets-filter-ui/locale/en-US'import '@univerjs/sheets-filter-ui/lib/index.css'import '@univerjs/sheets-filter/facade'const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      SheetsFilterUIEnUS,     ),  },})univer.registerPlugin(UniverSheetsFilterPlugin)univer.registerPlugin(UniverSheetsFilterUIPlugin)

Plugins and Configuration

TypeScript
interface IUniverSheetsFilterConfig {  /**   * Whether to display the filter sync switch in the filter panel.   * This configuration can be used in a collaboration scenario to allow users to choose whether to enable filter synchronization.   * If set to a defaultValue object, the filter sync switch will be displayed and its initial state will be determined by the defaultValue property.   * @default false   */  enableSyncSwitch?: boolean | { defaultValue: boolean }}

Preset Mode

Installation

Shell
pnpm add @univerjs/preset-sheets-filter

Usage

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { UniverSheetsFilterPreset } from '@univerjs/preset-sheets-filter'import UniverPresetSheetsFilterEnUS from '@univerjs/preset-sheets-filter/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-filter/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetSheetsCoreEnUS,      UniverPresetSheetsFilterEnUS,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsFilterPreset(),   ],})

Presets and Configuration

TypeScript
interface IUniverSheetsFilterPresetConfig {  /**   * Whether to display the filter sync switch in the filter panel.   * This configuration can be used in a collaboration scenario to allow users to choose whether to enable filter synchronization.   * If set to a defaultValue object, the filter sync switch will be displayed and its initial state will be determined by the defaultValue property.   * @default false   */  enableSyncSwitch?: boolean | { defaultValue: boolean }}

Facade API

Complete Facade API type definitions can be found in the FacadeAPI.

Importing

Plugin mode note

Only plugin mode requires manually importing the Facade package. Preset mode already includes the corresponding Facade package, so no extra import is needed.

TypeScript
import '@univerjs/sheets-filter/facade'

Get Filter

Returns an FFilter object. If the sheet does not have a filter, it returns null.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()// Get filter from FWorksheetconst fWorksheet = fWorkbook.getActiveSheet()const fFilter = fWorksheet.getFilter()fFilter?.getRange().getA1Notation()// Get filter from FRangeconst fRange = fWorksheet.getRange('A1:D14')const fFilter2 = fRange.getFilter()fFilter2?.getRange().getA1Notation()

Create Filter

Creates an FFilter object. If the sheet already has a filter, it returns null.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:D14')let fFilter = fRange.createFilter()// If the worksheet already has a filter, remove it and create a new filter.if (!fFilter) {  fWorksheet.getFilter().remove()  fFilter = fRange.createFilter()}fFilter.getRange().getA1Notation()

Remove Filter

FFilter.remove() removes the filter from the worksheet.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()fWorksheet.getFilter()?.remove()

Get Column Filter Criteria

The FFilter.getColumnFilterCriteria(column) method returns the filter criteria of the specified column.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Set some values of the range C1:F10const fRange = fWorksheet.getRange('C1:F10')fRange.setValues([  [1, 2, 3, 4],  [2, 3, 4, 5],  [3, 4, 5, 6],  [4, 5, 6, 7],  [5, 6, 7, 8],  [6, 7, 8, 9],  [7, 8, 9, 10],  [8, 9, 10, 11],  [9, 10, 11, 12],  [10, 11, 12, 13],])// Create a filter on the range C1:F10let fFilter = fRange.createFilter()// If the filter already exists, remove it and create a new oneif (!fFilter) {  fRange.getFilter().remove()  fFilter = fRange.createFilter()}// Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9const column = fWorksheet.getRange('C:C').getColumn()fFilter.setColumnFilterCriteria(column, {  colId: 0,  filters: {    filters: ['1', '5', '9'],  },})// Print the filter criteria of the column C and DfFilter.getColumnFilterCriteria(column) // { colId: 0, filters: { filters: ['1', '5', '9'] } }fFilter.getColumnFilterCriteria(column + 1) // undefined

Set Column Filter Criteria

FFilter.setColumnFilterCriteria(column, criteria) method sets the filter criteria of the specified column.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Set some values of the range C1:F10const fRange = fWorksheet.getRange('C1:F10')fRange.setValues([  [1, 2, 3, 4],  [2, 3, 4, 5],  [3, 4, 5, 6],  [4, 5, 6, 7],  [5, 6, 7, 8],  [6, 7, 8, 9],  [7, 8, 9, 10],  [8, 9, 10, 11],  [9, 10, 11, 12],  [10, 11, 12, 13],])// Create a filter on the range C1:F10let fFilter = fRange.createFilter()// If the filter already exists, remove it and create a new oneif (!fFilter) {  fRange.getFilter().remove()  fFilter = fRange.createFilter()}// Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9const column = fWorksheet.getRange('C:C').getColumn()fFilter.setColumnFilterCriteria(column, {  colId: 0,  filters: {    filters: ['1', '5', '9'],  },})

Remove Column Filter Criteria

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Set some values of the range C1:F10const fRange = fWorksheet.getRange('C1:F10')fRange.setValues([  [1, 2, 3, 4],  [2, 3, 4, 5],  [3, 4, 5, 6],  [4, 5, 6, 7],  [5, 6, 7, 8],  [6, 7, 8, 9],  [7, 8, 9, 10],  [8, 9, 10, 11],  [9, 10, 11, 12],  [10, 11, 12, 13],])// Create a filter on the range C1:F10let fFilter = fRange.createFilter()// If the filter already exists, remove it and create a new oneif (!fFilter) {  fRange.getFilter().remove()  fFilter = fRange.createFilter()}// Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9const column = fWorksheet.getRange('C:C').getColumn()fFilter.setColumnFilterCriteria(column, {  colId: 0,  filters: {    filters: ['1', '5', '9'],  },})// Clear the filter criteria of the column C after 3 secondssetTimeout(() => {  fFilter.removeColumnFilterCriteria(column)  // Or use fFilter.removeFilterCriteria() to remove all column filter criteria}, 3000)

Get Filtered Out Rows

FFilter.getFilteredOutRows() method returns an array containing the indexes of the rows that are filtered out.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Set some values of the range C1:F10const fRange = fWorksheet.getRange('C1:F10')fRange.setValues([  [1, 2, 3, 4],  [2, 3, 4, 5],  [3, 4, 5, 6],  [4, 5, 6, 7],  [5, 6, 7, 8],  [6, 7, 8, 9],  [7, 8, 9, 10],  [8, 9, 10, 11],  [9, 10, 11, 12],  [10, 11, 12, 13],])// Create a filter on the range C1:F10let fFilter = fRange.createFilter()// If the filter already exists, remove it and create a new oneif (!fFilter) {  fRange.getFilter().remove()  fFilter = fRange.createFilter()}// Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9const column = fWorksheet.getRange('C:C').getColumn()fFilter.setColumnFilterCriteria(column, {  colId: 0,  filters: {    filters: ['1', '5', '9'],  },})// Print the filtered out rowsfFilter.getFilteredOutRows() // [1, 2, 3, 5, 6, 7, 9]

Event Listeners

Complete event type definitions can be found in the Events.

SheetRangeFiltered event is triggered when the column filter criteria changes.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetRangeFiltered, (params) => {  const { workbook, worksheet, col, criteria } = params})// Remove the event listener, use `disposable.dispose()`

SheetBeforeRangeFilter event is triggered before the column filter criteria changes.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetBeforeRangeFilter, (params) => {  const { workbook, worksheet, col, criteria } = params  // Cancel the filter criteria change operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

SheetRangeFilterCleared event is triggered when the criteria is cleared.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetRangeFilterCleared, (params) => {  const { workbook, worksheet } = params})// Remove the event listener, use `disposable.dispose()`

SheetBeforeRangeFilterClear event is triggered before the criteria is cleared.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetBeforeRangeFilterClear, (params) => {  const { workbook, worksheet } = params  // Cancel the filter clear operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

How is this guide?

© 2026 DreamNum Co., Ltd.