# Editor state API | Mesh integrations

> Imperatively read and mutate the surrounding composition or entry from a Mesh location.

Source: https://docs.uniform.app/docs/integrations/mesh-integrations/editor-state-api

The Editor state API lets a Mesh location read and control whatever an author is currently editing in the visual editor, whether that is a composition, an entry, or a pattern. It is exposed as an object called **`editorState`** for Mesh locations that support it. This object acts as a live handle to that content, letting your location:

- Inspect the full content tree, including its nodes, properties, and metadata.
- Edit a property's value.
- Insert, move, or delete a node.
- Switch the active locale.
- Change the editor's current selection.

Changes you make are applied to the editor immediately, just as if an author had made them by hand.

Because a location renders in its own iframe, `editorState` is how it reaches outside that iframe to read and change the surrounding content. Its methods are asynchronous, so `await` them.

> **Changes are not persisted automatically:**
>
> `editorState` only updates the live, in-editor state of the composition, entry, or pattern being edited. It does not persist anything on its own: the changes behave exactly like manual edits and are only saved when the author saves, and only go live when they publish.

You typically reach for `editorState` to build tools that act on the whole composition or entry, for example:

- Translate or bulk-edit every text property in a composition, then enable and switch to the target locale.
- Generate or restructure content programmatically by inserting, moving, or deleting nodes.
- Read the current tree to drive a custom side-rail tool, inspector, or validation/preview panel.
- Derive computed values or run custom business logic from other fields, for example reading several field values and writing back a calculated price, slug, or summary.

`editorState` is provided to the following locations through `useMeshLocation`:

- [Editor tools location](https://docs.uniform.app/docs/integrations/mesh-integrations/locations/editor-tools) — `useMeshLocation('canvasEditorTools')`
- [Parameter Type location](https://docs.uniform.app/docs/integrations/mesh-integrations/locations/parameter-type)
- [Data Resource Selector location](https://docs.uniform.app/docs/integrations/mesh-integrations/locations/data-resource-selector)

## Using the Editor state API

> **Minimum SDK version:**
>
> The Editor state API requires `@uniformdev/mesh-sdk` version **20.66.1** or higher.

### Read the editor tree

- `getRootNodeId()` — root node ID
- `exportTree()` — full composition (`RootComponentInstance`) or entry (`EntryData`) tree
- `exportSubtree({ nodeId, options? })` — subtree for a node
- `exportMetadata()`, `exportRootNodeMetadata()` — composition or entry metadata
- `getNodeById`, `getNodeChildren`, `getNodeProperty`, `getNodeProperties`, `getParentInfo`
- `getPristine()` — whether the editor has unsaved changes

When editing entries, `exportTree()` returns entry-shaped data with `fields` at the root instead of composition `parameters`.

### Write and structure

- `updateNodeProperty({ nodeId, property, value, type?, locale?, conditionIndex? })`
- `insertNode`, `deleteNode`, `moveNode`, `insertPattern`
- `updateRootMetadata`, `updateRootNode`
- `isPatternPropertyOverridden`, `resetPatternPropertyOverride`

### Selection

- `getSelectedNodeId` / `setSelectedNodeId`
- `getSelectedParameterId` / `setSelectedParameterId`

### Locales

- `enableLocale({ locale })`, `disableLocale({ locale })`
- `setCurrentLocale({ locale })` — switch the active locale in the editor UI
- `setPropertyLocalizability({ nodeId, property, propertyDefinition, isLocalized, copyFromLocale? })` — toggle between shared and locale-specific values (same behavior as the dashboard locale drawer). Requires the schema `propertyDefinition` from the Uniform API.

### Example: walk the tree and update a property

```javascript
import { useMeshLocation } from '@uniformdev/mesh-sdk-react';

const TranslationTool = () => {
  const { editorState } = useMeshLocation('canvasEditorTools');

  const handleTranslate = async () => {
    const tree = await editorState.exportTree();
    await editorState.enableLocale({ locale: 'fr-FR' });
    await editorState.setCurrentLocale({ locale: 'fr-FR' });

    const rootId = await editorState.getRootNodeId();
    await editorState.updateNodeProperty({
      nodeId: rootId,
      property: 'title',
      value: 'Bonjour',
      locale: 'fr-FR',
      conditionIndex: -1,
      type: 'text',
    });
  };

  return <button type="button" onClick={handleTranslate}>Translate</button>;
};
```

For a full-featured translation example that walks every node and handles conditional values, see [`canvasEditorToolsTranslation.tsx`](https://github.com/uniformdev/examples/blob/main/mesh/mesh-integration/pages/reference/canvasEditorToolsTranslation.tsx) in the [Mesh integration starter kit](https://github.com/uniformdev/examples/tree/main/mesh/mesh-integration). For a tree-walking inspector that uses `getNodeById` and `getNodeChildren`, see [`canvasEditorTools.tsx`](https://github.com/uniformdev/examples/blob/main/mesh/mesh-integration/pages/reference/canvasEditorTools.tsx).