# Find & Replace

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

#### Package metadata

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

The Find & Replace feature allows users to quickly search for specific content in spreadsheets and replace it, supporting various matching options to help users efficiently process data.

> Interactive example: [Open the playground](/playground/sheets/find-replace)

## Preset Mode

### Installation

#### npm

```bash
npm install @univerjs/preset-sheets-find-replace
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-find-replace
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-find-replace
```

#### bun

```bash
bun add @univerjs/preset-sheets-find-replace
```

### Usage

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

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

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

## Plugin Mode

### Installation

#### npm

```bash
npm install @univerjs/find-replace @univerjs/sheets-find-replace
```

#### pnpm

```bash
pnpm add @univerjs/find-replace @univerjs/sheets-find-replace
```

#### yarn

```bash
yarn add @univerjs/find-replace @univerjs/sheets-find-replace
```

#### bun

```bash
bun add @univerjs/find-replace @univerjs/sheets-find-replace
```

### Usage

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverFindReplacePlugin } from '@univerjs/find-replace' // [!code ++]
import FindReplaceEnUS from '@univerjs/find-replace/locale/en-US' // [!code ++]
import { UniverSheetsFindReplacePlugin } from '@univerjs/sheets-find-replace' // [!code ++]

import '@univerjs/find-replace/lib/index.css' // [!code ++]

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

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

univer.registerPlugin(UniverFindReplacePlugin) // [!code ++]
univer.registerPlugin(UniverSheetsFindReplacePlugin) // [!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-find-replace/facade'
```

### Create Text Finder

`univerAPI.createTextFinderAsync()` creates a text finder and returns an `FTextFinder` instance.

Here are some member methods on [`FTextFinder`](https://docs.univer.ai/reference/facade/find-replace.md):

| Method                | Description                                                                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| findAll               | Get all the matched cells of the current sheet, the current matched cell is the last matched cell                                                             |
| findNext              | Get the next matched cell of the current sheet, if exists return the next matched cell and move the current matched cell to the next matched cell             |
| findPrevious          | Get the previous matched cell of the current sheet, if exists return the previous matched cell and move the current matched cell to the previous matched cell |
| getCurrentMatch       | Get the current matched cell of the current sheet                                                                                                             |
| matchCaseAsync        | Set the match case option, if true, the find operation will match case, otherwise, the find operation will ignore case                                        |
| matchEntireCellAsync  | Set the match entire cell option, if true, the find operation will match entire cell value, otherwise, the find operation will match part of the cell value   |
| matchFormulaTextAsync | Set the match formula text option, if true, the find operation will match formula text, otherwise, the find operation will match value                        |
| replaceAllWithAsync   | Replace all the matched text with the given text                                                                                                              |
| replaceWithAsync      | Replace the current matched text with the given text                                                                                                          |
| ensureCompleteAsync   | Ensure the find operation is completed. Especially when the current sheet changed use this method to ensure the find operation is completed                   |

```typescript
// Assume the current sheet is empty sheet.
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Set some values to the range A1:D10.
const fRange = fWorksheet.getRange('A1:D10')
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 text-finder to find the text '5'.
const textFinder = await univerAPI.createTextFinderAsync('5')

// Find all cells that contain the text '5'.
const matchCells = textFinder.findAll()
matchCells.forEach((cell) => {
  cell.getA1Notation() // D2, C3, B4, A5
})
```