---
url: >-
  https://plugin.stripo.email/extensions/reference/modification/ModificationDescription.md
---
# ModificationDescription

Class for providing context about template modifications.

```typescript
class ModificationDescription
```

## Description

`ModificationDescription` provides metadata about modifications for version history, undo/redo functionality, and internationalization support. Every modification applied through the Template Modifier API requires a description to document the change and provide context for collaboration and history tracking.

## Import

```typescript
import { ModificationDescription } from '@stripoinc/ui-editor-extensions';
```

## Constructor

```typescript
constructor(key: string)
```

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | `string` | Description text or internationalization key |

### Example

```typescript
// Simple text description
const description = new ModificationDescription('Changed button color');

// Internationalization key
const i18nDescription = new ModificationDescription('actions.button_color_changed');
```

## Methods

### withParams()

Adds parameters for template string interpolation.

```typescript
withParams(params: Record<string, any>): ModificationDescription
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `params` | `Record<string, any>` | Key-value pairs for template interpolation |

#### Returns

`ModificationDescription` - Returns this instance for method chaining

#### Description

This method allows you to provide dynamic values that will be interpolated into the description text. Parameters are replaced in the description string using `{paramName}` syntax.

#### Example

```typescript
const description = new ModificationDescription('Changed color from {oldColor} to {newColor}')
    .withParams({
        oldColor: '#000000',
        newColor: '#FF0000'
    });
// Results in: "Changed color from #000000 to #FF0000"
```

***

### asHidden()

:::::tip Version Availability
This method is available starting from v3.11.0
:::::

Marks the modification as a background change.

```typescript
asHidden(hidden: boolean = true): ModificationDescription
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `hidden` | `boolean` | (Optional) Pass `false` to keep the modification visible. Defaults to `true` |

#### Returns

`ModificationDescription` - Returns this instance for method chaining

#### Description

The modification is applied to the template as usual, but the patch it produces is kept out of the version history UI and out of undo/redo, so the user never sees (nor can accidentally undo) a change they did not make. The change still belongs to the document, so restoring an older version keeps it consistent with the rest of the template.

#### Usage Notes

* Use for technical changes an extension makes on its own, without a user action (e.g., migrating block markup or syncing service attributes)
* A hidden modification is not a separate undo/redo step: when it follows a visible modification, it is undone and redone together with that modification
* The patch is saved like any other, but the host application is not notified about it: the `onDataChanged` callback stays silent for background modifications
* Do not rely on `onDataChanged` to track changes an extension makes this way
* Changes made in response to user actions should stay visible, so users can find them in the version history and undo them

#### Example

```typescript
this.api.getDocumentModifier()
    .modifyHtml(node)
        .setAttribute('data-block-version', '2')
    .apply(new ModificationDescription('Migrated block markup').asHidden());
```

***

### isHidden()

:::::tip Version Availability
This method is available starting from v3.11.0
:::::

Tells whether the modification was marked as a background change via [asHidden()](#ashidden).

```typescript
isHidden(): boolean
```

#### Returns

`boolean` - `true` when the produced patch must stay out of version history and undo/redo. Defaults to `false`

***

### getValue()

Returns the description data structure.

```typescript
getValue(): {key: string; params: Record<string, any>}
```

#### Returns

An object containing:

* `key`: The description text or i18n key
* `params`: The parameters object (may be undefined if not set)

#### Example

```typescript
const description = new ModificationDescription('Button updated')
    .withParams({ type: 'primary' });

console.log(description.getValue());
// Output: { key: 'Button updated', params: { type: 'primary' } }
```