# Outline

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [sheets/features/outline.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/outline.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-outline",
      "facade": "@univerjs-pro/sheets-outline/facade"
    },
    {
      "client": "@univerjs-pro/sheets-outline-ui",
      "locale": "@univerjs-pro/sheets-outline-ui/locale/en-US",
      "style": "@univerjs-pro/sheets-outline-ui/lib/index.css"
    }
  ],
  "server": false
}
```

The outline feature (also known as grouping or dimension outline) allows you to group rows or columns in a worksheet. This is useful for organizing and summarizing large datasets by creating collapsible sections.

## Introduction

In Univer Sheets, the outline feature enables you to:

* **Group rows or columns**: Create hierarchical groups of rows or columns to organize data.
* **Collapse and expand groups**: Show or hide grouped rows or columns with a single click.
* **Nested groups**: Create multiple levels of groups for complex data hierarchies.

Outline groups are commonly used in the following scenarios:

* Summarizing detailed data: Group detailed rows under summary rows to create a cleaner view.
* Organizing large datasets: Group related columns or rows together for easier navigation.
* Creating collapsible reports: Allow users to expand or collapse sections of a report as needed.

> Interactive example: [Open the playground](/playground/sheets/outline)

## Preset Mode

The outline feature is included in the `@univerjs/preset-sheets-advanced` preset.

### Installation

#### npm

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

#### pnpm

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

#### yarn

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

#### bun

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

### Usage

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

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

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

If you have a commercial license for Univer, please refer to [Using License in Client](https://docs.univer.ai/server/license.md#in-preset-mode) for configuration.

## Plugin Mode

### Installation

#### npm

```bash
npm install @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-ui
```

#### pnpm

```bash
pnpm add @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-ui
```

#### yarn

```bash
yarn add @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-ui
```

#### bun

```bash
bun add @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-ui
```

### Usage

```typescript
import { UniverSheetsOutlinePlugin } from '@univerjs-pro/sheets-outline' // [!code ++]
import { UniverSheetsOutlineUIPlugin } from '@univerjs-pro/sheets-outline-ui' // [!code ++]
import SheetsOutlineUIEnUS from '@univerjs-pro/sheets-outline-ui/locale/en-US' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

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

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

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

univer.registerPlugin(UniverSheetsOutlinePlugin)
univer.registerPlugin(UniverSheetsOutlineUIPlugin)
```

If you have a commercial license for Univer, please refer to [Using License in Client](https://docs.univer.ai/server/license.md#in-plugin-mode) for configuration.

## Facade API

Complete Facade API type definitions can be found in the [FacadeAPI](https://docs.univer.ai/reference/facade/univer.md).

### 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-pro/sheets-outline/facade'
```

### Creating Row Outlines

You can create a row outline group using the Facade API:

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

// Group rows 2 to 6 (0-based index: startRow=1, numRows=5)
fWorksheet.addRowOutline(1, 5)
```

### Creating Column Outlines

Similarly, you can create a column outline group:

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

// Group columns B to E (0-based index: startColumn=1, numColumns=4)
fWorksheet.addColumnOutline(1, 4)
```

### Collapsing and Expanding Outlines

You can collapse or expand an outline group programmatically:

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

const rowOutlines = fWorksheet.getDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW)
if (rowOutlines.length > 0) {
  // Collapse the first row outline group
  fWorksheet.setDimensionOutlineCollapsed(rowOutlines[0].id, true)

  // Expand it later
  fWorksheet.setDimensionOutlineCollapsed(rowOutlines[0].id, false)
}
```

### Removing Outlines

You can remove a specific outline group by its ID:

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

const rowOutlines = fWorksheet.getDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW)
if (rowOutlines.length > 0) {
  fWorksheet.removeDimensionOutline(rowOutlines[0].id)
}
```

### Clearing Outlines in a Range

You can clear all outline groups within a specific range:

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

// Remove all row outline groups fully contained in rows 2 to 10
fWorksheet.clearDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW, 1, 9)
```

### Querying Outlines

You can retrieve all outline groups on a worksheet:

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

// Get all row outlines
const rowOutlines = fWorksheet.getDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW)
rowOutlines.forEach((outline) => {
  console.log(outline.id, outline.start, outline.end, outline.collapsed)
})

// Get all outlines (both row and column)
const allOutlines = fWorksheet.getDimensionOutlines()
```

## Outline Data Structure

Each outline group has the following properties:

| Property    | Type                   | Description                                 |
| ----------- | ---------------------- | ------------------------------------------- |
| `id`        | `string`               | Unique identifier for the outline group     |
| `unitId`    | `string`               | The workbook unit ID                        |
| `subUnitId` | `string`               | The worksheet sheet ID                      |
| `axis`      | `DimensionOutlineAxis` | The axis of the outline (`row` or `column`) |
| `start`     | `number`               | Zero-based inclusive start index            |
| `end`       | `number`               | Zero-based inclusive end index              |
| `collapsed` | `boolean`              | Whether the group is currently collapsed    |

## Validation and Errors

When creating outline groups, the following validations are performed:

* **Invalid range**: The range must be valid (non-negative, non-zero count).
* **Out of bounds**: The range must be within the worksheet boundaries.
* **Crossing groups**: New groups cannot cross existing groups.
* **Maximum depth**: There is a maximum nesting depth for outline groups.

The range for ungrouping must fully contain the outline group range, otherwise the validation will fail.

If a validation fails, the command will not execute and an error will be emitted through the `SheetsOutlineErrorService`.