# @atlaskit/editor-plugin-local-id

> LocalId plugin for @atlaskit/editor-core

Latest version **31.0.0** (published 2026-11-17) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @atlaskit/editor-plugin-local-id
pnpm add @atlaskit/editor-plugin-local-id
yarn add @atlaskit/editor-plugin-local-id
bun add @atlaskit/editor-plugin-local-id
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 31.0.0 |
| Published | 2026-11-17 |
| First published | 2025-08-07 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 8 |
| Unpacked size | 159.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Atlassian Pty Ltd |
| Maintainers | atlassianartifactteam |

## Links

- npm: https://www.npmjs.com/package/@atlaskit/editor-plugin-local-id
- Repository: https://bitbucket.org/atlassian/atlassian-frontend-mirror
- Homepage: https://bitbucket.org/atlassian/atlassian-frontend-mirror#readme
- Issues: https://bitbucket.org/atlassian/atlassian-frontend-mirror/issues
- npm.io page: https://npm.io/package/@atlaskit/editor-plugin-local-id

## Dependencies (8)

- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.0.0
- [@atlaskit/adf-schema](https://npm.io/package/@atlaskit/adf-schema.md) ^57.7.0
- [@atlaskit/editor-prosemirror](https://npm.io/package/@atlaskit/editor-prosemirror.md) ^9.0.0
- [@atlaskit/platform-feature-flags](https://npm.io/package/@atlaskit/platform-feature-flags.md) ^2.2.0
- [@atlaskit/editor-plugin-collab-edit](https://npm.io/package/@atlaskit/editor-plugin-collab-edit.md) ^35.0.0
- [@atlaskit/editor-plugin-composition](https://npm.io/package/@atlaskit/editor-plugin-composition.md) ^32.0.0
- [@atlaskit/editor-plugin-limited-mode](https://npm.io/package/@atlaskit/editor-plugin-limited-mode.md) ^30.0.0
- [@atlaskit/platform-feature-experiments](https://npm.io/package/@atlaskit/platform-feature-experiments.md) ^0.3.0

## Recent versions

- 31.0.0 (latest) — 2026-11-17
- 30.0.0 — 2026-11-17
- 29.0.0 — 2026-11-16
- 28.0.4 — 2026-11-02
- 28.0.3 — 2026-10-29
- 28.0.2 — 2026-10-28
- 28.0.1 — 2026-10-27
- 28.0.0 — 2026-10-27
- 27.0.4 — 2026-10-23
- 27.0.3 — 2026-10-22
- 27.0.2 — 2026-10-21
- 27.0.1 — 2026-10-21
- 27.0.0 — 2026-10-20
- 26.0.2 — 2026-10-19
- 26.0.1 — 2026-10-19
- … 279 more at https://npm.io/package/@atlaskit/editor-plugin-local-id/versions

## README

# Editor Plugin Local ID

LocalId plugin for @atlaskit/editor-core

**Note:** This component is designed for internal Atlassian development. External contributors will be able to use this component but will not be able to submit issues.

## Overview

The Local ID plugin ensures that all non-ignored nodes in the document have unique `localId` attributes. It combines two approaches for optimal performance:

1. **One-time initialization scan** - Adds missing local IDs to existing nodes when the editor starts
2. **Incremental transaction processing** - Adds local IDs to new nodes as they're created

## Key features

- **Automatic local ID assignment** - Ensures all nodes without local IDs receive unique identifiers
- **Efficient initialization** - Uses `requestIdleCallback` with `requestAnimationFrame` fallback for Safari
- **Incremental updates** - Processes only changed nodes during transactions
- **Node filtering** - Skips ignored node types (text, hardBreak, mediaGroup)
- **Batch processing** - Applies all updates in a single transaction
- **Error tracking** - Optional error reporting for local ID changes via watchmen plugin
- **Plugin actions** - Provides `getNode` and `replaceNode` actions for querying and modifying nodes by local ID

### How It Works

#### Initialization Phase

- **Trigger**: Uses the editor view's initialization lifecycle to schedule the scan
- **Execution**: Performs a single document traversal during browser idle time
- **Scheduling**: Uses `requestIdleCallback` with `requestAnimationFrame` fallback for Safari
- **Purpose**: Ensures all existing nodes have local IDs

#### Transaction Processing Phase

- **Trigger**: Activates on every document-changing transaction
- **Execution**: Processes only the new/changed nodes from transaction steps
- **Performance**: Only scans changed ranges, not the entire document
- **Purpose**: Adds local IDs to newly created nodes

#### Node Processing

For each node (both during initialization and transaction processing):
- **Ignored nodes**: Always skipped (text, hardBreak)
- **Nodes with existing localId**: Left unchanged
- **Nodes without localId**: New UUID generated and assigned

#### Transaction Handling

- **Incremental updates**: Only processes nodes that actually changed
- **Efficient scanning**: Uses `step.getMap()` to identify changed ranges
- **Position accuracy**: Gets precise document positions for all changed nodes
- **Batch processing**: All updates applied in a single transaction

#### Behavior

| Case | Action Taken | Transaction Impact |
|------|-------------|-------------------|
| Existing node without `localId` (initialization) | `localId` is added | Single transaction with all changes |
| New node added without `localId` (transaction) | `localId` is added | Single transaction with all changes |
| Node already has a `localId` | Left unchanged | No transaction |
| Only selection changes | No action taken | No transaction |
| Cut operations | Skipped to avoid conflicts | No transaction |
| Document unchanged | Early exit | No transaction |

## Install

- **Install** - *yarn add @atlaskit/editor-plugin-local-id*
- **npm** - [@atlaskit/editor-plugin-local-id](https://www.npmjs.com/package/@atlaskit/editor-plugin-local-id)
- **Source** - [Bitbucket](https://bitbucket.org/atlassian/atlassian-frontend/src/master/packages/editor/editor-plugin-local-id)
- **Bundle** - [unpkg.com](https://unpkg.com/@atlaskit/editor-plugin-local-id/dist/)

## Usage

**Internal use only**

@atlaskit/editor-plugin-local-id is intended for internal use by the @atlaskit/editor-core and as a plugin dependency of the Editor within your product.

Direct use of this component is not supported.

Please see [Atlaskit - Editor plugin local-id](https://atlaskit.atlassian.com/packages/editor/editor-plugin-local-id) for documentation and examples for this package.

## Support

For internal Atlassian, visit the slack channel [#help-editor](https://atlassian.slack.com/archives/CFG3PSQ9E) for support or visit [go/editor-help](https://go/editor-help) to submit a bug.

## License

Please see [Atlassian Frontend - License](https://hello.atlassian.net/wiki/spaces/AF/pages/2589099144/Documentation#License) for more licensing information.

---
_Source: https://npm.io/package/@atlaskit/editor-plugin-local-id · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
