---
url: https://plugin.stripo.email/extensions/reference/api/ControlApi.md
---
# ControlApi

API interface for control implementations in the Stripo Email Editor Extensions SDK.

```typescript
interface ControlApi extends BaseApi, BaseModifierApi
```

## Description

The `ControlApi` interface provides comprehensive API functionality for custom controls in the settings panel. It extends both `BaseApi` and `BaseModifierApi`, offering methods to manage UI elements, access document nodes, handle value changes, and modify the email template. Controls use this API to create rich, interactive settings interfaces for email elements.

## Import

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

## Inheritance

* Extends: [BaseApi](./BaseApi.md), [BaseModifierApi](./BaseModifierApi.md)

## Properties

None (all functionality provided through methods)

## Methods

### setVisibility()

Sets the visibility of a specific UI element within the control's scope.

```typescript
setVisibility(uiElementName: string, isVisible: boolean): void
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| uiElementName | `string` | The ID of the UI element to show/hide |
| isVisible | `boolean` | True to show the element, false to hide it |

#### Usage Notes

* Controls dynamic UI element visibility
* Useful for conditional settings
* Affects only elements within this control
* Changes are immediate

#### Example

```typescript
// Show/hide advanced options based on toggle
public onValueChanged(elementName: string, value: any): void {
    if (elementName === 'showAdvanced') {
        this.api.setVisibility('advancedSettingsSelectPicker', value);
    }
}
```

***

### setUIEAttribute()

Sets a specific attribute on a target UI element within the control's scope.

```typescript
setUIEAttribute(uiElementName: string, attribute: string, value: unknown): void
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| uiElementName | `string` | The ID of the target UI element |
| attribute | `string` | The name of the attribute to set (use UEAttr constants) |
| value | `unknown` | The value to set for the attribute |

#### Usage Notes

* Use with `UEAttr` constants for attribute names
* Dynamically modify UI element properties
* Common attributes: disabled, placeholder, min, max
* Changes apply immediately to the UI

#### Example

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

// Disable input based on condition
this.api.setUIEAttribute('fontSize', UEAttr.TEXT.disabled, isLocked);

// Update placeholder text
this.api.setUIEAttribute('customText', UEAttr.TEXT.placeholder,
    this.api.translate('placeholders.enterText'));

// Set min/max values
this.api.setUIEAttribute('width', UEAttr.COUNTER.minValue, 100);
this.api.setUIEAttribute('width', UEAttr.COUNTER.maxValue, 600);
```

***

### updateValues()

Updates the values of multiple UI elements within the control's scope at once.

```typescript
updateValues(valuesMap: Record<string, unknown>): void
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| valuesMap | `Record<string, unknown>` | Object where keys are UI element IDs and values are their new values |

#### Usage Notes

* Efficient bulk updates
* Use for setting initial values

#### Example

```typescript
// Set multiple values at once
this.api.updateValues({
    'enableFeatureSwitcher': true,
    'itemCountCounter': 5,
    'styleSelect': 'modern'
});
```

***

### updateUIElementValue()

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

Updates the value of a single UI element within the control's scope using path notation.

```typescript
updateUIElementValue(path: string, value: unknown): void
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| path | `string` | The path of the target UI element. Can include indices for repeatable elements. |
| value | `unknown` | The new value to set for the UI element. |

#### Usage Notes

* Supports granular updates
* Crucial for updating items within [REPEATABLE](../constants/UIElementType.md#repeatable) elements
* Path notation: `elementName` for top-level, `elementName[index].fieldName` for nested/repeatable elements

#### Example

```typescript
// Update the value of the input with the name 'text'
this.api.updateUIElementValue('text', 'updated value');

// Update the value of the input with name 'text' in the first item 
// of the REPEATABLE element with name 'items'
this.api.updateUIElementValue('items[0].text', 'updated value');
```

***

### getValues()

Returns the current values of all UI elements managed by this control.

```typescript
getValues(): Record<string, unknown>
```

#### Returns

`Record<string, unknown>` - Object with UI element IDs as keys and their current values

#### Usage Notes

* Get all values for saving/validation
* Useful for creating presets
* Includes only elements within this control
* Values reflect current UI state

#### Example

```typescript
// Save current settings as preset
public saveAsPreset(name: string): void {
    const currentValues = this.api.getValues();
    const preset = {
        name: name,
        values: currentValues,
        timestamp: Date.now()
    };
    this.savePreset(preset);
}

// Validate all values
public validateSettings(): boolean {
    const values = this.api.getValues();
    return values.itemCountCounter >= 1 &&
           values.itemCountCounter <= 10;
}
```

***

### onValueChanged()

Registers a callback function to be invoked when the value of a specific UI element changes.

```typescript
onValueChanged(
    uiElementName: string,
    callback: (newValue: unknown, oldValue: unknown, index?: number) => void
): void
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| uiElementName | `string` | The ID of the UI element to listen to |
| callback | `Function` | Function called when value changes, receiving new and old values, and an optional index if the element is part of a repeatable list |

#### Usage Notes

* `index` parameter (v3.5.0+) is provided when the changed element is part of a [REPEATABLE](../constants/UIElementType.md#repeatable) UI element.

#### Example

```typescript
public onRender(): void {
    // Basic usage
    this.api.onValueChanged('contentText', (newValue, oldValue) => {
        console.log(`Value changed from ${oldValue} to ${newValue}`);
    });

    // v3.5.0+: Usage with repeatable elements
    this.api.onValueChanged('items.title', (newValue, oldValue, index) => {
        console.log(`Item at index ${index} changed from ${oldValue} to ${newValue}`);
    });
}
```

***

### setSettingsPanelTabTitleHtml()

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

Updates a settings panel tab title using raw HTML.

```typescript
setSettingsPanelTabTitleHtml(tabId: string, html: string): void
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| tabId | `string` | The ID of the settings panel tab to update |
| html | `string` | HTML string to render as the tab title |

#### Example

```typescript
this.api.setSettingsPanelTabTitleHtml(
  'appearance',
  '<span class="icon icon-paint"></span> Appearance'
);
```

***

## Inherited Methods from BaseApi

[BaseApi](./BaseApi.md) - Base API interface

## Inherited Methods from BaseModifierApi

[BaseModifierApi](./BaseModifierApi.md) - Document modification API