# Sorting

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

#### Package metadata

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

Sorting functionality allows users to sort data in spreadsheets for better organization and analysis. It supports various sorting methods, including ascending, descending, and custom sorting, helping users quickly find the data they need.

## Preset Mode

### Installation

#### npm

```bash
npm install @univerjs/preset-sheets-sort
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-sort
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-sort
```

#### bun

```bash
bun add @univerjs/preset-sheets-sort
```

### Usage

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsSortPreset } from '@univerjs/preset-sheets-sort' // [!code ++]
import UniverPresetSheetsSortEnUS from '@univerjs/preset-sheets-sort/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-sort/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsSortEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsSortPreset(), // [!code ++]
  ],
})
```

## Plugin Mode

### Installation

#### npm

```bash
npm install @univerjs/sheets-sort @univerjs/sheets-sort-ui
```

#### pnpm

```bash
pnpm add @univerjs/sheets-sort @univerjs/sheets-sort-ui
```

#### yarn

```bash
yarn add @univerjs/sheets-sort @univerjs/sheets-sort-ui
```

#### bun

```bash
bun add @univerjs/sheets-sort @univerjs/sheets-sort-ui
```

### Usage

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverSheetsSortPlugin } from '@univerjs/sheets-sort' // [!code ++]
import { UniverSheetsSortUIPlugin } from '@univerjs/sheets-sort-ui' // [!code ++]
import SheetsSortUIEnUS from '@univerjs/sheets-sort-ui/locale/en-US' // [!code ++]

import '@univerjs/sheets-sort-ui/lib/index.css' // [!code ++]

import '@univerjs/sheets-sort/facade' // [!code ++]

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      SheetsSortUIEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsSortPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsSortUIPlugin) // [!code ++]
```

## Facade API

Complete Facade API type definitions can be found in the [FacadeAPI](https://reference.univer.ai/en-US).

### Importing

> [!INFO: 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-sort/facade'
```

### Worksheet Sorting

[`FWorksheet.sort(colIndex, asc)`](https://docs.univer.ai/reference/facade/worksheet.md#sort) method can sort the worksheet by the specified column.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Sorts the worksheet in ascending order based on the first column
fWorksheet.sort(0)

// Sorts the worksheet in descending order based on the first column
fWorksheet.sort(0, false)
```

### Range Sorting

[`FRange.sort(column)`](https://docs.univer.ai/reference/facade/range.md#sort) method can sort the cells in a specified range by the given column and order.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('D1:G10')

// Sorts the range in ascending order based on the first column
fRange.sort(0)

// Sorts the range in descending order based on the first column
fRange.sort({ column: 0, ascending: false })

// Sorts the range in descending order based on the first column and ascending order based on the second column
fRange.sort([{ column: 0, ascending: false }, 1])
```

### Event Listeners

Complete event type definitions can be found in the [Events](https://docs.univer.ai/reference/facade/events.md).

`SheetRangeSorted` event is triggered after the cell range sorting is completed.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetRangeSorted, (params) => {
  const { workbook, worksheet, range, sortColumn } = params
})

// Remove event listener using `disposable.dispose()`
```

`SheetBeforeRangeSort` event is triggered before the cell range sorting.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetBeforeRangeSort, (params) => {
  const { workbook, worksheet, range, sortColumn } = params

  // Cancel the sorting operation
  params.cancel = true
})

// Remove event listener using `disposable.dispose()`
```